runpane 2.4.165 → 2.4.166

package/dist/handoff.d.ts

@@ -0,0 +1,80 @@
+import type { ParsedArgs, RunpaneAgent } from './commands';
+import { type TailnetMachine } from './workspace';
+/**
+ * The note's sections. They extend Codex's compaction prompt
+ * (openai/codex codex-rs/prompts/templates/compact/prompt.md: progress and decisions, context and
+ * constraints, next steps, critical references) with what a receiver on another machine needs:
+ * what was verified, how to check it, and where the code is.
+ */
+export declare const HANDOFF_SECTIONS: readonly [{
+    readonly heading: "Goal";
+    readonly prompt: "What the work is for and what \"done\" means, in the person's terms. Name the issue or PR.";
+}, {
+    readonly heading: "Current state";
+    readonly prompt: "Where things stand right now, in two or three sentences.";
+}, {
+    readonly heading: "Done and verified";
+    readonly prompt: "Finished work, each item with how you verified it (command and result).";
+}, {
+    readonly heading: "In progress";
+    readonly prompt: "Half-done work: what is written, what is not, and any failing test or error, quoted.";
+}, {
+    readonly heading: "Next steps";
+    readonly prompt: "The ordered next actions. Make the first one concrete enough to start without asking.";
+}, {
+    readonly heading: "Decisions and constraints";
+    readonly prompt: "Decisions with their reasons, the person's preferences, non-goals, and approaches that failed (so they are not retried).";
+}, {
+    readonly heading: "Open questions";
+    readonly prompt: "What only the person can answer, and what you were unsure about. Write \"None\" if there are none.";
+}, {
+    readonly heading: "How to verify";
+    readonly prompt: "Exact commands to build, test, and see the change working, with the result you expect.";
+}, {
+    readonly heading: "Git state";
+    readonly prompt: "Repository, branch, head commit, whether it is pushed, and any uncommitted files that matter.";
+}];
+export interface HandoffDestination {
+    /** A Tailscale machine name, or null for this machine. */
+    machine: string | null;
+    agent: RunpaneAgent;
+    model?: string;
+    effort?: string;
+    /** Explicit WSL selection is recognized and rejected until supported. */
+    wsl?: true;
+}
+export interface DestinationOverrides {
+    machine?: string;
+    agent?: RunpaneAgent;
+    model?: string;
+    effort?: string;
+}
+/**
+ * Reads "codex gpt-5 high on parsas-macbook-pro" into a machine, agent, model, and effort.
+ * Flags win over the text. Anything it cannot place is an error, not a guess.
+ */
+export declare function parseDestination(text: string, machines: readonly TailnetMachine[], overrides?: DestinationOverrides): HandoffDestination;
+export interface NoteCheck {
+    ok: boolean;
+    /** Required sections with no heading. */
+    missing: string[];
+    /** Required sections whose heading is there but whose body is empty or only template comments. */
+    empty: string[];
+}
+/** Checks that every required section is present and written; "None" counts as written. */
+export declare function validateNote(text: string): NoteCheck;
+export interface NoteOrigin {
+    originMachine: string;
+    originPane?: string;
+    originPanel?: string;
+    originSession?: string;
+    repository?: string;
+    branch?: string;
+    head?: string;
+    remote?: string;
+    pushed?: boolean;
+}
+/** The note an agent fills in: front matter for the origin, then one section per required heading. */
+export declare function noteTemplate(origin: NoteOrigin): string;
+export declare function runHandoff(parsed: ParsedArgs): Promise<number>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI3D,OAAO,EAAgD,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhG;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUnB,CAAC;AAUX,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,SAAS,GAAE,oBAAyB,GAAG,kBAAkB,CA8C5I;AAaD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kGAAkG;IAClG,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAgBpD;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAcvD;AAuQD,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuIpE"}

package/dist/handoff.js

