runpane 2.4.185 → 2.4.187

package/dist/generated/contract.d.ts

@@ -25,7 +25,7 @@ export declare const RUNPANE_CONTRACT: {
         readonly watch: {
             readonly follow: {
                 readonly summary: "What `runpane watch --follow` does with no other flags: quiet, batched updates and expiry after 3 hours with nothing happening. Individual duration flags override the defaults.";
-                readonly kinds: readonly ["agent.report", "agent.ready", "agent.blocked", "agent.idle", "panel.exited", "panel.stopped", "pane.gone", "pane.associated", "pane.detached", "pr.conflicted", "pr.checks", "pr.merged", "pr.closed", "pr.head", "pr.review", "pr.comment", "pr.stopped", "github.unavailable", "github.recovered"];
+                readonly kinds: readonly ["agent.report", "agent.ready", "agent.blocked", "agent.idle", "panel.exited", "panel.stopped", "pane.gone", "pane.associated", "pane.detached", "pr.conflicted", "pr.checks", "pr.merged", "pr.closed", "pr.head", "pr.base_changed", "pr.base_deleted", "pr.review", "pr.comment", "pr.stopped", "github.unavailable", "github.recovered"];
                 readonly readySettle: "3m";
                 readonly blockedSettle: "30s";
                 readonly minInterval: "10m";
@@ -229,8 +229,8 @@ export declare const RUNPANE_CONTRACT: {
         readonly localControl: true;
     }, {
         readonly name: "handoff";
-        readonly summary: "Hand your task to a fresh agent on this or another machine: check your handoff note, make the branch reachable, send the note, and start the agent on it. From a Session's terminal, create the Session on another machine instead.";
-        readonly usage: readonly ["runpane handoff --template", "runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--dry-run] [--json]"];
+        readonly summary: "Hand your task to another agent on this or another machine: check your handoff note, make the branch reachable, send the note, and start the agent on it. A same-agent handoff from a Pane tab carries and resumes your own session (a fork on this machine) and checks it continued; otherwise a fresh agent starts with the note. From a Session's terminal, create the Session on another machine instead.";
+        readonly usage: readonly ["runpane handoff --template", "runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor|opencode>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--note-only] [--dry-run] [--json]"];
         readonly mutates: true;
         readonly wrappers: readonly ["npm"];
         readonly localControl: true;
@@ -244,11 +244,11 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes create";
         readonly summary: "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create a Pane (a new worktree) only when the work's branch has no Pane yet; for review, audit, fix or QA on existing work use `panels create --pane <id>`.";
-        readonly usage: readonly ["runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options] [--pane-dir <path>]", "runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options] [--pane-dir <path>]", "runpane panes create --from-json <path|-> [--yes] [--json] [--pane-dir <path>]"];
+        readonly usage: readonly ["runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] [options] [--pane-dir <path>]", "runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] [options] [--pane-dir <path>]", "runpane panes create --from-json <path|-> [--yes] [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly additive: true;
         readonly toolsets: readonly ["panes"];
-        readonly jsonSchemas: readonly ["paneCreateRequest", "paneCreateResult"];
+        readonly jsonSchemas: readonly ["paneCreateRequest", "paneCreateResult", "dispatchWaitResult"];
         readonly localControl: true;
     }, {
         readonly name: "panes adopt";
@@ -307,11 +307,11 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panels create";
         readonly summary: "Open a new agent or terminal tab inside an existing Pane, sharing its worktree. The default for review, QA, fixes and any other agent on work that already has a Pane.";
-        readonly usage: readonly ["runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready] --yes [--json] [--pane-dir <path>]", "runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--focus|--no-focus] [--wait-ready] --yes [--json] [--pane-dir <path>]"];
+        readonly usage: readonly ["runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json] [--pane-dir <path>]", "runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--focus|--no-focus] [--wait-ready] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly additive: true;
         readonly toolsets: readonly ["core", "panels"];
-        readonly jsonSchemas: readonly ["panelCreateRequest", "panelCreateResult"];
+        readonly jsonSchemas: readonly ["panelCreateRequest", "panelCreateResult", "dispatchWaitResult"];
         readonly localControl: true;
     }, {
         readonly name: "panels open";
@@ -352,10 +352,10 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panels submit";
         readonly summary: "Send and submit text to a terminal panel, including idle agent composers.";
-        readonly usage: readonly ["runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] [--source user|agent] --yes [--json] [--pane-dir <path>]"];
+        readonly usage: readonly ["runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer [--attach <file>]...] [--interrupt] [--source user|agent] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly toolsets: readonly ["panels"];
-        readonly jsonSchemas: readonly ["panelSubmitRequest", "panelSubmitResult"];
+        readonly jsonSchemas: readonly ["panelSubmitRequest", "panelSubmitResult", "dispatchWaitResult"];
         readonly localControl: true;
     }, {
         readonly name: "panels submit-composer";
@@ -667,6 +667,20 @@ export declare const RUNPANE_CONTRACT: {
         readonly toolsets: readonly ["agents"];
         readonly jsonSchemas: readonly ["reportResult"];
         readonly localControl: true;
+    }, {
+        readonly name: "inbox";
+        readonly summary: "List the reports, missing reports, and on-screen questions a Session's orchestrator has not acknowledged.";
+        readonly usage: readonly ["runpane inbox [--session <id|name>] [--json] [--pane-dir <path>]"];
+        readonly jsonSchemas: readonly ["inboxListResult"];
+        readonly localControl: true;
+    }, {
+        readonly name: "inbox ack";
+        readonly summary: "Clear Session inbox items once they are handled.";
+        readonly usage: readonly ["runpane inbox ack <item-id>... [--session <id|name>] [--json] [--pane-dir <path>]", "runpane inbox ack --all --session <id|name> [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly idempotent: true;
+        readonly jsonSchemas: readonly ["inboxAckResult"];
+        readonly localControl: true;
     }, {
         readonly name: "sessions list";
         readonly summary: "List durable named orchestration Sessions.";
@@ -939,6 +953,10 @@ export declare const RUNPANE_CONTRACT: {
             readonly value: "<path|->";
             readonly aliases: readonly ["--prompt-file"];
             readonly description: "Read initial input from a file or stdin. --prompt-file is an alias.";
+        }, {
+            readonly name: "--attach";
+            readonly value: "<file>";
+            readonly description: "Copy a file beside the --as-file-pointer prompt file and list its copy in the pointer line; repeatable.";
         }, {
             readonly name: "--from-json";
             readonly value: "<path|->";
@@ -1050,7 +1068,11 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--wait";
             readonly value: "<milliseconds>";
-            readonly description: "How long lock acquire waits for a held lock to come free; 0 (the default) returns at once.";
+            readonly description: "lock acquire: how long to wait for a held lock to come free; 0 (the default) returns at once. On panels submit, panels create and panes create, --wait takes no value: block until that panel reports, misses its report, waits on a prompt, or exits, then print one JSON result.";
+        }, {
+            readonly name: "--timeout";
+            readonly value: "<duration>";
+            readonly description: "With --wait: give up after this long (30m, 2h; 0 waits without limit) and exit 124.";
         }, {
             readonly name: "--note";
             readonly value: "<text>";
@@ -1165,7 +1187,7 @@ export declare const RUNPANE_CONTRACT: {
             readonly description: "Run an adopted pane's agent resume command immediately instead of staging it.";
         }, {
             readonly name: "--as-file-pointer";
-            readonly description: "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead.";
+            readonly description: "Write the prompt or text to a private prompt file (in the Pane's worktree, hidden from git, when it has one) and send the one line `Read and follow <path>` instead.";
         }, {
             readonly name: "--follow";
             readonly description: "Continue waiting for workspace events until interrupted.";
@@ -1202,14 +1224,26 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--push";
             readonly description: "Before a handoff, commit uncommitted work as WIP and push the branch (never forces).";
+        }, {
+            readonly name: "--note-only";
+            readonly description: "Hand off to a fresh agent with the note, instead of carrying and resuming your own session.";
         }, {
             readonly name: "--interrupt";
             readonly description: "Stop the current agent turn, wait for an empty idle composer, then submit and verify the replacement.";
+        }, {
+            readonly name: "--expect-report";
+            readonly description: "Pane expects a `runpane report` and emits agent.report.missing if the agent goes ready or exits without one. The default for work an agent sends; use it to ask for one on work marked --source user.";
+        }, {
+            readonly name: "--no-expect-report";
+            readonly description: "Send work without waiting for a `runpane report` (fire-and-forget input); no agent.report.missing follows.";
+        }, {
+            readonly name: "--all";
+            readonly description: "inbox ack only: clear every item of the --session.";
         }];
     };
     readonly help: {
         readonly npm: {
-            readonly default: readonly ["Usage:", "  runpane", "  runpane setup", "  runpane install [client|daemon] [options]", "  runpane update [options]", "  runpane version", "  runpane doctor", "  runpane doctor --report --body-file <path|->", "  runpane daemon repair [--pane-dir <path>] [--yes] [--json]", "  runpane agent-context [--json]", "  runpane mcp [--toolsets <name,...>] [--read-only]", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "  runpane repos list [--json]", "  runpane repos add --path <path> [--name <name>]", "  runpane sessions list [--json] [--pane-dir <path>]", "  runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]", "  runpane sessions get --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]", "  runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]", "  runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]", "  runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]", "  runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane workspace state [--repo <selector>] [--json]", "  runpane workspace list [--json]", "  runpane workspace <machine> read|write|exec|<command>", "  runpane watch --follow", "  runpane watch --until-event", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base-branch <branch>] [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] --yes", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) --yes [--json]", "  runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  runpane panels resume (--panel <panel-id>|--session <id|name>|--all-stopped) [--wait-ready] --yes [--json]", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json]", "  runpane panes git-status --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane panes commit --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes push --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes pull --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes rebase-main --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes restore --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane links create --pane <pane-id> [--panel <panel-id>] [--json]", "  runpane links open --url <pane-url> --yes [--json] [--pane-dir <path>]", "  runpane docs search --query <text> [--limit <count>] [--json]", "  runpane docs read --doc <path> [--json]", "  runpane agents start (--pane <pane-id> | --repo <selector> --name <name> [--base-branch <branch>]) (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> --yes [--json] [--pane-dir <path>]", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary-file <path|->] [--question <text>] [--json]", "  runpane panes squash-rebase --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes stash --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stash-pop --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes soft-reset --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes fetch --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes run-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stop-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes move --pane <pane-id> --folder <folder-id> --yes [--json] [--pane-dir <path>]", "  runpane folders list --repo <repo-id> [--json] [--pane-dir <path>]", "  runpane folders create --repo <repo-id> --name <name> --yes [--json] [--pane-dir <path>]", "  runpane help [command]", "", "Quick start:", "  npx --yes runpane@latest", "  npm i -g runpane && runpane setup", "", "Advanced examples:", "  npx --yes runpane@latest install client", "  npx --yes runpane@latest install daemon --label \"My Server\"", "  pnpm dlx runpane@latest", "", "Common commands:", "  runpane help", "  runpane setup", "  runpane install", "  runpane doctor", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json", "  runpane agent-context --command \"<command>\" --json", "", "Run \"runpane help panes create\" for pane orchestration options."];
+            readonly default: readonly ["Usage:", "  runpane", "  runpane setup", "  runpane install [client|daemon] [options]", "  runpane update [options]", "  runpane version", "  runpane doctor", "  runpane doctor --report --body-file <path|->", "  runpane daemon repair [--pane-dir <path>] [--yes] [--json]", "  runpane agent-context [--json]", "  runpane mcp [--toolsets <name,...>] [--read-only]", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "  runpane repos list [--json]", "  runpane repos add --path <path> [--name <name>]", "  runpane sessions list [--json] [--pane-dir <path>]", "  runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]", "  runpane sessions get --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]", "  runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]", "  runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]", "  runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]", "  runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]", "  runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane workspace state [--repo <selector>] [--json]", "  runpane workspace list [--json]", "  runpane workspace <machine> read|write|exec|<command>", "  runpane watch --follow", "  runpane watch --until-event", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base-branch <branch>] [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] --yes", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) --yes [--json]", "  runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  runpane panels resume (--panel <panel-id>|--session <id|name>|--all-stopped) [--wait-ready] --yes [--json]", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json]", "  runpane panes git-status --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane panes commit --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes push --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes pull --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes rebase-main --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes restore --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane links create --pane <pane-id> [--panel <panel-id>] [--json]", "  runpane links open --url <pane-url> --yes [--json] [--pane-dir <path>]", "  runpane docs search --query <text> [--limit <count>] [--json]", "  runpane docs read --doc <path> [--json]", "  runpane agents start (--pane <pane-id> | --repo <selector> --name <name> [--base-branch <branch>]) (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> --yes [--json] [--pane-dir <path>]", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary-file <path|->] [--question <text>] [--json]", "  runpane inbox [--session <id|name>] [--json]", "  runpane inbox ack <item-id>... [--session <id|name>] [--json]", "  runpane panes squash-rebase --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes stash --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stash-pop --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes soft-reset --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes fetch --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes run-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stop-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes move --pane <pane-id> --folder <folder-id> --yes [--json] [--pane-dir <path>]", "  runpane folders list --repo <repo-id> [--json] [--pane-dir <path>]", "  runpane folders create --repo <repo-id> --name <name> --yes [--json] [--pane-dir <path>]", "  runpane help [command]", "", "Quick start:", "  npx --yes runpane@latest", "  npm i -g runpane && runpane setup", "", "Advanced examples:", "  npx --yes runpane@latest install client", "  npx --yes runpane@latest install daemon --label \"My Server\"", "  pnpm dlx runpane@latest", "", "Common commands:", "  runpane help", "  runpane setup", "  runpane install", "  runpane doctor", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json", "  runpane agent-context --command \"<command>\" --json", "", "Run \"runpane help panes create\" for pane orchestration options."];
             readonly install: readonly ["Usage:", "  runpane install [client|daemon] [options]", "", "Examples:", "  npx --yes runpane@latest install client", "  npx --yes runpane@latest install daemon --label \"My Server\"", "  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \"VM\"", "", "Wrapper options:", "  --version <latest|vX.Y.Z>        Pane release to install", "  --format <auto|appimage|deb|dmg|zip|exe>", "  --download-dir <path>", "  --pane-path <path>               Use an existing Pane executable", "  --dry-run                       Print the plan without downloading", "  --yes                           Skip interactive prompts where possible", "  --verbose", "", "Daemon passthrough options:", "  --label <name>", "  --prefer-tunnel <tailscale|ssh|manual|auto>", "  --channel <stable|nightly>", "  --base-url <url>", "  --pane-dir <path>", "  --listen-port <port> / --port <port>", "  --auto-listen-port", "  --interactive-tailscale-setup", "  --no-install-service", "  --no-tailscale-serve", "  --print-only", "  --repo-ref <ref>"];
             readonly setup: readonly ["Usage:", "  runpane setup", "", "Opens the guided setup for desktop install, remote host setup, update, and diagnostics.", "", "Quick start:", "  npx --yes runpane@latest", "  npm i -g runpane && runpane setup"];
             readonly update: readonly ["Usage:", "  runpane update [--pane-only | --cli-only] [--version <latest|vX.Y.Z>] [--pane-dir <path>] [--dry-run] [--wait] [--json]", "  runpane update --status <operation-id> [--wait] [--pane-dir <path>] [--json]", "", "Updates both Pane and the invoked supported CLI by default, on this machine.", "Preflight identifies the host and installation owner before downtime. The independent helper stages an app, CLI, and standalone Node runtime before stopping Pane.", "Status distinguishes acceptance, installed components, host health, and per-panel restoration. No prompts or uncertain actions are replayed.", "CLI-only updates do not restart Pane; a managed CLI pin survives later Pane startup.", "Use workspace <machine> exec -- runpane update for an explicit remote machine."];
@@ -1223,8 +1257,8 @@ export declare const RUNPANE_CONTRACT: {
             readonly "panes cost": readonly ["Usage:", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "", "Reports estimated token costs per Pane for the last 30 days, including per-model and cache-efficiency details.", "", "Options:", "  --repo <selector>              Limit results to one saved repository", "  --pane <pane-id>               Return one Pane, including an idle Pane with zero usage", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly workspace: readonly ["Workspace commands: this machine's Panes, and your other machines over Tailscale.", "", "Usage:", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow", "  runpane workspace list [--json]", "  runpane workspace <machine> read <path>", "  runpane workspace <machine> write <path>          (content from stdin)", "  runpane workspace <machine> exec -- <command>", "  runpane workspace <machine> <runpane command>      (any command that talks to Pane, e.g. sessions list --json)", "  runpane workspace enable|disable", "", "<machine> is a Tailscale name, unique prefix, or IP. Your own machines are reachable, and a teammate's machine when its owner set Who can connect to Everyone on tailnet.", "Without <machine>, read, write, and exec route a path that cannot exist here (C:\\... on a Mac) to the one joined machine it fits.", "Commands that only run here (doctor, agent-context, mcp, docs) run there with: runpane workspace <machine> exec -- 'runpane doctor'"];
             readonly "workspace state": readonly ["Usage:", "  runpane workspace state [--repo <selector>] [--json]", "", "Returns one workspace snapshot of every Pane and CLI panel."];
-            readonly watch: readonly ["Usage:", "  runpane watch                  Print what changed since your cursor, then exit", "  runpane watch --follow         Keep watching, tuned for an agent watching unattended", "  runpane watch --until-event    Wait for one event worth waking for, print it, exit 0", "", "Waits for agent, Pane, panel, and PR events from the daemon without polling.", "", "What --follow does by default (see defaults.watch.follow in the contract):", "  prints WATCH OK once when armed, then one line per event, with no heartbeats", "  kinds: agent.report, agent.ready, agent.blocked, agent.idle, panel.exited, panel.stopped,", "         pane.gone, pane.associated, pane.detached, pr.conflicted, pr.checks, pr.merged", "  READY after 3m of quiet; BLOCKED after 30s; other lines batched at most every 10m", "    (REPORT, BLOCKED, conflicts, and failed checks arrive at once)", "  IDLE reminders at 10m, 30m, 1h, 3h, then daily", "  ends with WATCH EXPIRED and exit 0 after 3h with nothing but IDLE", "", "What --until-event does by default: waits for agent.report, agent.blocked, panel.exited,", "or pane.gone, prints that one line, and exits 0. Run it as a background task, act on", "its line, then run it again; its named cursor means nothing is missed between runs.", "Single-event waits deliver immediately without follow settling or batching.", "--follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since.", "", "Options:", "  --session <id|name>            Watch every Pane in a Session; associate/detach apply live", "  --pane <id>                    Watch one Pane; repeatable (default: every managed Pane)", "  --exclude-pane <id>            Leave out a Pane; repeatable", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --include-shells               Include plain shell panels (default: agent panels only)", "  --kinds <kind,...>             Replace the default event kinds", "  --json                         One JSON object per line", "  --as <name>                    Name the cursor (default: from --session or this panel)", "  --since <generation>           Use an explicit cursor instead of a name", "  --epoch <epoch>                Pair with --since to detect journal resets", "  --from <now|earliest>          Where a new named cursor starts (default: now)", "  --self-test                    Check the daemon watch path and exit", "", "Overrides (durations such as 30s, 10m, 3h; a bare number is milliseconds; 0 turns it off):", "  --ready-settle <duration>      Quiet time before READY (default 3m)", "  --blocked-settle <duration>    Time before BLOCKED (default 30s)", "  --min-interval <duration>      Batch window for non-urgent lines (default 10m)", "  --idle-after <duration>        First IDLE reminder (default 10m)", "  --expire-after <duration>      End after this long with nothing but IDLE (default 3h)", "  --heartbeat <duration>         Print a HEARTBEAT line this often (default off)", "  --timeout-ms <duration>        Per-request wait; with --until-event, the total deadline (exit 124)", "  --limit <count>                Maximum entries per response", "  --ack-now                      At-most-once cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Turn off STUCK detection", "  --pane-dir <path>              Connect to a specific Pane data directory", "", "How a watch ends: WATCH EXPIRED (exit 0) means nothing happened; arm a new one with the next", "dispatch. A non-zero exit or a WATCH ERROR line means it failed: say so and re-arm once. Judge", "a watch by WATCH OK and these endings, never by silence. Never pipe --follow into grep -m1 or head.", "STUCK means real unsubmitted composer text; a prompt suggestion never counts."];
-            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.", "", "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree directory name; defaults to --name", "  --branch <name>                Exact new branch name (slashes kept); must not exist; defaults to the worktree name", "  --base-branch <ref>            Ref to branch from; --base is an alias", "  --agent <codex|claude|cursor>  Built-in terminal template; with --tool-command, the agent it runs", "  --tool-command <command>       Custom terminal command", "  --title <title>                Terminal tab title", "  --initial-input <text>         Text sent after the command is ready", "  --prompt <text>                Alias for --initial-input", "  --initial-input-file <path|->  Read initial input from a file or stdin", "  --as-file-pointer              Send `Read and follow <prompt file>` instead of the prompt", "  --prompt-file <path|->         Alias for --initial-input-file", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for the agent's input box, then deliver and verify the prompt", "  --ready-timeout-ms <ms>        Readiness wait timeout; defaults to 30000", "  --concurrency <count>          Accepted; creation is currently serialized", "  --source <user|agent>          Mark mutation source; agent implies background creation", "  --no-focus                     Create in the background without stealing focus", "  --focus                        Explicitly focus the created pane", "  --pinned                       Request pinning at creation; first Session association clears it", "  --no-pinned                    Create unpinned (the UI's favorite/pin star)", "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without creating panes", "  --yes                          Skip confirmation for mutating commands", "", "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."];
+            readonly watch: readonly ["Usage:", "  runpane watch                  Print what changed since your cursor, then exit", "  runpane watch --follow         Keep watching, tuned for an agent watching unattended", "  runpane watch --until-event    Wait for one event worth waking for, print it, exit 0", "", "Waits for agent, Pane, panel, and PR events from the daemon without polling.", "", "What --follow does by default (see defaults.watch.follow in the contract):", "  prints WATCH OK once when armed, then one line per event, with no heartbeats", "  kinds: agent.report, agent.ready, agent.blocked, agent.idle, panel.exited, panel.stopped,", "         pane.gone, pane.associated, pane.detached, pr.conflicted, pr.checks, pr.merged,", "         pr.base_changed, pr.base_deleted", "  READY after 3m of quiet; BLOCKED after 30s; other lines batched at most every 10m", "    (REPORT, BLOCKED, conflicts, base changes, and failed checks arrive at once)", "  IDLE reminders at 10m, 30m, 1h, 3h, then daily", "  ends with WATCH EXPIRED and exit 0 after 3h with nothing but IDLE", "", "What --until-event does by default: waits for agent.report, agent.blocked, panel.exited,", "or pane.gone, prints that one line, and exits 0. Run it as a background task, act on", "its line, then run it again; its named cursor means nothing is missed between runs.", "Single-event waits deliver immediately without follow settling or batching.", "--follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since.", "agent.report.missing (an agent given work ended its turn or exited without `runpane report`) is opt-in:", "add it to --kinds to wake on MISSING REPORT too.", "", "Options:", "  --session <id|name>            Watch every Pane in a Session; associate/detach apply live", "  --pane <id>                    Watch one Pane; repeatable (default: every managed Pane)", "  --exclude-pane <id>            Leave out a Pane; repeatable", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --include-shells               Include plain shell panels (default: agent panels only)", "  --kinds <kind,...>             Replace the default event kinds", "  --json                         One JSON object per line", "  --as <name>                    Name the cursor (default: from --session or this panel)", "  --since <generation>           Use an explicit cursor instead of a name", "  --epoch <epoch>                Pair with --since to detect journal resets", "  --from <now|earliest>          Where a new named cursor starts (default: now)", "  --self-test                    Check the daemon watch path and exit", "", "Overrides (durations such as 30s, 10m, 3h; a bare number is milliseconds; 0 turns it off):", "  --ready-settle <duration>      Quiet time before READY (default 3m)", "  --blocked-settle <duration>    Time before BLOCKED (default 30s)", "  --min-interval <duration>      Batch window for non-urgent lines (default 10m)", "  --idle-after <duration>        First IDLE reminder (default 10m)", "  --expire-after <duration>      End after this long with nothing but IDLE (default 3h)", "  --heartbeat <duration>         Print a HEARTBEAT line this often (default off)", "  --timeout-ms <duration>        Per-request wait; with --until-event, the total deadline (exit 124)", "  --limit <count>                Maximum entries per response", "  --ack-now                      At-most-once cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Turn off STUCK detection", "  --pane-dir <path>              Connect to a specific Pane data directory", "", "How a watch ends: WATCH EXPIRED (exit 0) means nothing happened; arm a new one with the next", "dispatch. A non-zero exit or a WATCH ERROR line means it failed: say so and re-arm once. Judge", "a watch by WATCH OK and these endings, never by silence. Never pipe --follow into grep -m1 or head.", "STUCK means real unsubmitted composer text; a prompt suggestion never counts."];
+            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.", "", "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree directory name; defaults to --name", "  --branch <name>                Exact new branch name (slashes kept); must not exist; defaults to the worktree name", "  --base-branch <ref>            Ref to branch from; --base is an alias", "  --agent <codex|claude|cursor>  Built-in terminal template; with --tool-command, the agent it runs", "  --tool-command <command>       Custom terminal command", "  --title <title>                Terminal tab title", "  --initial-input <text>         Text sent after the command is ready", "  --prompt <text>                Alias for --initial-input", "  --initial-input-file <path|->  Read initial input from a file or stdin", "  --as-file-pointer              Send `Read and follow <prompt file>` instead of the prompt", "  --attach <file>                Copy a file beside the prompt file and list it; repeatable", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --prompt-file <path|->         Alias for --initial-input-file", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for the agent's input box, then deliver and verify the prompt", "  --ready-timeout-ms <ms>        Readiness wait timeout; defaults to 30000", "  --concurrency <count>          Accepted; creation is currently serialized", "  --source <user|agent>          Mark mutation source; agent implies background creation", "  --no-focus                     Create in the background without stealing focus", "  --focus                        Explicitly focus the created pane", "  --pinned                       Request pinning at creation; first Session association clears it", "  --no-pinned                    Create unpinned (the UI's favorite/pin star)", "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without creating panes", "  --yes                          Skip confirmation for mutating commands", "", "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."];
             readonly "panes adopt": readonly ["Usage:", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [options]", "", "Adopts an existing externally managed git worktree without creating, syncing, or deleting it. Archiving only removes its worktree with `panes archive --remove-worktree`. To start new work on a named branch, use `panes create --base <ref> --branch <name>` instead of `git worktree add` plus adopt.", "", "Options: --resume <id> stages the agent resume command (built-in agents only); --launch runs the command immediately; --prompt <text> or --prompt-file <path|-> and --wait-ready require --launch; --folder <name> groups the pane; --no-pinned opts out of pinning; --no-associate skips automatic Session association; --dry-run previews.", "", "With --tool-command, --agent names the agent the command runs (a wrapper such as `agent-farm run`): Pane launches the command unchanged and treats the panel as that agent. Without --agent, Pane detects Claude Code, Codex and Cursor from the foreground process or the agent's screen, and --wait-ready waits for the detected agent's input box; a command that never shows a supported agent is not ready and nothing is typed into it."];
             readonly "panes archive": readonly ["Usage:", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes [--json]", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--source user|agent] [--dry-run] --yes [--json]", "", "Archives a Pane (session) exactly like the UI Archive action, including removal of its Pane-managed git worktree. Refreshes the configured upstream before checking for unpushed commits and reports exact commit evidence. When the branch has no upstream or its upstream is gone, a merged GitHub pull request whose head is HEAD (found with `gh`) counts as pushed. Refuses unsafe archives unless --force is passed. An adopted worktree is kept unless --remove-worktree is passed, which applies the same safety check and removal. The local branch is always kept. With --session and --merged, archives every Pane associated with the Session whose work is clean and pushed or merged, and reports a reason for each Pane it skips. Use --dry-run to print the evidence without mutating Pane state.", "", "Options:", "  --pane <pane-id>               Pane/session id to archive", "  --source <user|agent>          Mark mutation source", "  --force                        Archive even if the pane has uncommitted, untracked, or unpushed changes", "  --remove-worktree              Also check and remove an adopted Pane's worktree (the branch is kept)", "  --session <id|name>            Archive the Panes associated with this Session (requires --merged)", "  --merged                       Only archive Panes that are clean and pushed, or merged via a PR", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Refresh and print archive safety evidence without archiving", "  --yes                          Skip confirmation for mutating commands"];
             readonly "panes pin": readonly ["Usage:", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "", "Declaratively pins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.", "", "Options:", "  --pane <pane-id>               Pane/session id to pin", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without pinning the pane", "  --yes                          Skip confirmation for mutating commands"];
@@ -1239,9 +1273,9 @@ export declare const RUNPANE_CONTRACT: {
             readonly mcp: readonly ["Usage:", "  runpane mcp [--toolsets <name,...>] [--read-only]", "", "Runs the Pane MCP server over stdio. Each runpane command with a JSON result becomes a tool that returns the same JSON as `runpane <command> --json`. Commands that need --yes take `yes: true` instead.", "Pane registers this server with Claude Code, Codex, and Cursor automatically (Settings > AI & Agents). To register it by hand:", "  claude mcp add --scope user pane -- npx --yes runpane@latest mcp", "  codex mcp add pane -- npx --yes runpane@latest mcp", "", "The MCP server ships in the npm package and inside the Pane app. The Python package does not include it.", "", "Options:", "  --toolsets <name,...>          core (default), all, read, repos, panes, panels, agents, sessions, git, docs, links, admin", "  --read-only                    Serve only read-only tools"];
             readonly "agents doctor": readonly ["Usage:", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "", "Diagnoses whether Codex or Claude is available in the same repository environment Pane will use.", "", "Options:", "  --agent <codex|claude|cursor>         Built-in agent command to diagnose", "  --repo <selector>              active, id, exact path, or saved repository name; defaults to active", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly "panels screen": readonly ["Usage:", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "", "Reads a compact current-screen view from a terminal panel. Prefers alternate-screen/TUI output and falls back to recent scrollback.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --limit <count>                Maximum lines to return; defaults to 80", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
-            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] --yes [--json]", "", "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.", "", "For a Claude or Codex panel with no composer on screen, nothing is sent: the result is ok: false with blocked.kind composer-unknown.", "", "Multi-line or long (over 512 characters) text reaches a Claude or Codex composer as one bracketed paste: CRLF becomes LF, and the submit key goes as its own write once the paste has settled, even while the agent is working.", "", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --text <text>                  Text to submit before Enter", "  --input-file <path|->          Read text from a file or stdin before Enter", "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command", "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"];
+            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer [--attach <file>]...] [--interrupt] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json]", "", "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.", "", "For a Claude or Codex panel with no composer on screen, nothing is sent: the result is ok: false with blocked.kind composer-unknown.", "", "Multi-line or long (over 512 characters) text reaches a Claude or Codex composer as one bracketed paste: CRLF becomes LF, and the submit key goes as its own write once the paste has settled, even while the agent is working.", "", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "", "Optional --wait returns a per-dispatch result; the orchestrator guide uses submit without --wait and a named watch. Choose one completion consumer.", "It returns once, with a compact result: outcome, ids, the report (state, summary,", "summaryPath, PR, head, question), screenLines for a prompt, or lastOutput for a missing", "report. Answer a blocked panel with `panels submit --no-expect-report`,", "then watch for the original result.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --text <text>                  Text to submit before Enter", "  --input-file <path|->          Read text from a file or stdin before Enter", "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`", "  --attach <file>                Copy a file beside the prompt file and list it; repeatable", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command", "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"];
             readonly "panels wait": readonly ["Usage:", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--contains <text>] [--timeout-ms <ms>] [--interval-ms <ms>] [--json]", "", "Polls a terminal panel until it is initialized, ready, idle, or contains text. Output is intentionally small and includes next-step guidance.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --for <condition>              initialized, ready, idle, or text; defaults to ready for CLI panels and idle otherwise", "  --contains <text>              Text required for --for text; implies --for text when omitted", "  --timeout-ms <milliseconds>    Wait timeout; defaults to 30000", "  --interval-ms <milliseconds>   Poll interval; defaults to 500", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
-            readonly "panels create": readonly ["Create a terminal-backed tool panel inside an existing Pane session.", "", "Usage:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--title <title>] [--initial-input <text>] [--no-focus] [--wait-ready] --yes [--json]", "  runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--no-focus] [--wait-ready] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor> Built-in agent command template, or with --tool-command the agent it runs.", "  --tool-command <command>      Custom terminal command to launch.", "  --title <title>               Panel title override.", "  --initial-input, --prompt     Initial input to send after the tool starts.", "  --initial-input-file <path|-> Read initial input from a file or stdin.", "  --as-file-pointer             Send `Read and follow <prompt file>` instead of the prompt.", "  --no-focus                    Create the panel in the background.", "  --focus                       Explicitly focus the created panel.", "  --source <user|agent>         Mark the mutation source; agent implies background creation.", "  --wait-ready                  Wait for the agent's input box, then deliver and verify the prompt.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
+            readonly "panels create": readonly ["Create a terminal-backed tool panel inside an existing Pane session.", "", "Usage:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--title <title>] [--initial-input <text>] [--no-focus] [--wait-ready] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json]", "  runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--no-focus] [--wait-ready] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor> Built-in agent command template, or with --tool-command the agent it runs.", "  --tool-command <command>      Custom terminal command to launch.", "  --title <title>               Panel title override.", "  --initial-input, --prompt     Initial input to send after the tool starts.", "  --initial-input-file <path|-> Read initial input from a file or stdin.", "  --as-file-pointer             Send `Read and follow <prompt file>` instead of the prompt.", "  --attach <file>               Copy a file beside the prompt file and list it; repeatable.", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --no-focus                    Create the panel in the background.", "  --focus                       Explicitly focus the created panel.", "  --source <user|agent>         Mark the mutation source; agent implies background creation.", "  --wait-ready                  Wait for the agent's input box, then deliver and verify the prompt.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "panels open": readonly ["Open a URL or file as a browser/editor tab in a Pane, in split view beside the agent by default.", "", "Usage:", "  runpane panels open [--pane <pane-id>] (--url <url>|--file <path>) [--title <title>] [--split|--tab] [--focus|--no-focus] [--source user|agent] --yes [--json]", "", "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: files open in an editor tab with read-only previews for supported formats; HTML opens as editable source. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.", "", "Options:", "  --pane <pane-id>              Pane to open the tab in; defaults to PANE_SESSION_ID.", "  --url <url>                   http(s) or file URL to open in a browser tab.", "  --file <path>                 File inside the Pane worktree (relative, Linux, Windows, or WSL UNC path).", "  --title <title>               Tab title override.", "  --split                       Open in split view beside the agent (default).", "  --tab                         Open in the current tab group instead.", "  --no-focus                    Open without selecting the tab.", "  --focus                       Select the tab (default); never raises the window.", "  --source <user|agent>         Mutation source.", "  --pane-dir <path>             Connect to a specific Pane data directory.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "panels submit-composer": readonly ["Submit an agent composer using the panel-appropriate key sequence.", "", "Usage:", "  runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "", "Options:", "  --panel <panel-id>            Terminal panel id.", "  --strategy <strategy>         Defaults to auto; Codex queues with Tab while working and submits with Enter when ready. auto retries once if the text is still in the composer.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "sessions list": readonly ["Usage:", "runpane sessions list [--json] [--pane-dir <path>]", "", "Options:", "  --session <id|name>         Named Session id or exact name.", "  --from-json <path|->         Read structured JSON from a file or stdin.", "  --pane <pane-id>             User-visible Pane to associate or detach.", "  --agent <codex|claude|cursor>  Agent terminal to use.", "  --json                       Print JSON output."];
@@ -1289,15 +1323,17 @@ export declare const RUNPANE_CONTRACT: {
             readonly "workspace read": readonly ["Usage:", "  runpane workspace [<machine>] read <path> [--json]", "", "Print a file from a machine on your tailnet; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).", "", "Options:", "  <machine>                       Tailscale machine name, unique prefix, MagicDNS name, or Tailscale IP. Omit it to route a path that cannot exist here to the one joined machine it fits.", "  <path>                          Absolute path in any form; ~ is that machine's home.", "  --json                          Print machine-readable output."];
             readonly "workspace write": readonly ["Usage:", "  runpane workspace [<machine>] write <path> [--json]", "", "Write stdin to a file on a machine on your tailnet, creating parent folders.", "", "Options:", "  <machine>                       Tailscale machine name, unique prefix, MagicDNS name, or Tailscale IP. Omit it to route a path that cannot exist here to the one joined machine it fits.", "  <path>                          Absolute path in any form.", "  --json                          Print machine-readable output."];
             readonly "workspace exec": readonly ["Usage:", "  runpane workspace <machine> exec [--cwd <path>] [--timeout-ms <ms>] [--json] -- <command>", "", "Run a command in another machine's shell and return stdout, stderr, the exit code, OS, and shell.", "", "Options:", "  <machine>                       Tailscale machine name, unique prefix, MagicDNS name, or Tailscale IP. Omit it to route a path that cannot exist here to the one joined machine it fits.", "  --cwd <path>                    Working directory on that machine, in any path form; defaults to its home.", "  --timeout-ms <milliseconds>     Stop the command after this long (default 120000, at most 540000).", "  --json                          Print machine-readable output.", "  -- <command>                    The command line, run by that machine's shell."];
-            readonly handoff: readonly ["Usage:", "  runpane handoff --template", "  runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--dry-run] [--json]", "", "Hand your task to a fresh agent. You write the note (runpane handoff --template); the CLI checks it,", "makes sure your branch is pushed, sends the note to the destination, and starts the agent there.", "From a Session's terminal it skips git and creates the Session on the other machine, with the note as", "its next action; the new Session waits for your first message. The sender Session stays.", "", "Options:", "  <destination>                   Freeform: agent, model, effort, and machine, such as \"codex gpt-5 high on parsas-macbook-pro\".", "  --template                      Print the note template, with this checkout's (or Session's) origin and git state filled in.", "  --note-file <path|->            The note to check and send; every template section must be filled in.", "  --machine <name>                Destination machine (Tailscale name or unique prefix); overrides the text.", "  --agent <codex|claude|cursor>   Receiving agent; overrides the text.", "  --model <model>                 Model for the receiving agent; overrides the text.", "  --effort <level>                minimal, low, medium, high, xhigh, or max; supported for Claude and Codex only; overrides the text. Cursor effort is rejected.", "  --repo <selector>               Saved repository on the destination; defaults to the one with the same remote.", "  --push                          Commit uncommitted work (not the note) as WIP and push the branch first (never forces).", "  --dry-run                       Check destination reachability, saved repo and OS; print note and git state; send nothing. From a Session: the name it would get.", "  --json                          Print machine-readable output.", "", "Examples:", "  runpane handoff --template > ~/handoff.md", "  runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md --push", "  runpane handoff \"codex gpt-5 high on parsa-devbox\" --note-file ~/handoff.md --dry-run"];
+            readonly handoff: readonly ["Usage:", "  runpane handoff --template", "  runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor|opencode>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--note-only] [--dry-run] [--json]", "", "Hand your task to another agent. You write the note (runpane handoff --template); the CLI checks it,", "makes sure your branch is pushed, sends the note to the destination, and starts the agent there.", "From a Pane tab, a handoff to the same agent (Claude, Codex, Cursor or OpenCode) carries your own session:", "another machine resumes a copy of it, this machine resumes a fork. The CLI then checks the receiver", "continued it (continued, inconclusive, or not-continued, which exits 1 and keeps the receiver).", "--note-only, another agent, or no session to carry starts a fresh agent with the note instead.", "From a Session's terminal it skips git and creates the Session on the other machine; a same-agent", "Session resumes your conversation when first opened, otherwise it reads the note. The sender Session stays.", "", "Options:", "  <destination>                   Freeform: agent, model, effort, and machine, such as \"codex gpt-5 high on parsas-macbook-pro\".", "  --template                      Print the note template, with this checkout's (or Session's) origin and git state filled in.", "  --note-file <path|->            The note to check and send; every template section must be filled in.", "  --machine <name>                Destination machine (Tailscale name or unique prefix); overrides the text.", "  --agent <codex|claude|cursor>   Receiving agent; overrides the text.", "  --model <model>                 Model for the receiving agent; overrides the text.", "  --effort <level>                minimal, low, medium, high, xhigh, or max; supported for Claude and Codex only; overrides the text. Cursor effort is rejected.", "  --repo <selector>               Saved repository on the destination; defaults to the one with the same remote.", "  --push                          Commit uncommitted work (not the note) as WIP and push the branch first (never forces).", "  --note-only                     Start a fresh agent with the note instead of carrying your own session.", "  --dry-run                       Check destination reachability, saved repo and OS; print note and git state; send nothing. From a Session: the name it would get.", "  --json                          Print machine-readable output.", "", "Examples:", "  runpane handoff --template > ~/handoff.md", "  runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md --push", "  runpane handoff \"codex gpt-5 high on parsa-devbox\" --note-file ~/handoff.md --dry-run"];
             readonly "sessions pin": readonly ["Usage:", "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]", "", "Set the named Session pin star on. Repeated requests keep that state. Uses the same Session update path as the UI."];
             readonly "sessions unpin": readonly ["Usage:", "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]", "", "Set the named Session pin star off. Repeated requests keep that state. Uses the same Session update path as the UI."];
             readonly "pr watch": readonly ["runpane pr watch [--pane <id>] --url <PR URL> [--head <full-sha>] [--json] [--pane-dir <path>]", "", "Register durable GitHub PR monitoring for a Pane."];
             readonly "pr unwatch": readonly ["runpane pr unwatch [--pane <id>] --url <PR URL> [--json] [--pane-dir <path>]", "", "Remove a Pane’s explicit PR registration."];
             readonly "pr list": readonly ["runpane pr list [--pane <id>] [--json] [--pane-dir <path>]", "", "List PR registrations and stopped watches."];
+            readonly inbox: readonly ["Usage:", "  runpane inbox [--session <id|name>] [--json] [--pane-dir <path>]", "", "Lists what a Session's orchestrator has not acknowledged: worker reports (agent.report),", "missing reports (agent.report.missing), and questions waiting on a worker's screen", "(agent.blocked; these clear themselves once the worker moves on). Pane keeps them across", "restarts. An orchestrator reads it when it starts or resumes, to catch what finished while it was down.", "", "Options:", "  --session <id|name>            Session; defaults to PANE_ORCHESTRATION_SESSION_ID", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "", "Clear handled items with `runpane inbox ack <item-id>...`."];
+            readonly "inbox ack": readonly ["Usage:", "  runpane inbox ack <item-id>... [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane inbox ack --all --session <id|name> [--json] [--pane-dir <path>]", "", "Clears Session inbox items. Ids that match nothing are listed as unknown; acknowledging twice is harmless.", "", "Options:", "  --session <id|name>            Only clear items of this Session; required with --all", "  --all                          Clear every item of the Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
         };
         readonly pip: {
-            readonly default: readonly ["Usage:", "  runpane", "  runpane setup", "  runpane install [client|daemon] [options]", "  runpane update [options]", "  runpane version", "  runpane doctor", "  runpane doctor --report --body-file <path|->", "  runpane daemon repair [--pane-dir <path>] [--yes] [--json]", "  runpane agent-context [--json]", "  runpane mcp [--toolsets <name,...>] [--read-only]", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "  runpane repos list [--json]", "  runpane repos add --path <path> [--name <name>]", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow", "  runpane watch --until-event", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base-branch <branch>] [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes", "  python -m runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] --yes", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) --yes [--json]", "  runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  runpane panels resume (--panel <panel-id>|--session <id|name>|--all-stopped) [--wait-ready] --yes [--json]", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json]", "  runpane panes git-status --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane panes commit --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes push --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes pull --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes rebase-main --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes restore --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane links create --pane <pane-id> [--panel <panel-id>] [--json]", "  runpane links open --url <pane-url> --yes [--json] [--pane-dir <path>]", "  runpane docs search --query <text> [--limit <count>] [--json]", "  runpane docs read --doc <path> [--json]", "  runpane agents start (--pane <pane-id> | --repo <selector> --name <name> [--base-branch <branch>]) (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> --yes [--json] [--pane-dir <path>]", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary-file <path|->] [--question <text>] [--json]", "  runpane panes squash-rebase --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes stash --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stash-pop --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes soft-reset --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes fetch --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes run-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stop-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes move --pane <pane-id> --folder <folder-id> --yes [--json] [--pane-dir <path>]", "  runpane folders list --repo <repo-id> [--json] [--pane-dir <path>]", "  runpane folders create --repo <repo-id> --name <name> --yes [--json] [--pane-dir <path>]", "  runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane help [command]", "", "Quick start:", "  pipx run runpane", "  python -m pip install runpane && python -m runpane setup", "", "Advanced examples:", "  pipx run runpane install client", "  pipx run runpane install daemon --label \"My Server\"", "  uvx runpane@latest", "", "Common commands:", "  runpane help", "  runpane setup", "  runpane install", "  runpane doctor", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json", "  runpane agent-context --command \"<command>\" --json", "", "Run \"runpane help panes create\" for pane orchestration options."];
+            readonly default: readonly ["Usage:", "  runpane", "  runpane setup", "  runpane install [client|daemon] [options]", "  runpane update [options]", "  runpane version", "  runpane doctor", "  runpane doctor --report --body-file <path|->", "  runpane daemon repair [--pane-dir <path>] [--yes] [--json]", "  runpane agent-context [--json]", "  runpane mcp [--toolsets <name,...>] [--read-only]", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "  runpane repos list [--json]", "  runpane repos add --path <path> [--name <name>]", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow", "  runpane watch --until-event", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base-branch <branch>] [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes", "  python -m runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] --yes", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) --yes [--json]", "  runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  runpane panels resume (--panel <panel-id>|--session <id|name>|--all-stopped) [--wait-ready] --yes [--json]", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json]", "  runpane panes git-status --pane <pane-id> [--json] [--pane-dir <path>]", "  runpane panes commit --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes push --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes pull --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes rebase-main --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes restore --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane links create --pane <pane-id> [--panel <panel-id>] [--json]", "  runpane links open --url <pane-url> --yes [--json] [--pane-dir <path>]", "  runpane docs search --query <text> [--limit <count>] [--json]", "  runpane docs read --doc <path> [--json]", "  runpane agents start (--pane <pane-id> | --repo <selector> --name <name> [--base-branch <branch>]) (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> --yes [--json] [--pane-dir <path>]", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary-file <path|->] [--question <text>] [--json]", "  runpane inbox [--session <id|name>] [--json]", "  runpane inbox ack <item-id>... [--session <id|name>] [--json]", "  runpane panes squash-rebase --pane <pane-id> --message <message> --yes [--json] [--pane-dir <path>]", "  runpane panes stash --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stash-pop --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes soft-reset --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes fetch --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes run-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes stop-script --pane <pane-id> --yes [--json] [--pane-dir <path>]", "  runpane panes move --pane <pane-id> --folder <folder-id> --yes [--json] [--pane-dir <path>]", "  runpane folders list --repo <repo-id> [--json] [--pane-dir <path>]", "  runpane folders create --repo <repo-id> --name <name> --yes [--json] [--pane-dir <path>]", "  runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "  runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane help [command]", "", "Quick start:", "  pipx run runpane", "  python -m pip install runpane && python -m runpane setup", "", "Advanced examples:", "  pipx run runpane install client", "  pipx run runpane install daemon --label \"My Server\"", "  uvx runpane@latest", "", "Common commands:", "  runpane help", "  runpane setup", "  runpane install", "  runpane doctor", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json", "  runpane agent-context --command \"<command>\" --json", "", "Run \"runpane help panes create\" for pane orchestration options."];
             readonly install: readonly ["Usage:", "  runpane install [client|daemon] [options]", "", "Examples:", "  npx --yes runpane@latest install daemon --label \"My Server\"", "  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \"VM\"", "  pipx run runpane install daemon --label \"My Server\"", "", "Wrapper options:", "  --version <latest|vX.Y.Z>", "  --format <auto|appimage|deb|dmg|zip|exe>", "  --download-dir <path>", "  --pane-path <path>", "  --dry-run", "  --yes", "  --verbose", "", "Daemon passthrough options:", "  --label <name>", "  --prefer-tunnel <tailscale|ssh|manual|auto>", "  --channel <stable|nightly>", "  --base-url <url>", "  --pane-dir <path>", "  --listen-port <port> / --port <port>", "  --auto-listen-port", "  --interactive-tailscale-setup", "  --no-install-service", "  --no-tailscale-serve", "  --print-only", "  --repo-ref <ref>"];
             readonly setup: readonly ["Usage:", "  runpane setup", "", "Opens the guided setup for desktop install, remote host setup, update, and diagnostics.", "", "Quick start:", "  pipx run runpane", "  python -m pip install runpane && python -m runpane setup"];
             readonly update: readonly ["Usage:", "  runpane update [--pane-only | --cli-only] [--version <latest|vX.Y.Z>] [--pane-dir <path>] [--dry-run] [--wait] [--json]", "  runpane update --status <operation-id> [--wait] [--pane-dir <path>] [--json]", "", "Updates both Pane and the invoked supported CLI by default, on this machine.", "Preflight identifies the host and installation owner before downtime. The independent helper stages an app, CLI, and standalone Node runtime before stopping Pane.", "Status distinguishes acceptance, installed components, host health, and per-panel restoration. No prompts or uncertain actions are replayed.", "CLI-only updates do not restart Pane; a managed CLI pin survives later Pane startup.", "Use workspace <machine> exec -- runpane update for an explicit remote machine."];
@@ -1311,8 +1347,8 @@ export declare const RUNPANE_CONTRACT: {
             readonly "panes cost": readonly ["Usage:", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "", "Reports estimated token costs per Pane for the last 30 days, including per-model and cache-efficiency details.", "", "Options:", "  --repo <selector>", "  --pane <pane-id>", "  --pane-dir <path>", "  --json"];
             readonly workspace: readonly ["Workspace commands: this machine's Panes, and your other machines over Tailscale.", "", "Usage:", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow", "", "runpane workspace list|read|write|exec|enable|disable ship in the npm package: npx --yes runpane@latest workspace list"];
             readonly "workspace state": readonly ["Usage:", "  runpane workspace state [--repo <selector>] [--json]", "", "Returns one workspace snapshot of every Pane and CLI panel."];
-            readonly watch: readonly ["Usage:", "  runpane watch                  Print what changed since your cursor, then exit", "  runpane watch --follow         Keep watching, tuned for an agent watching unattended", "  runpane watch --until-event    Wait for one event worth waking for, print it, exit 0", "", "Waits for agent, Pane, panel, and PR events from the daemon without polling.", "", "What --follow does by default (see defaults.watch.follow in the contract):", "  prints WATCH OK once when armed, then one line per event, with no heartbeats", "  kinds: agent.report, agent.ready, agent.blocked, agent.idle, panel.exited, panel.stopped,", "         pane.gone, pane.associated, pane.detached, pr.conflicted, pr.checks, pr.merged", "  READY after 3m of quiet; BLOCKED after 30s; other lines batched at most every 10m", "    (REPORT, BLOCKED, conflicts, and failed checks arrive at once)", "  IDLE reminders at 10m, 30m, 1h, 3h, then daily", "  ends with WATCH EXPIRED and exit 0 after 3h with nothing but IDLE", "", "What --until-event does by default: waits for agent.report, agent.blocked, panel.exited,", "or pane.gone, prints that one line, and exits 0. Run it as a background task, act on", "its line, then run it again; its named cursor means nothing is missed between runs.", "Single-event waits deliver immediately without follow settling or batching.", "--follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since.", "", "Options:", "  --session <id|name>            Watch every Pane in a Session; associate/detach apply live", "  --pane <id>                    Watch one Pane; repeatable (default: every managed Pane)", "  --exclude-pane <id>            Leave out a Pane; repeatable", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --include-shells               Include plain shell panels (default: agent panels only)", "  --kinds <kind,...>             Replace the default event kinds", "  --json                         One JSON object per line", "  --as <name>                    Name the cursor (default: from --session or this panel)", "  --since <generation>           Use an explicit cursor instead of a name", "  --epoch <epoch>                Pair with --since to detect journal resets", "  --from <now|earliest>          Where a new named cursor starts (default: now)", "  --self-test                    Check the daemon watch path and exit", "", "Overrides (durations such as 30s, 10m, 3h; a bare number is milliseconds; 0 turns it off):", "  --ready-settle <duration>      Quiet time before READY (default 3m)", "  --blocked-settle <duration>    Time before BLOCKED (default 30s)", "  --min-interval <duration>      Batch window for non-urgent lines (default 10m)", "  --idle-after <duration>        First IDLE reminder (default 10m)", "  --expire-after <duration>      End after this long with nothing but IDLE (default 3h)", "  --heartbeat <duration>         Print a HEARTBEAT line this often (default off)", "  --timeout-ms <duration>        Per-request wait; with --until-event, the total deadline (exit 124)", "  --limit <count>                Maximum entries per response", "  --ack-now                      At-most-once cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Turn off STUCK detection", "  --pane-dir <path>              Connect to a specific Pane data directory", "", "How a watch ends: WATCH EXPIRED (exit 0) means nothing happened; arm a new one with the next", "dispatch. A non-zero exit or a WATCH ERROR line means it failed: say so and re-arm once. Judge", "a watch by WATCH OK and these endings, never by silence. Never pipe --follow into grep -m1 or head.", "STUCK means real unsubmitted composer text; a prompt suggestion never counts."];
-            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  python -m runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.", "", "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree directory name; defaults to --name", "  --branch <name>                Exact new branch name (slashes kept); must not exist; defaults to the worktree name", "  --base-branch <ref>            Ref to branch from; --base is an alias", "  --agent <codex|claude|cursor>  Built-in terminal template; with --tool-command, the agent it runs", "  --tool-command <command>       Custom terminal command", "  --title <title>                Terminal tab title", "  --initial-input <text>         Text sent after the command is ready", "  --prompt <text>                Alias for --initial-input", "  --initial-input-file <path|->  Read initial input from a file or stdin", "  --as-file-pointer              Send `Read and follow <prompt file>` instead of the prompt", "  --prompt-file <path|->         Alias for --initial-input-file", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for the agent's input box, then deliver and verify the prompt", "  --ready-timeout-ms <ms>        Readiness wait timeout; defaults to 30000", "  --concurrency <count>          Accepted; creation is currently serialized", "  --source <user|agent>          Mark mutation source; agent implies background creation", "  --no-focus                     Create in the background without stealing focus", "  --focus                        Explicitly focus the created pane", "  --pinned                       Request pinning at creation; first Session association clears it", "  --no-pinned                    Create unpinned (the UI's favorite/pin star)", "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without creating panes", "  --yes                          Skip confirmation for mutating commands", "", "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."];
+            readonly watch: readonly ["Usage:", "  runpane watch                  Print what changed since your cursor, then exit", "  runpane watch --follow         Keep watching, tuned for an agent watching unattended", "  runpane watch --until-event    Wait for one event worth waking for, print it, exit 0", "", "Waits for agent, Pane, panel, and PR events from the daemon without polling.", "", "What --follow does by default (see defaults.watch.follow in the contract):", "  prints WATCH OK once when armed, then one line per event, with no heartbeats", "  kinds: agent.report, agent.ready, agent.blocked, agent.idle, panel.exited, panel.stopped,", "         pane.gone, pane.associated, pane.detached, pr.conflicted, pr.checks, pr.merged,", "         pr.base_changed, pr.base_deleted", "  READY after 3m of quiet; BLOCKED after 30s; other lines batched at most every 10m", "    (REPORT, BLOCKED, conflicts, base changes, and failed checks arrive at once)", "  IDLE reminders at 10m, 30m, 1h, 3h, then daily", "  ends with WATCH EXPIRED and exit 0 after 3h with nothing but IDLE", "", "What --until-event does by default: waits for agent.report, agent.blocked, panel.exited,", "or pane.gone, prints that one line, and exits 0. Run it as a background task, act on", "its line, then run it again; its named cursor means nothing is missed between runs.", "Single-event waits deliver immediately without follow settling or batching.", "--follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since.", "agent.report.missing (an agent given work ended its turn or exited without `runpane report`) is opt-in:", "add it to --kinds to wake on MISSING REPORT too.", "", "Options:", "  --session <id|name>            Watch every Pane in a Session; associate/detach apply live", "  --pane <id>                    Watch one Pane; repeatable (default: every managed Pane)", "  --exclude-pane <id>            Leave out a Pane; repeatable", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --include-shells               Include plain shell panels (default: agent panels only)", "  --kinds <kind,...>             Replace the default event kinds", "  --json                         One JSON object per line", "  --as <name>                    Name the cursor (default: from --session or this panel)", "  --since <generation>           Use an explicit cursor instead of a name", "  --epoch <epoch>                Pair with --since to detect journal resets", "  --from <now|earliest>          Where a new named cursor starts (default: now)", "  --self-test                    Check the daemon watch path and exit", "", "Overrides (durations such as 30s, 10m, 3h; a bare number is milliseconds; 0 turns it off):", "  --ready-settle <duration>      Quiet time before READY (default 3m)", "  --blocked-settle <duration>    Time before BLOCKED (default 30s)", "  --min-interval <duration>      Batch window for non-urgent lines (default 10m)", "  --idle-after <duration>        First IDLE reminder (default 10m)", "  --expire-after <duration>      End after this long with nothing but IDLE (default 3h)", "  --heartbeat <duration>         Print a HEARTBEAT line this often (default off)", "  --timeout-ms <duration>        Per-request wait; with --until-event, the total deadline (exit 124)", "  --limit <count>                Maximum entries per response", "  --ack-now                      At-most-once cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Turn off STUCK detection", "  --pane-dir <path>              Connect to a specific Pane data directory", "", "How a watch ends: WATCH EXPIRED (exit 0) means nothing happened; arm a new one with the next", "dispatch. A non-zero exit or a WATCH ERROR line means it failed: say so and re-arm once. Judge", "a watch by WATCH OK and these endings, never by silence. Never pipe --follow into grep -m1 or head.", "STUCK means real unsubmitted composer text; a prompt suggestion never counts."];
+            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  python -m runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.", "", "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree directory name; defaults to --name", "  --branch <name>                Exact new branch name (slashes kept); must not exist; defaults to the worktree name", "  --base-branch <ref>            Ref to branch from; --base is an alias", "  --agent <codex|claude|cursor>  Built-in terminal template; with --tool-command, the agent it runs", "  --tool-command <command>       Custom terminal command", "  --title <title>                Terminal tab title", "  --initial-input <text>         Text sent after the command is ready", "  --prompt <text>                Alias for --initial-input", "  --initial-input-file <path|->  Read initial input from a file or stdin", "  --as-file-pointer              Send `Read and follow <prompt file>` instead of the prompt", "  --attach <file>                Copy a file beside the prompt file and list it; repeatable", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --prompt-file <path|->         Alias for --initial-input-file", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for the agent's input box, then deliver and verify the prompt", "  --ready-timeout-ms <ms>        Readiness wait timeout; defaults to 30000", "  --concurrency <count>          Accepted; creation is currently serialized", "  --source <user|agent>          Mark mutation source; agent implies background creation", "  --no-focus                     Create in the background without stealing focus", "  --focus                        Explicitly focus the created pane", "  --pinned                       Request pinning at creation; first Session association clears it", "  --no-pinned                    Create unpinned (the UI's favorite/pin star)", "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without creating panes", "  --yes                          Skip confirmation for mutating commands", "", "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."];
             readonly "panes adopt": readonly ["Usage:", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [options]", "", "Adopts an existing externally managed git worktree without creating, syncing, or deleting it. Archiving only removes its worktree with `panes archive --remove-worktree`. To start new work on a named branch, use `panes create --base <ref> --branch <name>` instead of `git worktree add` plus adopt.", "", "Options: --resume <id> stages the agent resume command (built-in agents only); --launch runs the command immediately; --prompt <text> or --prompt-file <path|-> and --wait-ready require --launch; --folder <name> groups the pane; --no-pinned opts out of pinning; --no-associate skips automatic Session association; --dry-run previews.", "", "With --tool-command, --agent names the agent the command runs (a wrapper such as `agent-farm run`): Pane launches the command unchanged and treats the panel as that agent. Without --agent, Pane detects Claude Code, Codex and Cursor from the foreground process or the agent's screen, and --wait-ready waits for the detected agent's input box; a command that never shows a supported agent is not ready and nothing is typed into it."];
             readonly "panes archive": readonly ["Usage:", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes [--json]", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--source user|agent] [--dry-run] --yes [--json]", "", "Archives a Pane (session) exactly like the UI Archive action, including removal of its Pane-managed git worktree. Refreshes the configured upstream before checking for unpushed commits and reports exact commit evidence. When the branch has no upstream or its upstream is gone, a merged GitHub pull request whose head is HEAD (found with `gh`) counts as pushed. Refuses unsafe archives unless --force is passed. An adopted worktree is kept unless --remove-worktree is passed, which applies the same safety check and removal. The local branch is always kept. With --session and --merged, archives every Pane associated with the Session whose work is clean and pushed or merged, and reports a reason for each Pane it skips. Use --dry-run to print the evidence without mutating Pane state.", "", "Options:", "  --pane <pane-id>", "  --source <user|agent>", "  --force", "  --remove-worktree", "  --session <id|name>", "  --merged", "  --pane-dir <path>", "  --json", "  --dry-run", "  --yes"];
             readonly "panes pin": readonly ["Usage:", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "", "Declaratively pins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.", "", "Options:", "  --pane <pane-id>", "  --pane-dir <path>", "  --json", "  --dry-run", "  --yes"];
@@ -1327,9 +1363,9 @@ export declare const RUNPANE_CONTRACT: {
             readonly mcp: readonly ["Usage:", "  runpane mcp", "", "The Pane MCP server ships in the npm package and inside the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest mcp"];
             readonly "agents doctor": readonly ["Usage:", "  runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]", "", "Diagnoses whether Codex or Claude is available in the same repository environment Pane will use.", "", "Options:", "  --agent <codex|claude|cursor>         Built-in agent command to diagnose", "  --repo <selector>              active, id, exact path, or saved repository name; defaults to active", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly "panels screen": readonly ["Usage:", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "", "Reads a compact current-screen view from a terminal panel. Prefers alternate-screen/TUI output and falls back to recent scrollback.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --limit <count>                Maximum lines to return; defaults to 80", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
-            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] --yes [--json]", "", "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.", "", "For a Claude or Codex panel with no composer on screen, nothing is sent: the result is ok: false with blocked.kind composer-unknown.", "", "Multi-line or long (over 512 characters) text reaches a Claude or Codex composer as one bracketed paste: CRLF becomes LF, and the submit key goes as its own write once the paste has settled, even while the agent is working.", "", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --text <text>                  Text to submit before Enter", "  --input-file <path|->          Read text from a file or stdin before Enter", "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command", "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"];
+            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer [--attach <file>]...] [--interrupt] [--expect-report|--no-expect-report] [--wait [--timeout <duration>]] --yes [--json]", "", "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.", "", "For a Claude or Codex panel with no composer on screen, nothing is sent: the result is ok: false with blocked.kind composer-unknown.", "", "Multi-line or long (over 512 characters) text reaches a Claude or Codex composer as one bracketed paste: CRLF becomes LF, and the submit key goes as its own write once the paste has settled, even while the agent is working.", "", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "", "Optional --wait returns a per-dispatch result; the orchestrator guide uses submit without --wait and a named watch. Choose one completion consumer.", "It returns once, with a compact result: outcome, ids, the report (state, summary,", "summaryPath, PR, head, question), screenLines for a prompt, or lastOutput for a missing", "report. Answer a blocked panel with `panels submit --no-expect-report`,", "then watch for the original result.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --text <text>                  Text to submit before Enter", "  --input-file <path|->          Read text from a file or stdin before Enter", "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`", "  --attach <file>                Copy a file beside the prompt file and list it; repeatable", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command", "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"];
             readonly "panels wait": readonly ["Usage:", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--contains <text>] [--timeout-ms <ms>] [--interval-ms <ms>] [--json]", "", "Polls a terminal panel until it is initialized, ready, idle, or contains text. Output is intentionally small and includes next-step guidance.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --for <condition>              initialized, ready, idle, or text; defaults to ready for CLI panels and idle otherwise", "  --contains <text>              Text required for --for text; implies --for text when omitted", "  --timeout-ms <milliseconds>    Wait timeout; defaults to 30000", "  --interval-ms <milliseconds>   Poll interval; defaults to 500", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
-            readonly "panels create": readonly ["Create a terminal-backed tool panel inside an existing Pane session.", "", "Usage:", "  python -m runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--title <title>] [--initial-input <text>] [--no-focus] [--wait-ready] --yes [--json]", "  python -m runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--no-focus] [--wait-ready] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor> Built-in agent command template, or with --tool-command the agent it runs.", "  --tool-command <command>      Custom terminal command to launch.", "  --title <title>               Panel title override.", "  --initial-input, --prompt     Initial input to send after the tool starts.", "  --initial-input-file <path|-> Read initial input from a file or stdin.", "  --as-file-pointer             Send `Read and follow <prompt file>` instead of the prompt.", "  --no-focus                    Create the panel in the background.", "  --focus                       Explicitly focus the created panel.", "  --source <user|agent>         Mark the mutation source; agent implies background creation.", "  --wait-ready                  Wait for the agent's input box, then deliver and verify the prompt.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
+            readonly "panels create": readonly ["Create a terminal-backed tool panel inside an existing Pane session.", "", "Usage:", "  python -m runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--title <title>] [--initial-input <text>] [--no-focus] [--wait-ready] --yes [--json]", "  python -m runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--no-focus] [--wait-ready] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor> Built-in agent command template, or with --tool-command the agent it runs.", "  --tool-command <command>      Custom terminal command to launch.", "  --title <title>               Panel title override.", "  --initial-input, --prompt     Initial input to send after the tool starts.", "  --initial-input-file <path|-> Read initial input from a file or stdin.", "  --as-file-pointer             Send `Read and follow <prompt file>` instead of the prompt.", "  --attach <file>               Copy a file beside the prompt file and list it; repeatable.", "  --expect-report                Expect a `runpane report` even for --source user work (the default otherwise)", "  --no-expect-report             Fire-and-forget: no agent.report.missing if the agent ends without reporting", "  --wait                         Block until this panel reports, misses its report, waits on a prompt, or exits;", "                                 print one JSON line (exit 0 report, 3 missing, 4 blocked, 5 exited, 124 timeout)", "  --timeout <duration>           With --wait: give up after this long (30m, 2h)", "  --no-focus                    Create the panel in the background.", "  --focus                       Explicitly focus the created panel.", "  --source <user|agent>         Mark the mutation source; agent implies background creation.", "  --wait-ready                  Wait for the agent's input box, then deliver and verify the prompt.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "panels open": readonly ["Open a URL or file as a browser/editor tab in a Pane, in split view beside the agent by default.", "", "Usage:", "  python -m runpane panels open [--pane <pane-id>] (--url <url>|--file <path>) [--title <title>] [--split|--tab] [--focus|--no-focus] [--source user|agent] --yes [--json]", "", "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: files open in an editor tab with read-only previews for supported formats; HTML opens as editable source. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.", "", "Options:", "  --pane <pane-id>              Pane to open the tab in; defaults to PANE_SESSION_ID.", "  --url <url>                   http(s) or file URL to open in a browser tab.", "  --file <path>                 File inside the Pane worktree (relative, Linux, Windows, or WSL UNC path).", "  --title <title>               Tab title override.", "  --split                       Open in split view beside the agent (default).", "  --tab                         Open in the current tab group instead.", "  --no-focus                    Open without selecting the tab.", "  --focus                       Select the tab (default); never raises the window.", "  --source <user|agent>         Mutation source.", "  --pane-dir <path>             Connect to a specific Pane data directory.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "panels submit-composer": readonly ["Submit an agent composer using the panel-appropriate key sequence.", "", "Usage:", "  python -m runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]", "", "Options:", "  --panel <panel-id>            Terminal panel id.", "  --strategy <strategy>         Defaults to auto; Codex queues with Tab while working and submits with Enter when ready. auto retries once if the text is still in the composer.", "  --yes                         Skip confirmation prompts.", "  --json                        Print JSON output."];
             readonly "sessions list": readonly ["Usage:", "python -m runpane sessions list [--json] [--pane-dir <path>]", "", "Options:", "  --session <id|name>         Named Session id or exact name.", "  --from-json <path|->         Read structured JSON from a file or stdin.", "  --pane <pane-id>             User-visible Pane to associate or detach.", "  --agent <codex|claude|cursor>  Agent terminal to use.", "  --json                       Print JSON output."];
@@ -1377,12 +1413,14 @@ export declare const RUNPANE_CONTRACT: {
             readonly "workspace read": readonly ["Usage:", "  runpane workspace [<machine>] read <path> [--json]", "", "`runpane workspace read` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest workspace read"];
             readonly "workspace write": readonly ["Usage:", "  runpane workspace [<machine>] write <path> [--json]", "", "`runpane workspace write` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest workspace write"];
             readonly "workspace exec": readonly ["Usage:", "  runpane workspace <machine> exec [--cwd <path>] [--timeout-ms <ms>] [--json] -- <command>", "", "`runpane workspace exec` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest workspace exec"];
-            readonly handoff: readonly ["Usage:", "  runpane handoff --template", "  runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--dry-run] [--json]", "", "`runpane handoff` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest handoff"];
+            readonly handoff: readonly ["Usage:", "  runpane handoff --template", "  runpane handoff \"<destination>\" --note-file <path|-> [--machine <name>] [--agent <codex|claude|cursor|opencode>] [--model <model>] [--effort <level>] [--repo <selector>] [--push] [--note-only] [--dry-run] [--json]", "", "`runpane handoff` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest handoff"];
             readonly "sessions pin": readonly ["Usage:", "python -m runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]", "", "Set the named Session pin star on. Repeated requests keep that state. Uses the same Session update path as the UI."];
             readonly "sessions unpin": readonly ["Usage:", "python -m runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]", "", "Set the named Session pin star off. Repeated requests keep that state. Uses the same Session update path as the UI."];
             readonly "pr watch": readonly ["runpane pr watch [--pane <id>] --url <PR URL> [--head <full-sha>] [--json] [--pane-dir <path>]", "", "Register durable GitHub PR monitoring for a Pane."];
             readonly "pr unwatch": readonly ["runpane pr unwatch [--pane <id>] --url <PR URL> [--json] [--pane-dir <path>]", "", "Remove a Pane’s explicit PR registration."];
             readonly "pr list": readonly ["runpane pr list [--pane <id>] [--json] [--pane-dir <path>]", "", "List PR registrations and stopped watches."];
+            readonly inbox: readonly ["Usage:", "  runpane inbox [--session <id|name>] [--json] [--pane-dir <path>]", "", "Lists what a Session's orchestrator has not acknowledged: worker reports (agent.report),", "missing reports (agent.report.missing), and questions waiting on a worker's screen", "(agent.blocked; these clear themselves once the worker moves on). Pane keeps them across", "restarts. An orchestrator reads it when it starts or resumes, to catch what finished while it was down.", "", "Options:", "  --session <id|name>            Session; defaults to PANE_ORCHESTRATION_SESSION_ID", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "", "Clear handled items with `runpane inbox ack <item-id>...`."];
+            readonly "inbox ack": readonly ["Usage:", "  runpane inbox ack <item-id>... [--session <id|name>] [--json] [--pane-dir <path>]", "  runpane inbox ack --all --session <id|name> [--json] [--pane-dir <path>]", "", "Clears Session inbox items. Ids that match nothing are listed as unknown; acknowledging twice is harmless.", "", "Options:", "  --session <id|name>            Only clear items of this Session; required with --all", "  --all                          Clear every item of the Session", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
         };
     };
     readonly docs: {
@@ -1392,7 +1430,7 @@ export declare const RUNPANE_CONTRACT: {
         readonly pythonCommands: readonly ["pipx run runpane", "pipx run runpane setup", "python -m pip install runpane", "runpane", "runpane setup", "python -m runpane setup", "runpane install daemon --label \"My Server\"", "pipx install runpane", "runpane", "runpane setup", "pipx run runpane install daemon --label \"My Server\"", "uvx runpane@latest", "uvx runpane@latest setup", "uvx runpane@latest install daemon --label \"My Server\"", "python -m runpane install daemon --label \"My Server\""];
         readonly packageManagerNotes: readonly ["Use `pnpm dlx` for one-shot pnpm execution and `pnpm add -g` for persistent CLI installation.", "Do not document `pnpm install runpane` as the public CLI install path."];
         readonly commandUsages: readonly ["runpane", "runpane setup", "runpane install", "runpane install client", "runpane install daemon", "runpane update", "runpane version", "runpane doctor", "runpane doctor --json", "runpane daemon repair --pane-dir ~/.pane_remote --yes --json", "runpane agent-context", "runpane agent-context --command \"panes create\" --json", "runpane mcp", "runpane repos list --json", "runpane repos add --path /path/to/repo --name Pane --yes --json", "runpane panes list --repo active --json", "runpane panes cost --pane <pane-id> --json", "runpane panes create --repo active --name issue-252 --agent <agent> --prompt \"Kick off the discussion skill for issue 252\" --source agent --no-focus --wait-ready --yes --json", "runpane panes create --from-json panes.json --yes --json", "runpane panes archive --pane <pane-id> --source agent --yes --json", "runpane panes rename --pane <pane-id> --name issue-393 --yes --json", "runpane panels list --pane <pane-id> --json", "runpane panels output --panel <panel-id> --limit 200 --json", "printf 'Continue\\n' | runpane panels input --panel <panel-id> --input-file - --yes --json", "runpane sessions list [--json] [--pane-dir <path>]", "runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]", "runpane sessions get --session <id|name> [--json] [--pane-dir <path>]", "runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]", "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]", "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]", "runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]", "runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]", "runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]", "runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]", "runpane lock acquire --name testing-account --ttl 30m --wait 1800000 --note \"call QA\" --json", "runpane lock release --name testing-account --json", "runpane lock list --json", "runpane agents start --repo active --name fix-login --agent claude --prompt \"Fix the login redirect\" --yes --json", "runpane agents start --pane <pane-id> --agent codex --prompt \"Review the PR from this branch and report findings\" --yes --json", "runpane agents status --pane <pane-id> --json", "runpane agents send --pane <pane-id> --text \"Also add a test\" --yes --json", "runpane report --state ready --pr 747 --head fc5dce9 --summary-file /tmp/report.md --json", "runpane panels last-message --panel <panel-id> --json", "runpane panels resume --panel <panel-id> --wait-ready --yes --json", "runpane panels resume --session <id|name> --wait-ready --yes --json", "runpane docs search --query \"archive a pane\" --json", "runpane links create --pane <pane-id> --json", "runpane panes git-status --pane <pane-id> --json", "runpane help", "runpane <command> --help", "runpane watch --until-event", "runpane watch --follow", "runpane watch --session <id|name> --follow", "runpane watch --session <id|name> --follow --ready-settle 1m --blocked-settle 15s --min-interval 2m", "runpane pr watch [--pane <id>] --url <PR URL> [--head <full-sha>] [--json] [--pane-dir <path>]", "runpane pr unwatch [--pane <id>] --url <PR URL> [--json] [--pane-dir <path>]", "runpane pr list [--pane <id>] [--json] [--pane-dir <path>]"];
-        readonly commandDescriptions: readonly ["`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. The remote-host wizard asks only for a name, then runs interactive Tailscale setup with automatic port selection; explicit install daemon flags remain available for SSH and manual URLs. In non-interactive shells or CI, both forms must print help, common commands, and agent discovery hints, then exit successfully instead of waiting for input.", "`runpane install` is an alias for `runpane install client`.", "`runpane install client` downloads the selected Pane desktop artifact and installs, opens, or launches it for the current platform.", "`runpane install daemon` downloads or installs Pane, resolves a stable Pane executable path, and spawns `<pane executable> --remote-setup <forwarded remote setup args>`.", "The wrapper must stream Pane stdout/stderr without reformatting because `pane --remote-setup` prints the one-time `pane-remote://...` connection code.", "`runpane update` defaults to both app and active supported CLI, with independent supervision, staging, durable status, and explicit restoration outcomes. Prerequisites, status fields/exit codes, draft handling and manual recovery are documented in [Update recovery](UPDATE_RECOVERY.md).", "`runpane version` prints only wrapper package metadata and does not contact, launch, or focus the Pane app or daemon.", "`runpane doctor` checks platform support, release metadata reachability, download URL selection, installed Pane detection, daemon reachability, and remote-daemon hints. Add `--json` for a machine-readable report that agents should run before mutating Pane state. Installed app version detection must be best-effort and must not launch, focus, or configure Pane; macOS wrappers read app bundle metadata instead of executing `Pane --version`.", "`runpane daemon repair` rewrites and restarts only the managed remote-daemon launcher/service. It never creates pairing credentials, changes tunnels, or downloads Pane; doctor only recommends it and never runs it automatically.", "`runpane agent-context` prints a brief, token-efficient command schema for coding agents without connecting to the Pane daemon.", "`runpane agent-context --command \"panes create\"` prints the detailed definition for one command. Add `--json` for machine-readable output. An unknown command exits 2 and lists the closest command names; with `--json` it prints `{ ok: false, code: \"unknown_command\", message, candidates }` on stdout.", "`runpane mcp` runs a stdio MCP server whose tools are generated from this contract: every command with result `jsonSchemas` becomes a tool that runs `runpane <command> --json` and returns its output. Only the npm package and the Pane app include it; the Python wrapper prints how to run it with Node and exits non-zero.", "`runpane repos list` connects to the running local Pane daemon and prints saved repository records.", "`runpane repos add` registers an existing git repository with the running local Pane daemon. It does not create directories or initialize git repositories by default.", "`runpane panes list` lists Pane sessions, optionally scoped to one saved repository.", "`runpane panes cost` reports estimated token costs per Pane for the last 30 days, including per-model breakdowns and cache efficiency; unscoped output includes an Unattributed bucket that reconciles against workspace totals.", "`runpane panes create` connects to the running local Pane daemon, resolves the requested saved base repository, creates user-visible Pane sessions backed by Pane-managed worktrees/branches, opens terminal-backed tool tabs, and optionally sends initial input to the started tool. Built-in agent panes and `--source agent` default to background/no-focus unless `--focus` is passed. New Panes are pinned into the UI's favorite/pin set by default, except when the CLI runs inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID`), where child worktrees default to unpinned. Explicit `--pinned` / `--no-pinned` override creation defaults. First Session association clears an existing pin, including an explicit creation pin; use `panes pin` after association to pin a child. This avoids duplicating Session children in the global pinned list. Manual pins applied afterward are preserved. Panes created interactively in the Pane UI are unaffected. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.", "For `panes create --wait-ready` (and `panels create`, `panes adopt --launch`), ready means an identified agent at its own input box: declared with `--agent`, or detected from the command, its foreground process or its screen. A `--tool-command` that never shows a supported agent is not ready: `readiness.ok` is false with `readiness.reason.code` `no-agent-detected` after the timeout, or `command-exited` as soon as the command exits back to the shell, and nothing is typed into it. `agent-not-ready` means the agent was detected but its input box was not ready in time. CLI readiness is confirmed on consecutive polls. Codex also requires a recognized configured model or context footer below its live composer; its provisional startup composer is not ready. Hidden or unrecognized Codex status lines conservatively time out rather than prove readiness. Startup prompts return blocked with the prompt's own text in blocked.message and a suggestedCommand, and Pane never answers them: first-run trust and daemon dialogs and Agent Farm's `Trust this repository workspace? [y/N]` as blocked.kind=first-run-dialog; Codex's security setup banner and any other prompt, including a wrapper's or shell's `[y/N]` before the agent appears, as agent-prompt. A starting message blocked this way is held and sent once the prompt is answered and the agent's input box is ready. Every create with a starting message returns `initialInput`. Pane stages the text in the composer, presses the agent's submit key separately (Ctrl+Enter for Codex, declared or detected), and checks where it went: `initialInput.delivery` is `taken` or `queued` (from the agent's transcript or its screen), `in-composer`, or `unknown` (`argv` means a prompt was routed at launch; Pane gives the transcript up to 10 seconds before settling on unknown). `initialInput.verifiedSubmitted` is true exactly when it is `taken` or `queued`, and the create's `ok` is false unless a Claude or Codex starting message is verified. Cursor and OpenCode have no acceptance probe: their delivery stays `unknown` with a delivery.message saying so, `verification: unverifiable`, and `ok` follows readiness. Without `--wait-ready` the create returns at once with `initialInput.verifiedSubmitted: false`, a delivery.message saying the call did not wait, and a `panels wait` nextCommand; Pane still sends the message once the agent is identified and at its input box, and gives up without typing it if no supported agent appears within 30 seconds.", "`runpane panes archive` refreshes the configured upstream, reports exact unpushed commit evidence, and refuses unsafe archive operations unless `--force` is used. A branch whose upstream is gone counts as pushed when a merged GitHub pull request has HEAD as its head (`safetyCheck.mergedViaPr`). Add `--dry-run` to inspect the same evidence without archiving. `--remove-worktree` applies the same check and removal to an adopted worktree; local branches are always kept. Successful archives report `worktreeCleanup: completed` once the worktree is gone from its path and from git; `trashDeletion: pending` means its files are still being deleted in the background. `runpane panes archive --session <id|name> --merged` archives every Session Pane that is clean and pushed or merged, and reports a reason for each skipped Pane.", "`runpane panes rename` trims and updates a Pane's display name without changing its worktree, branch, panels, or focus, and returns the updated pane summary.", "`runpane panes focus` raises the Pane window and selects a Pane (and optionally one of its panels) exactly like clicking it in the UI. Because it steals the user's window focus, run it only on an explicit user request to open, focus, show, or switch to a Pane; never focus a Pane proactively, the same doctrine that keeps `panes create` background/no-focus for `--source agent`.", "`runpane panels open` opens a URL or a file from the Pane worktree as a tab in an existing Pane (default: the calling panel's Pane from `PANE_SESSION_ID`), in split view beside the agent unless `--tab` is passed. Files open in an editor tab with read-only previews for supported formats, and HTML opens as editable source; an existing tab showing the same target is reused. It brings the tab forward for clients already showing that Pane, and never raises or focuses the Pane window or switches anyone's Pane.", "`runpane panels list` lists tool panels inside one Pane session. Each panel with a saved agent session ID reports it as `resumeId`, with `resumeSource` (`agent-farm`, `configured`, or `agent`) naming the rule that reopens the conversation.", "`runpane panels output` reads bounded recent terminal output from one panel and strips common terminal control noise for agent use.", "`runpane panels input` sends exact input bytes to one terminal panel. Prefer `--input-file` for newlines, Ctrl-C, quotes, or shell-sensitive text.", "`runpane panes create --prompt` is an alias for `--initial-input`; request JSON and daemon payloads should use the canonical `initialInput` field.", "`runpane panes create --branch <name>` creates the Pane's worktree on exactly that new branch, slashes included (for example `agents/w5a`). The name is checked with `git check-ref-format --branch`, creation fails if the branch already exists, and Pane never renames it to make it unique. `--worktree-name` still names the directory and defaults to `--name`. `--base` is an alias for `--base-branch`, and `--prompt-file` for `--initial-input-file`. `panes create --base <ref> --branch <name> --prompt-file <file>` replaces `git worktree add` plus `panes adopt`. When the base is a remote-tracking branch (the default `origin/main`, or one named with `--base`), Pane fetches it first, waiting at most about 10 seconds, so the Pane starts at the remote's current tip. Each created item reports `base` (`ref`, `commit`, `refresh`); if the fetch fails the Pane still starts, from the local ref, and `base.notice` says so and how to catch up.", "`runpane panes adopt --launch` accepts `--prompt`, `--prompt-file`, `--wait-ready`, and `--ready-timeout-ms`, and reports `readiness`, `initialInput`, and `nextCommand` like `panes create`. A prompt without `--launch` is an error rather than being dropped.", "If composer submission cannot be verified without risking a duplicate, the create item is unsuccessful with `initialInput.staged`, `initialInput.attempts`, `initialInput.blocked.kind: submission_unverified`, and an actionable `nextCommand`. The CLI-facing `--prompt` alias maps to this canonical `initialInput` result.", "When running from WSL while Pane is installed on Windows, the Linux wrapper may look for a missing `/tmp/pane-daemon.../daemon.sock` or resolve to a Windows shim such as Volta. In that case invoke the Windows wrapper through PowerShell from a Windows cwd, for example `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane repos list --json'`.", "`runpane watch` waits for agent, Pane, panel, and PR events from the daemon journal without polling. `--follow` keeps watching with defaults tuned for an agent watching unattended (quiet, batched, and it ends itself after 3 hours with nothing happening); individual duration flags override these defaults. Cadence requires a named follow consumer; `--follow --since <generation>` has no consumer name and bypasses settling and batching. `--until-event` waits for one event worth waking for, prints it immediately without follow settling or batching, and exits 0. The defaults are listed in the contract under defaults.watch.", "A watch releases its pending slot when its client socket or named pipe disconnects. Re-arming the same named cursor takes over the previous request; the superseded watcher exits with a WATCH ERROR instead of competing for the cursor. Anonymous concurrent watchers retain the eight-wait limit. Each request also has a 125-second lease (slightly longer than the maximum 120-second long poll), so an abandoned request is reclaimed even if no disconnect arrives.", "`sessions list` list durable named orchestration Sessions.", "`sessions create` create a durable named orchestration Session and its hidden terminal owner.", "`sessions get` read one durable named orchestration Session.", "`sessions update` update a Session overview from structured JSON.", "`sessions pin` and `sessions unpin` set the Session pin star through the existing UI update path. Create JSON accepts `isPinned` (default false); update JSON preserves the pin when the field is omitted.", "`sessions set-agent` switch the durable terminal agent for a named Session.", "`sessions associate` associate a user-visible Pane with a named Session.", "`sessions detach` detach a Pane from a named Session.", "`sessions overview` read a live status, activity, git, and pull request overview for a named Session.", "`runpane lock acquire|release|list` coordinate a resource shared between agents, such as one test account. The caller's Pane and panel own the lock; it is scoped to the owner's Session (or global outside one), renews for the same owner, and is released on TTL expiry, owner panel exit, or owner Pane archive. `--wait` blocks in the daemon until the lock comes free.", "`runpane agents start|status|send` finish the three common agent jobs in one call each: start an agent on a task (a new tab in the work's Pane with `--pane <id>`, or a new Pane for new work), check on it, and send it a follow-up.", "`runpane report --state ready|blocked|failed|done` is how a worker hands back its result. It stores the latest report on the worker's panel (state, `--pr`, `--head`, up to 16,000 characters of `--summary` or `--summary-file`, and the `--question` a blocked worker needs answered), journals an opt-in `agent.report` watch event (`REPORT <pane-name> pane <pane-id> panel <panel-id> ready pr#747 fc5dce9`; it skips the `--min-interval` batch), records it as Session activity, and shows it in `agents status`, `panels list`, and `sessions overview` (`panes[].report`). Inside a Pane terminal the panel comes from `PANE_SESSION_ID` and `PANE_PANEL_ID`; elsewhere pass `--pane` and `--panel`. It prints how many watches were waiting for the report and received it (`Delivered to 1 waiting watcher.`, `liveWatchers` in JSON). Zero means nobody was waiting right now, not that the report is lost: it stays on the panel, and a named-cursor watch receives it when it next waits.", "`runpane panels resume --panel <panel-id>` restarts a stopped terminal panel in place, keeping its panel id: an agent panel relaunches with its resume command (Claude `--resume <session>`, `codex resume <session>`, Agent Farm `agent-farm run <profile> --resume <id>` with the ID Agent Farm printed; the result's `agentSessionId` names it), the same restart the app runs when it shows the panel, without taking focus. A running panel is left alone (`action: \"already-running\"`); one whose agent exited back to its shell is stopped, and resume runs its saved command again in that shell (`action: \"resumed\"`). If that command exits at once, `--wait-ready` returns `ok: false` with `reason.code: \"command-exited\"` and the error line it printed. `--session <id|name>` or `--all-stopped` resumes every stopped agent panel in that scope, `--concurrency` at a time (default 3), then, with `--wait-ready`, waits on the resumed panels together, and returns `{ resumed, alreadyRunning, failed, notReady, items[] }` with each panel's own result, readiness, and blocker or error. After a Pane restart, or once an agent exits back to its shell, stopped panels report `running: false` (`initialized` stays true while the shell lives) in `panels list`, `panels screen`, and `panels wait` (which returns `stopped: true` instead of timing out), and `nextCommand` points at `panels resume`. `runpane watch` reports them as `panel.stopped` (`STOPPED ...`) when `--kinds` lists that kind; other consumers and `workspace state` see `agent.unknown` with `running: false`, never `agent.ready`.", "`runpane panels last-message --panel <panel-id>` reads a Claude or Codex agent's last reply from its transcript (up to `--limit` characters, default 20,000, keeping the end and reporting `truncated`). It never scrapes the screen: without a transcript it prints `{ ok: false, reason: \"transcript-unavailable\" }` and exits 1.", "Commands with a contract `daemonAction` (the `panes` git, script, restore, and move commands, `folders list|create`, and `links open`) call the same Pane daemon channel as the matching button in the app and print `{ ok, data, error }`. Destructive ones add a pane:// `link` to review the Pane.", "`runpane links create` builds `pane://open?...` links; opening one in Pane selects what it names and never changes Pane state.", "`runpane docs search|read` search and read Pane docs, help, and installed Pane Chat skills offline. They ship in the npm package and the Pane app only.", "`runpane handoff` hands a task to a fresh agent on this or another of your machines. The sending agent writes the note from `runpane handoff --template` (goal, current state, done and verified, in progress, next steps, decisions and constraints, open questions, how to verify, git state); `runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md` checks every section is filled in, requires the branch to be pushed (or pushes it with `--push`, never forcing), writes the note to that machine's `~/.pane/handoffs/` and starts the agent in a new Pane branched from the sender's branch. From a Session's terminal it skips git and creates a Session with the same name, goal and agent on the other machine instead. The receiver reports back to the sender's panel.", "`runpane pr watch`: Register durable GitHub PR monitoring for a Pane.", "`runpane pr unwatch`: Remove a Pane’s explicit PR registration.", "`runpane pr list`: List PR registrations and stopped watches."];
+        readonly commandDescriptions: readonly ["`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. The remote-host wizard asks only for a name, then runs interactive Tailscale setup with automatic port selection; explicit install daemon flags remain available for SSH and manual URLs. In non-interactive shells or CI, both forms must print help, common commands, and agent discovery hints, then exit successfully instead of waiting for input.", "`runpane install` is an alias for `runpane install client`.", "`runpane install client` downloads the selected Pane desktop artifact and installs, opens, or launches it for the current platform.", "`runpane install daemon` downloads or installs Pane, resolves a stable Pane executable path, and spawns `<pane executable> --remote-setup <forwarded remote setup args>`.", "The wrapper must stream Pane stdout/stderr without reformatting because `pane --remote-setup` prints the one-time `pane-remote://...` connection code.", "`runpane update` defaults to both app and active supported CLI, with independent supervision, staging, durable status, and explicit restoration outcomes. Prerequisites, status fields/exit codes, draft handling and manual recovery are documented in [Update recovery](UPDATE_RECOVERY.md).", "`runpane version` prints only wrapper package metadata and does not contact, launch, or focus the Pane app or daemon.", "`runpane doctor` checks platform support, release metadata reachability, download URL selection, installed Pane detection, daemon reachability, and remote-daemon hints. Add `--json` for a machine-readable report that agents should run before mutating Pane state. Installed app version detection must be best-effort and must not launch, focus, or configure Pane; macOS wrappers read app bundle metadata instead of executing `Pane --version`.", "`runpane daemon repair` rewrites and restarts only the managed remote-daemon launcher/service. It never creates pairing credentials, changes tunnels, or downloads Pane; doctor only recommends it and never runs it automatically.", "`runpane agent-context` prints a brief, token-efficient command schema for coding agents without connecting to the Pane daemon.", "`runpane agent-context --command \"panes create\"` prints the detailed definition for one command. Add `--json` for machine-readable output. An unknown command exits 2 and lists the closest command names; with `--json` it prints `{ ok: false, code: \"unknown_command\", message, candidates }` on stdout.", "`runpane mcp` runs a stdio MCP server whose tools are generated from this contract: every command with result `jsonSchemas` becomes a tool that runs `runpane <command> --json` and returns its output. Only the npm package and the Pane app include it; the Python wrapper prints how to run it with Node and exits non-zero.", "`runpane repos list` connects to the running local Pane daemon and prints saved repository records.", "`runpane repos add` registers an existing git repository with the running local Pane daemon. It does not create directories or initialize git repositories by default.", "`runpane panes list` lists Pane sessions, optionally scoped to one saved repository.", "`runpane panes cost` reports estimated token costs per Pane for the last 30 days, including per-model breakdowns and cache efficiency; unscoped output includes an Unattributed bucket that reconciles against workspace totals.", "`runpane panes create` connects to the running local Pane daemon, resolves the requested saved base repository, creates user-visible Pane sessions backed by Pane-managed worktrees/branches, opens terminal-backed tool tabs, and optionally sends initial input to the started tool. Built-in agent panes and `--source agent` default to background/no-focus unless `--focus` is passed. New Panes are pinned into the UI's favorite/pin set by default, except when the CLI runs inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID`), where child worktrees default to unpinned. Explicit `--pinned` / `--no-pinned` override creation defaults. First Session association clears an existing pin, including an explicit creation pin; use `panes pin` after association to pin a child. This avoids duplicating Session children in the global pinned list. Manual pins applied afterward are preserved. Panes created interactively in the Pane UI are unaffected. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.", "For `panes create --wait-ready` (and `panels create`, `panes adopt --launch`), ready means an identified agent at its own input box: declared with `--agent`, or detected from the command, its foreground process or its screen. A `--tool-command` that never shows a supported agent is not ready: `readiness.ok` is false with `readiness.reason.code` `no-agent-detected` after the timeout, or `command-exited` as soon as the command exits back to the shell, and nothing is typed into it. `agent-not-ready` means the agent was detected but its input box was not ready in time. CLI readiness is confirmed on consecutive polls. Codex also requires a recognized configured model or context footer below its live composer; its provisional startup composer is not ready. Hidden or unrecognized Codex status lines conservatively time out rather than prove readiness. Startup prompts return blocked with the prompt's own text in blocked.message and a suggestedCommand, and Pane never answers them: first-run trust and daemon dialogs and Agent Farm's `Trust this repository workspace? [y/N]` as blocked.kind=first-run-dialog; Codex's security setup banner and any other prompt, including a wrapper's or shell's `[y/N]` before the agent appears, as agent-prompt. A starting message blocked this way is held and sent once the prompt is answered and the agent's input box is ready. Every create with a starting message returns `initialInput`. Pane stages the text in the composer, presses the agent's submit key separately (Ctrl+Enter for Codex, declared or detected), and checks where it went: `initialInput.delivery` is `taken` or `queued` (from the agent's transcript or its screen), `in-composer`, or `unknown` (`argv` means a prompt was routed at launch; Pane gives the transcript up to 10 seconds before settling on unknown). `initialInput.verifiedSubmitted` is true exactly when it is `taken` or `queued`, and the create's `ok` is false unless a Claude or Codex starting message is verified. Cursor and OpenCode have no acceptance probe: their delivery stays `unknown` with a delivery.message saying so, `verification: unverifiable`, and `ok` follows readiness. Without `--wait-ready` the create returns at once with `initialInput.verifiedSubmitted: false`, a delivery.message saying the call did not wait, and a `panels wait` nextCommand; Pane still sends the message once the agent is identified and at its input box, and gives up without typing it if no supported agent appears within 30 seconds.", "`runpane panes archive` refreshes the configured upstream, reports exact unpushed commit evidence, and refuses unsafe archive operations unless `--force` is used. A branch whose upstream is gone counts as pushed when a merged GitHub pull request has HEAD as its head (`safetyCheck.mergedViaPr`). Add `--dry-run` to inspect the same evidence without archiving. `--remove-worktree` applies the same check and removal to an adopted worktree; local branches are always kept. Successful archives report `worktreeCleanup: completed` once the worktree is gone from its path and from git; `trashDeletion: pending` means its files are still being deleted in the background. `runpane panes archive --session <id|name> --merged` archives every Session Pane that is clean and pushed or merged, and reports a reason for each skipped Pane.", "`runpane panes rename` trims and updates a Pane's display name without changing its worktree, branch, panels, or focus, and returns the updated pane summary.", "`runpane panes focus` raises the Pane window and selects a Pane (and optionally one of its panels) exactly like clicking it in the UI. Because it steals the user's window focus, run it only on an explicit user request to open, focus, show, or switch to a Pane; never focus a Pane proactively, the same doctrine that keeps `panes create` background/no-focus for `--source agent`.", "`runpane panels open` opens a URL or a file from the Pane worktree as a tab in an existing Pane (default: the calling panel's Pane from `PANE_SESSION_ID`), in split view beside the agent unless `--tab` is passed. Files open in an editor tab with read-only previews for supported formats, and HTML opens as editable source; an existing tab showing the same target is reused. It brings the tab forward for clients already showing that Pane, and never raises or focuses the Pane window or switches anyone's Pane.", "`runpane panels list` lists tool panels inside one Pane session. Each panel with a saved agent session ID reports it as `resumeId`, with `resumeSource` (`agent-farm`, `configured`, or `agent`) naming the rule that reopens the conversation.", "`runpane panels output` reads bounded recent terminal output from one panel and strips common terminal control noise for agent use.", "`runpane panels input` sends exact input bytes to one terminal panel. Prefer `--input-file` for newlines, Ctrl-C, quotes, or shell-sensitive text.", "`runpane panes create --prompt` is an alias for `--initial-input`; request JSON and daemon payloads should use the canonical `initialInput` field.", "`runpane panes create --branch <name>` creates the Pane's worktree on exactly that new branch, slashes included (for example `agents/w5a`). The name is checked with `git check-ref-format --branch`, creation fails if the branch already exists, and Pane never renames it to make it unique. `--worktree-name` still names the directory and defaults to `--name`. `--base` is an alias for `--base-branch`, and `--prompt-file` for `--initial-input-file`. `panes create --base <ref> --branch <name> --prompt-file <file>` replaces `git worktree add` plus `panes adopt`. When the base is a remote-tracking branch (the default `origin/main`, or one named with `--base`), Pane fetches it first, waiting at most about 10 seconds, so the Pane starts at the remote's current tip. Each created item reports `base` (`ref`, `commit`, `refresh`); if the fetch fails the Pane still starts, from the local ref, and `base.notice` says so and how to catch up.", "`runpane panes adopt --launch` accepts `--prompt`, `--prompt-file`, `--wait-ready`, and `--ready-timeout-ms`, and reports `readiness`, `initialInput`, and `nextCommand` like `panes create`. A prompt without `--launch` is an error rather than being dropped.", "If composer submission cannot be verified without risking a duplicate, the create item is unsuccessful with `initialInput.staged`, `initialInput.attempts`, `initialInput.blocked.kind: submission_unverified`, and an actionable `nextCommand`. The CLI-facing `--prompt` alias maps to this canonical `initialInput` result.", "When running from WSL while Pane is installed on Windows, the Linux wrapper may look for a missing `/tmp/pane-daemon.../daemon.sock` or resolve to a Windows shim such as Volta. In that case invoke the Windows wrapper through PowerShell from a Windows cwd, for example `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane repos list --json'`.", "`runpane watch` waits for agent, Pane, panel, and PR events from the daemon journal without polling. `--follow` keeps watching with defaults tuned for an agent watching unattended (quiet, batched, and it ends itself after 3 hours with nothing happening); individual duration flags override these defaults. Cadence requires a named follow consumer; `--follow --since <generation>` has no consumer name and bypasses settling and batching. `--until-event` waits for one event worth waking for, prints it immediately without follow settling or batching, and exits 0. The defaults are listed in the contract under defaults.watch.", "A watch releases its pending slot when its client socket or named pipe disconnects. Re-arming the same named cursor takes over the previous request; the superseded watcher exits with a WATCH ERROR instead of competing for the cursor. Anonymous concurrent watchers retain the eight-wait limit. Each request also has a 125-second lease (slightly longer than the maximum 120-second long poll), so an abandoned request is reclaimed even if no disconnect arrives.", "`sessions list` list durable named orchestration Sessions.", "`sessions create` create a durable named orchestration Session and its hidden terminal owner.", "`sessions get` read one durable named orchestration Session.", "`sessions update` update a Session overview from structured JSON.", "`sessions pin` and `sessions unpin` set the Session pin star through the existing UI update path. Create JSON accepts `isPinned` (default false); update JSON preserves the pin when the field is omitted.", "`sessions set-agent` switch the durable terminal agent for a named Session.", "`sessions associate` associate a user-visible Pane with a named Session.", "`sessions detach` detach a Pane from a named Session.", "`sessions overview` read a live status, activity, git, and pull request overview for a named Session. Each panel in `panes[].panels[]` carries its own latest `runpane report` as `report`, so one call shows what every worker last reported and when (`reportedAt`, next to the panel's `state` and `lastActivityAt`). When a report's summary is a complete JSON object, such as a status file sent with `--summary-file`, `report.data` holds it exactly as the worker gave it; Pane never reads, renames or validates its fields. A summary that is not a JSON object (plain text, an array, a scalar or invalid JSON), is nested more than 64 levels deep, or was truncated (`summaryTruncated`), has no `data`. A panel that never reported has no `report`. `panes[].report` is still the newest report among the Pane's panels.", "`runpane lock acquire|release|list` coordinate a resource shared between agents, such as one test account. The caller's Pane and panel own the lock; it is scoped to the owner's Session (or global outside one), renews for the same owner, and is released on TTL expiry, owner panel exit, or owner Pane archive. `--wait` blocks in the daemon until the lock comes free.", "`runpane agents start|status|send` finish the three common agent jobs in one call each: start an agent on a task (a new tab in the work's Pane with `--pane <id>`, or a new Pane for new work), check on it, and send it a follow-up.", "`runpane report --state ready|blocked|failed|done` is how a worker hands back its result. It stores the latest report on the worker's panel (state, `--pr`, `--head`, up to 16,000 characters of `--summary` or `--summary-file`, and the `--question` a blocked worker needs answered), journals an opt-in `agent.report` watch event (`REPORT <pane-name> pane <pane-id> panel <panel-id> ready pr#747 fc5dce9`; it skips the `--min-interval` batch), records it as Session activity, and shows it in `agents status`, `panels list`, and `sessions overview` (each panel's own report as `panes[].panels[].report`, with a JSON object summary as `data`, and the Pane's newest as `panes[].report`). Inside a Pane terminal the panel comes from `PANE_SESSION_ID` and `PANE_PANEL_ID`; elsewhere pass `--pane` and `--panel`. It prints how many watches were waiting for the report and received it (`Delivered to 1 waiting watcher.`, `liveWatchers` in JSON). Zero means nobody was waiting right now, not that the report is lost: it stays on the panel, and a named-cursor watch receives it when it next waits.", "Work sent to an agent through `runpane panels create`, `panes create` (with a prompt), or `panels submit` records that the sender waits for a `runpane report`, unless the request says `--source user` (Pane's own UI does) or `--no-expect-report`; `--expect-report` asks for one anyway. Typing into a tab never does. If the agent then goes ready or its panel exits without a report, Pane journals one opt-in `agent.report.missing` entry (`MISSING REPORT <pane-name> pane <pane-id> panel <panel-id> ready|exited`) whose `lastOutput` is the agent's last transcript reply or last screen lines; it skips the `--min-interval` batch and reaches only watchers that list it in `--kinds`. While the agent's screen shows background work (Claude's `· 1 shell` footer or a running background subagent row, Codex's `background terminal running` line), Pane waits and looks again every 10 seconds instead. `agent.blocked` entries carry `screenLines`, the prompt the agent waits on, and are journalled once a panel has stayed blocked for 2 seconds.", "The orchestrator guide prescribes submit without `--wait`, followed by its named watch; use one completion consumer. As an optional CLI route, `--wait` on `runpane panels submit`, `panels create`, and `panes create` turns the expected report on and blocks on that panel until the first `agent.report`, `agent.report.missing`, `agent.blocked`, `panel.exited`, or `pane.gone`, then prints one line of JSON (`dispatchWaitResult`): the outcome, ids, the report's state, summary, `summaryPath`, PR and head, `screenLines` for a prompt, or `lastOutput` for a missing report, never the transcript. It exits 0 for a report, 3 missing, 4 blocked, 5 exited or gone, and 124 when `--timeout <duration>` passes. It follows the journal from the position the daemon took before delivering the work, so nothing that happens right after delivery is missed. It reuses watch --until-event and returns indeterminate (exit 6) if the journal epoch changes or retained history is lost; inspect the panel and inbox before retrying. Report-expected dispatches are serialized per panel and refused before writing while a result or missing-output collection is outstanding. Answer a blocked panel with panels submit --no-expect-report, then watch for the original result.", "`runpane inbox [--session <id|name>] [--json]` lists what a Session's orchestrator has not acknowledged: reports, missing reports, and on-screen questions (a question clears itself once its panel moves on). `runpane inbox ack <item-id>...` or `--all --session <id|name>` clears items. An orchestrator runs it when it starts or resumes, to catch anything that finished while it was down; Pane never injects the inbox into its turns.", "`runpane panels resume --panel <panel-id>` restarts a stopped terminal panel in place, keeping its panel id: an agent panel relaunches with its resume command (Claude `--resume <session>`, `codex resume <session>`, Agent Farm `agent-farm run <profile> --resume <id>` with the ID Agent Farm printed; the result's `agentSessionId` names it), the same restart the app runs when it shows the panel, without taking focus. A running panel is left alone (`action: \"already-running\"`); one whose agent exited back to its shell is stopped, and resume runs its saved command again in that shell (`action: \"resumed\"`). If that command exits at once, `--wait-ready` returns `ok: false` with `reason.code: \"command-exited\"` and the error line it printed. `--session <id|name>` or `--all-stopped` resumes every stopped agent panel in that scope, `--concurrency` at a time (default 3), then, with `--wait-ready`, waits on the resumed panels together, and returns `{ resumed, alreadyRunning, failed, notReady, items[] }` with each panel's own result, readiness, and blocker or error. After a Pane restart, or once an agent exits back to its shell, stopped panels report `running: false` (`initialized` stays true while the shell lives) in `panels list`, `panels screen`, and `panels wait` (which returns `stopped: true` instead of timing out), and `nextCommand` points at `panels resume`. `runpane watch` reports them as `panel.stopped` (`STOPPED ...`) when `--kinds` lists that kind; other consumers and `workspace state` see `agent.unknown` with `running: false`, never `agent.ready`.", "`runpane panels last-message --panel <panel-id>` reads a Claude or Codex agent's last reply from its transcript (up to `--limit` characters, default 20,000, keeping the end and reporting `truncated`). It never scrapes the screen: without a transcript it prints `{ ok: false, reason: \"transcript-unavailable\" }` and exits 1.", "Commands with a contract `daemonAction` (the `panes` git, script, restore, and move commands, `folders list|create`, and `links open`) call the same Pane daemon channel as the matching button in the app and print `{ ok, data, error }`. Destructive ones add a pane:// `link` to review the Pane.", "`runpane links create` builds `pane://open?...` links; opening one in Pane selects what it names and never changes Pane state.", "`runpane docs search|read` search and read Pane docs, help, and installed Pane Chat skills offline. They ship in the npm package and the Pane app only.", "`runpane handoff` hands a task to another agent on this or another of your machines. The sending agent writes the note from `runpane handoff --template` (goal, current state, done and verified, in progress, next steps, decisions and constraints, open questions, how to verify, git state); `runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md` checks every section is filled in, requires the branch to be pushed (or pushes it with `--push`, never forcing), writes the note to that machine's `~/.pane/handoffs/` and starts the agent in a new Pane branched from the sender's branch. When the sender is a Pane tab running a Claude, Codex, Cursor or OpenCode session and the receiver is the same agent, the handoff carries that session: on another machine its files are copied into that machine's agent store and the receiver resumes the same id; on this machine the receiver resumes a fork, because two agents never resume one session on one machine. The receiver starts with no prompt, and the CLI runs the continuity check and reports JSON `continuity.result` `continued`, `inconclusive` (exit 0; `next` gives a probe question) or `not-continued` (exit 1; the receiver is kept and `next` gives the `--note-only` command). `--note-only`, a different agent, or a tab with no carried session starts a fresh agent with the note (`fresh-agent`). JSON `continuity` is `{ carried, result, agent, sessionId, resumedId, fork, files, bytes, checks: { resumedById, restartResumes, historyLoaded, originalUntouched?, originalAppended? }, reason, next }`: `sessionId` is the sender's session, `resumedId` the id the receiver resumes (the fork's on this machine), `checks` are the continuity checks (`historyLoaded` is null when there was nothing to compare; `originalUntouched` is set for forks), and a dry run sets `carried`, `sessionId`, `fork`, `files` and `bytes` with no `result`. After `continued` or `inconclusive` the sending agent ends its turn and makes no more changes on the branch. An OpenCode session travels as its export: `opencode export` on this machine, then `opencode import` inside the receiving repository there, and an OpenCode receiver is accepted only to continue an OpenCode session. A Cursor session is carried only to another machine, best effort since Cursor's store is undocumented: Cursor has no fork, and a copied chat still writes to the original, so on this machine the result is `not-continued` and nothing is started. A destination's agent store is assumed at its default location (`~/.claude`, `~/.codex`, `~/.cursor`); a copy already there is replaced only when the sender's holds all of it and no agent there runs it, otherwise nothing is copied and the result is `not-continued`. A destination Pane too old to resume a carried session is refused before anything is sent (`ERR_HANDOFF_RESUME_UNSUPPORTED`). From a Session's terminal it skips git and creates a Session with the same name, goal and agent on the other machine instead; a same-agent Session resumes the sender's conversation when first opened. The receiver reports back to the sender's panel.", "`runpane pr watch`: Register durable GitHub PR monitoring for a Pane.", "`runpane pr unwatch`: Remove a Pane’s explicit PR registration.", "`runpane pr list`: List PR registrations and stopped watches."];
         readonly wrapperFlagNote: "The top-level `runpane --version` form prints the wrapper version. The install subcommand form `runpane install --version vX.Y.Z` selects a Pane release.";
         readonly localControlFlagNote: "`runpane doctor --json`, `runpane repos list`, `runpane panes ...`, and `runpane panels ...` commands use or describe the local framed daemon socket/pipe for a running Pane app. `--pane-dir` points the wrapper at a non-default Pane data directory, such as `PANE_DIR=~/.pane_test` in development. `runpane agent-context` is local/offline and can be used before Pane is running. `agent-context` and `version` accept and ignore `--pane-dir`, so one `--pane-dir` can be passed to every runpane command. In a Pane repository checkout, if `runpane` is not on PATH, build the local wrapper with `pnpm --filter runpane build` and run it with Node 22 or newer, for example `node packages/runpane/dist/cli.js doctor --json`. From WSL, if the user runs Windows Pane, call the Windows wrapper through `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane ...'` so the command can reach the Windows named-pipe daemon and avoid UNC cwd issues.";
         readonly daemonFlagNote: "Unknown daemon flags should be forwarded rather than dropped so newer Pane versions can extend `--remote-setup` without requiring an immediate wrapper release. Unknown flags for non-daemon commands should fail clearly.";
@@ -1400,7 +1438,7 @@ export declare const RUNPANE_CONTRACT: {
         readonly publishingCredentials: readonly ["Local implementation, build, and dry-run validation do not need npm or PyPI API tokens.", "Release publishing should prefer npm Trusted Publishing and PyPI Trusted Publishing from GitHub Actions.", "Fallback `NPM_TOKEN` or `PYPI_API_TOKEN` credentials may be used for first package reservation or manual publication only. They must be supplied through local environment variables or GitHub Actions secrets, never committed, and revoked or rotated after use."];
     };
     readonly testFixtures: {
-        readonly parserSamples: readonly [readonly ["setup"], readonly ["install"], readonly ["install", "client", "--version", "v2.2.8", "--format", "dmg", "--download-dir", "/tmp/pane-downloads", "--dry-run", "--yes"], readonly ["install", "daemon", "--label", "VM", "--prefer-tunnel", "ssh", "--channel", "nightly", "--base-url", "https://example.test", "--pane-dir", "/tmp/pane", "--listen-port", "4555", "--auto-listen-port", "--print-only", "--repo-ref", "main", "--unknown-future-flag", "future-value", "--dry-run", "--verbose"], readonly ["update", "--version", "latest", "--format", "appimage", "--pane-path", "/usr/bin/pane", "--dry-run"], readonly ["doctor", "--pane-path", "/usr/bin/pane", "--format", "zip", "--verbose"], readonly ["doctor", "--json", "--pane-dir", "/tmp/pane"], readonly ["doctor", "--report", "--title", "watch failed", "--body-file", "/tmp/watch-evidence.txt", "--json"], readonly ["watch", "--as", "monitor", "--from", "earliest", "--follow", "--heartbeat", "60s", "--idle-after", "600000", "--ready-settle", "180000", "--blocked-settle", "30000", "--min-interval", "600000", "--expire-after", "10800000", "--exclude-pane", "pane-old", "--kinds", "agent.ready,agent.idle", "--include-held-input", "--self-test"], readonly ["daemon", "repair", "--pane-dir", "/tmp/pane-remote", "--yes", "--json"], readonly ["agent-context"], readonly ["agent-context", "--command", "panes create", "--json"], readonly ["repos", "list", "--json", "--pane-dir", "/tmp/pane"], readonly ["repos", "add", "--path", "/tmp/repo", "--name", "Repo", "--dry-run", "--yes", "--json", "--pane-dir", "/tmp/pane"], readonly ["panes", "list", "--repo", "active", "--json"], readonly ["panes", "cost", "--pane", "session-1", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "issue-252", "--agent", "codex", "--prompt", "Kick off discussion", "--source", "agent", "--pinned", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "issue-252", "--agent", "codex", "--prompt", "Kick off discussion", "--source", "agent", "--no-pinned", "--no-associate", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--from-json", "-", "--yes", "--json"], readonly ["panes", "archive", "--pane", "session-1", "--force", "--source", "agent", "--yes", "--json"], readonly ["panes", "pin", "--pane", "session-1", "--yes", "--json"], readonly ["panes", "unpin", "--pane", "session-1", "--yes", "--json"], readonly ["panes", "rename", "--pane", "session-1", "--name", "issue-393", "--yes", "--json"], readonly ["panes", "focus", "--pane", "session-1", "--panel", "panel-1", "--source", "user", "--yes", "--json"], readonly ["panels", "list", "--pane", "session-1", "--json"], readonly ["panels", "output", "--panel", "panel-1", "--limit", "200", "--json"], readonly ["panels", "input", "--panel", "panel-1", "--text", "Continue\\n", "--yes", "--json"], readonly ["--version"], readonly ["agents", "doctor", "--agent", "codex", "--repo", "active", "--json"], readonly ["panes", "create", "--from-json", "-", "--source", "agent", "--focus", "--wait-ready", "--ready-timeout-ms", "45000", "--concurrency", "2", "--yes", "--json"], readonly ["panels", "screen", "--panel", "panel-1", "--limit", "80", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "2", "--yes", "--json"], readonly ["panels", "wait", "--panel", "panel-1", "--for", "text", "--contains", "ready", "--timeout-ms", "30000", "--interval-ms", "500", "--json"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--source", "agent", "--no-focus", "--wait-ready", "--ready-timeout-ms", "15000", "--yes", "--json"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--focus", "--yes", "--json"], readonly ["panels", "submit-composer", "--panel", "panel-1", "--strategy", "auto", "--yes", "--json"], readonly ["sessions", "list", "--json"], readonly ["sessions", "get", "--session", "demo", "--json"], readonly ["sessions", "update", "--session", "demo", "--from-json", "-"], readonly ["panels", "submit", "--panel=panel-1", "--text=- [ ] item", "--yes", "--json"], readonly ["panes", "commit", "--pane", "pane-1", "--message", "fix: title\n\nbody", "--yes", "--json"], readonly ["links", "create", "--pane", "pane-1", "--panel", "panel-1", "--json"], readonly ["links", "open", "--url=pane://open?pane=pane-1", "--yes"], readonly ["mcp", "--toolsets", "core,git", "--read-only"], readonly ["docs", "search", "--query", "archive a pane", "--limit", "3"], readonly ["docs", "read", "--doc", "docs/PANE_MCP.md"], readonly ["agents", "start", "--repo", "active", "--name", "fix-login", "--agent", "claude", "--prompt", "Fix the login redirect", "--yes", "--json"], readonly ["agents", "send", "--pane", "pane-1", "--text=- [ ] item", "--yes"], readonly ["panels", "input", "--panel", "panel-1", "--keys", "down,enter", "--yes", "--json"], readonly ["panes", "squash-rebase", "--pane", "pane-1", "--message", "feat: land it", "--yes", "--json"], readonly ["folders", "create", "--repo", "3", "--name", "Reviews", "--yes"], readonly ["panes", "move", "--pane", "pane-1", "--folder", "folder-9", "--yes", "--json"], readonly ["watch", "--follow", "--json", "--pane-dir", "/tmp/pane"], readonly ["watch", "--follow"], readonly ["watch", "--session", "__orchestration_session_1b4e28ba-2fa1-11d2-883f-0016d3cca427__", "--follow", "--json", "--kinds", "agent.ready,agent.blocked,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged", "--ready-settle", "180000"], readonly ["watch", "--session=Release train", "--as", "release-watch", "--exclude-pane", "pane-old"], readonly ["agent-context", "--command", "panes create", "--json", "--pane-dir", "/tmp/pane"], readonly ["agent-context", "--pane-dir=/tmp/pane"], readonly ["version", "--pane-dir", "/tmp/pane"], readonly ["panes", "create", "--repo", "active", "--name", "w5a", "--agent", "claude", "--base-branch", "origin/release", "--source", "agent", "--no-focus", "--yes", "--json", "--pane-dir", "/tmp/pane"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--tool-command", "wrapper codex-run", "--wait-ready", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "farm", "--tool-command", "agent-farm run free-range", "--agent", "claude", "--prompt", "Plan", "--yes", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--input-file", "brief.md", "--as-file-pointer", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "long", "--agent", "claude", "--initial-input-file", "brief.md", "--as-file-pointer", "--dry-run", "--yes", "--json"], readonly ["report", "--state", "ready", "--pr", "747", "--head", "FC5DCE9", "--summary", "Done: tests pass", "--json"], readonly ["report", "--state", "blocked", "--question", "Which API version?", "--pane", "session-1", "--panel", "panel-1", "--summary-file", "-"], readonly ["report", "--state=done", "--summary-file=/tmp/report.md", "--pane-dir", "/tmp/pane"], readonly ["panels", "resume", "--all-stopped", "--wait-ready", "--concurrency", "2", "--yes", "--json"], readonly ["panels", "resume", "--panel", "panel-1", "--wait-ready", "--ready-timeout-ms", "45000", "--yes", "--json"], readonly ["panels", "last-message", "--panel", "panel-1", "--limit", "5000", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "w5a", "--base", "release/foo", "--branch", "agents/w5a", "--agent", "claude", "--prompt-file", "prompt.md", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "w5b", "--base-branch", "origin/main", "--branch", "agents/w5b", "--worktree-name", "w5b-dir", "--tool-command", "bash", "--initial-input-file", "-", "--dry-run", "--yes", "--json"], readonly ["panes", "archive", "--pane", "session-1", "--remove-worktree", "--yes", "--json"], readonly ["panes", "archive", "--session", "refactor", "--merged", "--dry-run", "--json"], readonly ["panes", "archive", "--session", "refactor", "--merged", "--remove-worktree", "--yes"], readonly ["lock", "acquire", "--name", "testing-account", "--ttl", "30m", "--wait", "1800000", "--note", "call QA", "--json"], readonly ["lock", "acquire", "--name", "staging-db", "--ttl", "1500", "--pane", "session-1", "--panel", "panel-1", "--pane-dir", "/tmp/pane"], readonly ["lock", "acquire", "--name=db", "--ttl=2h"], readonly ["lock", "release", "--name", "testing-account", "--force", "--session", "Release QA", "--json"], readonly ["lock", "list", "--session", "Release QA", "--json"], readonly ["lock", "--help"], readonly ["panels", "open", "--pane", "session-1", "--file", "plan.html", "--title", "Plan", "--split", "--no-focus", "--source", "agent", "--yes", "--json"], readonly ["panels", "open", "--url", "http://localhost:3000", "--tab", "--yes", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "correction", "--interrupt", "--yes", "--json"], readonly ["watch", "--as", "orch", "--until-event", "--json", "--kinds", "agent.report,agent.blocked,panel.exited,pane.gone", "--timeout-ms", "600000"], readonly ["pr", "watch", "--pane", "worker", "--url", "https://github.com/acme/app/pull/7"], readonly ["pr", "unwatch", "--pane", "worker", "--url", "https://github.com/acme/app/pull/7"], readonly ["pr", "list", "--pane", "worker"], readonly ["watch", "--follow", "--ready-settle", "5s", "--expire-after", "0"], readonly ["watch", "--until-event", "--timeout-ms", "30s"], readonly ["watch", "--timeout-ms", "off"], readonly ["watch", "--since", "42", "--epoch", "test-epoch", "--until-event", "--json"], readonly ["watch", "--follow", "--ready-settle", "5s", "--expire-after", "off"], readonly ["watch", "--follow", "--ready-settle", "5s", "--blocked-settle", "2s", "--min-interval", "1m", "--idle-after", "20m", "--expire-after", "off", "--heartbeat", "30s"], readonly ["watch", "--follow", "--since", "42", "--epoch", "test-epoch"]];
+        readonly parserSamples: readonly [readonly ["setup"], readonly ["install"], readonly ["install", "client", "--version", "v2.2.8", "--format", "dmg", "--download-dir", "/tmp/pane-downloads", "--dry-run", "--yes"], readonly ["install", "daemon", "--label", "VM", "--prefer-tunnel", "ssh", "--channel", "nightly", "--base-url", "https://example.test", "--pane-dir", "/tmp/pane", "--listen-port", "4555", "--auto-listen-port", "--print-only", "--repo-ref", "main", "--unknown-future-flag", "future-value", "--dry-run", "--verbose"], readonly ["update", "--version", "latest", "--format", "appimage", "--pane-path", "/usr/bin/pane", "--dry-run"], readonly ["doctor", "--pane-path", "/usr/bin/pane", "--format", "zip", "--verbose"], readonly ["doctor", "--json", "--pane-dir", "/tmp/pane"], readonly ["doctor", "--report", "--title", "watch failed", "--body-file", "/tmp/watch-evidence.txt", "--json"], readonly ["watch", "--as", "monitor", "--from", "earliest", "--follow", "--heartbeat", "60s", "--idle-after", "600000", "--ready-settle", "180000", "--blocked-settle", "30000", "--min-interval", "600000", "--expire-after", "10800000", "--exclude-pane", "pane-old", "--kinds", "agent.ready,agent.idle", "--include-held-input", "--self-test"], readonly ["daemon", "repair", "--pane-dir", "/tmp/pane-remote", "--yes", "--json"], readonly ["agent-context"], readonly ["agent-context", "--command", "panes create", "--json"], readonly ["repos", "list", "--json", "--pane-dir", "/tmp/pane"], readonly ["repos", "add", "--path", "/tmp/repo", "--name", "Repo", "--dry-run", "--yes", "--json", "--pane-dir", "/tmp/pane"], readonly ["panes", "list", "--repo", "active", "--json"], readonly ["panes", "cost", "--pane", "session-1", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "issue-252", "--agent", "codex", "--prompt", "Kick off discussion", "--source", "agent", "--pinned", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "issue-252", "--agent", "codex", "--prompt", "Kick off discussion", "--source", "agent", "--no-pinned", "--no-associate", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--from-json", "-", "--yes", "--json"], readonly ["panes", "archive", "--pane", "session-1", "--force", "--source", "agent", "--yes", "--json"], readonly ["panes", "pin", "--pane", "session-1", "--yes", "--json"], readonly ["panes", "unpin", "--pane", "session-1", "--yes", "--json"], readonly ["panes", "rename", "--pane", "session-1", "--name", "issue-393", "--yes", "--json"], readonly ["panes", "focus", "--pane", "session-1", "--panel", "panel-1", "--source", "user", "--yes", "--json"], readonly ["panels", "list", "--pane", "session-1", "--json"], readonly ["panels", "output", "--panel", "panel-1", "--limit", "200", "--json"], readonly ["panels", "input", "--panel", "panel-1", "--text", "Continue\\n", "--yes", "--json"], readonly ["--version"], readonly ["agents", "doctor", "--agent", "codex", "--repo", "active", "--json"], readonly ["panes", "create", "--from-json", "-", "--source", "agent", "--focus", "--wait-ready", "--ready-timeout-ms", "45000", "--concurrency", "2", "--yes", "--json"], readonly ["panels", "screen", "--panel", "panel-1", "--limit", "80", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "2", "--yes", "--json"], readonly ["panels", "wait", "--panel", "panel-1", "--for", "text", "--contains", "ready", "--timeout-ms", "30000", "--interval-ms", "500", "--json"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--source", "agent", "--no-focus", "--wait-ready", "--ready-timeout-ms", "15000", "--yes", "--json"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--focus", "--yes", "--json"], readonly ["panels", "submit-composer", "--panel", "panel-1", "--strategy", "auto", "--yes", "--json"], readonly ["sessions", "list", "--json"], readonly ["sessions", "get", "--session", "demo", "--json"], readonly ["sessions", "update", "--session", "demo", "--from-json", "-"], readonly ["panels", "submit", "--panel=panel-1", "--text=- [ ] item", "--yes", "--json"], readonly ["panes", "commit", "--pane", "pane-1", "--message", "fix: title\n\nbody", "--yes", "--json"], readonly ["links", "create", "--pane", "pane-1", "--panel", "panel-1", "--json"], readonly ["links", "open", "--url=pane://open?pane=pane-1", "--yes"], readonly ["mcp", "--toolsets", "core,git", "--read-only"], readonly ["docs", "search", "--query", "archive a pane", "--limit", "3"], readonly ["docs", "read", "--doc", "docs/PANE_MCP.md"], readonly ["agents", "start", "--repo", "active", "--name", "fix-login", "--agent", "claude", "--prompt", "Fix the login redirect", "--yes", "--json"], readonly ["agents", "send", "--pane", "pane-1", "--text=- [ ] item", "--yes"], readonly ["panels", "input", "--panel", "panel-1", "--keys", "down,enter", "--yes", "--json"], readonly ["panes", "squash-rebase", "--pane", "pane-1", "--message", "feat: land it", "--yes", "--json"], readonly ["folders", "create", "--repo", "3", "--name", "Reviews", "--yes"], readonly ["panes", "move", "--pane", "pane-1", "--folder", "folder-9", "--yes", "--json"], readonly ["watch", "--follow", "--json", "--pane-dir", "/tmp/pane"], readonly ["watch", "--follow"], readonly ["watch", "--session", "__orchestration_session_1b4e28ba-2fa1-11d2-883f-0016d3cca427__", "--follow", "--json", "--kinds", "agent.ready,agent.blocked,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged", "--ready-settle", "180000"], readonly ["watch", "--session=Release train", "--as", "release-watch", "--exclude-pane", "pane-old"], readonly ["agent-context", "--command", "panes create", "--json", "--pane-dir", "/tmp/pane"], readonly ["agent-context", "--pane-dir=/tmp/pane"], readonly ["version", "--pane-dir", "/tmp/pane"], readonly ["panes", "create", "--repo", "active", "--name", "w5a", "--agent", "claude", "--base-branch", "origin/release", "--source", "agent", "--no-focus", "--yes", "--json", "--pane-dir", "/tmp/pane"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "codex", "--tool-command", "wrapper codex-run", "--wait-ready", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "farm", "--tool-command", "agent-farm run free-range", "--agent", "claude", "--prompt", "Plan", "--yes", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--input-file", "brief.md", "--as-file-pointer", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "long", "--agent", "claude", "--initial-input-file", "brief.md", "--as-file-pointer", "--dry-run", "--yes", "--json"], readonly ["report", "--state", "ready", "--pr", "747", "--head", "FC5DCE9", "--summary", "Done: tests pass", "--json"], readonly ["report", "--state", "blocked", "--question", "Which API version?", "--pane", "session-1", "--panel", "panel-1", "--summary-file", "-"], readonly ["report", "--state=done", "--summary-file=/tmp/report.md", "--pane-dir", "/tmp/pane"], readonly ["panels", "resume", "--all-stopped", "--wait-ready", "--concurrency", "2", "--yes", "--json"], readonly ["panels", "resume", "--panel", "panel-1", "--wait-ready", "--ready-timeout-ms", "45000", "--yes", "--json"], readonly ["panels", "last-message", "--panel", "panel-1", "--limit", "5000", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "w5a", "--base", "release/foo", "--branch", "agents/w5a", "--agent", "claude", "--prompt-file", "prompt.md", "--dry-run", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "w5b", "--base-branch", "origin/main", "--branch", "agents/w5b", "--worktree-name", "w5b-dir", "--tool-command", "bash", "--initial-input-file", "-", "--dry-run", "--yes", "--json"], readonly ["panes", "archive", "--pane", "session-1", "--remove-worktree", "--yes", "--json"], readonly ["panes", "archive", "--session", "refactor", "--merged", "--dry-run", "--json"], readonly ["panes", "archive", "--session", "refactor", "--merged", "--remove-worktree", "--yes"], readonly ["lock", "acquire", "--name", "testing-account", "--ttl", "30m", "--wait", "1800000", "--note", "call QA", "--json"], readonly ["lock", "acquire", "--name", "staging-db", "--ttl", "1500", "--pane", "session-1", "--panel", "panel-1", "--pane-dir", "/tmp/pane"], readonly ["lock", "acquire", "--name=db", "--ttl=2h"], readonly ["lock", "release", "--name", "testing-account", "--force", "--session", "Release QA", "--json"], readonly ["lock", "list", "--session", "Release QA", "--json"], readonly ["lock", "--help"], readonly ["panels", "open", "--pane", "session-1", "--file", "plan.html", "--title", "Plan", "--split", "--no-focus", "--source", "agent", "--yes", "--json"], readonly ["panels", "open", "--url", "http://localhost:3000", "--tab", "--yes", "--json"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "correction", "--interrupt", "--yes", "--json"], readonly ["watch", "--as", "orch", "--until-event", "--json", "--kinds", "agent.report,agent.blocked,panel.exited,pane.gone", "--timeout-ms", "600000"], readonly ["pr", "watch", "--pane", "worker", "--url", "https://github.com/acme/app/pull/7"], readonly ["pr", "unwatch", "--pane", "worker", "--url", "https://github.com/acme/app/pull/7"], readonly ["pr", "list", "--pane", "worker"], readonly ["watch", "--follow", "--ready-settle", "5s", "--expire-after", "0"], readonly ["watch", "--until-event", "--timeout-ms", "30s"], readonly ["watch", "--timeout-ms", "off"], readonly ["watch", "--since", "42", "--epoch", "test-epoch", "--until-event", "--json"], readonly ["watch", "--follow", "--ready-settle", "5s", "--expire-after", "off"], readonly ["watch", "--follow", "--ready-settle", "5s", "--blocked-settle", "2s", "--min-interval", "1m", "--idle-after", "20m", "--expire-after", "off", "--heartbeat", "30s"], readonly ["watch", "--follow", "--since", "42", "--epoch", "test-epoch"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "go", "--expect-report", "--yes", "--json"], readonly ["panels", "create", "--pane", "pane-1", "--agent", "claude", "--expect-report", "--yes"], readonly ["panes", "create", "--repo", "active", "--name", "feat", "--agent", "codex", "--expect-report", "--yes"], readonly ["inbox", "--session", "Release", "--json"], readonly ["inbox", "ack", "in-1a2b3c4d", "in-5e6f7a8b", "--session", "Release", "--json"], readonly ["inbox", "ack", "--all", "--session", "Release"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "fyi", "--no-expect-report", "--yes"], readonly ["panels", "submit", "--panel", "panel-1", "--input-file", "prompt.md", "--as-file-pointer", "--wait", "--yes"], readonly ["panels", "submit", "--panel", "panel-1", "--text", "Red", "--wait", "--timeout", "30m", "--yes", "--json"], readonly ["panes", "create", "--repo", "active", "--name", "feat", "--agent", "claude", "--prompt-file", "task.md", "--wait", "--yes"], readonly ["lock", "acquire", "--name", "deploy", "--wait", "5000"]];
         readonly topLevelHelpIncludes: readonly ["runpane setup", "runpane install", "runpane update", "runpane version", "runpane doctor", "runpane agent-context", "runpane repos list", "runpane repos add", "runpane panes list", "runpane panes create", "runpane panes archive", "runpane panels create", "runpane panels list", "runpane panels output", "runpane panels input", "runpane agents doctor", "runpane panels screen", "runpane panels submit", "runpane panels submit-composer", "runpane panels wait", "runpane doctor --json", "runpane agent-context --json", "Agent discovery:", "Common commands:"];
         readonly npmHelpIncludes: readonly ["pnpm dlx runpane@latest", "npx --yes runpane@latest"];
         readonly pipHelpIncludes: readonly ["pipx run runpane", "python -m pip install runpane && python -m runpane setup"];
@@ -2009,6 +2047,12 @@ export declare const RUNPANE_CONTRACT: {
                                         readonly initialInputAsFilePointer: {
                                             readonly type: "boolean";
                                         };
+                                        readonly initialInputAttachments: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                            };
+                                        };
                                     };
                                     readonly additionalProperties: false;
                                 }, {
@@ -2030,6 +2074,12 @@ export declare const RUNPANE_CONTRACT: {
                                         readonly initialInputAsFilePointer: {
                                             readonly type: "boolean";
                                         };
+                                        readonly initialInputAttachments: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                            };
+                                        };
                                     };
                                     readonly additionalProperties: false;
                                 }];
@@ -2066,6 +2116,10 @@ export declare const RUNPANE_CONTRACT: {
                     readonly type: "string";
                     readonly description: "Session id to associate each created Pane with; the CLI sets it from PANE_ORCHESTRATION_SESSION_ID unless --no-associate.";
                 };
+                readonly expectReport: {
+                    readonly type: "boolean";
+                    readonly description: "true or false decides whether Pane waits for a `runpane report`; omitted, it waits unless source is user (and, for a submit, only on an agent's panel).";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -2315,6 +2369,12 @@ export declare const RUNPANE_CONTRACT: {
                                 readonly promptFile: {
                                     readonly type: "string";
                                 };
+                                readonly attachments: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                    };
+                                };
                                 readonly warnings: {
                                     readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/warnings";
                                 };
@@ -2393,6 +2453,10 @@ export declare const RUNPANE_CONTRACT: {
                         }];
                     };
                 };
+                readonly epoch: {
+                    readonly type: "string";
+                    readonly description: "Epoch of the journal position captured before dispatch; pass it with generation when waiting.";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -2730,7 +2794,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly type: "string";
                 };
                 readonly kind: {
-                    readonly enum: readonly ["agent.ready", "agent.busy", "agent.blocked", "agent.unknown", "agent.idle", "pane.created", "pane.gone", "panel.exited", "panel.stopped", "agent.report", "pane.associated", "pane.detached", "pr.conflicted", "pr.checks", "pr.merged", "pr.closed", "pr.head", "pr.review", "pr.comment", "pr.stopped", "github.unavailable", "github.recovered"];
+                    readonly enum: readonly ["agent.ready", "agent.busy", "agent.blocked", "agent.unknown", "agent.idle", "pane.created", "pane.gone", "panel.exited", "panel.stopped", "agent.report", "agent.report.missing", "pane.associated", "pane.detached", "pr.conflicted", "pr.checks", "pr.merged", "pr.closed", "pr.head", "pr.base_changed", "pr.base_deleted", "pr.review", "pr.comment", "pr.stopped", "github.unavailable", "github.recovered"];
                 };
                 readonly paneId: {
                     readonly type: "string";
@@ -2825,6 +2889,20 @@ export declare const RUNPANE_CONTRACT: {
                     };
                     readonly additionalProperties: false;
                 };
+                readonly base: {
+                    readonly type: "object";
+                    readonly description: "Base branch of a pr.base_changed (old to new) or pr.base_deleted (to is the PR's current base name) entry.";
+                    readonly required: readonly ["from", "to"];
+                    readonly properties: {
+                        readonly from: {
+                            readonly type: "string";
+                        };
+                        readonly to: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
                 readonly checks: {
                     readonly enum: readonly ["passed", "failed"];
                     readonly description: "Failures are immediate; success requires complete nonempty required checks on the pinned head.";
@@ -2844,6 +2922,25 @@ export declare const RUNPANE_CONTRACT: {
                     readonly type: "string";
                     readonly description: "Added to watch --json NDJSON events. Persist with gen after processing for numeric rearm.";
                 };
+                readonly lastOutput: {
+                    readonly type: "string";
+                    readonly description: "What an agent.report.missing entry's agent said last, up to 2,000 characters (the end is kept).";
+                };
+                readonly lastOutputSource: {
+                    readonly enum: readonly ["transcript", "screen"];
+                    readonly description: "transcript: the agent's last reply; screen: the last lines on its screen.";
+                };
+                readonly expectedSince: {
+                    readonly type: "string";
+                    readonly description: "When the work an agent.report.missing entry is about was sent.";
+                };
+                readonly screenLines: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "The screen lines of the prompt an agent.blocked entry's agent waits on (at most 20).";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -2879,6 +2976,42 @@ export declare const RUNPANE_CONTRACT: {
             };
             readonly additionalProperties: false;
         };
+        readonly panelReport: {
+            readonly type: "object";
+            readonly description: "A panel's latest runpane report in sessions overview. data is the summary when it is a complete JSON object, returned as the worker gave it; a plain-text, array, scalar, invalid, more than 64 levels deep, or truncated summary has no data.";
+            readonly required: readonly ["state", "reportedAt"];
+            readonly properties: {
+                readonly state: {
+                    readonly enum: readonly ["ready", "blocked", "failed", "done"];
+                };
+                readonly pr: {
+                    readonly type: "number";
+                };
+                readonly head: {
+                    readonly type: "string";
+                };
+                readonly summary: {
+                    readonly type: "string";
+                };
+                readonly summaryTruncated: {
+                    readonly const: true;
+                };
+                readonly summaryPath: {
+                    readonly type: "string";
+                };
+                readonly question: {
+                    readonly type: "string";
+                };
+                readonly reportedAt: {
+                    readonly type: "string";
+                };
+                readonly data: {
+                    readonly type: "object";
+                    readonly description: "The worker's JSON object summary, returned as given. Pane never reads, renames or validates its fields.";
+                };
+            };
+            readonly additionalProperties: false;
+        };
         readonly workspaceWaitRequest: {
             readonly type: "object";
             readonly properties: {
@@ -3798,6 +3931,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly asFilePointer: {
                     readonly type: "boolean";
                 };
+                readonly attachments: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
                 readonly source: {
                     readonly type: "string";
                     readonly enum: readonly ["user", "agent"];
@@ -3805,6 +3944,10 @@ export declare const RUNPANE_CONTRACT: {
                 readonly interrupt: {
                     readonly type: "boolean";
                 };
+                readonly expectReport: {
+                    readonly type: "boolean";
+                    readonly description: "true or false decides whether Pane waits for a `runpane report`; omitted, it waits unless source is user (and, for a submit, only on an agent's panel).";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -3862,6 +4005,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly promptFile: {
                     readonly type: "string";
                 };
+                readonly attachments: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
                 readonly warnings: {
                     readonly type: "array";
                     readonly items: {
@@ -3884,6 +4033,21 @@ export declare const RUNPANE_CONTRACT: {
                 readonly verification: {
                     readonly enum: readonly ["observed", "unverifiable"];
                 };
+                readonly expectedReport: {
+                    readonly type: "object";
+                    readonly required: readonly ["since"];
+                    readonly properties: {
+                        readonly since: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                    readonly description: "The report Pane now waits for: set for work an agent sent, or with --expect-report.";
+                };
+                readonly epoch: {
+                    readonly type: "string";
+                    readonly description: "Epoch of the journal position captured before dispatch; pass it with generation when waiting.";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -4474,6 +4638,10 @@ export declare const RUNPANE_CONTRACT: {
                 readonly readyTimeoutMs: {
                     readonly type: "number";
                 };
+                readonly expectReport: {
+                    readonly type: "boolean";
+                    readonly description: "true or false decides whether Pane waits for a `runpane report`; omitted, it waits unless source is user (and, for a submit, only on an agent's panel).";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -4607,12 +4775,33 @@ export declare const RUNPANE_CONTRACT: {
                 readonly promptFile: {
                     readonly type: "string";
                 };
+                readonly attachments: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
                 readonly warnings: {
                     readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/warnings";
                 };
                 readonly nextCommand: {
                     readonly type: "string";
                 };
+                readonly expectedReport: {
+                    readonly type: "object";
+                    readonly required: readonly ["since"];
+                    readonly properties: {
+                        readonly since: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                    readonly description: "The report Pane now waits for: set for work an agent sent, or with --expect-report.";
+                };
+                readonly epoch: {
+                    readonly type: "string";
+                    readonly description: "Epoch of the journal position captured before dispatch; pass it with generation when waiting.";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -4809,6 +4998,22 @@ export declare const RUNPANE_CONTRACT: {
                 };
                 readonly panes: {
                     readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly panels: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "object";
+                                    readonly properties: {
+                                        readonly report: {
+                                            readonly $ref: "#/jsonSchemas/panelReport";
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
                 };
                 readonly activity: {
                     readonly type: "array";
@@ -5428,6 +5633,187 @@ export declare const RUNPANE_CONTRACT: {
             };
             readonly additionalProperties: false;
         };
+        readonly inboxListResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "session", "items"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly session: {
+                    readonly type: "object";
+                    readonly required: readonly ["id", "name"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                        };
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+                readonly items: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["id", "sessionId", "kind", "at", "paneId", "paneName", "panelId"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly sessionId: {
+                                readonly type: "string";
+                            };
+                            readonly kind: {
+                                readonly enum: readonly ["report", "report.missing", "blocked"];
+                            };
+                            readonly at: {
+                                readonly type: "string";
+                            };
+                            readonly paneId: {
+                                readonly type: "string";
+                            };
+                            readonly paneName: {
+                                readonly type: "string";
+                            };
+                            readonly panelId: {
+                                readonly type: "string";
+                            };
+                            readonly panelTitle: {
+                                readonly type: "string";
+                            };
+                            readonly agentType: {
+                                readonly type: "string";
+                            };
+                            readonly report: {
+                                readonly $ref: "#/jsonSchemas/agentReport";
+                            };
+                            readonly lastOutput: {
+                                readonly type: "string";
+                            };
+                            readonly lastOutputSource: {
+                                readonly enum: readonly ["transcript", "screen"];
+                            };
+                            readonly reason: {
+                                readonly type: "string";
+                            };
+                            readonly screenLines: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly inboxAckResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "acknowledged", "unknown"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly acknowledged: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly unknown: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly dispatchWaitResult: {
+            readonly type: "object";
+            readonly description: "What `--wait` prints, as one line: how the dispatched work ended. Exit codes: 0 report, 3 missing, 4 blocked, 5 exited or gone, 124 timeout. Exit 6 is indeterminate after journal replacement or history loss; inspect the panel and inbox before retrying.";
+            readonly required: readonly ["ok", "outcome"];
+            readonly properties: {
+                readonly ok: {
+                    readonly type: "boolean";
+                    readonly description: "true only for outcome report.";
+                };
+                readonly outcome: {
+                    readonly enum: readonly ["report", "missing", "blocked", "exited", "gone", "timeout", "indeterminate"];
+                };
+                readonly paneId: {
+                    readonly type: "string";
+                };
+                readonly paneName: {
+                    readonly type: "string";
+                };
+                readonly panelId: {
+                    readonly type: "string";
+                };
+                readonly generation: {
+                    readonly type: "number";
+                    readonly description: "The journal entry that ended the wait (on timeout, the position reached).";
+                };
+                readonly at: {
+                    readonly type: "string";
+                };
+                readonly report: {
+                    readonly type: "object";
+                    readonly required: readonly ["state"];
+                    readonly properties: {
+                        readonly state: {
+                            readonly enum: readonly ["ready", "blocked", "failed", "done"];
+                        };
+                        readonly pr: {
+                            readonly type: "number";
+                        };
+                        readonly head: {
+                            readonly type: "string";
+                        };
+                        readonly summary: {
+                            readonly type: "string";
+                        };
+                        readonly summaryTruncated: {
+                            readonly const: true;
+                        };
+                        readonly summaryPath: {
+                            readonly type: "string";
+                        };
+                        readonly question: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+                readonly screenLines: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly lastOutput: {
+                    readonly type: "string";
+                };
+                readonly lastOutputSource: {
+                    readonly enum: readonly ["transcript", "screen"];
+                };
+                readonly reason: {
+                    readonly type: "string";
+                };
+                readonly exitCode: {
+                    readonly type: "number";
+                };
+                readonly nextCommand: {
+                    readonly type: "string";
+                    readonly description: "Recovery command when the outcome is indeterminate.";
+                };
+            };
+            readonly additionalProperties: false;
+        };
     };
     readonly agentContext: {
         readonly brief: {
@@ -5941,7 +6327,12 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--as-file-pointer";
                     readonly required: false;
-                    readonly description: "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead.";
+                    readonly description: "Write the prompt or text to a private prompt file (in the Pane's worktree, hidden from git, when it has one) and send the one line `Read and follow <path>` instead.";
+                }, {
+                    readonly name: "--attach";
+                    readonly required: false;
+                    readonly value: "<file>";
+                    readonly description: "Copy a file beside the --as-file-pointer prompt file and list its copy in the pointer line; repeatable. Needs --as-file-pointer; the result lists the copies in `attachments`.";
                 }, {
                     readonly name: "--from-json";
                     readonly value: "<path|->";
@@ -6003,10 +6394,27 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path>";
                     readonly required: false;
                     readonly description: "Connect to a specific Pane data directory.";
+                }, {
+                    readonly name: "--expect-report";
+                    readonly required: false;
+                    readonly description: "Expect a `runpane report` even for --source user work. Work an agent sends expects one by default: Pane emits agent.report.missing (with the agent's last output) if the agent goes ready or exits without one.";
+                }, {
+                    readonly name: "--no-expect-report";
+                    readonly required: false;
+                    readonly description: "Fire-and-forget input: don't wait for a report.";
+                }, {
+                    readonly name: "--wait";
+                    readonly required: false;
+                    readonly description: "Block until this panel reports (exit 0), misses its report (3), waits on a prompt (4), or exits (5); print one JSON line. The way an orchestrator dispatches: run it as a background tool call.";
+                }, {
+                    readonly name: "--timeout";
+                    readonly value: "<duration>";
+                    readonly required: false;
+                    readonly description: "With --wait: give up after this long and exit 124 (outcome timeout).";
                 }];
                 readonly examples: readonly ["runpane panes create --repo active --name issue-257 --agent <agent> --prompt \"Plan this issue\" --source agent --no-focus --wait-ready --yes --json", "runpane panes create --repo active --name w5a --base origin/main --branch agents/w5a --agent <agent> --prompt-file prompt.md --source agent --no-focus --wait-ready --yes --json", "runpane panes create --from-json panes.json --yes --json", "runpane panes create --repo active --name issue-123 --agent <agent> --prompt \"Plan this issue\" --source agent --no-focus --wait-ready --yes --json", "runpane panes create --repo active --name issue-123 --agent claude --initial-input-file brief.md --as-file-pointer --source agent --no-focus --wait-ready --yes --json"];
                 readonly jsonSchemas: readonly ["paneCreateRequest", "paneCreateResult"];
-                readonly notes: readonly ["At least one of --agent or --tool-command is required unless --from-json is used.", "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane: before creating one, find the feature's Pane with `runpane panes list --repo <repo> --json` by matching the PR's head branch (`gh pr view <n> --json headRefName`) against `git -C <worktreePath> branch --show-current`, and add a tab with `panels create --pane <id>` when it exists.", "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.", "`panes create --base <ref> --branch <name> --prompt-file <file>` replaces `git worktree add` plus `panes adopt`: Pane creates the worktree on exactly that branch name. `--branch` is checked with `git check-ref-format --branch` and fails if the branch already exists; `--worktree-name` still names the directory.", "Agent-created Panes should pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved. `panes create` pins the new Pane by default, so a follow-up `panes pin` call is unnecessary; pass `--no-pinned` for throwaway shells or bulk imports. `--pinned` is still accepted and is now a no-op. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.", "The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.", "Use --initial-input-file for multi-line prompts or shell-sensitive initial input. A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "`--as-file-pointer` writes the text to `<pane-dir>/prompts/<pane-id>/<timestamp>.md` (readable only by you) and sends the one line `Read and follow <path>`; the result includes `promptFile`. Prefer it for long prompts.", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "With --wait-ready, `initialInput.delivery` reports `taken`, `queued`, `in-composer` or `unknown` with its evidence (`transcript`, `screen`, or `argv` for a prompt passed at launch); verifiedSubmitted is true for `taken` or `queued`. Routing initial input alone does not imply verified submission, and the create's `ok` is false unless a Claude or Codex starting message is verified.", "If initialInput.blocked.kind is submission_unverified, do not submit again automatically. Inspect initialInput.staged and attempts, then run nextCommand to resolve the ambiguous composer state.", "When the JSON result includes nextCommand, run it to validate that the terminal produced output before reporting success.", "Multi-pane requests are created sequentially today. The --concurrency flag is accepted for compatibility, but agents should not rely on parallel creation.", "For POSIX or WSL command chaining, use a custom terminal command like `bash -lc 'cmd1 && cmd2 && cmd3'`.", "For Windows PowerShell command chaining, use a custom terminal command like `powershell -NoProfile -Command \"cmd1; if ($LASTEXITCODE) { exit $LASTEXITCODE }; cmd2\"`.", "From WSL with Windows Pane, invoke through PowerShell and select the saved WSL repo by name or id, for example `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane panes create --repo \"WSL Pane\" --name issue-123 --agent <agent> --prompt \"Plan this issue\" --source agent --no-focus --wait-ready --yes --json'`.", "Use --wait-ready when an agent needs the started agent at its input box, and its starting message verified, instead of only creating a pane.", "If readiness returns blocked, inspect blocked.suggestedCommand rather than guessing which prompt to answer.", "With --tool-command, --agent names the agent the command runs (a wrapper such as `agent-farm run`): Pane launches the command unchanged and treats the panel as that agent. Without --agent, Pane detects Claude Code, Codex and Cursor from the foreground process or the agent's screen, and --wait-ready waits for the detected agent's input box; a command that never shows a supported agent is not ready and nothing is typed into it.", "At most 2 Panes run setup at once (worktree file sync, dependency install, build script); more wait in line. A queued `panes create` returns the Pane id right away with `setupQueue` ({ position, message }) and no `panelId`; the agent starts when setup finishes. Find its panel later with `runpane panels list --pane <id> --json`.", "A Pane with its own worktree starts at the remote's current tip of a remote-tracking base (the default `origin/main`, or one named with `--base`): Pane fetches that branch first, waiting at most about 10 seconds, and creates started together share the fetch. Each item's `base` reports `{ ref, commit, refresh }`, where `refresh` is `fetched`, `recent` (reused a fetch from the last 30 seconds), `skipped` (a local branch or commit base) or `failed`. A failed refresh never fails the create; the Pane starts from the local ref and `base.notice` says what happened and how to catch up.", "`panes create --branch <name>` fails with code `ERR_RUNPANE_BRANCH_HAS_PANE` when another Pane already has that branch checked out. The message names the Pane and gives the next step: `runpane panels create --pane <id> --tool-command \"<cmd>\" --source agent --no-focus`."];
+                readonly notes: readonly ["At least one of --agent or --tool-command is required unless --from-json is used.", "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane: before creating one, find the feature's Pane with `runpane panes list --repo <repo> --json` by matching the PR's head branch (`gh pr view <n> --json headRefName`) against `git -C <worktreePath> branch --show-current`, and add a tab with `panels create --pane <id>` when it exists.", "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.", "`panes create --base <ref> --branch <name> --prompt-file <file>` replaces `git worktree add` plus `panes adopt`: Pane creates the worktree on exactly that branch name. `--branch` is checked with `git check-ref-format --branch` and fails if the branch already exists; `--worktree-name` still names the directory.", "Agent-created Panes should pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved. `panes create` pins the new Pane by default, so a follow-up `panes pin` call is unnecessary; pass `--no-pinned` for throwaway shells or bulk imports. `--pinned` is still accepted and is now a no-op. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.", "The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.", "Use --initial-input-file for multi-line prompts or shell-sensitive initial input. A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.", "`--as-file-pointer` writes the text to a prompt file readable only by you, inside the Pane's git worktree at `.pane/prompts/` (hidden by the repository's `.git/info/exclude`, never committed) when it has one, otherwise under `<pane-dir>/prompts/<pane-id>/`, so an agent limited to its working directories reads it without a permission prompt, and sends the one line `Read and follow <path>`, with the path relative to the worktree (where the agent starts) when the file is inside it; the result's `promptFile` is always absolute. Prefer it for long prompts.", "`--attach <file>` (repeatable, with `--as-file-pointer`) copies each file into a folder beside the prompt file and sends `Read and follow <path> (attached: <copy>, ...)`; the result lists the copies in `attachments`.", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "With --wait-ready, `initialInput.delivery` reports `taken`, `queued`, `in-composer` or `unknown` with its evidence (`transcript`, `screen`, or `argv` for a prompt passed at launch); verifiedSubmitted is true for `taken` or `queued`. Routing initial input alone does not imply verified submission, and the create's `ok` is false unless a Claude or Codex starting message is verified.", "If initialInput.blocked.kind is submission_unverified, do not submit again automatically. Inspect initialInput.staged and attempts, then run nextCommand to resolve the ambiguous composer state.", "When the JSON result includes nextCommand, run it to validate that the terminal produced output before reporting success.", "Multi-pane requests are created sequentially today. The --concurrency flag is accepted for compatibility, but agents should not rely on parallel creation.", "For POSIX or WSL command chaining, use a custom terminal command like `bash -lc 'cmd1 && cmd2 && cmd3'`.", "For Windows PowerShell command chaining, use a custom terminal command like `powershell -NoProfile -Command \"cmd1; if ($LASTEXITCODE) { exit $LASTEXITCODE }; cmd2\"`.", "From WSL with Windows Pane, invoke through PowerShell and select the saved WSL repo by name or id, for example `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane panes create --repo \"WSL Pane\" --name issue-123 --agent <agent> --prompt \"Plan this issue\" --source agent --no-focus --wait-ready --yes --json'`.", "Use --wait-ready when an agent needs the started agent at its input box, and its starting message verified, instead of only creating a pane.", "If readiness returns blocked, inspect blocked.suggestedCommand rather than guessing which prompt to answer.", "With --tool-command, --agent names the agent the command runs (a wrapper such as `agent-farm run`): Pane launches the command unchanged and treats the panel as that agent. Without --agent, Pane detects Claude Code, Codex and Cursor from the foreground process or the agent's screen, and --wait-ready waits for the detected agent's input box; a command that never shows a supported agent is not ready and nothing is typed into it.", "At most 2 Panes run setup at once (worktree file sync, dependency install, build script); more wait in line. A queued `panes create` returns the Pane id right away with `setupQueue` ({ position, message }) and no `panelId`; the agent starts when setup finishes. Find its panel later with `runpane panels list --pane <id> --json`.", "A Pane with its own worktree starts at the remote's current tip of a remote-tracking base (the default `origin/main`, or one named with `--base`): Pane fetches that branch first, waiting at most about 10 seconds, and creates started together share the fetch. Each item's `base` reports `{ ref, commit, refresh }`, where `refresh` is `fetched`, `recent` (reused a fetch from the last 30 seconds), `skipped` (a local branch or commit base) or `failed`. A failed refresh never fails the create; the Pane starts from the local ref and `base.notice` says what happened and how to catch up.", "`panes create --branch <name>` fails with code `ERR_RUNPANE_BRANCH_HAS_PANE` when another Pane already has that branch checked out. The message names the Pane and gives the next step: `runpane panels create --pane <id> --tool-command \"<cmd>\" --source agent --no-focus`."];
             };
             readonly "panes adopt": {
                 readonly name: "panes adopt";
@@ -6483,7 +6891,12 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--as-file-pointer";
                     readonly required: false;
-                    readonly description: "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead.";
+                    readonly description: "Write the prompt or text to a private prompt file (in the Pane's worktree, hidden from git, when it has one) and send the one line `Read and follow <path>` instead.";
+                }, {
+                    readonly name: "--attach";
+                    readonly required: false;
+                    readonly value: "<file>";
+                    readonly description: "Copy a file beside the --as-file-pointer prompt file and list its copy in the pointer line; repeatable. Needs --as-file-pointer; the result lists the copies in `attachments`.";
                 }, {
                     readonly name: "--interrupt";
                     readonly required: false;
@@ -6501,10 +6914,27 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path>";
                     readonly required: false;
                     readonly description: "Connect to a specific Pane data directory.";
+                }, {
+                    readonly name: "--expect-report";
+                    readonly required: false;
+                    readonly description: "Expect a `runpane report` even for --source user work. Work an agent sends expects one by default: Pane emits agent.report.missing (with the agent's last output) if the agent goes ready or exits without one.";
+                }, {
+                    readonly name: "--no-expect-report";
+                    readonly required: false;
+                    readonly description: "Fire-and-forget input: don't wait for a report.";
+                }, {
+                    readonly name: "--wait";
+                    readonly required: false;
+                    readonly description: "Block until this panel reports (exit 0), misses its report (3), waits on a prompt (4), or exits (5); print one JSON line. The way an orchestrator dispatches: run it as a background tool call.";
+                }, {
+                    readonly name: "--timeout";
+                    readonly value: "<duration>";
+                    readonly required: false;
+                    readonly description: "With --wait: give up after this long and exit 124 (outcome timeout).";
                 }];
-                readonly examples: readonly ["runpane panels submit --panel <panel-id> --text \"2\" --yes --json", "printf \"echo hello\" | runpane panels submit --panel <panel-id> --input-file - --yes --json", "runpane panels submit --panel <panel-id> --input-file brief.md --as-file-pointer --yes --json", "runpane panels submit --panel <panel-id> --text \"Stop that approach and follow this correction\" --interrupt --yes --json"];
+                readonly examples: readonly ["runpane panels submit --panel <panel-id> --input-file prompt.md --as-file-pointer --wait --yes", "runpane panels submit --panel <panel-id> --text \"2\" --yes --json", "printf \"echo hello\" | runpane panels submit --panel <panel-id> --input-file - --yes --json", "runpane panels submit --panel <panel-id> --input-file brief.md --as-file-pointer --yes --json", "runpane panels submit --panel <panel-id> --text \"Stop that approach and follow this correction\" --interrupt --yes --json"];
                 readonly jsonSchemas: readonly ["panelSubmitRequest", "panelSubmitResult"];
-                readonly notes: readonly ["The response includes sequenceName, verifiedSubmitted, delivery and nextCommand. For Claude and Codex, `delivery.state` is `taken` (the agent started a turn with the text), `queued` (it holds the text until its current turn ends), `in-composer` (the text is still in the composer) or `unknown`, and `delivery.evidence` is `transcript` (the agent's own transcript) or `screen`. verifiedSubmitted is true for `taken` or `queued`; never resend those. If ok is false, inspect blocked and do not assume the turn started.", "Do not follow `panels submit` with `panels submit-composer`; Claude and Codex composer submission is handled atomically.", "Use `panels input` for Ctrl-C, escape sequences, or any workflow requiring exact bytes.", "On `blocked.kind: composer-unknown`, nothing was typed. Check `panels screen`; if the agent is at a prompt Pane does not recognise, use `panels input`.", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "`--as-file-pointer` writes the text to `<pane-dir>/prompts/<pane-id>/<timestamp>.md` (readable only by you) and sends the one line `Read and follow <path>`; the result includes `promptFile`. Prefer it for long prompts.", "With --interrupt, Pane sends the stop key only while the agent is active, waits for an empty idle composer, then submits. If readiness times out, replacement text is not sent. A queued result is not read yet: delivery.message explains the delay; never resend queued text. Interrupt success requires delivery.state: taken. Unknown agents and occupied composers are rejected without typing."];
+                readonly notes: readonly ["The response includes sequenceName, verifiedSubmitted, delivery and nextCommand. For Claude and Codex, `delivery.state` is `taken` (the agent started a turn with the text), `queued` (it holds the text until its current turn ends), `in-composer` (the text is still in the composer) or `unknown`, and `delivery.evidence` is `transcript` (the agent's own transcript) or `screen`. verifiedSubmitted is true for `taken` or `queued`; never resend those. If ok is false, inspect blocked and do not assume the turn started.", "Do not follow `panels submit` with `panels submit-composer`; Claude and Codex composer submission is handled atomically.", "Use `panels input` for Ctrl-C, escape sequences, or any workflow requiring exact bytes.", "On `blocked.kind: composer-unknown`, nothing was typed. Check `panels screen`; if the agent is at a prompt Pane does not recognise, use `panels input`.", "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.", "`--as-file-pointer` writes the text to a prompt file readable only by you, inside the Pane's git worktree at `.pane/prompts/` (hidden by the repository's `.git/info/exclude`, never committed) when it has one, otherwise under `<pane-dir>/prompts/<pane-id>/`, so an agent limited to its working directories reads it without a permission prompt, and sends the one line `Read and follow <path>`, with the path relative to the worktree (where the agent starts) when the file is inside it; the result's `promptFile` is always absolute. Prefer it for long prompts.", "`--attach <file>` (repeatable, with `--as-file-pointer`) copies each file into a folder beside the prompt file and sends `Read and follow <path> (attached: <copy>, ...)`; the result lists the copies in `attachments`.", "With --interrupt, Pane sends the stop key only while the agent is active, waits for an empty idle composer, then submits. If readiness times out, replacement text is not sent. A queued result is not read yet: delivery.message explains the delay; never resend queued text. Interrupt success requires delivery.state: taken. Unknown agents and occupied composers are rejected without typing."];
             };
             readonly "panels resume": {
                 readonly name: "panels resume";
@@ -6672,7 +7102,12 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--as-file-pointer";
                     readonly required: false;
-                    readonly description: "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead.";
+                    readonly description: "Write the prompt or text to a private prompt file (in the Pane's worktree, hidden from git, when it has one) and send the one line `Read and follow <path>` instead.";
+                }, {
+                    readonly name: "--attach";
+                    readonly required: false;
+                    readonly value: "<file>";
+                    readonly description: "Copy a file beside the --as-file-pointer prompt file and list its copy in the pointer line; repeatable. Needs --as-file-pointer; the result lists the copies in `attachments`.";
                 }, {
                     readonly name: "--source";
                     readonly value: "<user|agent>";
@@ -6708,6 +7143,23 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path>";
                     readonly required: false;
                     readonly description: "Connect to a specific Pane data directory.";
+                }, {
+                    readonly name: "--expect-report";
+                    readonly required: false;
+                    readonly description: "Expect a `runpane report` even for --source user work. Work an agent sends expects one by default: Pane emits agent.report.missing (with the agent's last output) if the agent goes ready or exits without one.";
+                }, {
+                    readonly name: "--no-expect-report";
+                    readonly required: false;
+                    readonly description: "Fire-and-forget input: don't wait for a report.";
+                }, {
+                    readonly name: "--wait";
+                    readonly required: false;
+                    readonly description: "Block until this panel reports (exit 0), misses its report (3), waits on a prompt (4), or exits (5); print one JSON line. The way an orchestrator dispatches: run it as a background tool call.";
+                }, {
+                    readonly name: "--timeout";
+                    readonly value: "<duration>";
+                    readonly required: false;
+                    readonly description: "With --wait: give up after this long and exit 124 (outcome timeout).";
                 }];
                 readonly examples: readonly ["runpane panels create --pane <pane-id> --agent <agent> --source agent --no-focus --wait-ready --yes --json", "runpane panels create --pane <pane-id> --tool-command <command> --title <title> --source agent --no-focus --wait-ready --yes --json", "runpane panels create --pane <pane-id> --tool-command \"agent-farm run free-range\" --agent claude --source agent --no-focus --wait-ready --yes --json"];
                 readonly jsonSchemas: readonly ["panelCreateRequest", "panelCreateResult"];
@@ -6916,7 +7368,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--min-interval";
                     readonly value: "<duration>";
                     readonly required: false;
-                    readonly description: "Override: batch READY, IDLE, NEW, GONE, EXIT, and UNKNOWN lines at most once per interval; REPORT, BLOCKED, pr.conflicted, and failed pr.checks arrive at once and carry the held lines. Default 10m. 0 turns batching off.";
+                    readonly description: "Override: batch READY, IDLE, NEW, GONE, EXIT, and UNKNOWN lines at most once per interval; REPORT, BLOCKED, pr.conflicted, pr.base_changed, pr.base_deleted, and failed pr.checks arrive at once and carry the held lines. Default 10m. 0 turns batching off.";
                 }, {
                     readonly name: "--idle-after";
                     readonly value: "<duration>";
@@ -6966,7 +7418,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly required: false;
                 }];
                 readonly examples: readonly ["runpane watch --self-test", "runpane watch --until-event", "runpane watch --follow", "runpane watch --session <id|name> --follow", "runpane watch --session <id|name> --follow --ready-settle 1m --blocked-settle 15s --min-interval 2m", "runpane watch --follow --json --kinds agent.report,agent.blocked"];
-                readonly notes: readonly ["Every default is in the contract under defaults.watch: follow (what --follow does) and untilEvent (what --until-event waits for). An override flag replaces one value; nothing else needs remembering.", "Arming: wait for WATCH OK before relying on a --follow monitor. It prints once when the watch is armed. Run the monitor under your harness's background monitor (one line = one notification).", "Ending: WATCH EXPIRED (exit 0) means nothing happened for --expire-after: say so, and arm a new watch with the next dispatch. A non-zero exit or a WATCH ERROR line means it failed: tell the user and re-arm once; if it dies again, file runpane doctor --report. If the message says the cursor was superseded, keep the replacement monitor and leave the old one stopped. Judge a watch by these lines, never by silence.", "--until-event prints exactly one line: the event (exit 0), WATCH TIMEOUT (exit 124, only with --timeout-ms), or WATCH ERROR (exit 2).", "STUCK means real unsubmitted composer text. An agent prompt suggestion (for example a grey Try \"...\" hint) never counts.", "Cadence state is held per named consumer. Without numeric --since, follow uses an explicit --as or assigns a Session, panel, or follow-<pid> name. With numeric --since it has no name and bypasses cadence; --as cannot be combined with --since. Held lines survive a reconnect of the same consumer; a changed filter re-delivers them under the new filter.", "Journal loss is surfaced through reset and dropped metadata.", "The daemon treats omitted idleAfterMs as disabled so older clients never receive agent.idle unexpectedly.", "Control lines are not journal entries. Lines text and JSON kind: WATCH OK (_ok, once when armed), HEARTBEAT (_heartbeat, only with --heartbeat), WATCH RECONNECTED (_reconnected, after a retried daemon error), WATCH ERROR (_error; exit 2 unless --follow or --until-event retries it), RESET (_reset, the journal restarted or the cursor fell behind; a fresh baseline follows), DROPPED (_dropped, entries lost to journal truncation), WATCH TIMEOUT (_timeout, --until-event deadline; exit 124), and WATCH EXPIRED (_expired, --expire-after passed; exit 0). Under --until-event, only _timeout and _error print.", "Under --follow, JSON entries for panels holding unsubmitted composer text carry heldInputPresent: true, the JSON equivalent of the STUCK line. Only typed composer text counts, the same reading as panels screen composer.hasUndeliveredText; an agent's dim or grey prompt suggestion or placeholder does not. --no-held-input turns this off.", "--session <id|name> scopes the watch to a named Session. The daemon resolves the Session once per request and its associated Panes on every read, so sessions associate and sessions detach take effect without a re-arm; archived and detached Panes drop out, and the Session's own orchestrator panels are excluded. Cadence state is keyed by the Session, not its current Panes, so membership changes keep held lines. A detached Pane's held lines are dropped.", "Under --session, pane.associated (JOINED <pane-name> pane <pane-id> session <session-id>) and pane.detached (LEFT ...) report membership changes; list them in --kinds next to the agent kinds. Other consumers receive them only when --kinds lists them, so older clients never see an unknown kind.", "PR watching: the daemon batches up to 25 direct GraphQL fingerprints per host every ~2 minutes. Full details are read on change or a 30-minute backstop. Existing Session branch discovery remains; standalone Panes register with pr watch --url <PR URL> [--head <full-sha>]. Immediate failures, required-check-aware success, head/review/comment/closed/merged events and GitHub outage/recovery events share durable baselines and the journal. A head pin prevents stale success, empty/partial checks never pass, and merge status BLOCKED/UNKNOWN conservatively withholds success. Rate limits honor server waits and reserve 10% for interactive use. Eight other errors or ten comment-only updates stop the watch with pr.stopped. See pr watch/unwatch/list.", "A daemon that predates --session returns no session field; runpane then fails with WATCH ERROR instead of watching every Pane.", "Replay: after a reset (RESET/_reset), the baseline restates current state. In JSON, those entries carry replay: true (and changedWhileAway: true after an epoch change). A replayed agent.ready is never READY: re-read runpane sessions overview instead of acting on it. Lines mode prints only CHANGED for them.", "agent.report (REPORT <pane-name> pane <pane-id> panel <panel-id> <state> [pr#<n>] [<head>][: <question>]) is a worker's `runpane report`. It is in the default kinds of --follow and --until-event, and arrives from any panel: a shell tab or a wrapper launch whose agent is not yet detected included. It bypasses --min-interval, and orchestrators treat it as the completion signal; a READY without a report means look, and maybe nudge.", "Never pipe --follow into grep -m1, head, or any other exit-on-match reader: it does not exit when its reader does until its next write. To wait for one event, use --until-event.", "Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "--follow has one default cadence: READY 3m, BLOCKED 30s, non-urgent batches 10m, IDLE after 10m with backoff, expiry 3h, heartbeats off. Individual duration flags override it. --present and --profile were removed; use --ready-settle, --blocked-settle, and --min-interval for timing overrides.", "--until-event delivers matching events immediately without follow settling or batching. A harness that consumes a named follow stream gets its cadence; a process-exit waiter keeps immediate single-event semantics. --follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since."];
+                readonly notes: readonly ["Every default is in the contract under defaults.watch: follow (what --follow does) and untilEvent (what --until-event waits for). An override flag replaces one value; nothing else needs remembering.", "Arming: wait for WATCH OK before relying on a --follow monitor. It prints once when the watch is armed. Run the monitor under your harness's background monitor (one line = one notification).", "Ending: WATCH EXPIRED (exit 0) means nothing happened for --expire-after: say so, and arm a new watch with the next dispatch. A non-zero exit or a WATCH ERROR line means it failed: tell the user and re-arm once; if it dies again, file runpane doctor --report. If the message says the cursor was superseded, keep the replacement monitor and leave the old one stopped. Judge a watch by these lines, never by silence.", "--until-event prints exactly one line: the event (exit 0), WATCH TIMEOUT (exit 124, only with --timeout-ms), or WATCH ERROR (exit 2).", "STUCK means real unsubmitted composer text. An agent prompt suggestion (for example a grey Try \"...\" hint) never counts.", "Cadence state is held per named consumer. Without numeric --since, follow uses an explicit --as or assigns a Session, panel, or follow-<pid> name. With numeric --since it has no name and bypasses cadence; --as cannot be combined with --since. Held lines survive a reconnect of the same consumer; a changed filter re-delivers them under the new filter.", "Journal loss is surfaced through reset and dropped metadata.", "The daemon treats omitted idleAfterMs as disabled so older clients never receive agent.idle unexpectedly.", "Control lines are not journal entries. Lines text and JSON kind: WATCH OK (_ok, once when armed), HEARTBEAT (_heartbeat, only with --heartbeat), WATCH RECONNECTED (_reconnected, after a retried daemon error), WATCH ERROR (_error; exit 2 unless --follow or --until-event retries it), RESET (_reset, the journal restarted or the cursor fell behind; a fresh baseline follows), DROPPED (_dropped, entries lost to journal truncation), WATCH TIMEOUT (_timeout, --until-event deadline; exit 124), and WATCH EXPIRED (_expired, --expire-after passed; exit 0). Under --until-event, only _timeout and _error print.", "Under --follow, JSON entries for panels holding unsubmitted composer text carry heldInputPresent: true, the JSON equivalent of the STUCK line. Only typed composer text counts, the same reading as panels screen composer.hasUndeliveredText; an agent's dim or grey prompt suggestion or placeholder does not. --no-held-input turns this off.", "--session <id|name> scopes the watch to a named Session. The daemon resolves the Session once per request and its associated Panes on every read, so sessions associate and sessions detach take effect without a re-arm; archived and detached Panes drop out, and the Session's own orchestrator panels are excluded. Cadence state is keyed by the Session, not its current Panes, so membership changes keep held lines. A detached Pane's held lines are dropped.", "Under --session, pane.associated (JOINED <pane-name> pane <pane-id> session <session-id>) and pane.detached (LEFT ...) report membership changes; list them in --kinds next to the agent kinds. Other consumers receive them only when --kinds lists them, so older clients never see an unknown kind.", "PR watching: the daemon batches up to 25 direct GraphQL fingerprints per host every ~2 minutes. Full details are read on change or a 30-minute backstop. Existing Session branch discovery remains; standalone Panes register with pr watch --url <PR URL> [--head <full-sha>]. Immediate failures, required-check-aware success, head/review/comment/closed/merged events and GitHub outage/recovery events share durable baselines and the journal. A head pin prevents stale success, empty/partial checks never pass, and merge status BLOCKED/UNKNOWN conservatively withholds success. Rate limits honor server waits and reserve 10% for interactive use. Eight other errors or ten comment-only updates stop the watch with pr.stopped. See pr watch/unwatch/list.", "A daemon that predates --session returns no session field; runpane then fails with WATCH ERROR instead of watching every Pane.", "Replay: after a reset (RESET/_reset), the baseline restates current state. In JSON, those entries carry replay: true (and changedWhileAway: true after an epoch change). A replayed agent.ready is never READY: re-read runpane sessions overview instead of acting on it. Lines mode prints only CHANGED for them.", "agent.report (REPORT <pane-name> pane <pane-id> panel <panel-id> <state> [pr#<n>] [<head>][: <question>]) is a worker's `runpane report`. It is in the default kinds of --follow and --until-event, and arrives from any panel: a shell tab or a wrapper launch whose agent is not yet detected included. It bypasses --min-interval, and orchestrators treat it as the completion signal; a READY without a report means look, and maybe nudge.", "Never pipe --follow into grep -m1, head, or any other exit-on-match reader: it does not exit when its reader does until its next write. To wait for one event, use --until-event.", "Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.base_changed,pr.base_deleted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "--follow has one default cadence: READY 3m, BLOCKED 30s, non-urgent batches 10m, IDLE after 10m with backoff, expiry 3h, heartbeats off. Individual duration flags override it. --present and --profile were removed; use --ready-settle, --blocked-settle, and --min-interval for timing overrides.", "--until-event delivers matching events immediately without follow settling or batching. A harness that consumes a named follow stream gets its cadence; a process-exit waiter keeps immediate single-event semantics. --follow --since <generation> has no consumer name and bypasses settling and batching. Cadence requires a named follow consumer; --as cannot be combined with numeric --since."];
             };
             readonly "panes git-status": {
                 readonly name: "panes git-status";
@@ -7671,7 +8123,7 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--as-file-pointer";
                     readonly required: false;
-                    readonly description: "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead.";
+                    readonly description: "Write the prompt or text to a private prompt file (in the Pane's worktree, hidden from git, when it has one) and send the one line `Read and follow <path>` instead.";
                 }, {
                     readonly name: "--yes";
                     readonly required: false;
@@ -7688,7 +8140,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane agents send --pane <pane-id> --text \"Also add a test\" --yes --json", "runpane agents send --pane <pane-id> --text \"$(cat review-notes.md)\" --as-file-pointer --yes --json"];
                 readonly jsonSchemas: readonly ["agentSendResult"];
-                readonly notes: readonly ["`delivered` is true when the agent took the message or queued it for after its current turn; `delivery` says which (`taken` or `queued`) and how Pane knows (`transcript` or `screen`). Never resend a delivered message.", "It types the text, then queues with Tab when Codex is working or submits with Enter when ready. It is for messages, not keys. To answer a menu, use `runpane panels input --panel <panel-id> --keys down,enter --yes`, then check the screen with `runpane agents status`.", "`--as-file-pointer` writes the text to `<pane-dir>/prompts/<pane-id>/<timestamp>.md` (readable only by you) and sends the one line `Read and follow <path>`; the result includes `promptFile`. Prefer it for long prompts."];
+                readonly notes: readonly ["`delivered` is true when the agent took the message or queued it for after its current turn; `delivery` says which (`taken` or `queued`) and how Pane knows (`transcript` or `screen`). Never resend a delivered message.", "It types the text, then queues with Tab when Codex is working or submits with Enter when ready. It is for messages, not keys. To answer a menu, use `runpane panels input --panel <panel-id> --keys down,enter --yes`, then check the screen with `runpane agents status`.", "`--as-file-pointer` writes the text to a prompt file readable only by you, inside the Pane's git worktree at `.pane/prompts/` (hidden by the repository's `.git/info/exclude`, never committed) when it has one, otherwise under `<pane-dir>/prompts/<pane-id>/`, so an agent limited to its working directories reads it without a permission prompt, and sends the one line `Read and follow <path>`, with the path relative to the worktree (where the agent starts) when the file is inside it; the result's `promptFile` is always absolute. Prefer it for long prompts."];
             };
             readonly report: {
                 readonly name: "report";
@@ -7876,7 +8328,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionOverviewResult"];
-                readonly notes: readonly ["The result includes `locks`: named locks scoped to the Session or held by its Panes (see `runpane lock`)."];
+                readonly notes: readonly ["The result includes `locks`: named locks scoped to the Session or held by its Panes (see `runpane lock`).", "Each `panes[].panels[]` entry has `report`, that panel's latest `runpane report` (state, `pr`, `head`, `question`, `summary`, `summaryTruncated`, `summaryPath`, `reportedAt`). When the summary is a complete JSON object, `report.data` holds it exactly as the worker gave it; Pane never reads or renames its fields. A plain-text, array or scalar summary, invalid JSON, JSON nested more than 64 levels deep, or a truncated summary (`summaryTruncated`) has no `data`. A panel that never reported has no `report` but keeps `state` and `lastActivityAt`. `panes[].report` is still the newest report among the Pane's panels, with its `panelId`; daemons that predate per-panel reports omit `panels[].report`."];
             };
             readonly "lock acquire": {
                 readonly name: "lock acquire";
@@ -8122,8 +8574,8 @@ export declare const RUNPANE_CONTRACT: {
             };
             readonly handoff: {
                 readonly name: "handoff";
-                readonly summary: "Hand your task to a fresh agent on this or another machine: check your handoff note, make the branch reachable, send the note, and start the agent on it. From a Session's terminal, create the Session on another machine instead.";
-                readonly details: "Two steps. The agent writes the note, because only it has the context: run `runpane handoff --template > ~/handoff.md` (outside the checkout) and fill in every section (goal, current state, done and verified, in progress, next steps, decisions and constraints, open questions, how to verify, git state), writing \"None\" where one does not apply. Then `runpane handoff \"<destination>\" --note-file ~/handoff.md` moves it: it rejects a note with a missing or empty section, refuses an unpushed branch unless --push, finds the destination's saved repository with the same remote, fetches the branch there, writes the note to `~/.pane/handoffs/` on that machine with its origin in the front matter and receiver instructions appended, and starts the agent in a new Pane branched from your branch. The receiver verifies the head commit, continues from Next steps, pushes to your branch, and reports back to your panel with `runpane workspace <your machine> panels submit`. Run from a Session's terminal (its folder is outside git), handoff moves the Session instead: it skips git, writes the note to the other machine the same way, and creates a Session there with the same name, goal and agent (numbered \"<name> 2\" if the name is taken), whose context and next action point at the note. The sender Session stays as it is; the new one waits for your first message. A Session cannot be handed off to the machine it is on.";
+                readonly summary: "Hand your task to another agent on this or another machine: check your handoff note, make the branch reachable, send the note, and start the agent on it. A same-agent handoff from a Pane tab carries and resumes your own session (a fork on this machine) and checks it continued; otherwise a fresh agent starts with the note. From a Session's terminal, create the Session on another machine instead.";
+                readonly details: "Two steps. The agent writes the note, because only it has the context: run `runpane handoff --template > ~/handoff.md` (outside the checkout) and fill in every section (goal, current state, done and verified, in progress, next steps, decisions and constraints, open questions, how to verify, git state), writing \"None\" where one does not apply. Then `runpane handoff \"<destination>\" --note-file ~/handoff.md` moves it: it rejects a note with a missing or empty section, refuses an unpushed branch unless --push, finds the destination's saved repository with the same remote, fetches the branch there, writes the note to `~/.pane/handoffs/` on that machine with its origin in the front matter and receiver instructions appended, and starts the agent in a new Pane branched from your branch. When you run in a Pane tab and the receiver is your own agent, it carries your session instead of starting fresh: another machine gets a copy of the session's files in its agent store and resumes the same id; this machine resumes a fork. The receiver starts with no prompt, and the CLI checks it resumed and shows the session's last message, then tells it where the session moved. The receiver verifies the head commit, continues from Next steps, pushes to your branch, and reports back to your panel with `runpane workspace <your machine> panels submit`. Run from a Session's terminal (its folder is outside git), handoff moves the Session instead: it skips git, writes the note to the other machine the same way, and creates a Session there with the same name, goal and agent (numbered \"<name> 2\" if the name is taken), whose context and next action point at the note; a same-agent Session also gets your conversation's files and resumes it when first opened. The sender Session stays as it is; the new one waits for your first message. A Session cannot be handed off to the machine it is on.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
                 readonly arguments: readonly [{
@@ -8168,6 +8620,10 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--push";
                     readonly required: false;
                     readonly description: "Commit uncommitted work (except the note) as WIP and push the branch before sending; never forces. Without it, an unpushed branch stops the handoff.";
+                }, {
+                    readonly name: "--note-only";
+                    readonly required: false;
+                    readonly description: "Start a fresh agent with the note instead of carrying your own session. Without it, a handoff to the same agent carries and resumes your session.";
                 }, {
                     readonly name: "--dry-run";
                     readonly required: false;
@@ -8178,7 +8634,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly description: "Print machine-readable output.";
                 }];
                 readonly examples: readonly ["runpane handoff --template > ~/handoff.md", "runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md --push", "runpane handoff \"codex gpt-5 high on parsa-devbox\" --note-file ~/handoff.md --dry-run --json", "runpane handoff --machine build-server --agent cursor --note-file ~/handoff.md"];
-                readonly notes: readonly ["Another machine is reached through runpane workspace (Tailscale); it needs Pane running there with workspaces enabled and the repository saved. Repository listing and Pane creation call the reached daemon directly; no global destination CLI installation is required.", "Destination preflight runs before sender commit/push. Inside WSL, an absent or refused local Linux daemon can fall back to its Windows host through reachable Windows Tailscale and enabled workspaces; explicit Pane directory selection keeps its instance. Select a native Windows saved repository; WSL saved repositories are rejected before sending.", "A successful handoff requires initialInput.verifiedSubmitted and delivery taken or queued without blocked/error evidence. Unverified delivery exits nonzero with the created Pane, panel and a panels screen inspection command; inspect before retrying.", "From a Session's terminal (PANE_ORCHESTRATION_SESSION_ID set, folder outside git) the receiver is a Session, not a Pane: it needs only runpane:sessions:create and runpane:machine:write on the destination, pushes nothing, and refuses this machine before sending. JSON output then has receiver.route \"session\", session {id, name, machine} and no git field; a dry run reports the name the Session would get.", "Write the note for a reader with no context: quote errors and commands exactly, and record approaches that failed so they are not retried. Leave the front matter to the CLI.", "Model and effort become agent flags: claude --model/--effort, codex -m and -c model_reasoning_effort, cursor-agent --model. Cursor effort is not supported and is rejected before side effects.", "Run it from the checkout being handed off. On another machine the receiver works in a new Pane; on this machine, from the Pane that owns this checkout, it works in a new tab of that Pane (the result's receiver.route and receiver.reason say which). Either way it pushes back to your branch, so stop changing that branch yourself."];
+                readonly notes: readonly ["Another machine is reached through runpane workspace (Tailscale); it needs Pane running there with workspaces enabled and the repository saved. Repository listing and Pane creation call the reached daemon directly; no global destination CLI installation is required.", "Destination preflight runs before sender commit/push. Inside WSL, an absent or refused local Linux daemon can fall back to its Windows host through reachable Windows Tailscale and enabled workspaces; explicit Pane directory selection keeps its instance. Select a native Windows saved repository; WSL saved repositories are rejected before sending.", "A successful handoff requires initialInput.verifiedSubmitted and delivery taken or queued without blocked/error evidence. Unverified delivery exits nonzero with the created Pane, panel and a panels screen inspection command; inspect before retrying.", "From a Session's terminal (PANE_ORCHESTRATION_SESSION_ID set, folder outside git) the receiver is a Session, not a Pane: it needs only runpane:sessions:create and runpane:machine:write on the destination, pushes nothing, and refuses this machine before sending. JSON output then has receiver.route \"session\", session {id, name, machine} and no git field; a dry run reports the name the Session would get.", "Write the note for a reader with no context: quote errors and commands exactly, and record approaches that failed so they are not retried. Leave the front matter to the CLI.", "Model and effort become agent flags: claude --model/--effort, codex -m and -c model_reasoning_effort, cursor-agent --model. Cursor effort is not supported and is rejected before side effects.", "Run it from the checkout being handed off. On another machine the receiver works in a new Pane; on this machine, from the Pane that owns this checkout, it works in a new tab of that Pane (the result's receiver.route and receiver.reason say which). Either way it pushes back to your branch, so stop changing that branch yourself.", "JSON continuity: { carried, result: continued | inconclusive | not-continued | fresh-agent, agent, sessionId, resumedId, fork, files, bytes, checks: { resumedById, restartResumes, historyLoaded, originalUntouched?, originalAppended? }, reason, next }; a dry run sets carried, sessionId, fork, files and bytes and no result. inconclusive exits 0 and next says to ask the receiver \"What were you last working on? Answer in one or two sentences.\"; not-continued exits 1, keeps the receiver and gives the --note-only command for the person to choose. After continued or inconclusive, the sender ends its turn and makes no more changes on the branch. From a Session the result is inconclusive until the new Session is opened. A Cursor session is carried only to another machine (best effort); on this machine the result is not-continued, since a copied Cursor chat still writes to the original. The destination's agent store is assumed at its default location (~/.claude, ~/.codex, ~/.cursor); a copy already there that holds history the sender's lacks, or that an agent there is running, is never overwritten (not-continued). checks.originalAppended is set when the running sender's own turn appended to its transcript during the fork; every byte it held before is unchanged. A destination Pane too old to resume a carried session is refused before anything is sent (ERR_HANDOFF_RESUME_UNSUPPORTED)."];
             };
             readonly "sessions unpin": {
                 readonly name: "sessions unpin";
@@ -8263,7 +8719,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane pr watch [--pane <id>] --url <PR URL> [--head <full-sha>] [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["prWatchResult"];
-                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
+                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.base_changed,pr.base_deleted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
             };
             readonly "pr unwatch": {
                 readonly name: "pr unwatch";
@@ -8293,7 +8749,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane pr unwatch [--pane <id>] --url <PR URL> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["prWatchResult"];
-                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
+                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.base_changed,pr.base_deleted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
             };
             readonly "pr list": {
                 readonly name: "pr list";
@@ -8318,7 +8774,65 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane pr list [--pane <id>] [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["prWatchResult"];
-                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
+                readonly notes: readonly ["Registration returns generation and epoch. Initially arm watch --until-event --since <generation> --epoch <epoch> --pane <id> --json --kinds pr.checks,pr.head,pr.comment,pr.review,pr.closed,pr.merged,pr.conflicted,pr.base_changed,pr.base_deleted,pr.stopped,github.unavailable,github.recovered. Process every NDJSON event, then persist its gen and epoch for the next --since/--epoch; --limit 1 delivers one event per run. Never mix --as with --since/--epoch. On _reset or _dropped, resynchronize GitHub state, then use the control record generation and epoch; replay/baseline records are not new events. No merge or GitHub write is performed.", "Watches stop on merge/close, 8 non-rate-limit errors, or 10 comment-only updates. Archived/deleted Panes are removed. Re-register after resolving the reason. Session member PR discovery remains automatic."];
+            };
+            readonly inbox: {
+                readonly name: "inbox";
+                readonly summary: "List the reports, missing reports, and on-screen questions a Session's orchestrator has not acknowledged.";
+                readonly details: "An orchestrator runs it when it starts or resumes, to catch reports, missing reports, and questions that arrived while it was down. Pane never adds the inbox to the orchestrator's turns.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: false;
+                readonly arguments: readonly [{
+                    readonly name: "--session";
+                    readonly value: "<id|name>";
+                    readonly required: false;
+                    readonly description: "Session; defaults to PANE_ORCHESTRATION_SESSION_ID.";
+                }, {
+                    readonly name: "--json";
+                    readonly required: false;
+                    readonly description: "Print machine-readable output.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
+                readonly examples: readonly ["runpane inbox --session \"$PANE_ORCHESTRATION_SESSION_ID\" --json"];
+                readonly jsonSchemas: readonly ["inboxListResult"];
+                readonly notes: readonly ["Items: report (agent.report), report.missing (agent.report.missing), and blocked (agent.blocked, with the prompt's screen lines). Reports coalesce per panel, blockers clear when the panel moves on, and each Session keeps at most 200 items until acknowledged or superseded. A journal replay watermark recovers committed outcomes after restart within journal retention.", "A newer report replaces the panel's older report or missing report."];
+            };
+            readonly "inbox ack": {
+                readonly name: "inbox ack";
+                readonly summary: "Clear Session inbox items once they are handled.";
+                readonly details: "Acknowledge each item once you have acted on it, so the hook stops repeating it.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [{
+                    readonly name: "<item-id>...";
+                    readonly required: false;
+                    readonly description: "Item ids from `runpane inbox`.";
+                }, {
+                    readonly name: "--session";
+                    readonly value: "<id|name>";
+                    readonly required: false;
+                    readonly description: "Only clear items of this Session; required with --all.";
+                }, {
+                    readonly name: "--all";
+                    readonly required: false;
+                    readonly description: "Clear every item of the Session.";
+                }, {
+                    readonly name: "--json";
+                    readonly required: false;
+                    readonly description: "Print machine-readable output.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
+                readonly examples: readonly ["runpane inbox ack in-1a2b3c4d --json"];
+                readonly jsonSchemas: readonly ["inboxAckResult"];
+                readonly notes: readonly ["Unknown ids are reported under `unknown`; acknowledging twice is harmless."];
             };
         };
         readonly managedBlock: readonly ["## Pane", "", "This repository is used with [Pane](https://runpane.com). Drive it with the CLI or the `pane` MCP server.", "", "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Open later agents with `runpane panels create --pane <id>` (MCP: `panels_create` or `agents_start` with `pane`), not a new Pane.", "", "CLI: `npm i -g runpane` (or `npx --yes runpane@latest`), then `runpane doctor --json`. Full command reference: `runpane agent-context --json`.", "", "MCP: packaged Pane registers a stdio server named `pane` with Claude Code, Codex, and Cursor. Check the connection with `claude mcp list`, `codex mcp list`, or `agent mcp list`. Cursor may ask you to enable `pane` with `agent mcp enable pane`. If tools are missing, add it in the agent's MCP settings: Claude Code `claude mcp add --scope user pane -- npx --yes runpane@latest mcp`; Codex (`~/.codex/config.toml`) table `[mcp_servers.pane]` with `command = \"npx\"` and `args = [\"--yes\", \"runpane@latest\", \"mcp\"]`; Cursor (`~/.cursor/mcp.json`) uses `mcpServers.pane` with the same `npx` command and args; any other stdio client uses them too."];