runpane 2.4.185 → 2.4.186

package/dist/handoff.js

@@ -15,6 +15,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const boundaryDecoder_1 = require("./boundaryDecoder");
 const daemonClient_1 = require("./daemonClient");
 const localControl_1 = require("./localControl");
+const nativeSession_1 = require("./nativeSession");
 const errors_1 = require("./errors");
 const contract_1 = require("./generated/contract");
 const workspace_1 = require("./workspace");
@@ -80,8 +81,6 @@ function parseDestination(text, machines, overrides = {}) {
     const agent = overrides.agent ?? agents[0];
     if (!agent)
         throw new Error(`Name the agent: claude, codex, or cursor. For example: runpane handoff "claude opus on parsas-macbook-pro" --note-file ~/handoff.md`);
-    if (agent === 'opencode')
-        throw new Error('OpenCode is supported in terminal panes, but handoff to OpenCode is not supported yet. Choose claude, codex, or cursor; nothing was committed or sent.');
     let machine = null;
     if (overrides.machine) {
         machine = machineName((0, workspace_1.resolveMachine)(overrides.machine, machines));
@@ -103,6 +102,8 @@ function parseDestination(text, machines, overrides = {}) {
         throw new Error(`Invalid effort. Use ${[...EFFORTS].join(', ')}.`);
     if (agent === 'cursor' && effort !== undefined)
         throw new Error('Cursor effort is not supported. Omit --effort and effort text; nothing was committed or sent.');
+    if (agent === 'opencode' && effort !== undefined)
+        throw new Error('OpenCode effort is not supported. Omit --effort and effort text; nothing was committed or sent.');
     if (model)
         destination.model = model;
     if (effort)
@@ -170,7 +171,8 @@ function frontMatter(origin) {
 }
 /** Replaces the note's front matter with the CLI's own, so the origin and git state are never stale. */
 function stampNote(text, origin, receiver) {
-    const body = text.replace(/^---\n[\s\S]*?\n---\n/, '').replace(/^\n+/, '');
+    // A note saved by PowerShell starts with a BOM and uses CRLF; its front matter is replaced all the same.
+    const body = text.replace(/^/, '').replace(/\r\n/g, '\n').replace(/^---\n[\s\S]*?\n---\n/, '').replace(/^\n+/, '');
     return `${frontMatter(origin)}\n${body.trimEnd()}\n\n${receiver}\n`;
 }
 function git(args, cwd) {
@@ -273,7 +275,8 @@ async function remoteDestination(machine) {
         repos: () => (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:repos:list', [], localControl_1.repoListResultSchema),
         create: (request) => (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:panes:create', [request], localControl_1.paneCreateResultSchema, REPORT_TIMEOUT_MS),
         run: (argv, timeoutMs = 120_000) => (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:machine:exec', [{ command: argv.map((arg) => quote(arg, shell)).join(' '), timeoutMs }], execResultSchema, timeoutMs + 30_000),
-        write: async (file, content) => (await (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:machine:write', [{ path: file, content, encoding: 'utf8' }], writeResultSchema)).path,
+        write: async (file, content, encoding = 'utf8') => (await (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:machine:write', [{ path: file, content, encoding }], writeResultSchema, REPORT_TIMEOUT_MS)).path,
+        invoke: (channel, args, schema) => (0, daemonClient_1.invokeRemoteDaemon)(target, channel, args, schema, REPORT_TIMEOUT_MS),
     };
 }
 function localDestination(name, paneDir) {
@@ -292,18 +295,20 @@ function localDestination(name, paneDir) {
             child.on('error', (error) => resolve({ exitCode: 1, stdout, stderr: stderr + error.message }));
             child.on('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
         }),
-        write: async (file, content) => {
+        write: async (file, content, encoding = 'utf8') => {
             const resolved = file.replace(/^~(?=[\\/])/, process.env.HOME ?? process.env.USERPROFILE ?? '~');
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(resolved), { recursive: true });
-            node_fs_1.default.writeFileSync(resolved, content, { mode: 0o600 });
+            node_fs_1.default.writeFileSync(resolved, Buffer.from(content, encoding), { mode: 0o600 });
             return resolved;
         },
+        invoke: (channel, args, schema) => (0, daemonClient_1.invokeDaemon)(channel, args, schema, { paneDir, timeoutMs: REPORT_TIMEOUT_MS }),
     };
 }
 function quote(value, shell) {
     if (/^[\w./:@=+-]+$/.test(value))
         return value;
-    return /(?:powershell|pwsh)(?:\.exe)?$/i.test(shell) ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, `'\\''`)}'`;
+    // PowerShell also ends a single-quoted string at a typographic single quote.
+    return /(?:powershell|pwsh)(?:\.exe)?$/i.test(shell) ? `'${value.replace(/['\u2018\u2019\u201A\u201B]/g, '$&$&')}'` : `'${value.replace(/'/g, `'\\''`)}'`;
 }
 async function mustRun(destination, command, what, timeoutMs) {
     const result = await destination.run(command, timeoutMs);
@@ -368,14 +373,399 @@ function receiverInstructions(origin, state, remote, reporter) {
         `5. When you finish or get blocked, report back to the sender: ${reportTarget}`,
     ].join('\n');
 }
+/**
+ * Where an agent records, for every command it runs, which of its own conversations ran it. This is
+ * the sender's own live record, so it is trusted over the id Pane captured for the tab: Pane learns
+ * a Codex id only when Codex exits, and a command run through Codex's shared background server
+ * can inherit another tab's PANE_PANEL_ID.
+ */
+const LIVE_SESSION_ENV = [['claude', 'CLAUDE_CODE_SESSION_ID'], ['codex', 'CODEX_THREAD_ID']];
+/** Which session is handing off: the agent's live record when it has one, otherwise Pane's record for this tab. */
+function senderSession(recorded) {
+    const live = LIVE_SESSION_ENV.flatMap(([agent, key]) => {
+        const id = process.env[key]?.trim();
+        return id ? [{ agent, id }] : [];
+    });
+    // One agent started inside another sees both records; the tab's agent decides which one is speaking.
+    const chosen = live.length > 1 ? live.find(entry => entry.agent === recorded?.agentType) : live[0];
+    if (live.length > 1 && !chosen) {
+        return { fresh: `Both ${live.map(entry => entry.agent).join(' and ')} report a live session in this terminal (one agent was started by the other), so runpane can't tell which one is handing off. Run the handoff from that agent's own tab.` };
+    }
+    if (chosen) {
+        const sender = { ...chosen, live: true };
+        if (recorded?.agentType === chosen.agent && recorded.resumeId && recorded.resumeId !== chosen.id) {
+            sender.note = `Pane had recorded ${recorded.resumeId} for this tab; ${chosen.agent} itself reports ${chosen.id}, which is the one carried.`;
+        }
+        return { sender };
+    }
+    const agent = recorded?.agentType;
+    if (!(0, nativeSession_1.isNativeAgent)(agent) || !recorded?.resumeId)
+        return { fresh: 'This tab runs no Claude, Codex, Cursor or OpenCode session that Pane has an id for.' };
+    return { sender: { agent, id: recorded.resumeId } };
+}
+/**
+ * The sender's session when the receiver can continue it: the agent's own live record, or the id
+ * Pane recorded for this tab; the receiver is the same agent; and the session's files are here.
+ */
+async function planCarry(parsed, destination) {
+    if (parsed.handoffNoteOnly)
+        return { fresh: 'You passed --note-only.' };
+    const paneId = process.env.PANE_SESSION_ID;
+    const panelId = process.env.PANE_PANEL_ID;
+    let recorded;
+    let panels = [];
+    if (paneId && panelId) {
+        try {
+            const listed = await (0, daemonClient_1.invokeDaemon)('runpane:panels:list', [{ paneId }], localControl_1.panelListResultSchema, { paneDir: parsed.paneDir });
+            panels = listed.panels;
+            recorded = listed.panels.find(panel => panel.id === panelId || panel.panelId === panelId);
+        }
+        catch (error) {
+            if (!LIVE_SESSION_ENV.some(([, key]) => process.env[key])) {
+                return { fresh: `Pane could not say which agent session this tab runs (${error instanceof Error ? error.message : String(error)}).` };
+            }
+        }
+    }
+    else if (!LIVE_SESSION_ENV.some(([, key]) => process.env[key])) {
+        return { fresh: 'This terminal is not a Pane tab, so there is no agent session to carry.' };
+    }
+    const identified = senderSession(recorded);
+    if ('fresh' in identified)
+        return identified;
+    const { sender } = identified;
+    if (sender.agent !== destination.agent) {
+        return { fresh: `Your session is ${sender.agent} and the receiver is ${destination.agent}; a session can't move between agents.` };
+    }
+    const session = await (0, nativeSession_1.locateNativeSession)(sender.agent, sender.id, process.cwd());
+    if (!session)
+        return { fresh: `${sender.agent} session ${sender.id} has no files in this machine's ${sender.agent} store.` };
+    const carry = { session };
+    if (sender.note)
+        carry.note = sender.note;
+    if (sender.live) {
+        carry.live = true;
+        // When PANE_PANEL_ID's tab records another session, report back to the tab that records this one.
+        const owner = panels.find(panel => panel.resumeId === sender.id)?.id;
+        if (recorded?.resumeId && recorded.resumeId !== sender.id) {
+            carry.senderPanel = owner ?? null;
+        }
+        else if (!recorded?.resumeId && !owner && panels.filter(panel => panel.agentType === sender.agent && !panel.resumeId).length > 1) {
+            // No tab records this session yet (Pane learns a Codex id when Codex exits), and several of
+            // this agent's tabs could be the sender: an inherited PANE_PANEL_ID can't be trusted.
+            carry.senderPanel = null;
+        }
+    }
+    const snippet = (0, nativeSession_1.lastMessageSnippet)(session);
+    if (snippet)
+        carry.snippet = snippet;
+    return { carry };
+}
+function describeCarry(carry, fork) {
+    return {
+        carried: true,
+        agent: carry.session.agent,
+        sessionId: carry.session.id,
+        fork,
+        files: carry.session.files.length,
+        bytes: carry.session.files.reduce((total, file) => total + file.bytes, 0),
+        reason: (fork
+            ? `The receiver resumes a fork of your ${carry.session.agent} session ${carry.session.id}: two agents never resume one session on one machine.`
+            : `The receiver resumes your own ${carry.session.agent} session ${carry.session.id}, copied to the destination.`)
+            + (carry.note ? ` ${carry.note}` : ''),
+    };
+}
+/** Machine writes go through one request each; larger files go in parts joined on the destination. */
+const WRITE_CHUNK_BYTES = 8 * 1024 * 1024;
+/**
+ * Where the session's main file already is in the destination's store, as a path under home,
+ * so a session handed back and forth is replaced in place and its id never has two copies.
+ * Two copies there is an error: runpane can't tell which one the agent resumes.
+ */
+async function existingCopy(destination, session) {
+    const name = node_path_1.default.posix.basename(session.files[0].home);
+    const store = session.files[0].home.split('/').slice(0, 2).join('/');
+    const result = destination.os === 'Windows'
+        ? await destination.run(['powershell', '-NoProfile', '-Command',
+            `Get-ChildItem -Recurse -File -Path '${store}' -Filter '${name}' -ErrorAction SilentlyContinue | ForEach-Object { $_.FullName }`], 60_000)
+        : await destination.run(['find', store, '-name', name, '-type', 'f'], 60_000);
+    const found = result.stdout.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    if (found.length > 1) {
+        throw new Error(`${destination.name} has ${found.length} copies of ${session.agent} session ${session.id} (${found.join(', ')}), so runpane can't tell which one ${session.agent} resumes there. Nothing was copied. Remove the stale copy on ${destination.name}, then run the handoff again`);
+    }
+    if (found.length === 0)
+        return undefined;
+    const normalized = found[0].replace(/\\/g, '/').replace(/^\.\//, '');
+    if (normalized.startsWith(`${store}/`))
+        return normalized;
+    const index = normalized.indexOf(`/${store}/`);
+    return index >= 0 ? normalized.slice(index + 1) : undefined;
+}
+function quoted(value, windows) {
+    // PowerShell also ends a single-quoted string at a typographic single quote.
+    return windows ? `'${value.replace(/['‘’‚‛]/g, '$&$&')}'` : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Size and sha256 of each file on the destination (paths under home), by index; missing files are left out. */
+async function destinationDigests(destination, files) {
+    const windows = destination.os === 'Windows';
+    const list = files.map(file => quoted(file, windows));
+    // No double quotes in the PowerShell: Windows PowerShell mangles them in a nested -Command.
+    const script = windows
+        // .NET's SHA256, not Get-FileHash: a Windows PowerShell started from pwsh can fail to load the module that defines it.
+        ? `$i=0; $sha=[Security.Cryptography.SHA256]::Create(); foreach ($p in @(${list.join(',')})) { if (Test-Path -LiteralPath $p -PathType Leaf) { $b=[IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $p).ProviderPath); ($i, $b.Length, ([BitConverter]::ToString($sha.ComputeHash($b)) -replace '-','').ToLower()) -join ' ' }; $i++ }`
+        : `i=0; for p in ${list.join(' ')}; do if [ -f "$p" ]; then printf '%s %s %s\\n' "$i" "$(wc -c < "$p" | tr -d ' ')" "$( (sha256sum "$p" 2>/dev/null || shasum -a 256 "$p") | cut -d ' ' -f 1)"; fi; i=$((i+1)); done`;
+    const output = await mustRun(destination, windows ? ['powershell', '-NoProfile', '-Command', script] : ['sh', '-c', script], 'Reading the session files there', 300_000);
+    const digests = new Map();
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^(\d+) (\d+) ([0-9a-f]{64})$/.exec(line.trim());
+        if (match)
+            digests.set(Number(match[1]), { bytes: Number(match[2]), sha256: match[3] });
+    }
+    return digests;
+}
+/**
+ * Copies the session's files into the destination agent's store; returns the main file's path
+ * there. A copy already there (from an earlier handoff) is replaced only when this machine's copy
+ * holds everything it does and no agent there is running it: history continued on the destination
+ * is never overwritten. Every file is written beside its target and checked before any is swapped
+ * in, and a failed swap puts the previous copy back. An OpenCode session goes in as its export,
+ * imported into OpenCode's database from inside `repoPath`, so OpenCode files it under that repository.
+ */
+async function placeSession(destination, session, repoPath) {
+    if (session.exported)
+        return importOpenCodeSession(destination, session, repoPath);
+    const windows = destination.os === 'Windows';
+    const existing = await existingCopy(destination, session);
+    const mainDir = node_path_1.default.posix.dirname(session.files[0].home);
+    const targetDir = existing ? node_path_1.default.posix.dirname(existing) : mainDir;
+    const tag = `handoff-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+    const placements = session.files.map(file => {
+        const target = targetDir + file.home.slice(mainDir.length);
+        return { bytes: node_fs_1.default.readFileSync(file.absolute), target, staged: `${target}.${tag}`, previous: `${target}.${tag}.previous` };
+    });
+    if (existing) {
+        const there = await destinationDigests(destination, placements.map(placement => placement.target));
+        const diverged = placements.filter((placement, index) => {
+            const digest = there.get(index);
+            return digest !== undefined && (digest.bytes > placement.bytes.length || (0, nativeSession_1.sha256)(placement.bytes.subarray(0, digest.bytes)) !== digest.sha256);
+        });
+        if (diverged.length) {
+            throw new Error(`${destination.name}'s copy of ${session.agent} session ${session.id} has history this machine's copy doesn't (${diverged.map(placement => placement.target).join(', ')}): it was continued there after an earlier handoff. Nothing was copied, so that history is kept. Continue it on ${destination.name}, or hand it off from there back to here`);
+        }
+        await refuseRunningReceivers(destination, session, 'copied');
+    }
+    const written = [];
+    let mainPath = '';
+    try {
+        for (const placement of placements) {
+            let staged;
+            if (placement.bytes.length <= WRITE_CHUNK_BYTES) {
+                staged = await destination.write(`~/${placement.staged}`, placement.bytes.toString('base64'), 'base64');
+                written.push(staged);
+            }
+            else {
+                const parts = [];
+                for (let offset = 0, index = 0; offset < placement.bytes.length; offset += WRITE_CHUNK_BYTES, index += 1) {
+                    const part = await destination.write(`~/${placement.staged}.part${index}`, placement.bytes.subarray(offset, offset + WRITE_CHUNK_BYTES).toString('base64'), 'base64');
+                    parts.push(part);
+                    written.push(part);
+                }
+                staged = parts[0].replace(/\.part0$/, '');
+                written.push(staged);
+                const list = parts.map(part => quoted(part, windows));
+                const join = windows
+                    ? ['powershell', '-NoProfile', '-Command', `$out = [IO.File]::Create(${quoted(staged, true)}); foreach ($p in @(${list.join(',')})) { $b = [IO.File]::ReadAllBytes($p); $out.Write($b, 0, $b.Length) }; $out.Close(); Remove-Item ${list.join(',')}`]
+                    : ['sh', '-c', `cat ${list.join(' ')} > ${quoted(staged, false)} && rm ${list.join(' ')}`];
+                await mustRun(destination, join, `Joining ${node_path_1.default.posix.basename(placement.target)}`, 300_000);
+            }
+            if (placement === placements[0])
+                mainPath = staged.slice(0, -(tag.length + 1));
+        }
+        const staged = await destinationDigests(destination, placements.map(placement => placement.staged));
+        const damaged = placements.filter((placement, index) => staged.get(index)?.sha256 !== (0, nativeSession_1.sha256)(placement.bytes));
+        if (damaged.length)
+            throw new Error(`The copies of ${damaged.map(placement => node_path_1.default.posix.basename(placement.target)).join(', ')} written to ${destination.name} don't match this machine's`);
+    }
+    catch (error) {
+        const list = written.map(file => quoted(file, windows));
+        if (list.length) {
+            await destination.run(windows
+                ? ['powershell', '-NoProfile', '-Command', `Remove-Item -Force -ErrorAction SilentlyContinue -LiteralPath ${list.join(',')}`]
+                : ['sh', '-c', `rm -f ${list.join(' ')}`]).catch(() => undefined);
+        }
+        throw new Error(`${error instanceof Error ? error.message : String(error)}. Nothing in ${destination.name}'s ${session.agent} store was changed`, { cause: error });
+    }
+    await mustRun(destination, swapScript(placements, windows), 'Putting the session files in place (any previous copy was put back)', 300_000);
+    return mainPath;
+}
+/**
+ * Moves each staged file over its target in one script, keeping the target's previous copy until
+ * all are in place. If any move fails, every target gets its previous copy back (or is removed if
+ * it had none) and the staged files are deleted, so the store holds the old session or the new one.
+ */
+function swapScript(placements, windows) {
+    const q = (value) => quoted(value, windows);
+    if (windows) {
+        const list = placements.map(placement => `$p += ,@(${q(placement.staged)}, ${q(placement.target)}, ${q(placement.previous)})`).join('; ');
+        return ['powershell', '-NoProfile', '-Command', [
+                `$ErrorActionPreference = 'Stop'; $p = @(); ${list}`,
+                'function Undo { foreach ($x in $p) { if (Test-Path -LiteralPath $x[2]) { Move-Item -Force -LiteralPath $x[2] -Destination $x[1] } elseif (-not (Test-Path -LiteralPath $x[0])) { Remove-Item -Force -ErrorAction SilentlyContinue -LiteralPath $x[1] }; Remove-Item -Force -ErrorAction SilentlyContinue -LiteralPath $x[0] } }',
+                'try { foreach ($x in $p) { if (Test-Path -LiteralPath $x[1]) { Move-Item -LiteralPath $x[1] -Destination $x[2] }; Move-Item -LiteralPath $x[0] -Destination $x[1] } } catch { Undo; throw }',
+                'foreach ($x in $p) { Remove-Item -Force -ErrorAction SilentlyContinue -LiteralPath $x[2] }',
+                // -Command exits 1 when its last statement failed, even silently (no previous copy to remove).
+                'exit 0',
+            ].join('; ')];
+    }
+    const undo = placements.map(({ staged, target, previous }) => `if [ -e ${q(previous)} ]; then mv -f ${q(previous)} ${q(target)}; elif [ ! -e ${q(staged)} ]; then rm -f ${q(target)}; fi; rm -f ${q(staged)}`).join('; ');
+    const moves = placements.map(({ staged, target, previous }) => `if [ -e ${q(target)} ]; then mv -f ${q(target)} ${q(previous)} || { undo; exit 1; }; fi; mv -f ${q(staged)} ${q(target)} || { undo; exit 1; }`);
+    return ['sh', '-c', [`undo() { ${undo}; }`, ...moves, `rm -f ${placements.map(placement => q(placement.previous)).join(' ')}`].join('\n')];
+}
+/** Panels on the destination running this session, as "Pane <id> tab <id>". */
+async function runningReceivers(destination, session) {
+    // Panes list only Panes; a Session's agent tab lives in its hidden owner, so Sessions are listed too.
+    const { panes } = await destination.invoke('runpane:panes:list', [{}], localControl_1.paneListResultSchema);
+    const { sessions } = await destination.invoke('runpane:sessions:list', [], localControl_1.runpaneSessionListResultSchema);
+    const owners = [
+        ...panes.map(pane => ({ id: pane.id, label: `Pane ${pane.id}` })),
+        ...sessions.map(record => ({ id: record.internalSessionId, label: `Session "${record.name}"` })),
+    ];
+    const running = [];
+    for (const owner of owners) {
+        const { panels } = await destination.invoke('runpane:panels:list', [{ paneId: owner.id }], localControl_1.panelListResultSchema);
+        for (const panel of panels) {
+            if (panel.running && panel.resumeId === session.id && panel.agentType === session.agent)
+                running.push(`${owner.label} tab ${panel.id}`);
+        }
+    }
+    return running;
+}
+/** Stops the copy when an agent on the destination is running this session. */
+async function refuseRunningReceivers(destination, session, what) {
+    const running = await runningReceivers(destination, session);
+    if (running.length) {
+        throw new Error(`${session.agent} session ${session.id} is open on ${destination.name} (${running.join(', ')}), and replacing it under a running agent would mix two conversations. Nothing was ${what}. Close it there first, then run the handoff again`);
+    }
+}
+/** How `opencode export` says the session isn't in its database. */
+const OPENCODE_NO_SESSION = /not\s*found|NotFoundError|no such session|does not exist/i;
+/**
+ * An OpenCode session goes in with `opencode import`. A session already there is replaced only
+ * when this export holds every message it does and no agent there is running it; an export that
+ * fails for any reason but a missing session stops the import.
+ */
+async function importOpenCodeSession(destination, session, repoPath) {
+    const windows = destination.os === 'Windows';
+    const inRepo = (command) => windows
+        ? ['powershell', '-NoProfile', '-Command', `Set-Location -LiteralPath ${quoted(repoPath, true)}; ${command}`]
+        : ['sh', '-c', `cd ${quoted(repoPath, false)} && ${command}`];
+    const exported = node_fs_1.default.readFileSync(session.files[0].absolute, 'utf8');
+    const there = await destination.run(inRepo(`opencode export ${quoted(session.id, windows)}`), 120_000);
+    if (there.exitCode !== 0) {
+        // Only "no such session" means there is no history to keep; anything else (a locked database,
+        // a broken install) means runpane can't tell, so it stops instead of importing over it.
+        const detail = (there.stderr || there.stdout).trim().split('\n').slice(-3).join(' ');
+        if (!OPENCODE_NO_SESSION.test(detail)) {
+            throw new Error(`Couldn't read ${destination.name}'s OpenCode session ${session.id} to check for history this machine's copy lacks (${detail || `exit ${there.exitCode}`}). Nothing was imported. Fix that there, then run the handoff again`);
+        }
+    }
+    else {
+        await refuseRunningReceivers(destination, session, 'imported');
+    }
+    const missing = there.exitCode === 0 ? (0, nativeSession_1.openCodeMessagesMissing)(exported, there.stdout) : 0;
+    if (missing) {
+        throw new Error(`${destination.name}'s copy of OpenCode session ${session.id} has ${missing} message${missing === 1 ? '' : 's'} this machine's copy doesn't: it was continued there after an earlier handoff. Nothing was imported, so that history is kept. Continue it on ${destination.name}, or hand it off from there back to here`);
+    }
+    const written = await destination.write(`~/${session.files[0].home}`, Buffer.from(exported).toString('base64'), 'base64');
+    await mustRun(destination, inRepo(`opencode import ${quoted(written, windows)}`), `opencode import of session ${session.id}`, 300_000);
+    return `OpenCode's store, from ${written}`;
+}
+/** How long a receiver resuming a carried session has to reach its input box, unless --ready-timeout-ms says otherwise. */
+const CARRIED_READY_TIMEOUT_MS = 120_000;
+const PROBE = 'What were you last working on? Answer in one or two sentences.';
+/** Checks 1 to 4 of the continuity check on the receiver, then says what was found. */
+async function checkReceiver(options) {
+    const { destination, carry, resumedId, paneId, panelId, ready, blocked, original } = options;
+    const listed = await destination.invoke('runpane:panels:list', [{ paneId }], localControl_1.panelListResultSchema);
+    const panel = listed.panels.find(candidate => candidate.id === panelId || candidate.panelId === panelId);
+    const restartResumes = panel?.resumeId === resumedId;
+    const resumedById = restartResumes && (panel?.resumeSource ?? 'agent') === 'agent';
+    let historyLoaded = null;
+    if (ready && carry.snippet) {
+        const screen = await destination.invoke('runpane:panels:screen', [{ panelId, limit: 400 }], localControl_1.panelScreenResultSchema);
+        historyLoaded = (0, nativeSession_1.screenShows)(screen.text, carry.snippet);
+    }
+    const checks = { resumedById, restartResumes, historyLoaded };
+    const { changed, appended } = original ? await (0, nativeSession_1.originalChanges)(original, { appendOnly: carry.live }) : { changed: [], appended: [] };
+    if (original)
+        checks.originalUntouched = changed.length === 0;
+    if (appended.length)
+        checks.originalAppended = true;
+    if (!resumedById || !restartResumes) {
+        return { checks, result: 'not-continued', why: `Pane recorded ${panel?.resumeId ?? 'no id'} for the receiver, not ${resumedId}, so it is not resuming that session.` };
+    }
+    if (checks.originalUntouched === false) {
+        return { checks, result: 'not-continued', why: `Your session changed while it was forked (${changed.join(', ')}).` };
+    }
+    const then = `then check it shows your last work, and ask it "${PROBE}" if that is unclear.`;
+    if (!ready && blocked) {
+        // The agent resumed the session but stopped on its own notice or dialog; history can be checked once it's answered.
+        const prompt = blocked.message.split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' / ');
+        const command = blocked.suggestedCommand ? options.route(blocked.suggestedCommand) : undefined;
+        const answers = command !== undefined && /\bpanels (?:input|submit)\b/.test(command);
+        return {
+            checks,
+            result: 'inconclusive',
+            why: `The receiver resumed the session but is waiting on its agent's own prompt: ${prompt}`,
+            next: answers
+                ? `Answer it with ${command} (or by hand), ${then}`
+                : `Look at the prompt with ${command ?? options.inspect}, answer it in the receiver, ${then}`,
+        };
+    }
+    if (!ready) {
+        // Pane recorded the resumed id (checks 1 and 2), so the agent is resuming it; it is just slow to start.
+        return {
+            checks,
+            result: 'inconclusive',
+            why: 'The receiver is resuming the session but had not reached its input box when runpane stopped waiting, so its history was not checked.',
+            next: `Look at it with ${options.inspect} until it is ready, ${then}`,
+        };
+    }
+    if (historyLoaded === true)
+        return { checks, result: 'continued', why: `The receiver shows the session's last message ("${carry.snippet}").` };
+    return {
+        checks,
+        result: 'inconclusive',
+        why: carry.snippet
+            ? `The receiver is ready but its screen does not show the session's last message ("${carry.snippet}"); it may be scrolled or compacted.`
+            : 'The receiver is ready, but this session\'s store is not text runpane can read, so its last message could not be compared.',
+    };
+}
+/** What `runpane:doctor` says about the daemon's features; older Panes have none. */
+const doctorFeaturesSchema = boundaryDecoder_1.boundary.object({
+    app: boundaryDecoder_1.boundary.object({ version: boundaryDecoder_1.boundary.string }),
+    daemon: boundaryDecoder_1.boundary.object({ features: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.array(boundaryDecoder_1.boundary.string)) }),
+});
+/**
+ * The daemon feature (Pane's RUNPANE_DAEMON_FEATURES) that says panes, panels and sessions create
+ * honour `resume`. An older Pane drops the field it doesn't know and starts a fresh conversation,
+ * so a carried session must not be sent to it.
+ */
+const RESUME_ON_CREATE = 'resume-on-create';
+async function assertResumesOnCreate(invoke, where) {
+    const doctor = await invoke('runpane:doctor', [], doctorFeaturesSchema);
+    if (doctor.daemon.features?.includes(RESUME_ON_CREATE))
+        return;
+    throw new errors_1.RunpaneError('ERR_HANDOFF_RESUME_UNSUPPORTED', `Pane ${doctor.app.version} on ${where} can't resume a carried session: it would start a fresh conversation and report it as yours. Nothing was committed, copied or created.`, `Update Pane on ${where} (runpane install client), then run the handoff again. Or ask the person before handing off with only the note: add --note-only.`);
+}
 async function runHandoff(parsed) {
     const cwd = process.cwd();
     const tailnet = await (0, workspace_1.readTailnet)();
     const self = tailnet.ok ? tailnet.self.name : (process.env.HOSTNAME ?? 'this-machine');
+    // Which tab the receiver reports back to; planCarry may correct PANE_PANEL_ID.
+    let senderPanel;
     const origin = (state) => ({
         originMachine: self,
         originPane: process.env.PANE_SESSION_ID,
-        originPanel: process.env.PANE_PANEL_ID,
+        originPanel: senderPanel === undefined ? process.env.PANE_PANEL_ID : senderPanel ?? undefined,
         originSession: process.env.PANE_ORCHESTRATION_SESSION_ID,
         repository: state?.repository,
         branch: state?.branch,
@@ -397,6 +787,12 @@ async function runHandoff(parsed) {
     });
     if (destination.wsl)
         throw new Error('Handoff to a WSL receiver is not supported yet. Choose a native destination without wsl; nothing was committed or sent.');
+    // OpenCode receives a handoff only to continue an OpenCode session; a fresh OpenCode agent
+    // with only the note is not supported. Decide that before touching git or the destination.
+    const openCodePlan = destination.agent === 'opencode' ? await planCarry(parsed, destination) : undefined;
+    if (openCodePlan && 'fresh' in openCodePlan) {
+        throw new errors_1.RunpaneError('ERR_HANDOFF_OPENCODE_FRESH', `OpenCode receives a handoff only to continue your own OpenCode session, and this one can't be carried: ${openCodePlan.fresh} Nothing was committed or sent.`, 'Run handoff from the OpenCode tab whose session should continue, or choose claude, codex or cursor for a fresh agent with the note.');
+    }
     if (destination.machine && !tailnet.ok)
         throw new Error(`Handing off to another machine needs Tailscale: ${tailnet.reason}. ${tailnet.fix}`);
     const machineLabel = destination.machine ?? `${self} (this machine)`;
@@ -465,6 +861,27 @@ async function runHandoff(parsed) {
     if (!state.pushed)
         warnings.push(`${state.branch} at ${state.head.slice(0, 7)} is not on ${state.remote}. Push it, or pass --push.`);
     say(step('git', `${state.branch} @ ${state.head.slice(0, 7)}, ${state.pushed ? `pushed to ${state.remote}` : 'NOT pushed'}${state.dirty.length ? `, ${state.dirty.length} uncommitted` : ''}`, state.pushed && !state.dirty.length));
+    // A same-agent handoff carries the sender's own session; anything else is a fresh agent with the note.
+    const plan = openCodePlan ?? await planCarry(parsed, destination);
+    const carry = 'carry' in plan ? plan.carry : undefined;
+    if (carry?.senderPanel !== undefined) {
+        senderPanel = carry.senderPanel;
+        if (senderPanel === null)
+            warnings.push(`No tab in this Pane records ${carry.session.agent} session ${carry.session.id}, and this terminal's PANE_PANEL_ID may name another tab (it can be inherited from another tab's agent), so the receiver reports back on the branch instead of to a panel.`);
+    }
+    const continuity = carry ? describeCarry(carry, !target) : { carried: false, reason: 'fresh' in plan ? plan.fresh : '' };
+    const noteOnlyCommand = `runpane handoff ${quote(text || describeDestination(destination, machineLabel), senderShell)} --note-file ${quote(parsed.handoffNoteFile ?? '<note>', senderShell)} --note-only`;
+    // A second Cursor agent here would change the original chat (CURSOR_NO_FORK), so it is never
+    // started; the note route is the person's call, not a silent fallback.
+    const cursorHere = carry?.session.agent === 'cursor' && !target;
+    if (cursorHere) {
+        continuity.carried = false;
+        continuity.reason = `${nativeSession_1.CURSOR_NO_FORK}. Nothing was copied and no receiver was started.`;
+        continuity.next = `Ask the person before starting a fresh Cursor agent with the note instead: ${noteOnlyCommand}`;
+    }
+    say(carry && !cursorHere
+        ? step('session', continuity.reason)
+        : step('session', cursorHere ? continuity.reason : `A fresh ${destination.agent} with your note, not the same session. ${continuity.reason}`, false));
     const result = {
         ok: true,
         dryRun: parsed.dryRun,
@@ -473,17 +890,32 @@ async function runHandoff(parsed) {
         note: noteInfo,
         git: { repository: state.repository, branch: state.branch, head: state.head, remote: state.remote, pushed: state.pushed, dirty: state.dirty.length },
         warnings,
+        continuity,
     };
     if (parsed.dryRun) {
         for (const warning of warnings)
             say(`  ! ${warning}`);
+        if (cursorHere)
+            say(`Next: ${continuity.next}`);
         say('Dry run: nothing was sent.');
         if (parsed.json)
             console.log(JSON.stringify(result, null, 2));
         return 0;
     }
+    if (cursorHere) {
+        continuity.result = 'not-continued';
+        result.ok = false;
+        say(`Next: ${continuity.next}`);
+        if (parsed.json)
+            console.log(JSON.stringify(result, null, 2));
+        return 1;
+    }
+    if (!carry)
+        continuity.result = 'fresh-agent';
     if (!state.pushed)
         throw new Error(`${warnings.join(' ')}\nThe receiver would start without your work, so nothing was sent.`);
+    if (carry)
+        await assertResumesOnCreate(remote.invoke, remote.name);
     for (const warning of warnings)
         say(`  ! ${warning}`);
     await mustRun(remote, ['git', '-C', repo.path, 'fetch', repoRemote, state.branch], 'git fetch', 120_000);
@@ -493,9 +925,42 @@ async function runHandoff(parsed) {
     const noteOrigin = origin(state);
     const stamped = stampNote(noteText ?? '', noteOrigin, receiverInstructions(noteOrigin, state, repoRemote, 'runpane'));
     const notePath = await remote.write(`~/.pane/handoffs/${stamp}-${name}-${(0, node_crypto_1.randomUUID)()}.md`, stamped);
+    result.notePath = notePath;
     say(step('note sent', notePath));
+    // Same machine: the receiver resumes a fork, so two agents never share one session file.
+    // Another machine: the session is copied into that machine's store and resumed by its own id.
+    let original;
+    if (carry) {
+        try {
+            if (target) {
+                const placed = await placeSession(remote, carry.session, repo.path);
+                continuity.resumedId = carry.session.id;
+                say(step('copied', `${continuity.files} file${continuity.files === 1 ? '' : 's'} of ${carry.session.agent} session ${carry.session.id} to ${placed}`));
+            }
+            else {
+                original = await (0, nativeSession_1.snapshotOriginal)(carry.session, state.root);
+                continuity.resumedId = await (0, nativeSession_1.forkNativeSession)(carry.session, state.root);
+                say(step('forked', `${carry.session.agent} session ${carry.session.id} as ${continuity.resumedId}`));
+            }
+        }
+        catch (error) {
+            continuity.result = 'not-continued';
+            continuity.reason = `Could not ${target ? 'copy' : 'fork'} your ${carry.session.agent} session ${carry.session.id}: ${error instanceof Error ? error.message : String(error)}. No receiver was started.`;
+            continuity.next = `Fix that and run the handoff again, or ask the person before starting a fresh agent with the note instead: ${noteOnlyCommand}`;
+            result.ok = false;
+            say(step('session', continuity.reason, false));
+            say(`Next: ${continuity.next}`);
+            if (parsed.json)
+                console.log(JSON.stringify(result, null, 2));
+            return 1;
+        }
+    }
+    const resumedId = continuity.resumedId;
     const toolCommand = agentCommand(destination, remote.shell);
-    const prompt = `Read the handoff note at ${notePath} and continue the work it describes. Start with its "Receiver instructions" section.`;
+    // Resuming a long session is slower than starting fresh (Codex on another machine took over 30 s in QA).
+    const readyTimeoutMs = parsed.readyTimeoutMs ?? (resumedId ? CARRIED_READY_TIMEOUT_MS : undefined);
+    // A resumed session already knows its work; it gets the note with the "moved" message after the check.
+    const prompt = resumedId ? undefined : `Read the handoff note at ${notePath} and continue the work it describes. Start with its "Receiver instructions" section.`;
     // 1 feature = 1 worktree = 1 branch = 1 Pane: on this machine, from inside the
     // Pane that owns this checkout, the receiver opens as a new tab in that Pane.
     // Otherwise (another machine, or a checkout the sender's Pane does not own) it
@@ -516,15 +981,17 @@ async function runHandoff(parsed) {
     let receiver;
     if (senderPane) {
         const panelRequest = await (0, localControl_1.buildPanelCreateRequest)({
-            ...parsed, paneId: senderPane, agent: destination.agent, toolCommand, initialInput: prompt,
+            ...parsed, readyTimeoutMs, paneId: senderPane, agent: destination.agent, toolCommand, initialInput: prompt,
             source: 'agent', noFocus: true, focus: false, waitReady: true, yes: true,
         });
+        if (resumedId)
+            panelRequest.resume = resumedId;
         try {
             const panel = await (0, daemonClient_1.invokeDaemon)('runpane:panels:create', [panelRequest], localControl_1.panelCreateResultSchema, {
                 paneDir: parsed.paneDir,
-                timeoutMs: (parsed.readyTimeoutMs ?? 30_000) + 10_000,
+                timeoutMs: (readyTimeoutMs ?? 30_000) + 10_000,
             });
-            receiver = { ok: panel.ok, paneId: senderPane, panelId: panel.panelId, name: panel.title, initialInput: panel.initialInput, newTab: true };
+            receiver = { ok: panel.ok, paneId: senderPane, panelId: panel.panelId, name: panel.title, initialInput: panel.initialInput, ready: panel.readiness?.ok === true, blocked: panel.readiness?.blocked, newTab: true };
         }
         catch (error) {
             throw new Error(`runpane panels create failed in Pane ${senderPane}: ${error instanceof Error ? error.message : String(error)}. The note was sent to ${notePath}.`);
@@ -532,10 +999,12 @@ async function runHandoff(parsed) {
     }
     else {
         const request = await (0, localControl_1.buildPaneCreateRequest)({
-            ...parsed, repo: String(repo.id), name, baseBranch: state.head, agent: destination.agent,
+            ...parsed, readyTimeoutMs, repo: String(repo.id), name, baseBranch: state.head, agent: destination.agent,
             toolCommand, initialInput: prompt, source: 'agent', noFocus: true, focus: false,
             waitReady: true, yes: true, noAssociate: true, fromJson: undefined,
         });
+        if (resumedId)
+            request.panes = request.panes.map(item => ({ ...item, resume: resumedId }));
         let created;
         try {
             // Workspace control carries JSON directly to the reached daemon, without
@@ -547,25 +1016,46 @@ async function runHandoff(parsed) {
         }
         const item = created.items[0];
         if (item?.ok && item.sessionId && item.setupQueue) {
-            // The receiver's prompt rides on the launch after setup, so delivery is not verified yet.
-            result.ok = false;
-            result.notePath = notePath;
             result.pane = { id: item.sessionId, name: item.name, worktreePath: item.worktreePath };
-            warnings.push(`Pane ${item.sessionId} was created and is queued for setup (${item.setupQueue.message}). The receiver starts after setup with the note; its prompt is not verified yet, so do not retry. Check on it after setup: ${receiverStatus(item.sessionId)}`);
+            warnings.push(`Pane ${item.sessionId} was created and is queued for setup (${item.setupQueue.message}). The receiver starts after setup${resumedId ? ', resuming the session' : ' with the note'}; ${resumedId ? 'it is not checked' : 'its prompt is not verified'} yet, so do not retry. Check on it after setup: ${receiverStatus(item.sessionId)}`);
             for (const warning of warnings)
                 say(`  ! ${warning}`);
+            if (resumedId) {
+                // The carry itself succeeded; only the check waits for setup, which is what inconclusive (exit 0) means.
+                continuity.result = 'inconclusive';
+                continuity.reason = `Pane ${item.sessionId} is queued for setup; its agent resumes ${resumedId} after setup, so the continuity check has not run.`;
+                continuity.next = `After setup, check the receiver with ${receiverStatus(item.sessionId)} and, if its history is unclear, ask it: "${PROBE}". Then send it: ${receiverMessage(remote.name, item.worktreePath, notePath, true)}`;
+                say(step('queued', continuity.reason, false));
+                say(`Next: ${continuity.next}`);
+                say(`Your session continues there after setup. End your turn now and make no more changes on ${state.branch}.`);
+                if (parsed.json)
+                    console.log(JSON.stringify(result, null, 2));
+                return 0;
+            }
+            // The receiver's prompt rides on the launch after setup, so delivery is not verified yet.
+            result.ok = false;
             if (parsed.json)
                 console.log(JSON.stringify(result, null, 2));
             return 1;
         }
-        if (!item?.ok || !item.sessionId || !item.panelId)
+        if (!item?.ok && !(resumedId && item?.sessionId && item.panelId)) {
             throw new Error(`Pane on ${remote.name} did not start the agent: ${item && 'error' in item ? item.error.message : 'no pane was created'}. The note was sent to ${notePath}.${item?.sessionId ? ` Pane ${item.sessionId}. Check ${receiverStatus(item.sessionId, item.panelId)} before retrying.${item.panelId && !target ? ` Inspect panel ${item.panelId}: ${recovery('panels', 'screen', '--panel', item.panelId)}.` : ''}` : ` Check ${recovery('sessions', 'list')} before retrying.`}`);
-        receiver = { ok: created.ok, paneId: item.sessionId, panelId: item.panelId, name: item.name, worktreePath: item.worktreePath, initialInput: item.initialInput, newTab: false };
+        }
+        if (!item.sessionId || !item.panelId)
+            throw new Error(`Pane on ${remote.name} reported no panel for the receiver. The note was sent to ${notePath}. Check ${recovery('sessions', 'list')} before retrying.`);
+        const started = 'error' in item ? undefined : item;
+        receiver = { ok: created.ok, paneId: item.sessionId, panelId: item.panelId, name: item.name, worktreePath: item.worktreePath, initialInput: started?.initialInput, ready: started?.readiness?.ok === true, blocked: started?.readiness?.blocked, newTab: false };
     }
-    result.notePath = notePath;
     result.pane = { id: receiver.paneId, panelId: receiver.panelId, name: receiver.name, worktreePath: receiver.worktreePath };
     result.reportBack = noteOrigin.originPanel ? `${self} panel ${noteOrigin.originPanel}` : undefined;
     const inspect = recovery('panels', 'screen', '--panel', receiver.panelId);
+    const check = receiverStatus(receiver.paneId, receiver.panelId);
+    if (carry && resumedId) {
+        return reportCarried({ parsed, result, continuity, carry, resumedId, receiver, destination: remote, original, say,
+            target: Boolean(target), notePath, noteOnlyCommand, inspect, check, branch: state.branch,
+            submit: (panelId) => recovery('panels', 'submit', '--panel', panelId, '--text', '<message>', '--yes'),
+            route: (command) => command.replace(/^runpane\s+/, `${recovery()} `) });
+    }
     const input = receiver.initialInput;
     const verified = input?.verifiedSubmitted === true
         && (input.delivery?.state === 'taken' || input.delivery?.state === 'queued')
@@ -580,13 +1070,69 @@ async function runHandoff(parsed) {
         return 1;
     }
     say(step('started', receiver.newTab ? `${receiver.name ?? name} as a new tab in Pane ${receiver.paneId}` : `${receiver.name ?? name} on ${remote.name}${receiver.worktreePath ? ` (${receiver.worktreePath})` : ''}`));
-    const check = receiverStatus(receiver.paneId, receiver.panelId);
+    say(`It is a fresh ${destination.agent} with your note, not the same session.`);
     say(result.reportBack ? `The receiver reports back to ${result.reportBack}.` : 'No sender panel to report to; the receiver reports on the branch.');
     say(`Check on it: ${check}`);
     if (parsed.json)
         console.log(JSON.stringify(result, null, 2));
     return 0;
 }
+/**
+ * The first message a receiver that resumed the sender's session gets, after the check: where it
+ * now runs when the folder or machine changed, and where the sender's note is.
+ */
+function receiverMessage(machine, movedTo, notePath, moved) {
+    return `${moved ? `This session moved to ${movedTo ?? 'a new worktree'} on ${machine}.` : 'This session was handed off to this tab.'} Continue from where you were. The sender's handoff note is at ${notePath}; follow its "Receiver instructions" to report back.`;
+}
+/**
+ * Runs the continuity check on a receiver that resumed the sender's session, sends the "moved"
+ * message when it passed and the folder or machine changed, and reports. A receiver that fails
+ * is kept and never replaced: the next step names the note route for the person to choose.
+ */
+async function reportCarried(report) {
+    const { parsed, result, continuity, carry, resumedId, receiver, destination, original, target, say } = report;
+    const checked = await checkReceiver({ destination, carry, resumedId, paneId: receiver.paneId, panelId: receiver.panelId, ready: receiver.ready, blocked: receiver.blocked, original, inspect: report.inspect, route: report.route });
+    continuity.checks = checked.checks;
+    continuity.result = checked.result;
+    continuity.reason = carry.note ? `${checked.why} ${carry.note}` : checked.why;
+    const where = receiver.newTab ? `a new tab in Pane ${receiver.paneId}` : `Pane ${receiver.paneId} on ${destination.name}${receiver.worktreePath ? ` (${receiver.worktreePath})` : ''}`;
+    const moved = target || !receiver.newTab;
+    // The receiver started without a prompt, so it learns of the handoff (and its note) only from this.
+    const message = receiverMessage(destination.name, moved ? receiver.worktreePath ?? 'a new worktree' : undefined, report.notePath, moved);
+    if (checked.result === 'continued') {
+        const manual = `Send it yourself: ${report.submit(receiver.panelId)} with: ${message}`;
+        try {
+            const sent = await destination.invoke('runpane:panels:submit', [{ panelId: receiver.panelId, input: message, source: 'agent' }], localControl_1.panelSubmitResultSchema);
+            if (!sent.ok)
+                result.warnings.push(`The message telling the receiver to continue was not delivered to panel ${receiver.panelId}. ${manual}`);
+        }
+        catch (error) {
+            // The check passed and the receiver is kept; only this message's delivery is unknown.
+            result.warnings.push(`Sending the receiver its message to continue failed (${error instanceof Error ? error.message : String(error)}), so it may or may not have arrived. Look at the receiver first: ${report.inspect}. If the message isn't there, ${manual.charAt(0).toLowerCase()}${manual.slice(1)}`);
+        }
+        say(step('continued', `${carry.session.agent} session ${resumedId}${continuity.fork ? ` (a fork of ${carry.session.id})` : ''} in ${where}. ${checked.why}`));
+    }
+    else if (checked.result === 'inconclusive') {
+        continuity.next = `${checked.next ?? `Ask the receiver "${PROBE}" with ${report.submit(receiver.panelId)}, and compare its answer with your own last work.`} If it matches, send it this message: "${message}" If not, tell the person it is not continued.`;
+        say(step('unclear', `${where}. ${checked.why}`, false));
+        say(`Next: ${continuity.next}`);
+    }
+    else {
+        result.ok = false;
+        continuity.next = `The receiver is kept in ${where}; inspect it with ${report.inspect}. Ask the person before starting a fresh agent with the note instead: ${report.noteOnlyCommand}`;
+        say(step('not continued', checked.why, false));
+        say(`Next: ${continuity.next}`);
+    }
+    for (const warning of result.warnings)
+        say(`  ! ${warning}`);
+    if (checked.result !== 'not-continued') {
+        say(`Your session now continues in ${where}. End your turn now and make no more changes on ${report.branch}; the person can close this tab.`);
+        say(`Check on it: ${report.check}`);
+    }
+    if (parsed.json)
+        console.log(JSON.stringify(result, null, 2));
+    return checked.result === 'not-continued' ? 1 : 0;
+}
 /**
  * The Session route. From a Session's folder there is no git to move, so the receiver is a new
  * Session on another machine with the sender's name, goal and agent, and the note as its context
@@ -613,7 +1159,15 @@ async function handOffSession({ parsed, sessionId, destination, machines, self,
         receiver: { route: 'session', reason: `A Session's folder has no branch to move, so the receiver is a new Session on ${target.name}.` },
         session: { name, machine: target.name },
     };
+    // A same-agent move carries the Session agent's own conversation; the new Session resumes it when opened.
+    const plan = await planCarry(parsed, destination);
+    const carry = 'carry' in plan ? plan.carry : undefined;
+    const continuity = carry ? describeCarry(carry, false) : { carried: false, reason: 'fresh' in plan ? plan.fresh : '' };
+    result.continuity = continuity;
     say(step('session', `"${source.name}" becomes "${name}" on ${target.name}`));
+    say(carry
+        ? step('session', continuity.reason)
+        : step('session', `A fresh ${destination.agent} with your note, not the same conversation. ${continuity.reason}`, false));
     for (const warning of warnings)
         say(`  ! ${warning}`);
     if (parsed.dryRun) {
@@ -622,13 +1176,36 @@ async function handOffSession({ parsed, sessionId, destination, machines, self,
             console.log(JSON.stringify(result, null, 2));
         return 0;
     }
+    if (carry)
+        await assertResumesOnCreate((channel, args, schema) => (0, daemonClient_1.invokeRemoteDaemon)(remote, channel, args, schema), target.name);
     const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
     const slug = `handoff-${source.name}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 48).replace(/-+$/, '');
-    const stamped = stampNote(noteText ?? '', origin, sessionReceiverInstructions(origin, source.name, target.name));
+    const stamped = stampNote(noteText ?? '', origin, sessionReceiverInstructions(origin, source.name, target.name, carry !== undefined));
     const written = await (0, daemonClient_1.invokeRemoteDaemon)(remote, 'runpane:machine:write', [{ path: `~/.pane/handoffs/${stamp}-${slug}-${(0, node_crypto_1.randomUUID)()}.md`, content: stamped, encoding: 'utf8' }], writeResultSchema);
     const notePath = written.path;
     result.notePath = notePath;
     say(step('note sent', notePath));
+    if (carry) {
+        try {
+            const placed = await placeSession(await remoteDestination(target), carry.session, '~');
+            continuity.resumedId = carry.session.id;
+            say(step('copied', `${carry.session.agent} session ${carry.session.id} to ${placed}`));
+        }
+        catch (error) {
+            continuity.result = 'not-continued';
+            continuity.reason = `Could not copy your ${carry.session.agent} session ${carry.session.id}: ${error instanceof Error ? error.message : String(error)}. No Session was created.`;
+            continuity.next = `Fix that and run the handoff again, or ask the person before moving the Session with only the note: runpane handoff ${quote(parsed.handoffDestination ?? `${destination.agent} on ${target.name}`, 'sh')} --note-file <note> --note-only`;
+            result.ok = false;
+            say(step('session', continuity.reason, false));
+            say(`Next: ${continuity.next}`);
+            if (parsed.json)
+                console.log(JSON.stringify(result, null, 2));
+            return 1;
+        }
+    }
+    else {
+        continuity.result = 'fresh-agent';
+    }
     const launchCommand = agentCommand(destination, 'sh');
     let created;
     try {
@@ -636,9 +1213,12 @@ async function handOffSession({ parsed, sessionId, destination, machines, self,
                 name,
                 agent: destination.agent,
                 goal: source.goal,
-                context: `Handed off from Session "${source.name}" on ${self}, which stays there. The sending agent's handoff note is at ${notePath} on this machine: read it first, including its "Receiver instructions".`,
+                context: carry
+                    ? `Handed off from Session "${source.name}" on ${self}, which stays there. This Session resumes that Session's own ${carry.session.agent} conversation; the sending agent's handoff note is at ${notePath} on this machine.`
+                    : `Handed off from Session "${source.name}" on ${self}, which stays there. The sending agent's handoff note is at ${notePath} on this machine: read it first, including its "Receiver instructions".`,
                 nextAction: `Read the handoff note at ${notePath} and continue from it.`,
                 launchCommand,
+                resume: continuity.resumedId,
             }], localControl_1.runpaneSessionResultSchema, REPORT_TIMEOUT_MS);
     }
     catch (error) {
@@ -647,11 +1227,44 @@ async function handOffSession({ parsed, sessionId, destination, machines, self,
     result.session = { id: created.session.id, name: created.session.name, machine: target.name };
     result.reportBack = origin.originPanel ? `${self} panel ${origin.originPanel}` : undefined;
     say(step('created', `Session "${created.session.name}" on ${target.name}`));
-    say(`It waits for your first message: switch Pane to ${target.name}, open "${created.session.name}", and send "continue".`);
+    if (carry) {
+        // The Session's tab must already record the carried id, or opening it starts a fresh conversation.
+        const recorded = await sessionResumeId(remote, created);
+        if (recorded !== continuity.resumedId) {
+            continuity.result = 'not-continued';
+            continuity.checks = { resumedById: false, restartResumes: false, historyLoaded: null };
+            continuity.reason = `Session "${created.session.name}" on ${target.name} records ${recorded ?? 'no conversation'} for its agent, not ${continuity.resumedId}, so opening it would not continue your conversation.`;
+            continuity.next = `The Session is kept on ${target.name}; look at it before archiving it. Ask the person before moving the Session with only the note instead: runpane handoff ${quote(parsed.handoffDestination ?? `${destination.agent} on ${target.name}`, 'sh')} --note-file <note> --note-only`;
+            result.ok = false;
+            say(step('not continued', continuity.reason, false));
+            say(`Next: ${continuity.next}`);
+            if (parsed.json)
+                console.log(JSON.stringify(result, null, 2));
+            return 1;
+        }
+        continuity.checks = { resumedById: true, restartResumes: true, historyLoaded: null };
+        // A Session's agent launches when the person opens it, so the history check runs then.
+        continuity.result = 'inconclusive';
+        continuity.reason = `"${created.session.name}" resumes ${carry.session.agent} session ${carry.session.id} when it is first opened; its history can only be checked then.`;
+        continuity.next = `Open "${created.session.name}" on ${target.name} and check it shows your last message${carry.snippet ? ` ("${carry.snippet}")` : ''}; if that is unclear, ask it "${PROBE}". Then send it: This session moved to ${target.name}. Continue from where you were. The handoff note is at ${notePath}.`;
+        say(step('resumes', continuity.reason));
+        say(`Next: ${continuity.next}`);
+        say('Your conversation now continues on that machine. End your turn now; the person can archive this Session when they are done with it.');
+    }
+    else {
+        say(`It waits for your first message: switch Pane to ${target.name}, open "${created.session.name}", and send "continue".`);
+    }
     if (parsed.json)
         console.log(JSON.stringify(result, null, 2));
     return 0;
 }
+/** The conversation id a new Session's agent tab records, which it resumes when first opened. */
+async function sessionResumeId(remote, created) {
+    if (!created.internalSessionId || !created.panelId)
+        return undefined;
+    const listed = await (0, daemonClient_1.invokeRemoteDaemon)(remote, 'runpane:panels:list', [{ paneId: created.internalSessionId }], localControl_1.panelListResultSchema);
+    return listed.panels.find(panel => panel.id === created.panelId || panel.panelId === created.panelId)?.resumeId;
+}
 /** Pane's numbering for a taken Session name: "<name> 2", "<name> 3", compared without case. */
 function nextFreeName(name, taken) {
     const normalize = (value) => value.trim().toLocaleLowerCase();
@@ -661,7 +1274,7 @@ function nextFreeName(name, taken) {
         candidate = `${name} ${suffix}`;
     return candidate;
 }
-function sessionReceiverInstructions(origin, sender, receiverMachine) {
+function sessionReceiverInstructions(origin, sender, receiverMachine, carried) {
     const reportTarget = origin.originPanel
         ? `runpane workspace ${origin.originMachine} panels submit --panel ${origin.originPanel} --text "<one line: what you finished, and anything blocked>" --yes`
         : 'tell the person here, since the sender left no panel to report to';
@@ -669,7 +1282,9 @@ function sessionReceiverInstructions(origin, sender, receiverMachine) {
         '## Receiver instructions',
         '',
         '<!-- Added by runpane handoff. -->',
-        `1. You are a new Session on ${receiverMachine}, continuing Session "${sender}" from ${origin.originMachine}. Only this note was sent: the sender's conversation, Session folder and Panes stay on ${origin.originMachine}.`,
+        carried
+            ? `1. You are a new Session on ${receiverMachine}, continuing Session "${sender}" from ${origin.originMachine} in its own conversation, which was copied here. Its Session folder and Panes stay on ${origin.originMachine}.`
+            : `1. You are a new Session on ${receiverMachine}, continuing Session "${sender}" from ${origin.originMachine}. Only this note was sent: the sender's conversation, Session folder and Panes stay on ${origin.originMachine}.`,
         `2. Read this whole note. To read a file it names from the sender's machine, run \`runpane workspace ${origin.originMachine} read <path>\`.`,
         '3. Continue from "Next steps".',
         `4. When you finish or get blocked, report back to the sender: ${reportTarget}`,