@@ -0,0 +1,528 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDOFF_SECTIONS = void 0;
+exports.parseDestination = parseDestination;
+exports.validateNote = validateNote;
+exports.noteTemplate = noteTemplate;
+exports.runHandoff = runHandoff;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+const boundaryDecoder_1 = require("./boundaryDecoder");
+const daemonClient_1 = require("./daemonClient");
+const localControl_1 = require("./localControl");
+const contract_1 = require("./generated/contract");
+const workspace_1 = require("./workspace");
+/**
+ * The note's sections. They extend Codex's compaction prompt
+ * (openai/codex codex-rs/prompts/templates/compact/prompt.md: progress and decisions, context and
+ * constraints, next steps, critical references) with what a receiver on another machine needs:
+ * what was verified, how to check it, and where the code is.
+ */
+exports.HANDOFF_SECTIONS = [
+    { heading: 'Goal', prompt: 'What the work is for and what "done" means, in the person\'s terms. Name the issue or PR.' },
+    { heading: 'Current state', prompt: 'Where things stand right now, in two or three sentences.' },
+    { heading: 'Done and verified', prompt: 'Finished work, each item with how you verified it (command and result).' },
+    { heading: 'In progress', prompt: 'Half-done work: what is written, what is not, and any failing test or error, quoted.' },
+    { heading: 'Next steps', prompt: 'The ordered next actions. Make the first one concrete enough to start without asking.' },
+    { heading: 'Decisions and constraints', prompt: 'Decisions with their reasons, the person\'s preferences, non-goals, and approaches that failed (so they are not retried).' },
+    { heading: 'Open questions', prompt: 'What only the person can answer, and what you were unsure about. Write "None" if there are none.' },
+    { heading: 'How to verify', prompt: 'Exact commands to build, test, and see the change working, with the result you expect.' },
+    { heading: 'Git state', prompt: 'Repository, branch, head commit, whether it is pushed, and any uncommitted files that matter.' },
+];
+const AGENTS = new Set(contract_1.RUNPANE_CONTRACT.enums.agents);
+const AGENT_ALIASES = new Map([['claude-code', 'claude'], ['cursor-agent', 'cursor'], ['codex-cli', 'codex']]);
+const EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const MODEL_PATTERN = /^(gpt-|o\d|claude-|opus|sonnet|haiku|fable|composer|gemini|grok)/i;
+const FILLER = new Set(['on', 'to', 'with', 'using', 'via', 'at', 'in', 'a', 'an', 'the', 'and', 'effort', 'reasoning', 'model', 'machine']);
+const THIS_MACHINE = /\b(this machine|this computer|here|locally|local|localhost)\b/gi;
+const REPORT_TIMEOUT_MS = 180_000;
+/**
+ * Reads "codex gpt-5 high on parsas-macbook-pro" into a machine, agent, model, and effort.
+ * Flags win over the text. Anything it cannot place is an error, not a guess.
+ */
+function parseDestination(text, machines, overrides = {}) {
+    let local = false;
+    const words = text.replace(THIS_MACHINE, () => { local = true; return ' '; })
+        .split(/[\s,]+/).filter(Boolean);
+    const agents = [];
+    const efforts = [];
+    const models = [];
+    const unknown = [];
+    let wsl = false;
+    for (const raw of words) {
+        const [key, value] = raw.includes('=') ? raw.split('=', 2) : [undefined, raw];
+        const word = value.toLowerCase();
+        if (key?.toLowerCase() === 'model')
+            models.push(value);
+        else if (key && ['effort', 'reasoning'].includes(key.toLowerCase()))
+            efforts.push(word);
+        else if (AGENTS.has(word) || AGENT_ALIASES.has(word))
+            agents.push(AGENT_ALIASES.get(word) ?? decodeAgent(word));
+        else if (EFFORTS.has(word))
+            efforts.push(word);
+        else if (word === 'wsl')
+            wsl = true;
+        else if (MODEL_PATTERN.test(word))
+            models.push(word);
+        else if (!FILLER.has(word))
+            unknown.push(value);
+    }
+    for (const [label, found] of [['agents', [...new Set(agents)]], ['models', models], ['efforts', efforts]]) {
+        if (found.length > 1)
+            throw new Error(`"${text}" names two ${label}: ${found.join(' and ')}. Name one.`);
+    }
+    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`);
+    let machine = null;
+    if (overrides.machine) {
+        machine = machineName((0, workspace_1.resolveMachine)(overrides.machine, machines));
+    }
+    else if (unknown.length > 1) {
+        throw new Error(`Could not read "${unknown.join(' ')}" in "${text}". Name one machine, or pass --machine <name>.`);
+    }
+    else if (unknown.length === 1) {
+        if (local)
+            throw new Error(`"${text}" names this machine and "${unknown[0]}". Name one.`);
+        machine = machineName((0, workspace_1.resolveMachine)(unknown[0], machines));
+    }
+    const destination = { machine, agent };
+    const model = overrides.model ?? models[0];
+    const effort = overrides.effort ?? efforts[0];
+    if (model !== undefined && !/^[A-Za-z0-9._:/-]+$/.test(model))
+        throw new Error('Invalid model identifier. Use letters, numbers, dots, underscores, colons, slashes, or hyphens.');
+    if (effort !== undefined && !EFFORTS.has(effort))
+        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 (model)
+        destination.model = model;
+    if (effort)
+        destination.effort = effort;
+    if (wsl)
+        destination.wsl = true;
+    return destination;
+}
+function machineName(machine) {
+    return machine.self ? null : machine.name;
+}
+const agentSchema = boundaryDecoder_1.boundary.enumeration(...contract_1.RUNPANE_CONTRACT.enums.agents);
+function decodeAgent(value) {
+    return (0, boundaryDecoder_1.decodeBoundary)(value, agentSchema);
+}
+/** Checks that every required section is present and written; "None" counts as written. */
+function validateNote(text) {
+    const body = text.replace(/^---\n[\s\S]*?\n---\n/, '');
+    const headings = [...body.matchAll(/^#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$/gm)];
+    const missing = [];
+    const empty = [];
+    for (const section of exports.HANDOFF_SECTIONS) {
+        const index = headings.findIndex((match) => match[1].trim().toLowerCase() === section.heading.toLowerCase());
+        if (index === -1) {
+            missing.push(section.heading);
+            continue;
+        }
+        const start = (headings[index].index ?? 0) + headings[index][0].length;
+        const end = headings[index + 1]?.index ?? body.length;
+        if (!body.slice(start, end).replace(/<!--[\s\S]*?-->/g, '').trim())
+            empty.push(section.heading);
+    }
+    return { ok: missing.length === 0 && empty.length === 0, missing, empty };
+}
+/** The note an agent fills in: front matter for the origin, then one section per required heading. */
+function noteTemplate(origin) {
+    return [
+        frontMatter(origin),
+        '# Handoff: <title>',
+        '',
+        '<!--',
+        'Write this for an agent that has none of your context: no chat history, no memory, a different',
+        'machine. Be concise and concrete; quote errors and commands exactly. Every section is required;',
+        'write "None" when one does not apply. Based on Codex\'s compaction prompt',
+        '(github.com/openai/codex, codex-rs/prompts/templates/compact/prompt.md).',
+        '-->',
+        '',
+        ...exports.HANDOFF_SECTIONS.flatMap((section) => [`## ${section.heading}`, '', `<!-- ${section.prompt} -->`, '']),
+    ].join('\n');
+}
+function frontMatter(origin) {
+    const fields = [
+        ['origin_machine', origin.originMachine],
+        ['origin_pane', origin.originPane],
+        ['origin_panel', origin.originPanel],
+        ['origin_session', origin.originSession],
+        ['repository', origin.repository],
+        ['branch', origin.branch],
+        ['head', origin.head],
+        ['remote', origin.remote],
+        ['pushed', origin.pushed],
+    ];
+    const lines = fields.filter(([, value]) => value !== undefined && value !== '').map(([key, value]) => `${key}: ${value}`);
+    return ['---', ...lines, '---', ''].join('\n');
+}
+/** 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+/, '');
+    return `${frontMatter(origin)}\n${body.trimEnd()}\n\n${receiver}\n`;
+}
+function git(args, cwd) {
+    return (0, node_child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function tryGit(args, cwd) {
+    try {
+        return git(args, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function readGitState(cwd) {
+    const root = tryGit(['rev-parse', '--show-toplevel'], cwd);
+    if (!root)
+        throw new Error('runpane handoff runs inside the git repository being handed off.');
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+    if (branch === 'HEAD')
+        throw new Error('HEAD is detached. Check out a branch before handing off.');
+    const remote = tryGit(['config', `branch.${branch}.remote`], root) ?? 'origin';
+    const remoteUrl = tryGit(['remote', 'get-url', remote], root);
+    if (!remoteUrl)
+        throw new Error(`This repository has no "${remote}" remote, so the receiver cannot fetch the work. Add one, then hand off again.`);
+    const head = git(['rev-parse', 'HEAD'], root);
+    const remoteHead = tryGit(['rev-parse', `refs/remotes/${remote}/${branch}`], root);
+    return {
+        root,
+        repository: repositorySlug(remoteUrl) ?? node_path_1.default.basename(root),
+        branch,
+        head,
+        remote,
+        remoteUrl,
+        dirty: (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-z'], { cwd: root, encoding: 'utf8' }).split('\0').filter(Boolean),
+        pushed: remoteHead !== null && tryGit(['merge-base', '--is-ancestor', head, remoteHead], root) !== null,
+    };
+}
+function noteInCheckout(root, notePath) {
+    if (!notePath || notePath === '-')
+        return '';
+    const resolved = node_path_1.default.resolve(notePath);
+    // Git may report a canonical root while Windows TEMP uses an 8.3 alias.
+    // Canonicalize directories, keeping the leaf so a note symlink is excluded too.
+    const canonicalNote = node_path_1.default.join(node_fs_1.default.realpathSync.native(node_path_1.default.dirname(resolved)), node_path_1.default.basename(resolved));
+    const relative = node_path_1.default.relative(node_fs_1.default.realpathSync.native(root), canonicalNote);
+    return relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative) ? '' : relative;
+}
+/** --push: commit uncommitted work as WIP and push the branch; never forces. */
+/** The note is not part of the work: leave it out of the uncommitted count and the WIP commit. */
+function withoutNote(state, notePath) {
+    const relative = noteInCheckout(state.root, notePath).split(node_path_1.default.sep).join('/');
+    if (!relative)
+        return state;
+    return { ...state, dirty: state.dirty.filter((line) => line.slice(3) !== relative) };
+}
+function pushWork(state, destination, notePath) {
+    const noteRelative = noteInCheckout(state.root, notePath);
+    if (noteRelative && git(['diff', '--cached', '--name-only', '--', noteRelative], state.root)) {
+        throw new Error(`The handoff note is staged. Unstage it with git restore --staged -- ${JSON.stringify(noteRelative)}, then retry. Nothing was committed or pushed.`);
+    }
+    if (state.dirty.length) {
+        const relative = noteInCheckout(state.root, notePath);
+        git(['add', '-A', '--', '.', ...(relative ? [`:(exclude)${relative}`] : [])], state.root);
+        git(['commit', '-m', `WIP: hand off to ${destination}`], state.root);
+    }
+    git(['push', '-u', state.remote, `HEAD:refs/heads/${state.branch}`], state.root);
+    git(['fetch', state.remote, state.branch], state.root);
+    return withoutNote(readGitState(state.root), notePath);
+}
+/** owner/name for a GitHub-style remote URL. */
+function repositorySlug(url) {
+    const match = /[:/]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/.exec(url.trim());
+    return match ? `${match[1]}/${match[2]}` : null;
+}
+// ---------------------------------------------------------------- running on the destination
+const execResultSchema = boundaryDecoder_1.boundary.object({
+    os: boundaryDecoder_1.boundary.enumeration('macOS', 'Windows', 'Linux'),
+    shell: boundaryDecoder_1.boundary.string,
+    exitCode: boundaryDecoder_1.boundary.nullable(boundaryDecoder_1.boundary.number),
+    stdout: boundaryDecoder_1.boundary.string,
+    stderr: boundaryDecoder_1.boundary.string,
+});
+const writeResultSchema = boundaryDecoder_1.boundary.object({ path: boundaryDecoder_1.boundary.string, bytes: boundaryDecoder_1.boundary.number });
+const repoListSchema = boundaryDecoder_1.boundary.object({
+    repos: boundaryDecoder_1.boundary.array(boundaryDecoder_1.boundary.object({ id: boundaryDecoder_1.boundary.number, name: boundaryDecoder_1.boundary.string, path: boundaryDecoder_1.boundary.string, environment: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.string) })),
+});
+const paneCreateSchema = boundaryDecoder_1.boundary.object({
+    items: boundaryDecoder_1.boundary.array(boundaryDecoder_1.boundary.object({
+        ok: boundaryDecoder_1.boundary.boolean,
+        sessionId: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.string),
+        panelId: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.string),
+        name: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.string),
+        worktreePath: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.string),
+        error: boundaryDecoder_1.boundary.optional(boundaryDecoder_1.boundary.object({ message: boundaryDecoder_1.boundary.string })),
+    })),
+});
+async function remoteDestination(machine) {
+    const target = (0, workspace_1.workspaceTarget)(machine);
+    const probe = await (0, daemonClient_1.invokeRemoteDaemon)(target, 'runpane:machine:exec', [{ command: 'echo runpane-handoff', timeoutMs: 20_000 }], execResultSchema);
+    const shell = probe.shell;
+    // cmd has expansion rules that cannot safely represent arbitrary terminal prompts.
+    if (!/^(bash|zsh|sh|fish|pwsh|powershell)(?:\.exe)?$/i.test(node_path_1.default.posix.basename(shell.replace(/\\/g, '/')))) {
+        throw new Error(`Handoff does not support the destination shell "${shell}". Select Bash or PowerShell in Pane and retry.`);
+    }
+    return {
+        name: machine.name,
+        shell,
+        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,
+    };
+}
+function localDestination(name) {
+    return {
+        name,
+        shell: process.platform === 'win32' ? 'powershell' : (process.env.SHELL ?? 'sh'),
+        run: (command, timeoutMs = 120_000) => new Promise((resolve) => {
+            const child = (0, node_child_process_1.spawn)(command[0], command.slice(1), { shell: false, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+            child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            child.on('error', (error) => resolve({ exitCode: 1, stdout, stderr: stderr + error.message }));
+            child.on('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
+        }),
+        write: async (file, content) => {
+            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 });
+            return resolved;
+        },
+    };
+}
+function quote(value, shell) {
+    if (/^[\w./:@=+-]+$/.test(value))
+        return value;
+    return /(?:powershell|pwsh)(?:\.exe)?$/i.test(shell) ? `'${value.replace(/'/g, "''")}'` : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function mustRun(destination, command, what, timeoutMs) {
+    const result = await destination.run(command, timeoutMs);
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout).trim().split('\n').slice(-3).join(' ');
+        throw new Error(`${what} failed on ${destination.name}: ${detail || `exit ${result.exitCode}`}`);
+    }
+    return result.stdout;
+}
+/** The saved repository on the destination whose remotes include ours; returns it and that remote's name. */
+async function findRepo(destination, runpane, state, selector) {
+    const listed = (0, boundaryDecoder_1.decodeBoundary)(JSON.parse(await mustRun(destination, [...runpane, 'repos', 'list', '--json'], 'runpane repos list')), repoListSchema);
+    const candidates = selector
+        ? listed.repos.filter((repo) => String(repo.id) === selector || repo.name === selector || repo.path === selector)
+        : listed.repos;
+    if (selector && !candidates.length)
+        throw new Error(`${destination.name} has no saved repository "${selector}". Its repositories: ${listed.repos.map((repo) => repo.name).join(', ')}.`);
+    const wanted = repositorySlug(state.remoteUrl)?.toLowerCase();
+    for (const repo of candidates) {
+        const remotes = await destination.run(['git', '-C', repo.path, 'remote', '-v'], 20_000);
+        if (remotes.exitCode !== 0)
+            continue;
+        const match = remotes.stdout.split('\n').map((line) => line.split(/\s+/))
+            .find(([, url]) => url && repositorySlug(url)?.toLowerCase() === wanted);
+        if (match)
+            return { repo, remote: match[0] };
+    }
+    throw new Error(`No saved repository on ${destination.name} has a remote for ${wanted}. Add a matching Git remote to the destination clone, then save the clone there with: runpane workspace ${destination.name} exec -- runpane repos add --path <clone> --yes.`);
+}
+function agentCommand(destination, shell) {
+    if (!destination.model && !destination.effort)
+        return undefined;
+    const base = contract_1.RUNPANE_CONTRACT.agentTemplates[destination.agent].command;
+    const { model, effort } = destination;
+    const flags = destination.agent === 'codex'
+        ? [model && `-m ${quote(model, shell)}`, effort && `-c ${quote(`model_reasoning_effort=${effort}`, shell)}`]
+        : destination.agent === 'claude'
+            ? [model && `--model ${quote(model, shell)}`, effort && `--effort ${quote(effort, shell)}`]
+            : [model && `--model ${quote(model, shell)}`];
+    return [base, ...flags].filter(Boolean).join(' ');
+}
+function describeDestination(destination, machine) {
+    const detail = [destination.model, destination.effort && `${destination.effort} effort`].filter(Boolean).join(', ');
+    return `${destination.agent}${detail ? ` (${detail})` : ''} on ${machine}`;
+}
+function receiverInstructions(origin, state, remote, reporter) {
+    const reportTarget = origin.originPanel
+        ? `${reporter} workspace ${origin.originMachine} panels submit --panel ${origin.originPanel} --text "<one line: what you finished, the commit or PR, and anything blocked>" --yes`
+        : `a comment on the PR, or a commit message on ${state.branch}, since the sender left no panel to report to`;
+    return [
+        '## Receiver instructions',
+        '',
+        '<!-- Added by runpane handoff. -->',
+        '1. Read the repository\'s AGENTS.md or CLAUDE.md, then this whole note.',
+        `2. Check the git state: your worktree starts at sender commit ${state.head}; \`git log -1 --format=%H\` must print ${state.head}. If it does not, stop and report.`,
+        '3. Run the commands under "How to verify" to confirm the state the note describes, then continue from "Next steps".',
+        `4. Push your commits to the original branch: \`git push ${remote} HEAD:${state.branch}\`. Never force-push.`,
+        `5. When you finish or get blocked, report back to the sender: ${reportTarget}`,
+    ].join('\n');
+}
+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');
+    const origin = (state) => ({
+        originMachine: self,
+        originPane: process.env.PANE_SESSION_ID,
+        originPanel: process.env.PANE_PANEL_ID,
+        originSession: process.env.PANE_ORCHESTRATION_SESSION_ID,
+        repository: state?.repository,
+        branch: state?.branch,
+        head: state?.head,
+        remote: state?.remote,
+        pushed: state?.pushed,
+    });
+    if (parsed.handoffTemplate) {
+        process.stdout.write(noteTemplate(origin(tryReadGitState(cwd))));
+        return 0;
+    }
+    const text = parsed.handoffDestination ?? '';
+    if (!text && !parsed.handoffMachine && !parsed.agent) {
+        throw new Error('runpane handoff needs a destination, for example: runpane handoff "claude opus on parsas-macbook-pro" --note-file ~/handoff.md. Start the note with: runpane handoff --template > ~/handoff.md');
+    }
+    const machines = tailnet.ok ? [tailnet.self, ...tailnet.machines] : [];
+    const destination = parseDestination(text, machines, {
+        machine: parsed.handoffMachine, agent: parsed.agent, model: parsed.handoffModel, effort: parsed.handoffEffort,
+    });
+    if (destination.wsl)
+        throw new Error('WSL handoff is not supported yet. Choose a native destination without wsl; nothing was committed or sent.');
+    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)`;
+    const say = (line) => { if (!parsed.json)
+        console.log(line); };
+    say(`Handoff to ${describeDestination(destination, machineLabel)}`);
+    const warnings = [];
+    let noteText;
+    let noteInfo;
+    if (parsed.handoffNoteFile) {
+        noteText = node_fs_1.default.readFileSync(parsed.handoffNoteFile === '-' ? 0 : parsed.handoffNoteFile, 'utf8');
+        const check = validateNote(noteText);
+        if (!check.ok) {
+            const parts = [check.missing.length && `missing ${check.missing.join(', ')}`, check.empty.length && `not filled in: ${check.empty.join(', ')}`].filter(Boolean);
+            throw new Error(`The note is incomplete (${parts.join('; ')}). Fill in every section, writing "None" where one does not apply. The template: runpane handoff --template`);
+        }
+        noteInfo = { path: node_path_1.default.resolve(parsed.handoffNoteFile), sections: exports.HANDOFF_SECTIONS.length, bytes: Buffer.byteLength(noteText) };
+        say(step('note', `${noteInfo.sections} sections, ${formatBytes(noteInfo.bytes)}`));
+    }
+    else if (!parsed.dryRun) {
+        throw new Error('runpane handoff needs --note-file <path>. Write it from: runpane handoff --template > ~/handoff.md');
+    }
+    let state = withoutNote(readGitState(cwd), parsed.handoffNoteFile);
+    if (parsed.handoffPush && !parsed.dryRun && (!state.pushed || state.dirty.length)) {
+        state = pushWork(state, machineLabel, parsed.handoffNoteFile);
+    }
+    if (state.dirty.length)
+        warnings.push(`${state.dirty.length} uncommitted file${state.dirty.length === 1 ? '' : 's'} will not reach the receiver. Commit them, or pass --push to commit them as WIP.`);
+    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));
+    const result = {
+        ok: true,
+        dryRun: parsed.dryRun,
+        destination,
+        note: noteInfo,
+        git: { repository: state.repository, branch: state.branch, head: state.head, remote: state.remote, pushed: state.pushed, dirty: state.dirty.length },
+        warnings,
+    };
+    if (parsed.dryRun) {
+        for (const warning of warnings)
+            say(`  ! ${warning}`);
+        say('Dry run: nothing was sent.');
+        if (parsed.json)
+            console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    if (!state.pushed)
+        throw new Error(`${warnings.join(' ')}\nThe receiver would start without your work, so nothing was sent.`);
+    for (const warning of warnings)
+        say(`  ! ${warning}`);
+    const target = destination.machine ? machines.find((machine) => machine.name === destination.machine) : undefined;
+    const remote = target ? await remoteDestination(target) : localDestination(self);
+    const installed = await remote.run(['runpane', '--version'], 30_000);
+    const runpane = target
+        ? (installed.exitCode === 0 ? ['runpane'] : ['npx', '--yes', 'runpane@latest'])
+        : (process.platform === 'win32' || installed.exitCode !== 0 ? [process.execPath, node_path_1.default.join(__dirname, 'cli.js')] : ['runpane']);
+    if (!target && parsed.paneDir)
+        runpane.push('--pane-dir', parsed.paneDir);
+    // `runpane workspace` arrived in 2.4.164; an older runpane there reports back through npx.
+    const reporter = installed.exitCode === 0 && versionAtLeast(installed.stdout, [2, 4, 164]) ? 'runpane' : 'npx --yes runpane@latest';
+    const { repo, remote: repoRemote } = await findRepo(remote, runpane, state, parsed.repo);
+    say(step('repo', `${repo.name} (${repo.path}), remote ${repoRemote}`));
+    await mustRun(remote, ['git', '-C', repo.path, 'fetch', repoRemote, state.branch], 'git fetch', 120_000);
+    await mustRun(remote, ['git', '-C', repo.path, 'cat-file', '-e', `${state.head}^{commit}`], 'verify sender commit');
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
+    const name = `handoff-${state.branch.replace(/^handoff[-/]/i, '')}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 48).replace(/-+$/, '');
+    const noteOrigin = origin(state);
+    const stamped = stampNote(noteText ?? '', noteOrigin, receiverInstructions(noteOrigin, state, repoRemote, reporter));
+    const notePath = await remote.write(`~/.pane/handoffs/${stamp}-${name}-${(0, node_crypto_1.randomUUID)()}.md`, stamped);
+    say(step('note sent', notePath));
+    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.`;
+    let create = [
+        ...runpane, 'panes', 'create', '--repo', String(repo.id), '--name', name, '--base', state.head, '--agent', destination.agent,
+        ...(toolCommand ? ['--tool-command', toolCommand] : []),
+        '--prompt', prompt, '--source', 'agent', '--no-focus', '--wait-ready', '--yes', '--json',
+    ];
+    let created;
+    try {
+        // PowerShell 5.1 strips embedded quotes and empty arguments when launching
+        // native npm wrappers. Keep prompts and nested tool commands in JSON.
+        if (target && /(?:powershell|pwsh)(?:\.exe)?$/i.test(remote.shell)) {
+            const request = await (0, localControl_1.buildPaneCreateRequest)({
+                ...parsed, 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,
+            });
+            const requestPath = await remote.write(`${notePath}.create.json`, JSON.stringify(request));
+            create = [...runpane, 'panes', 'create', '--from-json', requestPath, '--no-associate', '--yes', '--json'];
+        }
+        created = (0, boundaryDecoder_1.decodeBoundary)(JSON.parse(await mustRun(remote, create, 'runpane panes create', REPORT_TIMEOUT_MS)), paneCreateSchema);
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}. The note was sent to ${notePath}. Check runpane sessions list on ${remote.name} before retrying to avoid a duplicate Pane.`);
+    }
+    const item = created.items[0];
+    if (!item?.ok || !item.sessionId || !item.panelId)
+        throw new Error(`Pane on ${remote.name} did not start the agent: ${item?.error?.message ?? 'no pane was created'}. The note was sent to ${notePath}.${item?.sessionId ? ` Check runpane agents status --pane ${item.sessionId} on ${remote.name} before retrying.` : ` Check runpane sessions list on ${remote.name} before retrying.`}`);
+    say(step('started', `${item.name ?? name} on ${remote.name}${item.worktreePath ? ` (${item.worktreePath})` : ''}`));
+    result.repo = { id: repo.id, name: repo.name, path: repo.path };
+    result.notePath = notePath;
+    result.pane = { id: item.sessionId, panelId: item.panelId, name: item.name, worktreePath: item.worktreePath };
+    result.reportBack = noteOrigin.originPanel ? `${self} panel ${noteOrigin.originPanel}` : undefined;
+    const check = `${destination.machine ? `runpane workspace ${remote.name} exec -- ` : ''}runpane agents status --pane ${item.sessionId}`;
+    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;
+}
+function tryReadGitState(cwd) {
+    try {
+        return readGitState(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function versionAtLeast(output, minimum) {
+    const parts = /(\d+)\.(\d+)\.(\d+)/.exec(output)?.slice(1).map(Number);
+    if (!parts)
+        return false;
+    const index = parts.findIndex((part, position) => part !== minimum[position]);
+    return index === -1 || parts[index] > minimum[index];
+}
+function step(label, detail, ok = true) {
+    return `  ${ok ? '✓' : '!'} ${label.padEnd(10)} ${detail}`;
+}
+function formatBytes(bytes) {
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}
+//# sourceMappingURL=handoff.js.map