opt-in per-session wallet sync (issue #123) (#200)

* core/account: let migrateSessions scope to a single session

The opt-in per-session sync (#123) reuses the existing re-key copy
loop but must move exactly one session. An optional sessionId filters
the source listing; omitted, the bulk wallet-switch behavior is
unchanged. Covered by a new spec case: the scoped run copies only the
named session, leaves siblings untouched, and an unknown id is a
clean no-op.

* surfaces/localhost: stop auto-migrating guest sessions on wallet connect

Connecting a wallet used to copy every guest session into that
wallet's store, silently binding pre-wallet local work to whatever
identity the user connected (#123). adoptWallet now only swaps the
wallet in; guest sessions stay in the device store and ride along on
every sessions push tagged local: true (cached guest-only metas,
spliced synchronously so SSE ordering is untouched, deduped against
stale pre-connect clients). A new syncSessionToWallet message moves
exactly one session through the same migrateSessions machinery and
answers with sessionSynced. Sessions created while a wallet is
connected are born in the wallet's store, so their auto-sync behavior
is unchanged.

* webview: Local tag + opt-in sync confirm for pre-wallet sessions

Chat-list rows for sessions still living in the device store show a
LOCAL tag with a sync mark while a wallet is connected (#123).
Tapping the row opens a confirm sheet that shows the destination
wallet address up front; Sync sends syncSessionToWallet for that one
session and the tag clears on the sessionSynced ack. The row never
opens the chat while local: the wallet runtime cannot load it, and
sending into an empty same-id chat would fork the history and block
the sync. Long-press delete is skipped there for the same reason.

* localhost+webview: truthful sync ack, destination avatar in the confirm

Review fixes on the opt-in sync flow:

- migrateSessions swallows per-session faults into report.skipped, so the
  handler acked ok and cleared the Local tag even when nothing was
  copied (an unloadable guest page). The ack is now ok only when
  report.copied is 1; a skipped copy keeps the tag and reports a
  readable error.
- The confirm sheet showed the destination address only; issue #123
  point 3 asks for the agent identity too, so the wallet-derived avatar
  (same generator as the rank cards) now sits beside the address.

---------

Co-authored-by: RemilioNubilio <275382225+RemilioNubilio@users.noreply.github.com>

Author: RemilioNubilio

packages/core/src/account/migrate.spec.ts

@@ -189,6 +189,24 @@ describe("account/migrate — session re-key between wallets", () => {
     expect((await storeFor(walletB).load("s-ok"))?.messages).toHaveLength(3);
   });
 
+  it("scopes to one session when a sessionId is given: siblings are untouched", async () => {
+    const src = storeFor(walletA);
+    await seed(src, meta("s1", "wanted", 2000), 3);
+    await seed(src, meta("s2", "left local", 1000), 2);
+
+    const report = await migrateSessions(storeFor(walletA), storeFor(walletB), "s1");
+    expect(report).toEqual({ copied: 1, skipped: 0, messages: 3 });
+
+    const dst = storeFor(walletB);
+    expect((await dst.listMine()).map((s) => s.sessionId)).toEqual(["s1"]);
+    expect((await dst.load("s1"))?.messages).toHaveLength(3);
+    expect(await dst.load("s2")).toBeNull();
+
+    // An unknown id copies nothing and fails nothing.
+    const miss = await migrateSessions(storeFor(walletA), storeFor(walletB), "nope");
+    expect(miss).toEqual({ copied: 0, skipped: 0, messages: 0 });
+  });
+
   it("covers the guest-unlock shape: a signMessage-only device wallet migrates into a real wallet", async () => {
     // Mirror of the surface's deviceGuestWallet: session-key signing works, chain signing
     // fails closed. Migration must only ever need signMessage.

packages/core/src/account/migrate.ts

@@ -12,6 +12,9 @@
 // Idempotent: sessions already complete in the destination are skipped; a partial
 // copy (an interrupted earlier run) resumes — only the missing tail is appended,
 // matched by JSON prefix; a same-id session with DIFFERENT content is never touched.
+//
+// `sessionId` scopes the run to that one session (the opt-in per-session sync);
+// omitted, every source session is copied (the wallet-switch bulk path).
 
 import type { SessionStore } from "./store.js";
 
@@ -24,10 +27,12 @@ export interface MigrationReport {
 export async function migrateSessions(
   source: SessionStore,
   destination: SessionStore,
+  sessionId?: string,
 ): Promise<MigrationReport> {
   const report: MigrationReport = { copied: 0, skipped: 0, messages: 0 };
   const existing = new Set((await destination.listMine()).map((s) => s.sessionId));
-  for (const meta of await source.listMine()) {
+  const metas = await source.listMine();
+  for (const meta of sessionId ? metas.filter((m) => m.sessionId === sessionId) : metas) {
     // Per-session tolerance (mirrors listMine's): one undecryptable/corrupt session
     // must not abort the run — count it and keep copying the healthy ones.
     try {

surfaces/localhost/src/index.ts

@@ -52,6 +52,7 @@ import {
   type ClaudeLogin,
   type CodexLogin,
   type Wallet,
+  type SessionMeta,
   type GoogleLogin,
   type StorageConfig,
   switchStorage,
@@ -205,22 +206,60 @@ async function ensureGuestRuntime(): Promise<AgentRuntime> {
   return ensureRuntime(guest);
 }
 
-// Preserve the value-first conversation when the user unlocks. Guest pages are decrypted
-// with the device key and re-encrypted into the real wallet's local store; the copy loop
-// (dedupe/resume/fault tolerance) lives in core's migrateSessions — this owns the surface
-// part only: which wallets and stores are involved.
-async function migrateGuestSessions(realWallet: Wallet): Promise<void> {
+// A wallet's manual store is always keyed by its own address; keep the pairing in one place.
+function sessionStoreFor(w: Wallet): SessionStore {
+  return new SessionStore(w, manualStorage(w.address));
+}
+
+// Preserve the value-first conversation when the user opts in (issue #123). Guest pages are
+// decrypted with the device key and re-encrypted into the real wallet's local store; the
+// copy loop (dedupe/resume/fault tolerance) lives in core's migrateSessions, this owns the
+// surface part only: which wallets and stores are involved. Scoped to ONE session, so
+// connecting a wallet never adopts guest work wholesale; the user pulls sessions in one
+// at a time from the chat list.
+async function migrateGuestSession(realWallet: Wallet, sessionId: string): Promise<boolean> {
   const guest = await deviceGuestWallet();
   const report = await migrateSessions(
-    new SessionStore(guest, manualStorage(guest.address)),
-    new SessionStore(realWallet, manualStorage(realWallet.address)),
+    sessionStoreFor(guest),
+    sessionStoreFor(realWallet),
+    sessionId,
   );
-  if (report.copied || report.skipped) {
-    console.log(
-      `[wallet] guest migration: ${report.copied} session(s) copied ` +
-        `(${report.messages} messages), ${report.skipped} skipped`,
-    );
-  }
+  console.log(
+    `[wallet] session sync ${sessionId.slice(0, 8)}: ${report.copied} copied ` +
+      `(${report.messages} messages), ${report.skipped} skipped`,
+  );
+  // migrateSessions swallows per-session faults into report.skipped (an unloadable
+  // guest page throws inside the loop, not out of it), so "did not throw" is NOT
+  // "copied": only a real copy may clear the Local tag.
+  return report.copied === 1;
+}
+
+// Guest sessions NOT yet present in the connected wallet's store, cached at adopt/sync
+// time. While a wallet is connected these ride along on every `sessions` push tagged
+// `local: true`, so the UI can show the Local tag + per-session sync affordance. Null
+// while no wallet is connected (a guest's list already IS its own local sessions).
+let localSessions: SessionMeta[] | null = null;
+
+async function refreshLocalSessions(realWallet: Wallet): Promise<void> {
+  const guest = await deviceGuestWallet();
+  const owned = new Set((await sessionStoreFor(realWallet).listMine()).map((s) => s.sessionId));
+  localSessions = (await sessionStoreFor(guest).listMine()).filter((s) => !owned.has(s.sessionId));
+}
+
+// Splice the cached guest-only sessions into a core `sessions` push, newest first and
+// tagged local. Pass-through for every other message and while no wallet is connected.
+// Synchronous (cached metas only), so SSE event ordering is untouched. Ids already in
+// the push are skipped: a client attached before the connect still lists from the guest
+// runtime until it reconnects, and appending there would duplicate every row.
+function withLocalSessions(msg: any): unknown {
+  if (msg?.type !== "sessions" || !walletAddress || !localSessions?.length) return msg;
+  const seen = new Set(msg.list.map((s: SessionMeta) => s.sessionId));
+  const extras = localSessions.filter((s) => !seen.has(s.sessionId));
+  if (!extras.length) return msg;
+  const list = [...msg.list, ...extras.map((s) => ({ ...s, local: true }))].sort(
+    (a, b) => b.ts - a.ts,
+  );
+  return { ...msg, list };
 }
 
 // Latest drive-mirror sync result + the hook the active chat sets to surface it
@@ -371,22 +410,27 @@ async function submitGoogleAuthCode(c: Client, code: string) {
 }
 
 // The one path a wallet takes to become THE connected wallet, whatever produced it
-// (external web/MWA wallet or a device-local keypair). Migrate the guest's work into the
-// new wallet's store, swap it in, and rebuild the runtime so the WebView reopens straight
-// into the unlocked state. Idempotent per host: re-connecting the same address is a no-op
-// so re-opened tabs don't rebuild. Adapters below build the Wallet; this owns the connect.
+// (external web/MWA wallet or a device-local keypair). Swap it in and rebuild the runtime
+// so the WebView reopens straight into the unlocked state. Guest sessions are NOT migrated
+// here (issue #123): connecting a wallet must not silently bind the device's local chats
+// to that identity. They stay in the guest store, listed with a Local tag, and move only
+// through the explicit syncSessionToWallet flow. Sessions created from here on are born
+// in the wallet's store, so those keep syncing automatically as before. Idempotent per
+// host: re-connecting the same address is a no-op so re-opened tabs don't rebuild.
+// Adapters below build the Wallet; this owns the connect.
 async function adoptWallet(connected: Wallet, address: string): Promise<void> {
   if (walletAddress === address) return;
-  // A damaged guest store must never lock the user out of connecting — the guest copy
-  // stays on disk, so a later connect can retry the migration.
-  try {
-    await migrateGuestSessions(connected);
-  } catch (e) {
-    console.error("[wallet] guest session migration failed:", e);
-  }
   wallet = connected;
   walletAddress = address;
   walletEpoch += 1;
+  // A damaged guest store must never lock the user out of connecting; tagging is
+  // best-effort and recomputed on the next connect.
+  try {
+    await refreshLocalSessions(connected);
+  } catch (e) {
+    localSessions = [];
+    console.error("[wallet] local session listing failed:", e);
+  }
   await rebuildRuntime(connected);
 }
 
@@ -994,7 +1038,9 @@ function attachMarketHandlers(c: Client) {
 // arrives via the same onRecv (POST), so TransportApprovalChannel is unchanged.
 function attachChat(id: string, c: Client, rt: AgentRuntime) {
   const transport = {
-    send: (msg: unknown) => c.send(msg),
+    // Local (guest) sessions ride along on the dispatcher's sessions pushes while a
+    // wallet is connected (see withLocalSessions); everything else passes through.
+    send: (msg: unknown) => c.send(withLocalSessions(msg)),
     // Subscribe (don't replace): both the dispatcher and the approval channel register a
     // handler on the same transport. POST fans out to all of them.
     onRecv: (cb: (m: any) => void) => { c.recvs.push(cb); },
@@ -1033,6 +1079,7 @@ function attachChat(id: string, c: Client, rt: AgentRuntime) {
       await clearWalletMode(); // explicit disconnect = the standing choice is gone
       await disconnectCloud();
       walletAddress = null;
+      localSessions = null; // back to guest: its own list IS the local sessions
       runtime = null;
       wallet = await deviceGuestWallet();
       walletEpoch += 1;
@@ -1143,6 +1190,28 @@ function attachWalletConnection(c: Client) {
       await pushCliStatus(c);
       return;
     }
+    // Opt-in per-session sync (issue #123): copy ONE local (guest) session into the
+    // connected wallet's store. The reused migrateSessions machinery is idempotent, so
+    // a retry after a partial copy resumes instead of duplicating. On success the tag
+    // cache drops the session; the UI clears its Local tag off the sessionSynced ack.
+    if (m?.type === "syncSessionToWallet" && typeof m.sessionId === "string") {
+      if (!wallet || !walletAddress) {
+        c.send({ type: "sessionSynced", sessionId: m.sessionId, ok: false, error: "Connect a wallet first." });
+        return;
+      }
+      try {
+        const copied = await migrateGuestSession(wallet, m.sessionId);
+        if (!copied) {
+          c.send({ type: "sessionSynced", sessionId: m.sessionId, ok: false, error: "Could not read this session from local storage." });
+          return;
+        }
+        if (localSessions) localSessions = localSessions.filter((s) => s.sessionId !== m.sessionId);
+        c.send({ type: "sessionSynced", sessionId: m.sessionId, ok: true });
+      } catch (e) {
+        c.send({ type: "sessionSynced", sessionId: m.sessionId, ok: false, error: (e as Error).message });
+      }
+      return;
+    }
     if (m?.type !== "connectWallet" || typeof m.address !== "string" || !Array.isArray(m.signature)) return;
     // A SILENT restore must never override the user's standing choice: drop it when a
     // wallet is already connected (the boot local reconnect won) or the persisted mode

surfaces/webview/src/chat/Sessions.tsx

@@ -1,4 +1,5 @@
 import { useState, useEffect, useRef, type ReactNode, type CSSProperties, type PointerEvent as ReactPointerEvent } from "react";
+import { walletAvatarSvg } from "../market/walletAvatar";
 import { useStore } from "../state/store";
 import { IqLogo, AgentIcon, LockIcon, SkillIcon } from "../icons";
 import { useOnline } from "../layoutEffects";
@@ -19,6 +20,18 @@ function WifiOffIcon({ className, style }: { className?: string; style?: CSSProp
     </svg>
   );
 }
+
+// circular-arrows mark for the per-session sync affordance (issue #123; inline SVG, no emoji).
+function SyncIcon({ className, style }: { className?: string; style?: CSSProperties }) {
+  return (
+    <svg className={className} style={style} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
+      <path d="M21 3v5h-5" />
+      <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />
+      <path d="M8 16H3v5" />
+    </svg>
+  );
+}
 import { forgetAndroidWallet } from "../onboarding/androidWallet";
 import { openExternalUrl } from "../platform/openExternalUrl";
 import { useAutoOpenExternalUrl } from "../platform/useAutoOpenExternalUrl";
@@ -171,6 +184,10 @@ export function Sessions({
   // Long-press a chat row to reveal a delete menu (replaces the always-on per-row x).
   // `pressFired` suppresses the row's open-on-click that would otherwise follow pointerup.
   const [menuFor, setMenuFor] = useState<{ id: string; title: string } | null>(null);
+  // Confirm sheet for the opt-in per-session sync (issue #123): tapping a Local row
+  // opens this instead of the chat, so a pre-wallet session is never opened (and
+  // possibly forked) under the wallet identity without an explicit yes.
+  const [syncFor, setSyncFor] = useState<{ id: string; title: string } | null>(null);
   const pressTimer = useRef<number | null>(null);
   const pressOrigin = useRef<{ x: number; y: number } | null>(null);
   const pressFired = useRef(false);
@@ -369,15 +386,25 @@ export function Sessions({
                 {state.sessions.map((s) => {
                   const active = s.sessionId === state.activeSessionId;
                   const running = state.sessionsRunning.includes(s.sessionId);
+                  // Pre-wallet session still in the device store (server tags these only
+                  // while a wallet is connected). Its row opens the sync confirm, never
+                  // the chat: the wallet runtime can't load it, and sending into an empty
+                  // same-id chat would fork the history and block the sync forever. No
+                  // long-press delete either; the wallet store doesn't hold this session.
+                  const local = !!s.local;
                   return (
                     <button
                       key={s.sessionId}
-                      onPointerDown={(e) => startPress(e, s)}
+                      onPointerDown={(e) => { if (!local) startPress(e, s); }}
                       onPointerMove={movePress}
                       onPointerUp={clearPress}
                       onPointerCancel={clearPress}
                       onClick={() => {
                         if (pressFired.current) { pressFired.current = false; return; }
+                        if (local) {
+                          setSyncFor({ id: s.sessionId, title: s.title || t(M.menu.untitled) });
+                          return;
+                        }
                         send({ type: "open", sessionId: s.sessionId });
                         onClose();
                       }}
@@ -387,6 +414,12 @@ export function Sessions({
                       <span className="an-term-mono min-w-0 flex-1 truncate text-[15px] font-bold" style={{ color: running ? "var(--an-run-fg)" : active ? "var(--an-term-fg)" : "var(--an-term-fg-2)" }}>
                         {s.title || t(M.menu.untitled)}
                       </span>
+                      {local && (
+                        <span className="an-term-mono ml-2 flex flex-none items-center gap-1.5 text-[11px] font-bold" style={{ color: "var(--an-term-fg-6)", letterSpacing: "0.5px" }}>
+                          LOCAL
+                          <SyncIcon className="h-3.5 w-3.5" style={{ color: "var(--an-green)" }} />
+                        </span>
+                      )}
                       {running && (
                         <span className="an-term-mono an-run ml-2 flex-none text-[11px] font-bold" style={{ color: "var(--an-run-accent)", letterSpacing: "0.5px" }}>
                           RUN
@@ -428,6 +461,37 @@ export function Sessions({
                 </div>
               </div>
             )}
+
+            {/* Opt-in per-session sync confirm (issue #123): show the destination wallet
+                address up front, then migrate that ONE session on an explicit yes. */}
+            {syncFor && (
+              <div className="an-chatmenu-backdrop" onClick={() => setSyncFor(null)}>
+                <div className="an-chatmenu" onClick={(e) => e.stopPropagation()}>
+                  <div className="an-chatmenu-title truncate">{syncFor.title}</div>
+                  <div className="px-3 pb-3">
+                    <p className="text-[12px] leading-relaxed" style={{ color: "var(--an-fg-dim)" }}>{t(M.menu.syncConfirm)}</p>
+                    {/* Destination identity, address AND the agent it renders as (issue #123
+                        point 3): the avatar is derived from the wallet, same as the rank cards. */}
+                    <div className="an-term-mono mt-2 flex items-center gap-2.5 border px-2 py-1.5 text-[11px] leading-relaxed" style={{ borderColor: "var(--an-green-line)", background: "var(--an-green-dim)", color: "var(--an-term-fg)" }}>
+                      <span className="h-7 w-7 shrink-0 overflow-hidden" style={{ border: "1px solid var(--an-line)" }} aria-hidden="true" dangerouslySetInnerHTML={{ __html: walletAvatarSvg(state.walletAddress ?? "") }} />
+                      <span className="break-all">{state.walletAddress}</span>
+                    </div>
+                    <div className="mt-3 flex gap-2">
+                      <button className="an-btn an-btn-outline flex-1" onClick={() => setSyncFor(null)}>{t(M.menu.syncKeepLocal)}</button>
+                      <button
+                        className="an-btn an-btn-green flex-1"
+                        onClick={() => {
+                          send({ type: "syncSessionToWallet", sessionId: syncFor.id });
+                          setSyncFor(null);
+                        }}
+                      >
+                        {t(M.menu.syncAction)}
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            )}
           </>
         ) : settingsMode === "configure" ? (
           <div className="flex h-full flex-col">

surfaces/webview/src/i18n/messages.ts

@@ -213,6 +213,11 @@ export const M = {
     untitled: m("(untitled)", "(제목 없음)", "(без названия)"),
     newChat: m("New chat", "새 채팅", "Новый чат"),
     deleteChat: m("Delete chat", "채팅 삭제", "Удалить чат"),
+    // opt-in per-session sync (issue #123): confirm sheet for pulling a Local chat
+    // into the connected wallet. The LOCAL row tag itself is a terminal token (inline).
+    syncConfirm: m("Sync this session with this agent?", "이 세션을 이 에이전트와 동기화할까요?", "Синхронизировать эту сессию с этим агентом?"),
+    syncAction: m("Sync", "동기화", "Синхронизировать"),
+    syncKeepLocal: m("Keep local", "로컬로 유지", "Оставить локально"),
   },
 
   settings: {

surfaces/webview/src/state/store.tsx

@@ -433,6 +433,14 @@ function reducer(state: State, ev: Action): State {
         sessionsRunning: ev.running ?? [],
         activeSessionId: state.activeSessionId ?? ev.activeId,
       };
+    case "sessionSynced":
+      // Per-session sync ack (issue #123). Clear the row's Local tag right away instead of
+      // waiting for the next natural sessions push (which only fires at turn edges/ready).
+      if (!ev.ok) return { ...state, toast: `Sync failed: ${ev.error ?? "unknown"}` };
+      return {
+        ...state,
+        sessions: state.sessions.map((s) => (s.sessionId === ev.sessionId ? { ...s, local: undefined } : s)),
+      };
     case "loading":
       return { ...state, loading: true };
     // Optimistic session switch: the moment the user taps a chat, flip the active id (so