runpane 2.4.136 → 2.4.137

package/dist/generated/contract.d.ts

@@ -94,7 +94,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "version";
         readonly summary: "Print the runpane wrapper version without contacting, launching, or focusing Pane.";
-        readonly usage: readonly ["runpane version", "runpane --version"];
+        readonly usage: readonly ["runpane version [--pane-dir <path>]", "runpane --version"];
     }, {
         readonly name: "doctor";
         readonly summary: "Run platform, release, installed Pane, daemon reachability, and remote setup diagnostics.";
@@ -112,7 +112,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "agents doctor";
         readonly summary: "Diagnose whether a built-in agent command is available in a Pane repository environment.";
-        readonly usage: readonly ["runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json]"];
+        readonly usage: readonly ["runpane agents doctor --agent <codex|claude|cursor> [--repo <selector>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["admin"];
         readonly jsonSchemas: readonly ["agentDoctorResult"];
     }, {
@@ -135,7 +135,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "repos add";
         readonly summary: "Register an existing git repository with the running Pane app.";
-        readonly usage: readonly ["runpane repos add --path <path> [--name <name>] [--json] [--yes]"];
+        readonly usage: readonly ["runpane repos add --path <path> [--name <name>] [--json] [--yes] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly additive: true;
         readonly idempotent: true;
@@ -144,31 +144,31 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes list";
         readonly summary: "List Pane sessions in a saved repository.";
-        readonly usage: readonly ["runpane panes list [--repo <selector>] [--json]"];
+        readonly usage: readonly ["runpane panes list [--repo <selector>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["core", "panes"];
         readonly jsonSchemas: readonly ["paneListResult"];
     }, {
         readonly name: "panes cost";
         readonly summary: "Report estimated token cost per Pane, with per-model breakdown and cache efficiency.";
-        readonly usage: readonly ["runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]"];
+        readonly usage: readonly ["runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["panes"];
         readonly jsonSchemas: readonly ["paneCostRequest", "paneCostResult"];
     }, {
         readonly name: "workspace state";
         readonly summary: "Read one workspace snapshot of every Pane and CLI panel.";
-        readonly usage: readonly ["runpane workspace state [--repo <selector>] [--json]"];
+        readonly usage: readonly ["runpane workspace state [--repo <selector>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["core", "agents"];
         readonly jsonSchemas: readonly ["workspaceStateResult"];
     }, {
         readonly name: "watch";
         readonly summary: "Wait for workspace agent and Pane transitions using a daemon-held cursor.";
-        readonly usage: readonly ["runpane watch [--as <name>|--since <generation>] [--follow] [--format <lines|json>] [--heartbeat <seconds>] [--idle-after <ms>] [--settle <ms>] [--blocked-settle <ms>] [--min-interval <ms>] [--idle-backoff] [--all-managed|--pane <id>] [--include-shells] [--self-test] [--kinds <kind,...>] [--repo <selector>] [--name-contains <text>] [--timeout-ms <ms>] [--from <now|earliest>] [--json]"];
+        readonly usage: readonly ["runpane watch [--as <name>|--since <generation>] [--follow] [--format <lines|json>] [--heartbeat <seconds>] [--idle-after <ms>] [--settle <ms>] [--blocked-settle <ms>] [--min-interval <ms>] [--idle-backoff] [--all-managed|--pane <id>|--session <id|name>] [--include-shells] [--self-test] [--quiet] [--kinds <kind,...>] [--repo <selector>] [--name-contains <text>] [--timeout-ms <ms>] [--from <now|earliest>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["agents"];
         readonly jsonSchemas: readonly ["workspaceWaitRequest", "workspaceWaitResult"];
     }, {
         readonly name: "panes create";
         readonly summary: "Create user-visible Panes (Pane sessions) backed by Pane-managed worktrees for feature/PR work and open terminal-backed tool tabs.";
-        readonly usage: readonly ["runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [options]", "runpane panes create --from-json <path|-> [--yes] [--json]"];
+        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 mutates: true;
         readonly additive: true;
         readonly toolsets: readonly ["panes"];
@@ -176,22 +176,22 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes adopt";
         readonly summary: "Adopt an existing externally managed git worktree as a Pane without changing the worktree.";
-        readonly usage: readonly ["runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [--resume <id>] [--folder <name>] [--launch] [--no-pinned] [--no-associate] [--dry-run] [--yes] [--json]"];
+        readonly usage: readonly ["runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [--resume <id>] [--folder <name>] [--launch [--prompt <text>|--prompt-file <path|->] [--wait-ready] [--ready-timeout-ms <ms>]] [--no-pinned] [--no-associate] [--dry-run] [--yes] [--json] [--pane-dir <path>]", "runpane panes adopt --repo <selector> --path <dir> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--folder <name>] [--launch [--prompt <text>|--prompt-file <path|->] [--wait-ready] [--ready-timeout-ms <ms>]] [--no-pinned] [--no-associate] [--dry-run] [--yes] [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly additive: true;
         readonly toolsets: readonly ["panes"];
         readonly jsonSchemas: readonly ["paneCreateResult"];
     }, {
         readonly name: "panes archive";
-        readonly summary: "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.";
-        readonly usage: readonly ["runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--dry-run] --yes [--json]"];
+        readonly summary: "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree, or archive every merged Pane in a Session.";
+        readonly usage: readonly ["runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--remove-worktree] [--dry-run] --yes [--json] [--pane-dir <path>]", "runpane panes archive --session <id|name> --merged [--remove-worktree] [--source user|agent] [--dry-run] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly toolsets: readonly ["core", "panes"];
-        readonly jsonSchemas: readonly ["paneArchiveRequest", "paneArchiveResult"];
+        readonly jsonSchemas: readonly ["paneArchiveRequest", "paneArchiveBulkRequest", "paneArchiveResult", "paneArchiveBulkResult"];
     }, {
         readonly name: "panes pin";
         readonly summary: "Declaratively pin a Pane; pinned is the Pane UI's favorite/pin star and repeated requests are idempotent.";
-        readonly usage: readonly ["runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]"];
+        readonly usage: readonly ["runpane panes pin --pane <pane-id> --yes [--dry-run] [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly idempotent: true;
         readonly toolsets: readonly ["panes"];
@@ -199,7 +199,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes unpin";
         readonly summary: "Declaratively unpin a Pane; pinned is the Pane UI's favorite/pin star and repeated requests are idempotent.";
-        readonly usage: readonly ["runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]"];
+        readonly usage: readonly ["runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly idempotent: true;
         readonly toolsets: readonly ["panes"];
@@ -207,7 +207,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes rename";
         readonly summary: "Rename a Pane without changing its worktree, branch, panels, or focus.";
-        readonly usage: readonly ["runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]"];
+        readonly usage: readonly ["runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly idempotent: true;
         readonly toolsets: readonly ["panes"];
@@ -215,7 +215,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panes focus";
         readonly summary: "Raise the Pane window and select a Pane (and optionally one of its panels) on explicit user request.";
-        readonly usage: readonly ["runpane panes focus --pane <pane-id> [--panel <panel-id>] --source user|agent --yes [--json]"];
+        readonly usage: readonly ["runpane panes focus --pane <pane-id> [--panel <panel-id>] --source user|agent --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly additive: true;
         readonly idempotent: true;
@@ -224,7 +224,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panels create";
         readonly summary: "Create a terminal-backed tool panel inside an existing Pane session.";
-        readonly usage: readonly ["runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready] --yes [--json]", "runpane panels create --pane <pane-id> --tool-command <command> [--title <title>] [--focus|--no-focus] --yes [--json]"];
+        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 mutates: true;
         readonly additive: true;
         readonly toolsets: readonly ["panels"];
@@ -232,48 +232,54 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "panels list";
         readonly summary: "List tool panels inside a Pane session.";
-        readonly usage: readonly ["runpane panels list --pane <pane-id> [--json]"];
+        readonly usage: readonly ["runpane panels list --pane <pane-id> [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelListResult"];
     }, {
         readonly name: "panels output";
         readonly summary: "Read recent terminal output from a panel.";
-        readonly usage: readonly ["runpane panels output --panel <panel-id> [--limit <count>] [--json]"];
+        readonly usage: readonly ["runpane panels output --panel <panel-id> [--limit <count>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelOutputResult"];
     }, {
         readonly name: "panels screen";
         readonly summary: "Read a compact current-screen view from a terminal panel.";
-        readonly usage: readonly ["runpane panels screen --panel <panel-id> [--limit <count>] [--json]"];
+        readonly usage: readonly ["runpane panels screen --panel <panel-id> [--limit <count>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelScreenResult"];
     }, {
         readonly name: "panels input";
         readonly summary: "Send input bytes to a terminal panel.";
-        readonly usage: readonly ["runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]"];
+        readonly usage: readonly ["runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly toolsets: readonly ["core", "panels"];
         readonly jsonSchemas: readonly ["panelInputRequest", "panelInputResult"];
     }, {
         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|->) --yes [--json]"];
+        readonly usage: readonly ["runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelSubmitRequest", "panelSubmitResult"];
     }, {
         readonly name: "panels submit-composer";
         readonly summary: "Submit an agent composer using the panel-appropriate key sequence.";
-        readonly usage: readonly ["runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json]"];
+        readonly usage: readonly ["runpane panels submit-composer --panel <panel-id> [--strategy auto|codex-ctrl-enter|enter|tab] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelSubmitComposerRequest", "panelSubmitComposerResult"];
     }, {
         readonly name: "panels wait";
         readonly summary: "Wait for a terminal panel to initialize, become ready/idle, or contain text.";
-        readonly usage: readonly ["runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--contains <text>] [--timeout-ms <ms>] [--interval-ms <ms>] [--json]"];
+        readonly usage: readonly ["runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--contains <text>] [--timeout-ms <ms>] [--interval-ms <ms>] [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["panels"];
         readonly jsonSchemas: readonly ["panelWaitResult"];
+    }, {
+        readonly name: "panels last-message";
+        readonly summary: "Read an agent's last reply from its transcript, without scraping the screen.";
+        readonly usage: readonly ["runpane panels last-message --panel <panel-id> [--limit <count>] [--json] [--pane-dir <path>]"];
+        readonly toolsets: readonly ["panels", "agents"];
+        readonly jsonSchemas: readonly ["panelLastMessageResult"];
     }, {
         readonly name: "panes git-status";
         readonly summary: "Read the git status of a Pane worktree: uncommitted, unpushed, and behind-main counts.";
@@ -514,11 +520,20 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         readonly name: "agents send";
         readonly summary: "Send a follow-up message to an agent and confirm it was submitted.";
-        readonly usage: readonly ["runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]"];
+        readonly usage: readonly ["runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> [--as-file-pointer] --yes [--json] [--pane-dir <path>]"];
         readonly mutates: true;
         readonly wrappers: readonly ["npm"];
         readonly toolsets: readonly ["core", "agents"];
         readonly jsonSchemas: readonly ["agentSendResult"];
+    }, {
+        readonly name: "report";
+        readonly summary: "Hand back a worker's structured report: state, PR, head commit, summary, and the question when blocked.";
+        readonly usage: readonly ["runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary <text>|--summary-file <path|->] [--question <text>] [--pane <pane-id> --panel <panel-id>] [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly additive: true;
+        readonly idempotent: true;
+        readonly toolsets: readonly ["agents"];
+        readonly jsonSchemas: readonly ["reportResult"];
     }, {
         readonly name: "sessions list";
         readonly summary: "List durable named orchestration Sessions.";
@@ -578,6 +593,29 @@ export declare const RUNPANE_CONTRACT: {
         readonly usage: readonly ["runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]"];
         readonly toolsets: readonly ["sessions"];
         readonly jsonSchemas: readonly ["sessionOverviewResult"];
+    }, {
+        readonly name: "lock acquire";
+        readonly summary: "Acquire a named lock on a resource shared between agents, such as one test account, optionally waiting for it.";
+        readonly usage: readonly ["runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly additive: true;
+        readonly idempotent: true;
+        readonly toolsets: readonly ["sessions"];
+        readonly jsonSchemas: readonly ["lockAcquireRequest", "lockAcquireResult"];
+    }, {
+        readonly name: "lock release";
+        readonly summary: "Release a named lock you hold, or force-release another owner's lock.";
+        readonly usage: readonly ["runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly idempotent: true;
+        readonly toolsets: readonly ["sessions"];
+        readonly jsonSchemas: readonly ["lockReleaseResult"];
+    }, {
+        readonly name: "lock list";
+        readonly summary: "List held named locks, optionally only one Session's.";
+        readonly usage: readonly ["runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]"];
+        readonly toolsets: readonly ["sessions"];
+        readonly jsonSchemas: readonly ["lockListResult"];
     }];
     readonly flags: {
         readonly wrapper: readonly [{
@@ -666,15 +704,20 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--name";
             readonly value: "<name>";
-            readonly description: "Name for the registered repository or created/renamed pane session.";
+            readonly description: "Name for the registered repository, created/renamed pane session, or named lock.";
         }, {
             readonly name: "--worktree-name";
             readonly value: "<name>";
             readonly description: "Worktree name to request. Defaults to --name.";
+        }, {
+            readonly name: "--branch";
+            readonly value: "<name>";
+            readonly description: "Exact new branch name for the created worktree, slashes included. Must not exist yet; defaults to the worktree name.";
         }, {
             readonly name: "--base-branch";
-            readonly value: "<branch>";
-            readonly description: "Base branch for the created worktree.";
+            readonly value: "<ref>";
+            readonly aliases: readonly ["--base"];
+            readonly description: "Ref the created worktree branches from. --base is an alias.";
         }, {
             readonly name: "--folder";
             readonly value: "<name>";
@@ -686,7 +729,7 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--agent";
             readonly value: "<codex|claude|cursor>";
-            readonly description: "Built-in agent terminal template to open.";
+            readonly description: "Built-in agent terminal template to open. With --tool-command, the agent that command runs.";
         }, {
             readonly name: "--tool-command";
             readonly value: "<command>";
@@ -703,7 +746,8 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--initial-input-file";
             readonly value: "<path|->";
-            readonly description: "Read initial input from a file or stdin.";
+            readonly aliases: readonly ["--prompt-file"];
+            readonly description: "Read initial input from a file or stdin. --prompt-file is an alias.";
         }, {
             readonly name: "--from-json";
             readonly value: "<path|->";
@@ -715,7 +759,7 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--ready-timeout-ms";
             readonly value: "<milliseconds>";
-            readonly description: "Readiness wait timeout for panes create --wait-ready.";
+            readonly description: "Readiness wait timeout for panes create/adopt --wait-ready.";
         }, {
             readonly name: "--concurrency";
             readonly value: "<count>";
@@ -799,7 +843,7 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--min-interval";
             readonly value: "<milliseconds>";
-            readonly description: "Follow-only opt-in: hold non-urgent lines and flush them together at most once per interval; BLOCKED bypasses it.";
+            readonly description: "Follow-only opt-in: hold non-urgent lines and flush them together at most once per interval; BLOCKED, REPORT, PR CONFLICTED, and PR CHECKS FAILED bypass it.";
         }, {
             readonly name: "--body-file";
             readonly value: "<path|->";
@@ -808,6 +852,18 @@ export declare const RUNPANE_CONTRACT: {
             readonly name: "--session";
             readonly value: "<id|name>";
             readonly description: "Named orchestration Session id or exact name.";
+        }, {
+            readonly name: "--ttl";
+            readonly value: "<duration>";
+            readonly description: "How long a named lock is held before it expires: a number with ms, s, m, or h (such as 30m); a bare number is milliseconds. At least 1s, at most 24h.";
+        }, {
+            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 name: "--note";
+            readonly value: "<text>";
+            readonly description: "What a named lock is for. Outside a Pane terminal it also names the owner, so pass the same note to release it.";
         }, {
             readonly name: "--message";
             readonly value: "<message>";
@@ -832,6 +888,30 @@ export declare const RUNPANE_CONTRACT: {
             readonly name: "--keys";
             readonly value: "<name,...>";
             readonly description: "Named keys for panels input, such as down,enter.";
+        }, {
+            readonly name: "--state";
+            readonly value: "<ready|blocked|failed|done>";
+            readonly description: "Report state for runpane report.";
+        }, {
+            readonly name: "--pr";
+            readonly value: "<number>";
+            readonly description: "Pull request number for runpane report.";
+        }, {
+            readonly name: "--head";
+            readonly value: "<sha>";
+            readonly description: "Head commit (7-40 hex characters) for runpane report.";
+        }, {
+            readonly name: "--summary";
+            readonly value: "<text>";
+            readonly description: "Report summary text; up to 16,000 characters are kept.";
+        }, {
+            readonly name: "--summary-file";
+            readonly value: "<path|->";
+            readonly description: "Read the report summary from a file or stdin.";
+        }, {
+            readonly name: "--question";
+            readonly value: "<text>";
+            readonly description: "What a blocked worker needs answered; required with --state blocked.";
         }];
         readonly localBoolean: readonly [{
             readonly name: "--json";
@@ -856,10 +936,19 @@ export declare const RUNPANE_CONTRACT: {
             readonly description: "Inside a Session orchestrator, do not associate the created pane with that Session.";
         }, {
             readonly name: "--force";
-            readonly description: "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes.";
+            readonly description: "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes; for lock release, release another owner's lock.";
+        }, {
+            readonly name: "--remove-worktree";
+            readonly description: "Also check and remove an adopted Pane's worktree when archiving it. The local branch is kept.";
+        }, {
+            readonly name: "--merged";
+            readonly description: "With panes archive --session, archive only Panes that are clean and pushed, or merged via a pull request.";
         }, {
             readonly name: "--launch";
             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 name: "--follow";
             readonly description: "Continue waiting for workspace events until interrupted.";
@@ -874,16 +963,20 @@ export declare const RUNPANE_CONTRACT: {
             readonly description: "Limit workspace events to CLI agent panels.";
         }, {
             readonly name: "--all-managed";
-            readonly description: "Watch all non-archived, non-hidden managed panes.";
+            readonly description: "Watch every non-archived, non-hidden managed pane. This is the default scope; the flag states it explicitly and cannot be combined with --pane.";
         }, {
             readonly name: "--include-shells";
             readonly description: "Include ordinary shell panels in follow mode.";
         }, {
             readonly name: "--no-held-input";
-            readonly description: "Disable redacted STUCK detection in lines follow mode.";
+            readonly description: "Disable redacted held-input detection under --follow (STUCK lines, and heldInputPresent in JSON).";
         }, {
             readonly name: "--self-test";
             readonly description: "Probe the current daemon watch path without advancing a named cursor.";
+        }, {
+            readonly name: "--quiet";
+            readonly aliases: readonly ["--no-control-lines"];
+            readonly description: "Watch only: drop the WATCH OK, HEARTBEAT, and WATCH RECONNECTED control lines (_ok, _heartbeat, _reconnected in JSON). Errors, resets, and dropped counts always print.";
         }, {
             readonly name: "--idle-backoff";
             readonly description: "Follow-only opt-in: IDLE fires at --idle-after, then 30m, 1h, 3h, then daily per panel; any activity resets it.";
@@ -897,40 +990,40 @@ export declare const RUNPANE_CONTRACT: {
     };
     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 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 panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--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 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 --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --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 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 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 watch --follow", "  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 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 --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --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 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 [options]", "", "Updates Pane using the same artifact selection as \"runpane install client\".", "", "Options:", "  --version <latest|vX.Y.Z>", "  --format <auto|appimage|deb|dmg|zip|exe>", "  --download-dir <path>", "  --pane-path <path>", "  --dry-run", "  --yes", "  --verbose"];
-            readonly version: readonly ["Usage:", "  runpane version", "  runpane --version"];
+            readonly version: readonly ["Usage:", "  runpane version [--pane-dir <path>]", "  runpane --version"];
             readonly doctor: readonly ["Usage:", "  runpane doctor [--json] [--pane-dir <path>] [--pane-path <path>] [--format <format>] [--verbose]", "  runpane doctor --report [--title <text>] --body-file <path|-> [--yes] [--json]", "", "Checks wrapper/runtime details, release metadata, installed Pane detection, and Pane daemon reachability.", "", "Options:", "  --json                         Print a machine-readable environment report", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --pane-path <path>             Inspect a specific Pane executable", "  --format <format>              Release artifact format to inspect", "  --verbose                      Print extra diagnostics", "  --report                       Prepare a redacted, inspectable report", "  --body-file <path|->           Read report evidence from a file or stdin", "  --title <text>                 Report title", "  --yes                          Confirm creating one greenfield-inc/Pane issue", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json"];
             readonly "daemon repair": readonly ["Usage:", "  runpane daemon repair [--pane-dir <path>] [--pane-path <path>] [--yes] [--json]", "", "Repairs and restarts only the managed remote-daemon launcher and service definition.", "", "Options:", "  --pane-dir <path>              Remote daemon data directory (default: ~/.pane_remote)", "  --pane-path <path>             Existing Pane executable used to perform repair", "  --yes                         Skip the restart confirmation", "  --json                        Print one machine-readable repair result"];
             readonly "repos list": readonly ["Usage:", "  runpane repos list [--json] [--pane-dir <path>]", "", "Lists repositories saved in the running Pane app.", "", "Options:", "  --json                         Print machine-readable output", "  --pane-dir <path>              Connect to a specific Pane data directory"];
             readonly "repos add": readonly ["Usage:", "  runpane repos add --path <path> [--name <name>] [--json] [--yes]", "", "Registers an existing git repository with the running Pane app.", "", "Options:", "  --path <path>                  Existing git repository path", "  --name <name>                  Saved repository name; defaults to the directory name", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without adding the repo", "  --yes                          Skip confirmation for mutating commands"];
-            readonly panes: readonly ["Pane session commands.", "", "Usage:", "  runpane panes <command> [options]", "", "Commands:", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes archive --pane <pane-id> [--force] [--source user|agent] [--dry-run] --yes [--json]", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Run \"runpane help panes <command>\" for command-specific options."];
-            readonly "panes list": readonly ["Usage:", "  runpane panes list [--repo <selector>] [--json]", "", "Lists Pane sessions. Pass --repo to limit results to one saved repository.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
+            readonly panes: readonly ["Pane session commands.", "", "Usage:", "  runpane panes <command> [options]", "", "Commands:", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes archive --pane <pane-id> [--force] [--remove-worktree] [--source user|agent] [--dry-run] --yes [--json]", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes [--json]", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Run \"runpane help panes <command>\" for command-specific options."];
+            readonly "panes list": readonly ["Usage:", "  runpane panes list [--repo <selector>] [--json]", "", "Lists Pane sessions. Pass --repo to limit results to one saved repository.", "", "status is running while any terminal panel is live. agentState is the most urgent state of the live agent panels: blocked, working, ready, or none.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             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 observation commands.", "", "Usage:", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow"];
             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 [--as <name>|--since <generation>] [--follow] [options]", "", "Waits for agent state, Pane lifecycle, and panel exit transitions without polling.", "", "Options:", "  --as <name>                    Use a persisted daemon-held cursor", "  --since <generation>           Use an explicit cursor instead", "  --from <now|earliest>          Starting point for a new named cursor", "  --follow                       Continue waiting until interrupted", "  --format <lines|json>          Output format; lines is the follow default", "  --heartbeat <seconds>          Healthy-silence bound; defaults to 60 under --follow", "  --idle-after <ms>              Re-firing READY idle interval; defaults to 600000 under --follow", "  --settle <ms>                  Opt-in: emit READY only after this quiet window (--follow only)", "  --blocked-settle <ms>          Opt-in: emit BLOCKED only after this window (--follow only)", "  --min-interval <ms>            Opt-in: batch non-urgent lines per interval; BLOCKED bypasses (--follow only)", "  --idle-backoff                 Opt-in: IDLE at --idle-after, 30m, 1h, 3h, then daily (--follow only)", "  --all-managed                  Explicitly watch all managed panes", "  --include-shells               Include ordinary shell panels", "  --agents-only                  Limit to CLI agent panels", "  --exclude-pane <id>            Exclude a Pane; repeatable", "  --self-test                    Anonymous, read-only daemon path probe", "  --kinds <kind,...>             Limit event kinds", "  --pane <id>                    Limit to a Pane; repeatable", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --timeout-ms <ms>              Wait timeout; 0 polls once", "  --limit <count>                Maximum entries per response", "  --ack-now                      Use at-most-once named-cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Disable redacted STUCK detection", "  --json                         Alias for --format json", "", "Defaults are responsive: no settle, no batching, all kinds, IDLE every --idle-after. BUSY carries no action; drop it with --kinds.", "Expensive consumers opt in: --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "Pane Chat arms those flags itself through its skill; pass them only for your own scripts.", "STUCK means real unsubmitted composer text; an agent prompt suggestion never counts.", "Dead watch: HEARTBEAT is proof of life only. Judge death by a non-zero exit or a WATCH ERROR line, not by silence."];
-            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree name; defaults to --name", "  --base-branch <branch>         Base branch for the worktree", "  --agent <codex|claude|cursor>         Built-in terminal template", "  --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", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for terminal readiness before returning", "  --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                       Accepted for compatibility; creation already pins by default", "  --no-pinned                    Create unpinned instead of the default pinned (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"];
-            readonly "panes adopt": readonly ["Usage:", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [options]", "", "Adopts an existing externally managed git worktree without creating, syncing, or deleting it.", "", "Options: --resume <id> stages the agent resume command; --launch runs it immediately; --folder <name> groups the pane; --no-pinned opts out of pinning; --no-associate skips automatic Session association; --dry-run previews."];
-            readonly "panes archive": readonly ["Usage:", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--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. Refuses unsafe archives unless --force is passed. 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", "  --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 watch: readonly ["Usage:", "  runpane watch [--as <name>|--since <generation>] [--follow] [options]", "", "Waits for agent state, Pane lifecycle, and panel exit transitions without polling.", "", "Options:", "  --as <name>                    Use a persisted daemon-held cursor", "  --since <generation>           Use an explicit cursor instead", "  --from <now|earliest>          Starting point for a new named cursor", "  --follow                       Continue waiting until interrupted", "  --format <lines|json>          Output format; lines is the follow default", "  --heartbeat <seconds>          Healthy-silence bound; defaults to 60 under --follow", "  --idle-after <ms>              Re-firing READY idle interval; defaults to 600000 under --follow", "  --settle <ms>                  Opt-in: emit READY only after this quiet window (--follow only)", "  --blocked-settle <ms>          Opt-in: emit BLOCKED only after this window (--follow only)", "  --min-interval <ms>            Opt-in: batch non-urgent lines per interval; BLOCKED, REPORT, and PR failures bypass (--follow only)", "  --idle-backoff                 Opt-in: IDLE at --idle-after, 30m, 1h, 3h, then daily (--follow only)", "  --all-managed                  Explicitly watch all managed panes", "  --include-shells               Include ordinary shell panels", "  --agents-only                  Limit to CLI agent panels", "  --exclude-pane <id>            Exclude a Pane; repeatable", "  --self-test                    Anonymous, read-only daemon path probe", "  --quiet                        Drop WATCH OK, HEARTBEAT, and WATCH RECONNECTED lines", "  --no-control-lines             Alias for --quiet", "  --kinds <kind,...>             Limit event kinds", "  --pane <id>                    Limit to a Pane; repeatable", "  --session <id|name>            Follow every Pane in a named Session; associate/detach apply live", "  --repo <selector>              Limit to a saved repository", "  --name-contains <text>         Limit by Pane name substring", "  --timeout-ms <ms>              Wait timeout; 0 polls once", "  --limit <count>                Maximum entries per response", "  --ack-now                      Use at-most-once named-cursor delivery", "  --include-held-input           Include unsubmitted composer text in JSON", "  --no-held-input                Disable redacted STUCK detection", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Alias for --format json", "", "Defaults are responsive: no settle, no batching, all kinds, IDLE every --idle-after. BUSY carries no action; drop it with --kinds.", "agent.report (a worker ran `runpane report`) is opt-in: list it in --kinds. REPORT lines skip the --min-interval batch.", "Unattended (Pane Chat default): --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "User present: the same kinds with --settle 60000 --blocked-settle 15000 --min-interval 120000 and no --idle-backoff", "Session orchestrator: runpane watch --session <id|name> --follow --quiet --json --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "Pane Chat arms those flags itself through its skill; pass them only for your own scripts.", "STUCK means real unsubmitted composer text; an agent prompt suggestion never counts.", "Dead watch: HEARTBEAT is proof of life only (--quiet drops it). Judge death by a non-zero exit or a WATCH ERROR line, not by silence."];
+            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 user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.", "", "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 terminal readiness before returning", "  --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                       Accepted for compatibility; creation already pins by default", "  --no-pinned                    Create unpinned instead of the default pinned (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"];
+            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."];
+            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"];
             readonly "panes unpin": readonly ["Usage:", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "", "Declaratively unpins 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 unpin", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without unpinning the pane", "  --yes                          Skip confirmation for mutating commands"];
             readonly "panes rename": readonly ["Usage:", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Renames a Pane without changing its worktree, branch, panels, or focus. The name is trimmed like the Pane UI. Use --dry-run to validate and preview the updated pane without mutating.", "", "Options:", "  --pane <pane-id>               Pane/session id to rename", "  --name <new-name>              New non-empty Pane/session name", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --dry-run                      Validate and preview without renaming the pane", "  --yes                          Skip confirmation for mutating commands"];
             readonly "panes focus": readonly ["Usage:", "  runpane panes focus --pane <pane-id> [--panel <panel-id>] --source user|agent --yes [--json]", "", "Raises the Pane window and selects a Pane (and optionally one of its panels) exactly like clicking it in the UI. Steals window focus, so run it only on an explicit user request to open, focus, or show a Pane, never proactively.", "", "Options:", "  --pane <pane-id>               Pane/session id to focus", "  --panel <panel-id>             Optional panel/tab id inside the Pane to select", "  --source <user|agent>          Mutation source; does not change focus behavior", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for mutating commands"];
-            readonly panels: readonly ["Terminal-backed panel commands.", "", "Usage:", "  runpane panels <command> [options]", "", "Commands:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [options]", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--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]", "", "Run \"runpane help panels create\" or another command-specific topic for options."];
-            readonly "panels list": readonly ["Usage:", "  runpane panels list --pane <pane-id> [--json]", "", "Lists tool panels in a Pane session.", "", "Options:", "  --pane <pane-id>               Pane/session id", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
+            readonly panels: readonly ["Terminal-backed panel commands.", "", "Usage:", "  runpane panels <command> [options]", "", "Commands:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [options]", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--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 last-message --panel <panel-id> [--limit <count>] [--json]", "", "Run \"runpane help panels create\" or another command-specific topic for options."];
+            readonly "panels list": readonly ["Usage:", "  runpane panels list --pane <pane-id> [--json]", "", "Lists tool panels in a Pane session.", "", "agentDetection says how Pane knows agentType: declared, command, process, or screen. launchCommand is the command the panel was launched with.", "", "Options:", "  --pane <pane-id>               Pane/session id", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly "panels output": readonly ["Usage:", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "", "Reads bounded recent terminal output from a panel.", "", "Options:", "  --panel <panel-id>             Tool panel id", "  --limit <count>                Maximum recent output lines or records to read", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly "panels input": readonly ["Usage:", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "", "Sends exact input bytes to a terminal panel. Include a newline in the input when you mean Enter.", "", "Options:", "  --panel <panel-id>             Terminal panel id", "  --text <text>                  Text bytes to send", "  --keys <name,...>              Keys to press: enter, escape, tab, up, down, ctrl-c, ...", "  --input-file <path|->          Read input from a file or stdin", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for mutating commands"];
-            readonly "agent-context": readonly ["Usage:", "  runpane agent-context [--json]", "  runpane agent-context --command <command> [--json]", "", "Prints Pane command context for coding agents without requiring a running Pane app.", "", "Options:", "  --command <command>            Print the full definition for one runpane command", "  --json                         Print machine-readable output", "", "Examples:", "  runpane agent-context", "  runpane agent-context --json", "  runpane agent-context --command \"panes create\"", "  runpane agent-context --command \"panes create\" --json"];
+            readonly "agent-context": readonly ["Usage:", "  runpane agent-context [--json]", "  runpane agent-context --command <command> [--json]", "", "Prints Pane command context for coding agents without requiring a running Pane app.", "", "Options:", "  --command <command>            Print the full definition for one runpane command", "  --json                         Print machine-readable output", "  --pane-dir <path>              Accepted and ignored; agent-context never contacts Pane", "", "Examples:", "  runpane agent-context", "  runpane agent-context --json", "  runpane agent-context --command \"panes create\"", "  runpane agent-context --command \"panes create\" --json"];
             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|->) --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.", "", "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", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command"];
+            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] --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"];
             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> [--title <title>] [--no-focus] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor>        Built-in agent command template to launch.", "  --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.", "  --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 until the terminal tool is ready.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --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.", "  --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] --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 until the terminal tool is ready.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --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."];
             readonly "sessions create": readonly ["Usage:", "runpane sessions create --from-json <path|-> [--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."];
             readonly "sessions get": readonly ["Usage:", "runpane sessions get --session <id|name> [--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."];
@@ -961,44 +1054,50 @@ export declare const RUNPANE_CONTRACT: {
             readonly "docs read": readonly ["Usage:", "  runpane docs read --doc <path> [--json]", "", "Read one Pane doc, help topic, or skill in full.", "", "Options:", "  --doc <path>                    Path from docs search, such as docs/PANE_MCP.md.", "  --json                          Print machine-readable output."];
             readonly "agents start": readonly ["Usage:", "  runpane agents start --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --yes [--json] [--pane-dir <path>]", "", "Start an agent on a task: create a Pane in a repository, launch the agent with the prompt, and wait until it is ready.", "", "Options:", "  --repo <selector>               Repository: active, id, exact path, or saved name.", "  --name <name>                   Name for the new Pane.", "  --agent <codex|claude|cursor>   Built-in agent to launch.", "  --tool-command <command>        Custom terminal command instead of a built-in agent.", "  --prompt <task>                 The task to send once the agent is ready.", "  --base-branch <branch>          Branch to start the worktree from.", "  --yes                           Confirm this change; required in non-interactive shells.", "  --json                          Print machine-readable output.", "  --pane-dir <path>               Connect to a specific Pane data directory."];
             readonly "agents status": readonly ["Usage:", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "", "Check on an agent: whether it is working, ready, blocked, or idle, plus its current screen.", "", "Options:", "  --pane <pane-id>                Pane id; its agent panel is used.", "  --panel <panel-id>              Panel id.", "  --limit <count>                 Screen lines to return; defaults to 40.", "  --json                          Print machine-readable output.", "  --pane-dir <path>               Connect to a specific Pane data directory."];
-            readonly "agents send": readonly ["Usage:", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "", "Send a follow-up message to an agent and confirm it was submitted.", "", "Options:", "  --pane <pane-id>                Pane id; its agent panel is used.", "  --panel <panel-id>              Panel id.", "  --text <message>                The message to submit.", "  --yes                           Confirm this change; required in non-interactive shells.", "  --json                          Print machine-readable output.", "  --pane-dir <path>               Connect to a specific Pane data directory."];
+            readonly "agents send": readonly ["Usage:", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> [--as-file-pointer] --yes [--json] [--pane-dir <path>]", "", "Send a follow-up message to an agent and confirm it was submitted.", "", "Options:", "  --pane <pane-id>                Pane id; its agent panel is used.", "  --panel <panel-id>              Panel id.", "  --text <message>                The message to submit.", "  --as-file-pointer               Write the message to a prompt file and send `Read and follow <path>`.", "  --yes                           Confirm this change; required in non-interactive shells.", "  --json                          Print machine-readable output.", "  --pane-dir <path>               Connect to a specific Pane data directory."];
             readonly sessions: readonly ["Usage:", "  runpane sessions <list|create|get|update|set-agent|associate|detach|overview> [options]", "", "Use a named Session to keep context, activity, and evidence attached to one orchestration thread."];
+            readonly report: readonly ["Usage:", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary <text>|--summary-file <path|->] [--question <text>] [--pane <pane-id> --panel <panel-id>] [--json] [--pane-dir <path>]", "", "Hands back a worker's structured report for its panel: the orchestrator receives it as an", "agent.report watch event and reads it in `agents status` and `sessions overview`.", "Inside a Pane terminal the panel comes from PANE_SESSION_ID and PANE_PANEL_ID.", "", "Options:", "  --state <state>                ready, blocked, failed, or done", "  --pr <number>                  Pull request number", "  --head <sha>                   Head commit, 7-40 hex characters", "  --summary <text>               Summary text; up to 16,000 characters are kept", "  --summary-file <path|->        Read the summary from a file or stdin", "  --question <text>              What you need answered; required with --state blocked", "  --pane <pane-id>               Pane id when not running inside a Pane terminal", "  --panel <panel-id>             Panel id when not running inside a Pane terminal", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "", "Example:", "  runpane report --state ready --pr 747 --head fc5dce9 --summary-file /tmp/report.md"];
+            readonly "panels last-message": readonly ["Usage:", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json] [--pane-dir <path>]", "", "Reads a Claude or Codex agent's last reply from its transcript. It never scrapes the screen:", "without a transcript it reports transcript-unavailable and exits non-zero.", "", "Options:", "  --panel <panel-id>             Agent panel id", "  --limit <count>                Maximum characters to return; defaults to 20000 (the end is kept)", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
+            readonly lock: readonly ["Usage:", "  runpane lock <acquire|release|list> [options]", "", "Named locks coordinate a resource shared between agents, such as one test account.", "The caller is the owner: the Pane and panel from $PANE_SESSION_ID and $PANE_PANEL_ID.", "A lock is scoped to the owner's Session when its Pane belongs to one; otherwise it is global.", "It is released on --ttl expiry, when the owner panel exits, or when the owner Pane is archived."];
+            readonly "lock acquire": readonly ["Usage:", "runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON output."];
+            readonly "lock release": readonly ["Usage:", "runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON output."];
+            readonly "lock list": readonly ["Usage:", "runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON 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 panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready]", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--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 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 --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --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 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:", "  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 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 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 --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --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 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 [--version <latest|vX.Y.Z>] [--dry-run] [--yes]"];
-            readonly version: readonly ["Usage:", "  runpane version", "  runpane --version"];
+            readonly version: readonly ["Usage:", "  runpane version [--pane-dir <path>]", "  runpane --version"];
             readonly doctor: readonly ["Usage:", "  runpane doctor [--json] [--pane-dir <path>] [--pane-path <path>] [--format <format>] [--verbose]", "  runpane doctor --report [--title <text>] --body-file <path|-> [--yes] [--json]", "", "Checks wrapper/runtime details, release metadata, installed Pane detection, and Pane daemon reachability.", "", "Options:", "  --json", "  --pane-dir <path>", "  --pane-path <path>", "  --format <format>", "  --verbose", "  --report", "  --body-file <path|->", "  --title <text>", "  --yes", "", "Agent discovery:", "  runpane doctor --json", "  runpane agent-context --json"];
             readonly "daemon repair": readonly ["Usage:", "  runpane daemon repair [--pane-dir <path>] [--pane-path <path>] [--yes] [--json]", "", "Repairs and restarts only the managed remote-daemon launcher and service definition.", "", "Options:", "  --pane-dir <path>", "  --pane-path <path>", "  --yes", "  --json"];
             readonly "repos list": readonly ["Usage:", "  runpane repos list [--json] [--pane-dir <path>]", "", "Lists repositories saved in the running Pane app.", "", "Options:", "  --json", "  --pane-dir <path>"];
             readonly "repos add": readonly ["Usage:", "  runpane repos add --path <path> [--name <name>] [--json] [--yes]", "", "Registers an existing git repository with the running Pane app.", "", "Options:", "  --path <path>", "  --name <name>", "  --pane-dir <path>", "  --json", "  --dry-run", "  --yes"];
-            readonly panes: readonly ["Pane session commands.", "", "Usage:", "  runpane panes <command> [options]", "", "Commands:", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes archive --pane <pane-id> [--force] [--source user|agent] [--dry-run] --yes [--json]", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Run \"runpane help panes <command>\" for command-specific options."];
-            readonly "panes list": readonly ["Usage:", "  runpane panes list [--repo <selector>] [--json]", "", "Lists Pane sessions. Pass --repo to limit results to one saved repository.", "", "Options:", "  --repo <selector>", "  --pane-dir <path>", "  --json"];
+            readonly panes: readonly ["Pane session commands.", "", "Usage:", "  runpane panes <command> [options]", "", "Commands:", "  runpane panes list [--repo <selector>] [--json]", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes archive --pane <pane-id> [--force] [--remove-worktree] [--source user|agent] [--dry-run] --yes [--json]", "  runpane panes archive --session <id|name> --merged [--remove-worktree] [--dry-run] --yes [--json]", "  runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Run \"runpane help panes <command>\" for command-specific options."];
+            readonly "panes list": readonly ["Usage:", "  runpane panes list [--repo <selector>] [--json]", "", "Lists Pane sessions. Pass --repo to limit results to one saved repository.", "", "status is running while any terminal panel is live. agentState is the most urgent state of the live agent panels: blocked, working, ready, or none.", "", "Options:", "  --repo <selector>", "  --pane-dir <path>", "  --json"];
             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 observation commands.", "", "Usage:", "  runpane workspace state [--repo <selector>] [--json]", "  runpane watch --follow"];
             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 [--as <name>|--since <generation>] [--follow] [options]", "", "Waits for workspace transitions without polling.", "", "Options:", "  --as <name>", "  --since <generation>", "  --from <now|earliest>", "  --follow", "  --format <lines|json>", "  --heartbeat <seconds>", "  --idle-after <ms>", "  --settle <ms>                  Opt-in READY quiet window (--follow only)", "  --blocked-settle <ms>          Opt-in BLOCKED window (--follow only)", "  --min-interval <ms>            Opt-in batching; BLOCKED bypasses (--follow only)", "  --idle-backoff                 Opt-in IDLE backoff (--follow only)", "  --all-managed", "  --include-shells", "  --agents-only", "  --exclude-pane <id>            Repeatable", "  --self-test", "  --kinds <kind,...>", "  --pane <id>                    Repeatable", "  --repo <selector>", "  --name-contains <text>", "  --timeout-ms <ms>              0 polls once", "  --limit <count>", "  --ack-now", "  --include-held-input", "  --no-held-input", "  --json                         Alias for --format json", "", "Defaults are responsive: no settle, no batching, all kinds, IDLE every --idle-after. BUSY carries no action; drop it with --kinds.", "Expensive consumers opt in: --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "Pane Chat arms those flags itself through its skill; pass them only for your own scripts.", "STUCK means real unsubmitted composer text; an agent prompt suggestion never counts.", "Dead watch: HEARTBEAT is proof of life only. Judge death by a non-zero exit or a WATCH ERROR line, not by silence."];
-            readonly "panes create": readonly ["Usage:", "  runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [options]", "  runpane panes create --from-json <path|-> [--yes] [--json]", "", "Creates user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.", "", "Options:", "  --repo <selector>              active, id, exact path, or saved repository name", "  --name <name>                  Pane/session name", "  --worktree-name <name>         Worktree name; defaults to --name", "  --base-branch <branch>         Base branch for the worktree", "  --agent <codex|claude|cursor>         Built-in terminal template", "  --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", "  --from-json <path|->           Read a full request payload", "  --timeout-ms <milliseconds>    Pane creation timeout", "  --wait-ready                   Wait for terminal readiness before returning", "  --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                       Accepted for compatibility; creation already pins by default", "  --no-pinned                    Create unpinned instead of the default pinned (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"];
-            readonly "panes adopt": readonly ["Usage:", "  runpane panes adopt --repo <selector> --path <dir> --name <name> --agent <codex|claude|cursor> [options]", "", "Adopts an existing externally managed git worktree without creating, syncing, or deleting it.", "", "Options: --resume <id> stages the agent resume command; --launch runs it immediately; --folder <name> groups the pane; --no-pinned opts out of pinning; --no-associate skips automatic Session association; --dry-run previews."];
-            readonly "panes archive": readonly ["Usage:", "  runpane panes archive --pane <pane-id> [--source user|agent] [--force] [--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. Refuses unsafe archives unless --force is passed. Use --dry-run to print the evidence without mutating Pane state.", "", "Options:", "  --pane <pane-id>", "  --source <user|agent>", "  --force", "  --pane-dir <path>", "  --json", "  --dry-run", "  --yes"];
+            readonly watch: readonly ["Usage:", "  runpane watch [--as <name>|--since <generation>] [--follow] [options]", "", "Waits for workspace transitions without polling.", "", "Options:", "  --as <name>", "  --since <generation>", "  --from <now|earliest>", "  --follow", "  --format <lines|json>", "  --heartbeat <seconds>", "  --idle-after <ms>", "  --settle <ms>                  Opt-in READY quiet window (--follow only)", "  --blocked-settle <ms>          Opt-in BLOCKED window (--follow only)", "  --min-interval <ms>            Opt-in batching; BLOCKED, REPORT, and PR failures bypass (--follow only)", "  --idle-backoff                 Opt-in IDLE backoff (--follow only)", "  --all-managed", "  --include-shells", "  --agents-only", "  --exclude-pane <id>            Repeatable", "  --self-test", "  --quiet                        Drop OK, HEARTBEAT, and RECONNECTED lines", "  --no-control-lines             Alias for --quiet", "  --kinds <kind,...>", "  --pane <id>                    Repeatable", "  --session <id|name>            Follow a named Session's Panes; no re-arm", "  --repo <selector>", "  --name-contains <text>", "  --timeout-ms <ms>              0 polls once", "  --limit <count>", "  --ack-now", "  --include-held-input", "  --no-held-input", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Alias for --format json", "", "Defaults are responsive: no settle, no batching, all kinds, IDLE every --idle-after. BUSY carries no action; drop it with --kinds.", "agent.report (a worker ran `runpane report`) is opt-in: list it in --kinds. REPORT lines skip the --min-interval batch.", "Unattended (Pane Chat default): --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "User present: the same kinds with --settle 60000 --blocked-settle 15000 --min-interval 120000 and no --idle-backoff", "Session orchestrator: runpane watch --session <id|name> --follow --quiet --json --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "Pane Chat arms those flags itself through its skill; pass them only for your own scripts.", "STUCK means real unsubmitted composer text; an agent prompt suggestion never counts.", "Dead watch: HEARTBEAT is proof of life only (--quiet drops it). Judge death by a non-zero exit or a WATCH ERROR line, not by silence."];
+            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 user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.", "", "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 terminal readiness before returning", "  --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                       Accepted for compatibility; creation already pins by default", "  --no-pinned                    Create unpinned instead of the default pinned (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"];
+            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."];
+            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"];
             readonly "panes unpin": readonly ["Usage:", "  runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]", "", "Declaratively unpins 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"];
             readonly "panes rename": readonly ["Usage:", "  runpane panes rename --pane <pane-id> --name <new-name> --yes [--dry-run] [--json]", "", "Renames a Pane without changing its worktree, branch, panels, or focus. The name is trimmed like the Pane UI. Use --dry-run to validate and preview the updated pane without mutating.", "", "Options:", "  --pane <pane-id>", "  --name <new-name>", "  --pane-dir <path>", "  --json", "  --dry-run", "  --yes"];
             readonly "panes focus": readonly ["Usage:", "  runpane panes focus --pane <pane-id> [--panel <panel-id>] --source user|agent --yes [--json]", "", "Raises the Pane window and selects a Pane (and optionally one of its panels) exactly like clicking it in the UI. Steals window focus, so run it only on an explicit user request to open, focus, or show a Pane, never proactively.", "", "Options:", "  --pane <pane-id>", "  --panel <panel-id>", "  --source <user|agent>", "  --pane-dir <path>", "  --json", "  --yes"];
-            readonly panels: readonly ["Terminal-backed panel commands.", "", "Usage:", "  runpane panels <command> [options]", "", "Commands:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [options]", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--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]", "", "Run \"runpane help panels create\" or another command-specific topic for options."];
-            readonly "panels list": readonly ["Usage:", "  runpane panels list --pane <pane-id> [--json]", "", "Lists tool panels in a Pane session.", "", "Options:", "  --pane <pane-id>", "  --pane-dir <path>", "  --json"];
+            readonly panels: readonly ["Terminal-backed panel commands.", "", "Usage:", "  runpane panels <command> [options]", "", "Commands:", "  runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [options]", "  runpane panels list --pane <pane-id> [--json]", "  runpane panels screen --panel <panel-id> [--limit <count>] [--json]", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "  runpane panels input --panel <panel-id> (--text <text>|--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 last-message --panel <panel-id> [--limit <count>] [--json]", "", "Run \"runpane help panels create\" or another command-specific topic for options."];
+            readonly "panels list": readonly ["Usage:", "  runpane panels list --pane <pane-id> [--json]", "", "Lists tool panels in a Pane session.", "", "agentDetection says how Pane knows agentType: declared, command, process, or screen. launchCommand is the command the panel was launched with.", "", "Options:", "  --pane <pane-id>", "  --pane-dir <path>", "  --json"];
             readonly "panels output": readonly ["Usage:", "  runpane panels output --panel <panel-id> [--limit <count>] [--json]", "", "Reads recent terminal output records from a panel.", "", "Options:", "  --panel <panel-id>", "  --limit <count>", "  --pane-dir <path>", "  --json"];
             readonly "panels input": readonly ["Usage:", "  runpane panels input --panel <panel-id> (--text <text>|--keys <name,...>|--input-file <path|->) --yes [--json]", "", "Sends exact input bytes to a terminal panel. Include a newline in the input when you mean Enter.", "", "Options:", "  --panel <panel-id>", "  --text <text>", "  --keys <name,...>              Keys to press: enter, escape, tab, up, down, ctrl-c, ...", "  --input-file <path|->", "  --pane-dir <path>", "  --json", "  --yes"];
-            readonly "agent-context": readonly ["Usage:", "  runpane agent-context [--json]", "  runpane agent-context --command <command> [--json]", "", "Prints Pane command context for coding agents without requiring a running Pane app.", "", "Options:", "  --command <command>", "  --json", "", "Examples:", "  runpane agent-context", "  runpane agent-context --json", "  runpane agent-context --command \"panes create\"", "  runpane agent-context --command \"panes create\" --json"];
+            readonly "agent-context": readonly ["Usage:", "  runpane agent-context [--json]", "  runpane agent-context --command <command> [--json]", "", "Prints Pane command context for coding agents without requiring a running Pane app.", "", "Options:", "  --command <command>", "  --json", "  --pane-dir <path>              Accepted and ignored", "", "Examples:", "  runpane agent-context", "  runpane agent-context --json", "  runpane agent-context --command \"panes create\"", "  runpane agent-context --command \"panes create\" --json"];
             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|->) --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.", "", "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", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "  --yes                          Skip confirmation for this mutating command"];
+            readonly "panels submit": readonly ["Usage:", "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] --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"];
             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> [--title <title>] [--no-focus] --yes [--json]", "", "Options:", "  --pane <pane-id>              Existing Pane session to add the panel to.", "  --agent <codex|claude|cursor>        Built-in agent command template to launch.", "  --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.", "  --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 until the terminal tool is ready.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --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.", "  --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.", "  --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 until the terminal tool is ready.", "  --ready-timeout-ms <ms>       Readiness wait timeout.", "  --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."];
             readonly "sessions create": readonly ["Usage:", "python -m runpane sessions create --from-json <path|-> [--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."];
             readonly "sessions get": readonly ["Usage:", "python -m runpane sessions get --session <id|name> [--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."];
@@ -1029,8 +1128,14 @@ export declare const RUNPANE_CONTRACT: {
             readonly "docs read": readonly ["Usage:", "  runpane docs read --doc <path> [--json]", "", "`runpane docs read` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest docs read"];
             readonly "agents start": readonly ["Usage:", "  runpane agents start --repo <selector> --name <name> (--agent <codex|claude|cursor>|--tool-command <command>) --prompt <task> [--base-branch <branch>] --yes [--json] [--pane-dir <path>]", "", "`runpane agents start` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest agents start"];
             readonly "agents status": readonly ["Usage:", "  runpane agents status (--pane <pane-id>|--panel <panel-id>) [--limit <count>] [--json] [--pane-dir <path>]", "", "`runpane agents status` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest agents status"];
-            readonly "agents send": readonly ["Usage:", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> --yes [--json] [--pane-dir <path>]", "", "`runpane agents send` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest agents send"];
+            readonly "agents send": readonly ["Usage:", "  runpane agents send (--pane <pane-id>|--panel <panel-id>) --text <message> [--as-file-pointer] --yes [--json] [--pane-dir <path>]", "", "`runpane agents send` ships in the npm package and the Pane app, not in the Python package.", "Run it with Node instead: npx --yes runpane@latest agents send"];
             readonly sessions: readonly ["Usage:", "  runpane sessions <list|create|get|update|set-agent|associate|detach|overview> [options]", "", "Use a named Session to keep context, activity, and evidence attached to one orchestration thread."];
+            readonly report: readonly ["Usage:", "  runpane report --state <ready|blocked|failed|done> [--pr <number>] [--head <sha>] [--summary <text>|--summary-file <path|->] [--question <text>] [--pane <pane-id> --panel <panel-id>] [--json] [--pane-dir <path>]", "", "Hands back a worker's structured report for its panel: the orchestrator receives it as an", "agent.report watch event and reads it in `agents status` and `sessions overview`.", "Inside a Pane terminal the panel comes from PANE_SESSION_ID and PANE_PANEL_ID.", "", "Options:", "  --state <state>                ready, blocked, failed, or done", "  --pr <number>                  Pull request number", "  --head <sha>                   Head commit, 7-40 hex characters", "  --summary <text>               Summary text; up to 16,000 characters are kept", "  --summary-file <path|->        Read the summary from a file or stdin", "  --question <text>              What you need answered; required with --state blocked", "  --pane <pane-id>               Pane id when not running inside a Pane terminal", "  --panel <panel-id>             Panel id when not running inside a Pane terminal", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output", "", "Example:", "  runpane report --state ready --pr 747 --head fc5dce9 --summary-file /tmp/report.md"];
+            readonly "panels last-message": readonly ["Usage:", "  runpane panels last-message --panel <panel-id> [--limit <count>] [--json] [--pane-dir <path>]", "", "Reads a Claude or Codex agent's last reply from its transcript. It never scrapes the screen:", "without a transcript it reports transcript-unavailable and exits non-zero.", "", "Options:", "  --panel <panel-id>             Agent panel id", "  --limit <count>                Maximum characters to return; defaults to 20000 (the end is kept)", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
+            readonly lock: readonly ["Usage:", "  python -m runpane lock <acquire|release|list> [options]", "", "Named locks coordinate a resource shared between agents, such as one test account.", "The caller is the owner: the Pane and panel from $PANE_SESSION_ID and $PANE_PANEL_ID.", "A lock is scoped to the owner's Session when its Pane belongs to one; otherwise it is global.", "It is released on --ttl expiry, when the owner panel exits, or when the owner Pane is archived."];
+            readonly "lock acquire": readonly ["Usage:", "python -m runpane lock acquire --name <name> --ttl <duration> [--wait <milliseconds>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON output."];
+            readonly "lock release": readonly ["Usage:", "python -m runpane lock release --name <name> [--force] [--session <id|name>] [--note <text>] [--pane <pane-id>] [--panel <panel-id>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON output."];
+            readonly "lock list": readonly ["Usage:", "python -m runpane lock list [--session <id|name>] [--json] [--pane-dir <path>]", "", "Options:", "  --name <name>                Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".", "  --ttl <duration>             Time to live, such as 90s, 30m, or 2h; a bare number is milliseconds.", "  --wait <milliseconds>        Wait this long for a held lock to come free (acquire).", "  --note <text>                What the lock is for; outside a Pane it also names the owner.", "  --pane <pane-id>             Act for this Pane instead of $PANE_SESSION_ID.", "  --panel <panel-id>           Act for this panel instead of $PANE_PANEL_ID.", "  --force                      Release a lock another owner holds (release).", "  --session <id|name>          Named Session whose locks to list or release.", "  --json                       Print JSON output."];
         };
     };
     readonly docs: {
@@ -1039,16 +1144,16 @@ export declare const RUNPANE_CONTRACT: {
         readonly npmCommands: readonly ["npx --yes runpane@latest", "npx --yes runpane@latest setup", "npx --yes runpane@latest install client", "npx --yes runpane@latest install daemon --label \"My Server\"", "pnpm dlx runpane@latest", "pnpm dlx runpane@latest install daemon --label \"My Server\"", "npm i -g runpane && runpane", "npm i -g runpane && runpane setup", "npm i -g runpane && runpane install daemon --label \"My Server\"", "pnpm add -g runpane && runpane", "pnpm add -g runpane && runpane setup", "pnpm add -g runpane && runpane install daemon --label \"My Server\"", "yarn dlx runpane@latest install daemon --label \"My Server\"", "bunx runpane@latest install daemon --label \"My Server\""];
         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 watch --self-test", "runpane watch --follow", "runpane watch --follow --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "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 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 agents start --repo active --name fix-login --agent claude --prompt \"Fix the login redirect\" --yes --json", "runpane agents status --pane <pane-id> --json", "runpane agents send --pane <pane-id> --text \"Also add a test\" --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"];
-        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` uses the same release resolution and installer path as `install client`.", "`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.", "`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; pass `--no-pinned` to opt out. 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`, `initialInput.verifiedSubmitted: true` is reported only after argument attachment or composer-clear plus activity evidence. Routing input does not by itself verify submission.", "`runpane panes archive` refreshes the configured upstream, reports exact unpushed commit evidence, and refuses unsafe archive operations unless `--force` is used. Add `--dry-run` to inspect the same evidence without archiving. Successful archives wait for worktree removal and report `worktreeCleanup`.", "`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 list` lists tool panels inside one Pane session.", "`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.", "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 workspace transitions from the daemon journal without polling. `--follow` keeps waiting and prints one line per event: READY, BLOCKED, IDLE, STUCK, NEW, GONE, EXIT, plus HEARTBEAT every 60 seconds as proof of life. Defaults are responsive: no settle, no batching, all kinds, IDLE every `--idle-after`. Expensive consumers opt into `--kinds` (drop `agent.busy`; BUSY carries no action), `--settle <ms>` (READY only after a quiet window; a BUSY inside it cancels the line), `--blocked-settle <ms>`, `--min-interval <ms>` (batch non-urgent lines; BLOCKED bypasses it), and `--idle-backoff` (10m, 30m, 1h, 3h, then daily). The recommended orchestrator invocation is `runpane watch --follow --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff`, which budgets about 6 wake-ups per active pane per hour worst case, usually 1-3. Pane Chat arms it automatically through its skill; only your own scripts need the flags. STUCK means real unsubmitted composer text, never an agent prompt suggestion. Judge a dead watch by a non-zero exit or a WATCH ERROR line, not by silence.", "`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 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 agents start|status|send` finish the three common agent jobs in one call each: start an agent on a task in a repository, check on it, and send it a follow-up.", "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."];
+        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 watch --self-test", "runpane watch --follow", "runpane watch --follow --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "runpane watch --session <id|name> --follow --quiet --json --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "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 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 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 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"];
+        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` uses the same release resolution and installer path as `install client`.", "`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; pass `--no-pinned` to opt out. 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`, `initialInput.delivery` says where the prompt went: `taken` or `queued` (from the agent's transcript, its screen, or `argv` for a launch-argument prompt), `in-composer`, or `unknown`. `initialInput.verifiedSubmitted` is true exactly when it is `taken` or `queued`. Routing input does not by itself verify submission.", "`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 list` lists tool panels inside one Pane session.", "`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`.", "`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 workspace transitions from the daemon journal without polling. `--follow` keeps waiting and prints one line per event: READY, BLOCKED, IDLE, STUCK, NEW, GONE, EXIT, plus HEARTBEAT every 60 seconds as proof of life. Defaults are responsive: no settle, no batching, all kinds, IDLE every `--idle-after`. Expensive consumers opt into `--kinds` (drop `agent.busy`; BUSY carries no action), `--settle <ms>` (READY only after a quiet window; a BUSY inside it cancels the line), `--blocked-settle <ms>`, `--min-interval <ms>` (batch non-urgent lines; BLOCKED bypasses it), and `--idle-backoff` (10m, 30m, 1h, 3h, then daily). Two profiles cover orchestrators. Unattended: `runpane watch --follow --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff`, which budgets about 6 wake-ups per active pane per hour worst case, usually 1-3, and can deliver READY up to about 13 minutes late. User present: the same kinds with `--settle 60000 --blocked-settle 15000 --min-interval 120000` and no `--idle-backoff`, so READY arrives within about 3 minutes. Pane Chat arms it automatically through its skill; only your own scripts need the flags. STUCK means real unsubmitted composer text, never an agent prompt suggestion. `--quiet` (alias `--no-control-lines`) drops the WATCH OK, HEARTBEAT, and WATCH RECONNECTED control lines (`_ok`, `_heartbeat`, `_reconnected` in JSON); WATCH ERROR, RESET, and DROPPED (`_error`, `_reset`, `_dropped`) always print. Judge a dead watch by a non-zero exit or a WATCH ERROR line, not by silence. `--session <id|name>` follows every Pane associated with a named Session and re-reads membership on every read, so associate and detach need no re-arm; JOINED and LEFT (`pane.associated`, `pane.detached`) report membership changes. For Session members with an open PR, the daemon polls GitHub about every 3 minutes and reports `pr.conflicted` (`PR <pane-name> pane <pane-id> #<number> CONFLICTED`), `pr.checks` (`... CHECKS PASSED` or `... CHECKS FAILED <names>`), and `pr.merged` (`... MERGED`) on transitions only; list them in `--kinds`. In JSON, an entry with `replay: true` restates current state after a reset and is never READY.", "`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 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 in a repository, 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`.", "`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."];
         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. In a Pane repository checkout, if `runpane` is not on PATH, use the built local wrapper with Node 22, for example `PATH=/opt/homebrew/opt/node@22/bin:$PATH 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 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, use the built local wrapper with Node 22, for example `PATH=/opt/homebrew/opt/node@22/bin:$PATH 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.";
         readonly downloadAttribution: readonly ["The npm package uses `source=npm` for all npm-registry consumers, including `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, and global npm/pnpm installs.", "The PyPI package uses `source=pip` for all Python consumers, including pip, pipx, uvx, and `python -m runpane`.", "Wrappers should prefer `https://runpane.com/api/download?platform=<platform>&arch=<arch>&format=<format>&version=<version>&channel=<channel>&source=<npm|pip>`.", "If the website route cannot satisfy the download, wrappers may fall back to the matching GitHub release asset and print a warning that website attribution may be incomplete for that run.", "Wrappers also emit best-effort lifecycle telemetry to `https://runpane.com/api/runpane/telemetry` for command start/success/failure, download request/success/failure, and GitHub fallback usage.", "Wrapper telemetry uses a persisted anonymous `install_id` in the form `install_<uuid>` and PostHog `distinct_id = install:<install_id>` so distinct wrapper users can be counted with `count(DISTINCT properties.install_id)`.", "Wrapper telemetry must be disabled in CI and when `RUNPANE_TELEMETRY_DISABLED` is set, and must not include raw paths, labels, prompts, raw error text, or environment values."];
         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", "--format", "lines", "--heartbeat", "60", "--idle-after", "600000", "--settle", "180000", "--blocked-settle", "30000", "--min-interval", "600000", "--idle-backoff", "--all-managed", "--agents-only", "--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 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", "--format", "lines", "--heartbeat", "60", "--idle-after", "600000", "--settle", "180000", "--blocked-settle", "30000", "--min-interval", "600000", "--idle-backoff", "--all-managed", "--agents-only", "--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", "--quiet", "--json", "--pane-dir", "/tmp/pane"], readonly ["watch", "--follow", "--no-control-lines", "--all-managed"], readonly ["watch", "--session", "__orchestration_session_1b4e28ba-2fa1-11d2-883f-0016d3cca427__", "--follow", "--quiet", "--json", "--kinds", "agent.ready,agent.blocked,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged", "--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", "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 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"];
@@ -1518,6 +1623,9 @@ export declare const RUNPANE_CONTRACT: {
                             readonly worktreeName: {
                                 readonly type: "string";
                             };
+                            readonly branch: {
+                                readonly type: "string";
+                            };
                             readonly baseBranch: {
                                 readonly type: "string";
                             };
@@ -1541,6 +1649,9 @@ export declare const RUNPANE_CONTRACT: {
                                         readonly initialInput: {
                                             readonly type: "string";
                                         };
+                                        readonly initialInputAsFilePointer: {
+                                            readonly type: "boolean";
+                                        };
                                     };
                                     readonly additionalProperties: false;
                                 }, {
@@ -1550,12 +1661,18 @@ export declare const RUNPANE_CONTRACT: {
                                         readonly command: {
                                             readonly type: "string";
                                         };
+                                        readonly agentType: {
+                                            readonly enum: readonly ["codex", "claude", "cursor"];
+                                        };
                                         readonly title: {
                                             readonly type: "string";
                                         };
                                         readonly initialInput: {
                                             readonly type: "string";
                                         };
+                                        readonly initialInputAsFilePointer: {
+                                            readonly type: "boolean";
+                                        };
                                     };
                                     readonly additionalProperties: false;
                                 }];
@@ -1755,6 +1872,9 @@ export declare const RUNPANE_CONTRACT: {
                                         readonly verifiedSubmitted: {
                                             readonly type: "boolean";
                                         };
+                                        readonly delivery: {
+                                            readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/delivery";
+                                        };
                                         readonly staged: {
                                             readonly type: "boolean";
                                         };
@@ -1818,6 +1938,12 @@ export declare const RUNPANE_CONTRACT: {
                                     };
                                     readonly additionalProperties: false;
                                 };
+                                readonly promptFile: {
+                                    readonly type: "string";
+                                };
+                                readonly warnings: {
+                                    readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/warnings";
+                                };
                             };
                             readonly additionalProperties: false;
                         }, {
@@ -1918,6 +2044,9 @@ export declare const RUNPANE_CONTRACT: {
                             readonly agentStatus: {
                                 readonly enum: readonly ["active", "idle"];
                             };
+                            readonly agentState: {
+                                readonly enum: readonly ["ready", "working", "blocked", "none"];
+                            };
                             readonly ownership: {
                                 readonly enum: readonly ["pane", "external"];
                             };
@@ -2194,7 +2323,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"];
+                    readonly enum: readonly ["agent.ready", "agent.busy", "agent.blocked", "agent.unknown", "agent.idle", "pane.created", "pane.gone", "panel.exited", "agent.report", "pane.associated", "pane.detached", "pr.conflicted", "pr.checks", "pr.merged"];
                 };
                 readonly paneId: {
                     readonly type: "string";
@@ -2224,7 +2353,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly enum: readonly ["blocked", "working", "idle", "unknown"];
                 };
                 readonly source: {
-                    readonly enum: readonly ["agent", "exit", "session"];
+                    readonly enum: readonly ["agent", "exit", "session", "github"];
                 };
                 readonly reason: {
                     readonly oneOf: readonly [{
@@ -2254,9 +2383,84 @@ export declare const RUNPANE_CONTRACT: {
                 readonly baseline: {
                     readonly const: true;
                 };
+                readonly replay: {
+                    readonly const: true;
+                    readonly description: "Set on baseline entries delivered after a reset. A replayed entry restates current state and is never a new transition: a replayed agent.ready is not READY.";
+                };
                 readonly changedWhileAway: {
                     readonly type: "boolean";
                 };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Named Session of a pane.associated or pane.detached entry.";
+                };
+                readonly sessionName: {
+                    readonly type: "string";
+                };
+                readonly pr: {
+                    readonly type: "object";
+                    readonly description: "PR of a pr.conflicted, pr.checks, or pr.merged entry.";
+                    readonly required: readonly ["number", "url", "headOid"];
+                    readonly properties: {
+                        readonly number: {
+                            readonly type: "number";
+                        };
+                        readonly url: {
+                            readonly type: "string";
+                        };
+                        readonly headOid: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+                readonly checks: {
+                    readonly enum: readonly ["passed", "failed"];
+                    readonly description: "Settled result of a pr.checks entry: every check on pr.headOid finished.";
+                };
+                readonly failingChecks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Up to five failing check names of a failed pr.checks entry.";
+                };
+                readonly report: {
+                    readonly $ref: "#/jsonSchemas/agentReport";
+                    readonly description: "Report of an agent.report entry; its summary is cut to 2,000 characters (the panel keeps up to 16,000).";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly agentReport: {
+            readonly type: "object";
+            readonly description: "The latest runpane report from an agent panel.";
+            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 additionalProperties: false;
         };
@@ -2290,6 +2494,10 @@ export declare const RUNPANE_CONTRACT: {
                         readonly type: "string";
                     };
                 };
+                readonly session: {
+                    readonly type: "string";
+                    readonly description: "Named Session id or exact name. Limits the wait to the Session's associated Panes, resolved on every read, and implies the opt-in pane.associated, pane.detached, and pr.* entries. Cannot be combined with paneIds.";
+                };
                 readonly excludePaneIds: {
                     readonly type: "array";
                     readonly items: {
@@ -2411,6 +2619,20 @@ export declare const RUNPANE_CONTRACT: {
                     };
                     readonly additionalProperties: false;
                 };
+                readonly session: {
+                    readonly type: "object";
+                    readonly description: "The Session a session request resolved to. A client that sent session and gets no session back is talking to a daemon that ignored it.";
+                    readonly required: readonly ["id", "name"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                        };
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
                 readonly nextCommand: {
                     readonly type: "string";
                 };
@@ -2433,6 +2655,9 @@ export declare const RUNPANE_CONTRACT: {
                 readonly dryRun: {
                     readonly type: "boolean";
                 };
+                readonly removeWorktree: {
+                    readonly type: "boolean";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -2570,6 +2795,11 @@ export declare const RUNPANE_CONTRACT: {
                     };
                     readonly worktreeCleanup: {
                         readonly enum: readonly ["completed", "failed", "timeout", "not-applicable"];
+                        readonly description: "`completed`: the worktree is gone from its path and from git (see trashDeletion). `failed`: removal failed and the worktree may remain; ok is false. `timeout`: the archive script or git removal is still running in the background; ok stays true. `not-applicable`: nothing was removed (main-repo Pane, or an adopted worktree without --remove-worktree). Released CLIs decode exactly these values.";
+                    };
+                    readonly trashDeletion: {
+                        readonly enum: readonly ["pending", "done"];
+                        readonly description: "Present with worktreeCleanup `completed`. `pending`: the removed worktree was moved into the repository's .git/pane-trash and its files are still being deleted in the background. `done`: the files are gone.";
                     };
                     readonly worktreePath: {
                         readonly type: "string";
@@ -2615,6 +2845,30 @@ export declare const RUNPANE_CONTRACT: {
                                     readonly additionalProperties: false;
                                 };
                             };
+                            readonly reason: {
+                                readonly enum: readonly ["external-worktree", "main-repo", "missing-project-context", "git-error"];
+                            };
+                            readonly worktreeWillRemain: {
+                                readonly const: true;
+                            };
+                            readonly upstreamGone: {
+                                readonly type: "boolean";
+                                readonly description: "The branch had an upstream that no longer exists on the remote, so commits were compared with the base branch.";
+                            };
+                            readonly mergedViaPr: {
+                                readonly type: "object";
+                                readonly description: "A merged pull request whose head commit is HEAD. Its commits are not counted as unpushed.";
+                                readonly required: readonly ["number", "headOid"];
+                                readonly properties: {
+                                    readonly number: {
+                                        readonly type: "number";
+                                    };
+                                    readonly headOid: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly additionalProperties: false;
+                            };
                         };
                         readonly additionalProperties: false;
                     };
@@ -2714,6 +2968,12 @@ export declare const RUNPANE_CONTRACT: {
                                             readonly additionalProperties: false;
                                         };
                                     };
+                                    readonly reason: {
+                                        readonly enum: readonly ["external-worktree", "main-repo", "missing-project-context", "git-error"];
+                                    };
+                                    readonly worktreeWillRemain: {
+                                        readonly const: true;
+                                    };
                                 };
                                 readonly additionalProperties: false;
                             };
@@ -2767,6 +3027,12 @@ export declare const RUNPANE_CONTRACT: {
                             readonly agentType: {
                                 readonly type: "string";
                             };
+                            readonly agentDetection: {
+                                readonly enum: readonly ["declared", "command", "process", "screen"];
+                            };
+                            readonly launchCommand: {
+                                readonly type: "string";
+                            };
                             readonly isCliPanel: {
                                 readonly type: "boolean";
                             };
@@ -2779,6 +3045,9 @@ export declare const RUNPANE_CONTRACT: {
                             readonly lastActiveAt: {
                                 readonly type: "string";
                             };
+                            readonly report: {
+                                readonly $ref: "#/jsonSchemas/agentReport";
+                            };
                         };
                         readonly additionalProperties: false;
                     };
@@ -3053,6 +3322,9 @@ export declare const RUNPANE_CONTRACT: {
                         readonly hasUndeliveredText: {
                             readonly type: "boolean";
                         };
+                        readonly ghostText: {
+                            readonly type: "string";
+                        };
                     };
                     readonly additionalProperties: false;
                 };
@@ -3075,6 +3347,9 @@ export declare const RUNPANE_CONTRACT: {
                 readonly input: {
                     readonly type: "string";
                 };
+                readonly asFilePointer: {
+                    readonly type: "boolean";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -3106,12 +3381,44 @@ export declare const RUNPANE_CONTRACT: {
                 readonly verifiedSubmitted: {
                     readonly type: "boolean";
                 };
+                readonly delivery: {
+                    readonly type: "object";
+                    readonly required: readonly ["state", "evidence"];
+                    readonly properties: {
+                        readonly state: {
+                            readonly enum: readonly ["taken", "queued", "in-composer", "unknown"];
+                        };
+                        readonly evidence: {
+                            readonly enum: readonly ["transcript", "screen", "argv"];
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
                 readonly sentAt: {
                     readonly type: "string";
                 };
                 readonly blocked: {
                     readonly $ref: "#/jsonSchemas/panelSubmitComposerResult/properties/blocked";
                 };
+                readonly promptFile: {
+                    readonly type: "string";
+                };
+                readonly warnings: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["code", "message"];
+                        readonly properties: {
+                            readonly code: {
+                                readonly enum: readonly ["leading-bang-runs-shell", "leading-hash-memory", "leading-slash-command", "leading-at-mention"];
+                            };
+                            readonly message: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                };
                 readonly nextCommand: {
                     readonly type: "string";
                 };
@@ -3212,6 +3519,60 @@ export declare const RUNPANE_CONTRACT: {
             };
             readonly additionalProperties: false;
         };
+        readonly panelLastMessageResult: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["ok", "panelId", "paneId", "agentType", "text", "length", "limit", "truncated"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: true;
+                    };
+                    readonly panelId: {
+                        readonly type: "string";
+                    };
+                    readonly paneId: {
+                        readonly type: "string";
+                    };
+                    readonly agentType: {
+                        readonly enum: readonly ["claude", "codex"];
+                    };
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly length: {
+                        readonly type: "number";
+                    };
+                    readonly limit: {
+                        readonly type: "number";
+                    };
+                    readonly truncated: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["ok", "panelId", "paneId", "reason", "message"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: false;
+                    };
+                    readonly panelId: {
+                        readonly type: "string";
+                    };
+                    readonly paneId: {
+                        readonly type: "string";
+                    };
+                    readonly reason: {
+                        readonly const: "transcript-unavailable";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
         readonly agentDoctorResult: {
             readonly type: "object";
             readonly required: readonly ["ok", "agent", "command", "available", "checks"];
@@ -3410,6 +3771,12 @@ export declare const RUNPANE_CONTRACT: {
                     };
                     readonly additionalProperties: false;
                 };
+                readonly promptFile: {
+                    readonly type: "string";
+                };
+                readonly warnings: {
+                    readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/warnings";
+                };
                 readonly nextCommand: {
                     readonly type: "string";
                 };
@@ -3457,6 +3824,9 @@ export declare const RUNPANE_CONTRACT: {
                 readonly verifiedSubmitted: {
                     readonly type: "boolean";
                 };
+                readonly delivery: {
+                    readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/delivery";
+                };
                 readonly sentAt: {
                     readonly type: "string";
                 };
@@ -3465,7 +3835,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly required: readonly ["kind", "message"];
                     readonly properties: {
                         readonly kind: {
-                            readonly enum: readonly ["codex-update", "agent-prompt", "submission_unverified", "unknown"];
+                            readonly enum: readonly ["codex-update", "agent-prompt", "submission_unverified", "composer-unknown", "unknown"];
                         };
                         readonly message: {
                             readonly type: "string";
@@ -3545,61 +3915,259 @@ export declare const RUNPANE_CONTRACT: {
                 readonly refreshedAt: {
                     readonly type: "string";
                 };
-            };
-            readonly additionalProperties: false;
-        };
-        readonly daemonActionResult: {
-            readonly type: "object";
-            readonly required: readonly ["ok"];
-            readonly properties: {
-                readonly ok: {
-                    readonly type: "boolean";
-                };
-                readonly data: {};
-                readonly error: {
-                    readonly type: "object";
-                    readonly required: readonly ["message"];
-                    readonly properties: {
-                        readonly message: {
-                            readonly type: "string";
-                        };
+                readonly locks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items";
                     };
-                    readonly additionalProperties: false;
-                };
-                readonly link: {
-                    readonly type: "string";
                 };
             };
             readonly additionalProperties: false;
         };
-        readonly linkCreateResult: {
+        readonly lockListResult: {
             readonly type: "object";
-            readonly required: readonly ["ok", "url", "target"];
+            readonly required: readonly ["ok", "locks"];
             readonly properties: {
                 readonly ok: {
                     readonly const: true;
                 };
-                readonly url: {
-                    readonly type: "string";
-                };
-                readonly target: {
-                    readonly type: "object";
-                    readonly required: readonly ["kind", "id"];
-                    readonly properties: {
-                        readonly kind: {
-                            readonly enum: readonly ["pane", "repo", "session"];
-                        };
-                        readonly id: {
-                            readonly type: "string";
-                        };
-                        readonly panelId: {
-                            readonly type: "string";
-                        };
-                    };
-                    readonly additionalProperties: false;
-                };
-            };
-            readonly additionalProperties: false;
+                readonly locks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["name", "scope", "owner", "acquiredAt", "expiresAt", "ttlMs"];
+                        readonly properties: {
+                            readonly name: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly scope: {
+                                readonly enum: readonly ["session", "global"];
+                            };
+                            readonly sessionId: {
+                                readonly type: "string";
+                            };
+                            readonly owner: {
+                                readonly type: "object";
+                                readonly required: readonly ["kind"];
+                                readonly properties: {
+                                    readonly kind: {
+                                        readonly enum: readonly ["pane", "external"];
+                                    };
+                                    readonly paneId: {
+                                        readonly type: "string";
+                                    };
+                                    readonly panelId: {
+                                        readonly type: "string";
+                                    };
+                                    readonly label: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly additionalProperties: false;
+                            };
+                            readonly note: {
+                                readonly type: "string";
+                            };
+                            readonly acquiredAt: {
+                                readonly type: "string";
+                            };
+                            readonly expiresAt: {
+                                readonly type: "string";
+                            };
+                            readonly ttlMs: {
+                                readonly type: "number";
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly lockAcquireRequest: {
+            readonly type: "object";
+            readonly required: readonly ["name", "ttlMs", "owner"];
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly ttlMs: {
+                    readonly type: "number";
+                };
+                readonly waitMs: {
+                    readonly type: "number";
+                };
+                readonly note: {
+                    readonly type: "string";
+                };
+                readonly owner: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly paneId: {
+                            readonly type: "string";
+                        };
+                        readonly panelId: {
+                            readonly type: "string";
+                        };
+                        readonly label: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly lockAcquireResult: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["ok", "acquired", "renewed", "waitedMs", "lock"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: true;
+                    };
+                    readonly acquired: {
+                        readonly const: true;
+                    };
+                    readonly renewed: {
+                        readonly type: "boolean";
+                    };
+                    readonly waitedMs: {
+                        readonly type: "number";
+                    };
+                    readonly lock: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items";
+                    };
+                };
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["ok", "acquired", "timedOut", "waitedMs", "heldBy", "expiresAt", "lock"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: false;
+                    };
+                    readonly acquired: {
+                        readonly const: false;
+                    };
+                    readonly timedOut: {
+                        readonly type: "boolean";
+                    };
+                    readonly waitedMs: {
+                        readonly type: "number";
+                    };
+                    readonly heldBy: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items/properties/owner";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "string";
+                    };
+                    readonly lock: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+        readonly lockReleaseResult: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["ok", "released", "forced"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: true;
+                    };
+                    readonly released: {
+                        readonly type: "boolean";
+                    };
+                    readonly forced: {
+                        readonly type: "boolean";
+                    };
+                    readonly lock: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items";
+                    };
+                };
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["ok", "released", "reason", "heldBy", "expiresAt", "lock"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly const: false;
+                    };
+                    readonly released: {
+                        readonly const: false;
+                    };
+                    readonly reason: {
+                        readonly const: "not-owner";
+                    };
+                    readonly heldBy: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items/properties/owner";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "string";
+                    };
+                    readonly lock: {
+                        readonly $ref: "#/jsonSchemas/lockListResult/properties/locks/items";
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
+        readonly daemonActionResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok"];
+            readonly properties: {
+                readonly ok: {
+                    readonly type: "boolean";
+                };
+                readonly data: {};
+                readonly error: {
+                    readonly type: "object";
+                    readonly required: readonly ["message"];
+                    readonly properties: {
+                        readonly message: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+                readonly link: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly linkCreateResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "url", "target"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly url: {
+                    readonly type: "string";
+                };
+                readonly target: {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "id"];
+                    readonly properties: {
+                        readonly kind: {
+                            readonly enum: readonly ["pane", "repo", "session"];
+                        };
+                        readonly id: {
+                            readonly type: "string";
+                        };
+                        readonly panelId: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly additionalProperties: false;
         };
         readonly docsSearchResult: {
             readonly type: "object";
@@ -3720,6 +4288,9 @@ export declare const RUNPANE_CONTRACT: {
                 readonly link: {
                     readonly type: "string";
                 };
+                readonly report: {
+                    readonly $ref: "#/jsonSchemas/agentReport";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -3739,21 +4310,181 @@ export declare const RUNPANE_CONTRACT: {
                 readonly delivered: {
                     readonly type: "boolean";
                 };
+                readonly delivery: {
+                    readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/delivery";
+                };
                 readonly blocked: {
                     readonly type: "string";
                 };
+                readonly promptFile: {
+                    readonly type: "string";
+                };
+                readonly warnings: {
+                    readonly $ref: "#/jsonSchemas/panelSubmitResult/properties/warnings";
+                };
                 readonly next: {
                     readonly type: "string";
                 };
             };
             readonly additionalProperties: false;
         };
+        readonly agentContextUnknownCommandError: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "code", "message", "candidates"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: false;
+                };
+                readonly code: {
+                    readonly const: "unknown_command";
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+                readonly candidates: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly reportResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "paneId", "panelId", "report", "sessionIds"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly generation: {
+                    readonly type: "number";
+                };
+                readonly paneId: {
+                    readonly type: "string";
+                };
+                readonly panelId: {
+                    readonly type: "string";
+                };
+                readonly report: {
+                    readonly $ref: "#/jsonSchemas/agentReport";
+                };
+                readonly sessionIds: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly paneArchiveBulkRequest: {
+            readonly type: "object";
+            readonly required: readonly ["sessionId", "merged"];
+            readonly properties: {
+                readonly sessionId: {
+                    readonly type: "string";
+                };
+                readonly merged: {
+                    readonly const: true;
+                };
+                readonly source: {
+                    readonly enum: readonly ["user", "agent"];
+                };
+                readonly dryRun: {
+                    readonly type: "boolean";
+                };
+                readonly removeWorktree: {
+                    readonly type: "boolean";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly paneArchiveBulkResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "sessionId", "merged", "removeWorktree", "archived", "skipped", "failed", "items"];
+            readonly properties: {
+                readonly ok: {
+                    readonly type: "boolean";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                };
+                readonly merged: {
+                    readonly const: true;
+                };
+                readonly dryRun: {
+                    readonly const: true;
+                };
+                readonly removeWorktree: {
+                    readonly type: "boolean";
+                };
+                readonly archived: {
+                    readonly type: "number";
+                    readonly description: "Panes archived, or that would be archived with --dry-run.";
+                };
+                readonly skipped: {
+                    readonly type: "number";
+                };
+                readonly failed: {
+                    readonly type: "number";
+                };
+                readonly items: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["paneId", "outcome"];
+                        readonly properties: {
+                            readonly paneId: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly outcome: {
+                                readonly enum: readonly ["archived", "would-archive", "skipped", "failed"];
+                            };
+                            readonly skipped: {
+                                readonly type: "object";
+                                readonly required: readonly ["code", "message"];
+                                readonly properties: {
+                                    readonly code: {
+                                        readonly enum: readonly ["uncommitted-changes", "unpushed-commits", "uncommitted-and-unpushed", "status-unknown", "missing-pane", "already-archived", "main-repo"];
+                                    };
+                                    readonly message: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly additionalProperties: false;
+                            };
+                            readonly error: {
+                                readonly type: "string";
+                            };
+                            readonly safetyCheck: {
+                                readonly $ref: "#/jsonSchemas/paneArchiveResult/oneOf/0/properties/safetyCheck";
+                            };
+                            readonly worktreeCleanup: {
+                                readonly $ref: "#/jsonSchemas/paneArchiveResult/oneOf/0/properties/worktreeCleanup";
+                            };
+                            readonly trashDeletion: {
+                                readonly $ref: "#/jsonSchemas/paneArchiveResult/oneOf/0/properties/trashDeletion";
+                            };
+                            readonly worktreePath: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly additionalProperties: false;
+        };
     };
     readonly agentContext: {
         readonly brief: {
             readonly title: "Pane agent context";
             readonly summary: "Pane lets a developer manage saved base repositories, user-visible Panes (Pane sessions) for feature/PR work, and terminal-backed panel tabs. A Pane is a visible workspace that normally maps to one Pane-managed git worktree and branch; a panel is a terminal tab inside one Pane and shares that Pane's worktree; an agent is a CLI process running inside a panel.";
-            readonly rules: readonly ["Start with `runpane doctor --json` to understand wrapper, platform, daemon reachability, and the next safe commands before mutating Pane state.", "In a Pane repository checkout, if `runpane` is not on PATH, use the built local wrapper with Node 22, for example `PATH=/opt/homebrew/opt/node@22/bin:$PATH node packages/runpane/dist/cli.js doctor --json`.", "Happy path for any user request to use Pane/RunPane: run `runpane doctor --json`, read `runpane agent-context --json`, resolve or add the saved base repo, create the requested visible Pane with a complete command such as `runpane panes create --repo <repo> --name <name> --agent <agent> --prompt \"<task>\" --source agent --no-focus --wait-ready --yes --json` (the new Pane is pinned by default; add `--no-pinned` for a throwaway Pane, or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`. For long-lived supervision, use `runpane watch --follow` instead of polling wait or screen.", "Treat Pane as the user's visible cockpit for watching/co-driving work. Do not create Panes or panels for private delegation unless the user asked for visible Pane orchestration or the result should appear in the Pane app.", "Register the saved base repository once with `repos add`; do not register a pre-created worktree as a separate repo unless the user explicitly asks.", "Use `panes create` for separate visible Panes (Pane sessions) for feature/PR work. Pane creates and owns the worktree/branch for each new Pane.", "Use `panels create` for reviewer/helper/clean-context tabs that should stay inside an existing Pane and share that Pane's worktree.", "For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.", "Skill routing: Pane's skills live in `<PANE_DIR>/skills/pane-chat/skills/`, and the Pane Chat entry point is `<PANE_DIR>/skills/pane-chat/pane-orchestrator/SKILL.md`; read the skill that matches the request, such as `discussion`, `create-ticket`, `tdd`, `prepare-pr`, or `review`.", "When an agent creates Panes or panels, pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved; `panes create` pins the new Pane into the UI's favorite/pin set by default, so no follow-up `panes pin` call is needed and `--no-pinned` is the opt-out for throwaway Panes.", "Use `runpane agent-context --json` for the full agent-facing CLI context, or `runpane agent-context --command <command> --json` for one detailed command definition.", "For `agent-context --command`, use canonical spaced names like `panes create`; copied forms like `panes.create` or `runpane panes create` are accepted too.", "Use `runpane repos list --json` to find the saved repository when unsure after doctor shows the daemon is reachable.", "If WSL cannot reach Pane or `runpane` resolves to a broken Windows shim, the user may be running Windows Pane; try `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane doctor --json'`.", "If the repository exists on disk but is not saved in Pane, use `runpane repos add --path <repo> --yes --json` before creating panes.", "Use `runpane agents doctor --agent <codex|claude|cursor> --repo <selector> --json` when agent availability differs across host, Windows, WSL, or repo environments.", "Use `runpane panes create --wait-ready` to create Panes and validate initial terminal readiness in one call.", "Use `runpane panels screen` for compact current state, including Claude and Codex composer state. Use `panels wait` for create-time readiness or text checks. Use `runpane watch --follow` to block on workspace transitions (READY, BLOCKED, IDLE, STUCK, EXIT) without polling. Use `panels submit` to send and submit a new turn. Use `panels submit-composer --strategy auto` only for a composer that was filled separately.", "Use `runpane panels input` only when exact bytes are required, such as Ctrl-C or handcrafted terminal input.", "Pane terminals draw inline images: sixel, iTerm2 inline images, and the kitty graphics protocol. Tools that need kitty graphics, such as terminal-browser and terminal-doom, run inside a Pane panel; `runpane doctor --json` reports the exact list under `terminal.graphicsProtocols`.", "After creating Panes or sending terminal input, validate with `panels wait` or bounded `panels screen` before reporting success. For ongoing supervision, `runpane watch --follow` is the canonical monitor."];
+            readonly rules: readonly ["Start with `runpane doctor --json` to understand wrapper, platform, daemon reachability, and the next safe commands before mutating Pane state.", "In a Pane repository checkout, if `runpane` is not on PATH, use the built local wrapper with Node 22, for example `PATH=/opt/homebrew/opt/node@22/bin:$PATH node packages/runpane/dist/cli.js doctor --json`.", "Happy path for any user request to use Pane/RunPane: run `runpane doctor --json`, read `runpane agent-context --json`, resolve or add the saved base repo, create the requested visible Pane with a complete command such as `runpane panes create --repo <repo> --name <name> --agent <agent> --prompt \"<task>\" --source agent --no-focus --wait-ready --yes --json` (the new Pane is pinned by default; add `--no-pinned` for a throwaway Pane, add `--base-branch <ref>` to branch from something other than the repository default, or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`. For long-lived supervision, use `runpane watch --follow` instead of polling wait or screen.", "Treat Pane as the user's visible cockpit for watching/co-driving work. Do not create Panes or panels for private delegation unless the user asked for visible Pane orchestration or the result should appear in the Pane app.", "Register the saved base repository once with `repos add`; do not register a pre-created worktree as a separate repo unless the user explicitly asks.", "Use `panes create` for separate visible Panes (Pane sessions) for feature/PR work. Pane creates and owns the worktree/branch for each new Pane.", "Use `panels create` for reviewer/helper/clean-context tabs that should stay inside an existing Pane and share that Pane's worktree.", "For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.", "Skill routing: Pane's skills live in `<PANE_DIR>/skills/pane-chat/skills/`, and the Pane Chat entry point is `<PANE_DIR>/skills/pane-chat/pane-orchestrator/SKILL.md`; read the skill that matches the request, such as `discussion`, `create-ticket`, `tdd`, `prepare-pr`, or `review`.", "When an agent creates Panes or panels, pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved; `panes create` pins the new Pane into the UI's favorite/pin set by default, so no follow-up `panes pin` call is needed and `--no-pinned` is the opt-out for throwaway Panes.", "Use `runpane agent-context --json` for the full agent-facing CLI context, or `runpane agent-context --command <command> --json` for one detailed command definition.", "For `agent-context --command`, use canonical spaced names like `panes create`; copied forms like `panes.create` or `runpane panes create` are accepted too.", "Use `runpane repos list --json` to find the saved repository when unsure after doctor shows the daemon is reachable.", "If WSL cannot reach Pane or `runpane` resolves to a broken Windows shim, the user may be running Windows Pane; try `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane doctor --json'`.", "If the repository exists on disk but is not saved in Pane, use `runpane repos add --path <repo> --yes --json` before creating panes.", "Use `runpane agents doctor --agent <codex|claude|cursor> --repo <selector> --json` when agent availability differs across host, Windows, WSL, or repo environments.", "Use `runpane panes create --wait-ready` to create Panes and validate initial terminal readiness in one call.", "Use `runpane panels screen` for compact current state, including Claude and Codex composer state. Use `panels wait` for create-time readiness or text checks. Use `runpane watch --follow` to block on workspace transitions (READY, BLOCKED, IDLE, STUCK, EXIT) without polling. Use `panels submit` to send and submit a new turn. Use `panels submit-composer --strategy auto` only for a composer that was filled separately.", "Use `runpane panels input` only when exact bytes are required, such as Ctrl-C or handcrafted terminal input.", "Pane terminals draw inline images: sixel, iTerm2 inline images, and the kitty graphics protocol. Tools that need kitty graphics, such as terminal-browser and terminal-doom, run inside a Pane panel; `runpane doctor --json` reports the exact list under `terminal.graphicsProtocols`.", "After creating Panes or sending terminal input, validate with `panels wait` or bounded `panels screen` before reporting success. For ongoing supervision, `runpane watch --follow` is the canonical monitor.", "When several agents share one resource, such as a test account, name a lock in their prompts: each worker runs `runpane lock acquire --name <name> --ttl 30m --wait 1800000 --json` before using it and `runpane lock release --name <name>` after."];
             readonly detailCommand: "runpane agent-context --command <command> [--json]";
             readonly tools: readonly [{
                 readonly name: "doctor";
@@ -3789,8 +4520,8 @@ export declare const RUNPANE_CONTRACT: {
                 readonly arguments: readonly ["--repo <selector>", "--name <name>", "--agent <codex|claude|cursor>", "--tool-command <command>", "--prompt <text>", "--initial-input-file <path|->", "--from-json <path|->", "--source <user|agent>", "--pinned", "--no-pinned", "--no-associate", "--no-focus", "--focus", "--wait-ready", "--ready-timeout-ms <ms>", "--concurrency <count>", "--yes", "--json"];
             }, {
                 readonly name: "panes archive";
-                readonly summary: "Archive a Pane exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.";
-                readonly arguments: readonly ["--pane <pane-id>", "--source <user|agent>", "--force", "--dry-run", "--yes", "--json"];
+                readonly summary: "Archive a Pane exactly like the UI Archive action, including safe removal of its Pane-managed git worktree, or archive every merged Pane in a Session.";
+                readonly arguments: readonly ["--pane <pane-id>", "--session <id|name>", "--merged", "--source <user|agent>", "--force", "--remove-worktree", "--dry-run", "--yes", "--json"];
             }, {
                 readonly name: "panes pin";
                 readonly summary: "Declaratively pin a Pane (the Pane UI's favorite/pin star) without changing focus.";
@@ -3841,8 +4572,8 @@ export declare const RUNPANE_CONTRACT: {
                 readonly arguments: readonly ["--panel <panel-id>", "--for <condition>", "--contains <text>", "--timeout-ms <ms>", "--interval-ms <ms>", "--json", "--pane-dir <path>"];
             }, {
                 readonly name: "watch";
-                readonly summary: "Wait for workspace transitions (READY, BLOCKED, IDLE, STUCK, NEW, GONE, EXIT) from the daemon journal without polling; responsive by default, with opt-in cadence flags for expensive consumers.";
-                readonly arguments: readonly ["--follow", "--self-test", "--kinds <kind,...>", "--settle <ms>", "--blocked-settle <ms>", "--min-interval <ms>", "--idle-backoff", "--json"];
+                readonly summary: "Wait for workspace transitions (READY, BLOCKED, IDLE, STUCK, NEW, GONE, EXIT, JOINED, LEFT, PR) from the daemon journal without polling; responsive by default, with opt-in cadence flags for expensive consumers.";
+                readonly arguments: readonly ["--follow", "--session <id|name>", "--self-test", "--kinds <kind,...>", "--settle <ms>", "--blocked-settle <ms>", "--min-interval <ms>", "--idle-backoff", "--json"];
             }];
         };
         readonly commands: {
@@ -3935,6 +4666,11 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path>";
                     readonly required: false;
                     readonly description: "Ignored for version; retained only for parser compatibility.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Accepted and ignored, so one --pane-dir can be passed to every runpane command.";
                 }];
                 readonly examples: readonly ["runpane version", "runpane --version"];
                 readonly notes: readonly [];
@@ -4037,8 +4773,8 @@ export declare const RUNPANE_CONTRACT: {
                     readonly description: "Print machine-readable output.";
                 }];
                 readonly examples: readonly ["runpane agent-context", "runpane agent-context --command \"panes create\" --json"];
-                readonly jsonSchemas: readonly ["agentContextBriefResult", "agentContextCommandResult"];
-                readonly notes: readonly ["Default output is brief so AGENTS.md can point here without bloating context.", "`--command` accepts canonical spaced names and common copied forms, including `panes.create` and `runpane panes create`."];
+                readonly jsonSchemas: readonly ["agentContextBriefResult", "agentContextCommandResult", "agentContextUnknownCommandError"];
+                readonly notes: readonly ["Default output is brief so AGENTS.md can point here without bloating context.", "`--command` accepts canonical spaced names and common copied forms, including `panes.create` and `runpane panes create`.", "An unknown `--command` exits 2. With `--json` it prints `{ ok: false, code: \"unknown_command\", message, candidates }` on stdout, where `candidates` lists the closest command names first; without `--json` the same candidates go to stderr.", "`--pane-dir <path>` is accepted and ignored, so one `--pane-dir` can be passed to every runpane command."];
             };
             readonly mcp: {
                 readonly name: "mcp";
@@ -4140,7 +4876,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane panes list --repo active --json"];
                 readonly jsonSchemas: readonly ["paneListResult"];
-                readonly notes: readonly ["Without --repo, this lists sessions across saved Pane repositories."];
+                readonly notes: readonly ["Without --repo, this lists sessions across saved Pane repositories.", "`status` is `running` while any terminal panel is live, otherwise the stored lifecycle value. `agentState` is the most urgent state of the live agent panels: `blocked`, `working`, `ready`, or `none`. `agentStatus` (`active`/`idle`) is kept for older clients."];
             };
             readonly "panes cost": {
                 readonly name: "panes cost";
@@ -4188,16 +4924,41 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<name>";
                     readonly required: true;
                     readonly description: "Pane/session name.";
+                }, {
+                    readonly name: "--base-branch";
+                    readonly value: "<branch>";
+                    readonly required: false;
+                    readonly description: "Branch the new worktree from this ref (for example origin/main or release/2.4) instead of the repository default.";
+                }, {
+                    readonly name: "--worktree-name";
+                    readonly value: "<name>";
+                    readonly required: false;
+                    readonly description: "Worktree and branch name; defaults to --name. Characters outside [a-z0-9-] are removed.";
                 }, {
                     readonly name: "--agent";
                     readonly value: "<codex|claude|cursor>";
                     readonly required: false;
-                    readonly description: "Built-in agent terminal template to open.";
+                    readonly description: "Built-in agent terminal template to open. With --tool-command, the agent that command runs.";
                 }, {
                     readonly name: "--tool-command";
                     readonly value: "<command>";
                     readonly required: false;
                     readonly description: "Custom terminal command to run instead of a built-in agent.";
+                }, {
+                    readonly name: "--base-branch";
+                    readonly value: "<ref>";
+                    readonly required: false;
+                    readonly description: "Ref to branch from, such as origin/main or release/foo. --base is an alias.";
+                }, {
+                    readonly name: "--branch";
+                    readonly value: "<name>";
+                    readonly required: false;
+                    readonly description: "Exact new branch name, slashes included (for example agents/w5a). Fails if the branch exists; never renamed to be unique. Defaults to the worktree name.";
+                }, {
+                    readonly name: "--worktree-name";
+                    readonly value: "<name>";
+                    readonly required: false;
+                    readonly description: "Worktree directory name; defaults to --name.";
                 }, {
                     readonly name: "--prompt";
                     readonly value: "<text>";
@@ -4207,7 +4968,11 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--initial-input-file";
                     readonly value: "<path|->";
                     readonly required: false;
-                    readonly description: "Read initial input from a file or stdin.";
+                    readonly description: "Read initial input from a file or stdin. --prompt-file is an alias.";
+                }, {
+                    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 name: "--from-json";
                     readonly value: "<path|->";
@@ -4264,10 +5029,15 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<count>";
                     readonly required: false;
                     readonly description: "Accepted for compatibility. Pane currently serializes multi-pane session creation so queued jobs do not time out before starting.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
                 }];
-                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 --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"];
+                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.", "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.", "Use `panels create` instead when a reviewer/helper should share an existing Pane's worktree.", "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.", "With --wait-ready, verifiedSubmitted is earned from delivery evidence; routing initial input alone does not imply verified submission.", "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 to verify that an agent terminal started instead of only creating a pane.", "If readiness returns blocked, inspect blocked.suggestedCommand rather than guessing which prompt to answer."];
+                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.", "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.", "Use `panels create` instead when a reviewer/helper should share an existing Pane's worktree.", "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.", "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 to verify that an agent terminal started 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."];
             };
             readonly "panes adopt": {
                 readonly name: "panes adopt";
@@ -4293,8 +5063,13 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--agent";
                     readonly value: "<codex|claude|cursor>";
-                    readonly required: true;
-                    readonly description: "Agent whose terminal to create.";
+                    readonly required: false;
+                    readonly description: "Agent whose terminal to create; with --tool-command, the agent that command runs.";
+                }, {
+                    readonly name: "--tool-command";
+                    readonly value: "<command>";
+                    readonly required: false;
+                    readonly description: "Custom command to stage or launch instead of a built-in agent, such as a wrapper that runs one.";
                 }, {
                     readonly name: "--resume";
                     readonly value: "<id>";
@@ -4308,7 +5083,26 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--launch";
                     readonly required: false;
-                    readonly description: "Run the resume command immediately.";
+                    readonly description: "Run the agent (or its resume command) immediately.";
+                }, {
+                    readonly name: "--prompt";
+                    readonly value: "<text>";
+                    readonly required: false;
+                    readonly description: "Alias for --initial-input; sent once the launched agent is ready. Requires --launch.";
+                }, {
+                    readonly name: "--prompt-file";
+                    readonly value: "<path|->";
+                    readonly required: false;
+                    readonly description: "Alias for --initial-input-file; read the prompt from a file or stdin. Requires --launch.";
+                }, {
+                    readonly name: "--wait-ready";
+                    readonly required: false;
+                    readonly description: "Wait for the launched agent to be ready and the prompt submitted before returning. Requires --launch.";
+                }, {
+                    readonly name: "--ready-timeout-ms";
+                    readonly value: "<ms>";
+                    readonly required: false;
+                    readonly description: "Readiness timeout; defaults to 30000.";
                 }, {
                     readonly name: "--no-pinned";
                     readonly required: false;
@@ -4329,22 +5123,27 @@ export declare const RUNPANE_CONTRACT: {
                     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 panes adopt --repo active --path /path/to/worktree --name imported --agent codex --resume <id> --yes --json"];
+                readonly examples: readonly ["runpane panes adopt --repo active --path /path/to/worktree --name imported --agent codex --resume <id> --yes --json", "runpane panes adopt --repo active --path /path/to/worktree --name imported --tool-command \"agent-farm run free-range\" --agent claude --launch --yes --json", "runpane panes adopt --repo active --path /path/to/worktree --name imported --agent claude --launch --prompt-file prompt.md --wait-ready --yes --json"];
                 readonly jsonSchemas: readonly ["paneCreateResult"];
-                readonly notes: readonly ["The resume command is staged without Enter unless --launch is passed.", "Pane never removes an externally owned worktree."];
+                readonly notes: readonly ["The resume command is staged without Enter unless --launch is passed.", "Archiving never deletes an adopted worktree unless `runpane panes archive --remove-worktree` is used.", "One of --agent or --tool-command is required.", "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.", "--resume needs a built-in agent command; a wrapper command resumes its own way.", "The adopted Pane reports `status: running` in `panes list` while its terminal is live.", "A prompt (--prompt, --initial-input, --prompt-file, --initial-input-file) or --wait-ready needs --launch; without it adopt fails instead of dropping the prompt.", "With --launch the result carries the same readiness, initialInput, and nextCommand fields as panes create. With --resume the prompt goes to the resumed conversation's composer once the agent is ready.", "To start new work on a named branch, prefer `panes create --base <ref> --branch <name>` over `git worktree add` plus adopt."];
             };
             readonly "panes archive": {
                 readonly name: "panes archive";
-                readonly summary: "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.";
-                readonly details: "Use this to close out a Pane once its PR has merged. The safety check refreshes the configured upstream before comparing it to HEAD and includes exact unpushed commit IDs and subjects. Refuses unsafe archive operations unless --force is used. Use --dry-run to inspect the same evidence without mutating Pane state.";
+                readonly summary: "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree, or archive every merged Pane in a Session.";
+                readonly details: "Use this to close out a Pane once its PR has merged. The safety check refreshes the configured upstream before comparing it to HEAD and includes exact unpushed commit IDs and subjects. When the branch has no upstream or its upstream is gone (GitHub deletes merged branches), a merged pull request whose head is HEAD counts as pushed, so squash-merged branches archive without --force. Refuses unsafe archive operations unless --force is used. Use --dry-run to inspect the same evidence without mutating Pane state. Use --session <id|name> --merged to close out every finished Pane of a Session at once.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
                 readonly arguments: readonly [{
                     readonly name: "--pane";
                     readonly value: "<pane-id>";
-                    readonly required: true;
-                    readonly description: "Pane/session id to archive.";
+                    readonly required: false;
+                    readonly description: "Pane/session id to archive. Required unless --session is used.";
                 }, {
                     readonly name: "--source";
                     readonly value: "<user|agent>";
@@ -4354,6 +5153,19 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--force";
                     readonly required: false;
                     readonly description: "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes.";
+                }, {
+                    readonly name: "--remove-worktree";
+                    readonly required: false;
+                    readonly description: "Also check and remove an adopted Pane's worktree. Pane-managed worktrees are always removed; the local branch is always kept.";
+                }, {
+                    readonly name: "--session";
+                    readonly value: "<id|name>";
+                    readonly required: false;
+                    readonly description: "Archive the Panes associated with this named Session instead of one Pane. Requires --merged.";
+                }, {
+                    readonly name: "--merged";
+                    readonly required: false;
+                    readonly description: "With --session, archive only Panes that are clean and pushed, or merged via a pull request; skip the rest with a reason.";
                 }, {
                     readonly name: "--yes";
                     readonly required: false;
@@ -4365,11 +5177,16 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--json";
                     readonly required: false;
-                    readonly description: "Print machine-readable output.";
+                    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 panes archive --pane <pane-id> --source agent --yes --json", "runpane panes archive --pane <pane-id> --dry-run --json", "runpane panes archive --pane <pane-id> --force --yes --json"];
-                readonly jsonSchemas: readonly ["paneArchiveRequest", "paneArchiveResult"];
-                readonly notes: readonly ["If the result has ok:false with a blocked field, the pane was NOT archived; inspect blocked.code and rerun with --force if discarding the flagged work is intentional.", "Inspect safetyCheck.unpushedCommitDetails for exact commit IDs and subjects; upstreamRefreshed confirms the tracking ref was refreshed first.", "A --dry-run result sets dryRun:true and wouldArchive without deleting the Pane or its worktree.", "A successful archive waits for the Pane-managed worktree to be removed before returning; check worktreeCleanup in the result for the final outcome.", "Archiving a main-repo Pane (no Pane-managed worktree) always succeeds immediately since nothing is deleted from disk.", "Undo an archive with `runpane panes restore --pane <pane-id> --yes`, which recreates the worktree. `runpane links create --pane <pane-id>` gives the user a link to review the Pane first."];
+                readonly examples: readonly ["runpane panes archive --pane <pane-id> --source agent --yes --json", "runpane panes archive --pane <pane-id> --dry-run --json", "runpane panes archive --pane <pane-id> --remove-worktree --yes --json", "runpane panes archive --session <id|name> --merged --dry-run --json", "runpane panes archive --session <id|name> --merged --remove-worktree --yes --json", "runpane panes archive --pane <pane-id> --force --yes --json"];
+                readonly jsonSchemas: readonly ["paneArchiveRequest", "paneArchiveBulkRequest", "paneArchiveResult", "paneArchiveBulkResult"];
+                readonly notes: readonly ["If the result has ok:false with a blocked field, the pane was NOT archived; inspect blocked.code and rerun with --force if discarding the flagged work is intentional.", "Inspect safetyCheck.unpushedCommitDetails for exact commit IDs and subjects; upstreamRefreshed confirms the tracking ref was refreshed first.", "A --dry-run result sets dryRun:true and wouldArchive without deleting the Pane or its worktree.", "A successful archive reports worktreeCleanup `completed` once the worktree is gone from its path and from git. trashDeletion `pending` means a large worktree (for example one with node_modules) is still being deleted from .git/pane-trash in the background; that is still ok:true. `timeout` (also ok:true) means removal is still running; only `failed` sets ok:false.", "safetyCheck.mergedViaPr names the merged PR whose head is HEAD; it needs an authenticated `gh`. Without it, a squash-merged branch whose remote branch was deleted reports unpushed-commits.", "An adopted Pane (panes adopt) keeps its worktree unless --remove-worktree is passed. `panes restore` does not recreate a removed adopted worktree; the local branch is kept, so `git worktree add <path> <branch>` brings it back.", "With --session --merged, each item has outcome archived, would-archive (dry run), skipped (with skipped.code and skipped.message), or failed.", "Archiving a main-repo Pane (no Pane-managed worktree) always succeeds immediately since nothing is deleted from disk.", "Undo an archive with `runpane panes restore --pane <pane-id> --yes`, which recreates the worktree. `runpane links create --pane <pane-id>` gives the user a link to review the Pane first.", "When the safety check is skipped, `safetyCheck.reason` says why: `external-worktree` (an adopted Pane whose worktree Pane does not own), `main-repo`, `missing-project-context`, or `git-error`. `worktreeWillRemain: true` means archiving leaves the worktree on disk."];
             };
             readonly "panes pin": {
                 readonly name: "panes pin";
@@ -4394,6 +5211,11 @@ export declare const RUNPANE_CONTRACT: {
                     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 panes pin --pane <pane-id> --yes --json", "runpane panes pin --pane <pane-id> --dry-run --json"];
                 readonly jsonSchemas: readonly ["panePinRequest", "panePinResult"];
@@ -4422,6 +5244,11 @@ export declare const RUNPANE_CONTRACT: {
                     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 panes unpin --pane <pane-id> --yes --json", "runpane panes unpin --pane <pane-id> --dry-run --json"];
                 readonly jsonSchemas: readonly ["panePinRequest", "panePinResult"];
@@ -4455,6 +5282,11 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--json";
                     readonly required: false;
                     readonly description: "Print machine-readable output including the updated pane.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
                 }];
                 readonly examples: readonly ["runpane panes rename --pane <pane-id> --name issue-393 --yes --json", "runpane panes rename --pane <pane-id> --name issue-393 --dry-run --json"];
                 readonly jsonSchemas: readonly ["paneRenameRequest", "paneRenameResult"];
@@ -4489,6 +5321,11 @@ export declare const RUNPANE_CONTRACT: {
                     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 panes focus --pane <pane-id> --source user --yes --json", "runpane panes focus --pane <pane-id> --panel <panel-id> --source user --yes --json"];
                 readonly jsonSchemas: readonly ["paneFocusRequest", "paneFocusResult"];
@@ -4517,7 +5354,7 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane panels list --pane <pane-id> --json"];
                 readonly jsonSchemas: readonly ["panelListResult"];
-                readonly notes: readonly ["The ids returned here are stable inputs for `panels output` and `panels input`."];
+                readonly notes: readonly ["The ids returned here are stable inputs for `panels output` and `panels input`.", "`agentType` is the agent Pane treats the panel as; `agentDetection` says how it knows (`declared`, `command`, `process`, or `screen`), and `launchCommand` is the command the panel was launched with."];
             };
             readonly "panels output": {
                 readonly name: "panels output";
@@ -4651,12 +5488,12 @@ export declare const RUNPANE_CONTRACT: {
                 }];
                 readonly examples: readonly ["runpane panels screen --panel <panel-id> --limit 80 --json"];
                 readonly jsonSchemas: readonly ["panelScreenResult"];
-                readonly notes: readonly ["Use this before `panels output` when an agent only needs the latest visible/current state.", "The composer object reports whether a Claude or Codex composer is present and whether it holds undelivered text. Claude's dim placeholder suggestion does not count as undelivered text.", "If hasMore is true and context is missing, rerun with a larger --limit or use `panels output`."];
+                readonly notes: readonly ["Use this before `panels output` when an agent only needs the latest visible/current state.", "The composer object reports whether a Claude or Codex composer is present and whether it holds undelivered text. Placeholder and suggestion text (drawn dim or grey, such as Claude's suggested next prompt) does not count as undelivered text; `composer.ghostText` carries it, and text output marks its line with `⟨suggestion⟩`.", "If hasMore is true and context is missing, rerun with a larger --limit or use `panels output`."];
             };
             readonly "panels submit": {
                 readonly name: "panels submit";
                 readonly summary: "Send and submit text to a terminal panel, including idle agent composers.";
-                readonly details: "Use this for ordinary interactive submissions. For Claude, Pane waits for the composer to appear and show the staged text, then sends Enter on its own and verifies that the composer cleared; Claude keeps an Enter that arrives together with the text as a newline. For an idle Codex composer, Pane stages the text, waits for Codex paste handling, sends the Codex submit sequence, and verifies that the turn started when visible evidence is available. Other terminals receive a normalized CR Enter. Exact byte workflows remain on `panels input`.";
+                readonly details: "Use this for ordinary interactive submissions. For Claude, Pane waits for the composer to appear and show the staged text, then sends Enter on its own and verifies that the composer cleared; Claude keeps an Enter that arrives together with the text as a newline. For a Codex composer, Pane stages the text, waits for paste handling, then queues with Tab while working or submits with Enter when ready, and verifies delivery when visible evidence is available. Wrapper-launched agents are handled the same way once Pane knows the agent (declared, from the foreground process, or from the screen). A Claude or Codex panel with no composer on screen gets nothing: 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. Other terminals receive a normalized CR Enter. Exact byte workflows remain on `panels input`.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
                 readonly arguments: readonly [{
@@ -4674,6 +5511,10 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path|->";
                     readonly required: false;
                     readonly description: "Read text from a file or stdin before Enter.";
+                }, {
+                    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 name: "--yes";
                     readonly required: false;
@@ -4688,9 +5529,9 @@ export declare const RUNPANE_CONTRACT: {
                     readonly required: false;
                     readonly description: "Connect to a specific Pane data directory.";
                 }];
-                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"];
+                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"];
                 readonly jsonSchemas: readonly ["panelSubmitRequest", "panelSubmitResult"];
-                readonly notes: readonly ["The response includes sequenceName, verifiedSubmitted, and nextCommand. If ok is false, inspect blocked and do not assume the turn started.", "Do not follow `panels submit` with `panels submit-composer`; Claude and idle Codex composer submission is handled atomically.", "Use `panels input` for Ctrl-C, escape sequences, or any workflow requiring exact bytes."];
+                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."];
             };
             readonly "panels wait": {
                 readonly name: "panels wait";
@@ -4737,6 +5578,36 @@ export declare const RUNPANE_CONTRACT: {
                 readonly jsonSchemas: readonly ["panelWaitResult"];
                 readonly notes: readonly ["If blocked is present, do not assume success. Use blocked.suggestedCommand or inspect `panels screen`.", "The default timeout and screen are intentionally small for agent context safety."];
             };
+            readonly "panels last-message": {
+                readonly name: "panels last-message";
+                readonly summary: "Read an agent's last reply from its transcript, without scraping the screen.";
+                readonly details: "Use this when a worker is READY and you need what it said, such as its PR number or result. It reads the Claude or Codex transcript Pane found for the panel and never falls back to the screen.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: false;
+                readonly arguments: readonly [{
+                    readonly name: "--panel";
+                    readonly value: "<panel-id>";
+                    readonly required: true;
+                    readonly description: "Agent panel id.";
+                }, {
+                    readonly name: "--limit";
+                    readonly value: "<count>";
+                    readonly required: false;
+                    readonly description: "Maximum characters to return; defaults to 20000. The end of the reply is kept.";
+                }, {
+                    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 panels last-message --panel <panel-id> --json"];
+                readonly jsonSchemas: readonly ["panelLastMessageResult"];
+                readonly notes: readonly ["Without a transcript (a shell panel, another agent, or no reply yet) the result is `{ ok: false, reason: \"transcript-unavailable\" }` and the command exits 1. Use `panels screen` then.", "A worker that ran `runpane report` already handed back its state, PR, head, and summary; read those with `agents status` before reading the whole reply."];
+            };
             readonly "panels create": {
                 readonly name: "panels create";
                 readonly summary: "Create a reviewer/helper terminal tab inside an existing Pane.";
@@ -4752,7 +5623,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--agent";
                     readonly value: "<codex|claude|cursor>";
                     readonly required: false;
-                    readonly description: "Built-in agent command template to launch.";
+                    readonly description: "Built-in agent command template to launch. With --tool-command, the agent that command runs.";
                 }, {
                     readonly name: "--tool-command";
                     readonly value: "<command>";
@@ -4773,6 +5644,10 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<path|->";
                     readonly required: false;
                     readonly description: "Read initial input from a file or stdin.";
+                }, {
+                    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 name: "--source";
                     readonly value: "<user|agent>";
@@ -4803,10 +5678,15 @@ export declare const RUNPANE_CONTRACT: {
                     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 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"];
+                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"];
-                readonly notes: readonly ["Use this for same-pane reviewer loops after PR creation/testing.", "Panels share the existing Pane's worktree and branch.", "`panels create` is for visible helper/reviewer tabs, not the agent's default private delegation mechanism.", "For agent-created panels, prefer --source agent or --no-focus to avoid stealing focus from the user or implementation tab."];
+                readonly notes: readonly ["Use this for same-pane reviewer loops after PR creation/testing.", "Panels share the existing Pane's worktree and branch.", "`panels create` is for visible helper/reviewer tabs, not the agent's default private delegation mechanism.", "For agent-created panels, prefer --source agent or --no-focus to avoid stealing focus from the user or implementation tab.", "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."];
             };
             readonly "panels submit-composer": {
                 readonly name: "panels submit-composer";
@@ -4832,10 +5712,15 @@ export declare const RUNPANE_CONTRACT: {
                     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 panels submit-composer --panel <codex-panel-id> --strategy auto --yes --json", "runpane panels submit-composer --panel <panel-id> --strategy enter --yes --json"];
                 readonly jsonSchemas: readonly ["panelSubmitComposerRequest", "panelSubmitComposerResult"];
-                readonly notes: readonly ["Use `panels input` or `panels submit` to write prompt text first; this command only submits the current composer.", "Use --strategy auto for agent workflows; explicit strategies are diagnostic escape hatches.", "The JSON result includes sequenceName and verifiedSubmitted. If ok is false, follow blocked.suggestedCommand instead of assuming submission happened."];
+                readonly notes: readonly ["Use `panels input` or `panels submit` to write prompt text first; this command only submits the current composer.", "Use --strategy auto for agent workflows; explicit strategies are diagnostic escape hatches.", "The JSON result includes sequenceName, verifiedSubmitted and, for Claude and Codex, delivery (`taken`, `queued`, `in-composer` or `unknown`, with `transcript` or `screen` evidence). If ok is false, follow blocked.suggestedCommand instead of assuming submission happened.", "With `--strategy auto`, if the staged text is still visible in the composer after the first attempt, Pane retries once and checks again: Tab for working Codex, Enter otherwise. It never retries an empty composer."];
             };
             readonly "workspace state": {
                 readonly name: "workspace state";
@@ -4852,6 +5737,11 @@ export declare const RUNPANE_CONTRACT: {
                     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 workspace state --json"];
                 readonly notes: readonly ["The response carries the daemon epoch and current journal generation."];
@@ -4866,7 +5756,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--as";
                     readonly value: "<consumer-name>";
                     readonly required: false;
-                    readonly description: "Use a persisted named cursor (at-least-once delivery). Default: PANE_PANEL_ID under --follow when set, otherwise anonymous.";
+                    readonly description: "Use a persisted named cursor (at-least-once delivery): 1-128 letters, numbers, dots, underscores, or hyphens (daemons before this release accept 64). Default under --follow: session-<uuid> with --session (session-<name> for a name; shortened to session-<sha256 prefix> when longer than 64 characters), else PANE_PANEL_ID when set, shortened to panel-<sha256 prefix> when it is longer than 64 characters; otherwise anonymous.";
                 }, {
                     readonly name: "--since";
                     readonly value: "<generation>";
@@ -4890,7 +5780,7 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--heartbeat";
                     readonly value: "<seconds>";
                     readonly required: false;
-                    readonly description: "Healthy-silence bound; a HEARTBEAT line proves the watcher is alive. Default 60 under --follow, 0 otherwise. Filter it out of any monitor that wakes an agent.";
+                    readonly description: "Healthy-silence bound; a HEARTBEAT line proves the watcher is alive. Default 60 under --follow, 0 otherwise. Any monitor that wakes an agent should pass --quiet, which drops it.";
                 }, {
                     readonly name: "--idle-after";
                     readonly value: "<milliseconds>";
@@ -4900,17 +5790,17 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--settle";
                     readonly value: "<milliseconds>";
                     readonly required: false;
-                    readonly description: "Opt-in (follow only): emit READY only after the panel stays idle this long; a BUSY, BLOCKED, UNKNOWN, EXIT, or GONE inside the window cancels it silently. Default 0. Use when a pane flips idle/working while it waits on subagents; the orchestrator value is 180000.";
+                    readonly description: "Opt-in (follow only): emit READY only after the panel stays idle this long; a BUSY, BLOCKED, UNKNOWN, EXIT, or GONE inside the window cancels it silently. Default 0. Use when a pane flips idle/working while it waits on subagents; the unattended orchestrator value is 180000, the user-present value 60000.";
                 }, {
                     readonly name: "--blocked-settle";
                     readonly value: "<milliseconds>";
                     readonly required: false;
-                    readonly description: "Opt-in (follow only): emit BLOCKED only after this window; an in-pane answer inside it cancels the line. Default 0. The orchestrator value is 30000.";
+                    readonly description: "Opt-in (follow only): emit BLOCKED only after this window; an in-pane answer inside it cancels the line. Default 0. The unattended orchestrator value is 30000, the user-present value 15000.";
                 }, {
                     readonly name: "--min-interval";
                     readonly value: "<milliseconds>";
                     readonly required: false;
-                    readonly description: "Opt-in (follow only): hold READY, IDLE, NEW, GONE, EXIT, and UNKNOWN lines and flush them together at most once per interval; BLOCKED bypasses it and carries the held lines with it. Default 0. The orchestrator value is 600000.";
+                    readonly description: "Opt-in (follow only): hold READY, IDLE, NEW, GONE, EXIT, and UNKNOWN lines and flush them together at most once per interval; BLOCKED, REPORT, pr.conflicted, and failed pr.checks bypass it and carry the held lines with them. Default 0. The unattended orchestrator value is 600000, the user-present value 120000.";
                 }, {
                     readonly name: "--idle-backoff";
                     readonly required: false;
@@ -4919,12 +5809,17 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--kinds";
                     readonly required: false;
                     readonly value: "<kind,...>";
-                    readonly description: "Limit event kinds: agent.ready, agent.busy, agent.blocked, agent.unknown, agent.idle, pane.created, pane.gone, panel.exited. Default all. Drop agent.busy for any consumer that acts on lines; BUSY carries no action.";
+                    readonly description: "Limit event kinds: agent.ready, agent.busy, agent.blocked, agent.unknown, agent.idle, pane.created, pane.gone, panel.exited, agent.report, pane.associated, pane.detached, pr.conflicted, pr.checks, pr.merged. agent.report arrives only when listed explicitly. Default all, except that pane.associated, pane.detached, and the pr.* kinds arrive only when listed here or implied by --session. Drop agent.busy for any consumer that acts on lines; BUSY carries no action.";
                 }, {
                     readonly name: "--pane";
                     readonly required: false;
                     readonly value: "<pane-id>";
-                    readonly description: "Limit to a Pane; repeatable. Default all managed panes.";
+                    readonly description: "Limit to a Pane; repeatable. Default all managed panes. Cannot be combined with --session.";
+                }, {
+                    readonly name: "--session";
+                    readonly required: false;
+                    readonly value: "<id|name>";
+                    readonly description: "Follow every Pane associated with a named Session (id or exact name). The daemon re-reads membership on every read, so a Pane associated after arming is included and a detached or archived Pane drops out without a re-arm. The Session's own orchestrator panels are never reported. Cannot be combined with --pane or --all-managed; an unknown Session fails.";
                 }, {
                     readonly name: "--exclude-pane";
                     readonly required: false;
@@ -4947,7 +5842,7 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--all-managed";
                     readonly required: false;
-                    readonly description: "Explicit spelling for the all-managed default scope.";
+                    readonly description: "Explicit spelling of the default scope: every non-archived, non-hidden managed Pane. Cannot be combined with --pane.";
                 }, {
                     readonly name: "--include-shells";
                     readonly required: false;
@@ -4969,22 +5864,36 @@ export declare const RUNPANE_CONTRACT: {
                 }, {
                     readonly name: "--include-held-input";
                     readonly required: false;
-                    readonly description: "Include up to 120 characters of unsubmitted composer text in JSON entries. Default off (presence only).";
+                    readonly description: "Include up to 120 characters of unsubmitted composer text in JSON entries. Default off: under --follow, JSON entries carry only heldInputPresent: true.";
                 }, {
                     readonly name: "--no-held-input";
                     readonly required: false;
-                    readonly description: "Disable redacted STUCK detection in lines follow mode.";
+                    readonly description: "Disable redacted held-input detection under --follow: no STUCK lines, and no heldInputPresent in JSON.";
                 }, {
                     readonly name: "--self-test";
                     readonly required: false;
                     readonly description: "Probe the watch path anonymously without advancing a named cursor; run it before arming --follow.";
+                }, {
+                    readonly name: "--quiet";
+                    readonly required: false;
+                    readonly description: "Drop the control lines that only prove liveness: WATCH OK, HEARTBEAT, and WATCH RECONNECTED (_ok, _heartbeat, _reconnected in JSON). WATCH ERROR/_error, RESET/_reset, and DROPPED/_dropped always print, and --self-test still prints its WATCH OK result. Alias: --no-control-lines.";
                 }, {
                     readonly name: "--json";
                     readonly required: false;
                     readonly description: "Emit structured NDJSON; held-input content remains opt-in.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }, {
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
                 }];
-                readonly examples: readonly ["runpane watch --self-test", "runpane watch --follow", "runpane watch --as monitor --follow --json", "runpane watch --follow --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff"];
-                readonly notes: readonly ["Defaults stay responsive: no settle, no batching, all kinds, IDLE every --idle-after. Cadence flags are opt-in for expensive consumers and require --follow.", "Recommended orchestrator invocation (what Pane Chat arms automatically): runpane watch --self-test, then runpane watch --follow --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff. Budget: about 6 wake-ups per active pane per hour worst case, usually 1-3.", "BUSY carries no action; drop it with --kinds. HEARTBEAT is client-side proof of life, is never shaped by cadence flags, and should be filtered out of any monitor that wakes an agent.", "STUCK means real unsubmitted composer text. An agent prompt suggestion (for example a grey Try \"...\" hint) never counts.", "Dead watch: judge death by a non-zero exit or a WATCH ERROR line, not by silence. Re-arm once; if it dies again, file runpane doctor --report.", "Cadence state is held per named consumer; an anonymous --follow with a cadence flag names itself follow-<pid>. 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."];
+                readonly examples: readonly ["runpane watch --self-test", "runpane watch --follow", "runpane watch --as monitor --follow --quiet --json", "runpane watch --follow --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "runpane watch --follow --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 60000 --blocked-settle 15000 --min-interval 120000", "runpane watch --session <id|name> --follow --quiet --json --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff", "runpane watch --session <id|name> --follow --quiet --json --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone,pane.associated,pane.detached,pr.conflicted,pr.checks,pr.merged --settle 60000 --blocked-settle 15000 --min-interval 120000"];
+                readonly notes: readonly ["Defaults stay responsive: no settle, no batching, all kinds, IDLE every --idle-after. Cadence flags are opt-in for expensive consumers and require --follow.", "Unattended profile (what Pane Chat arms automatically, for overnight or background runs): runpane watch --self-test, then runpane watch --follow --quiet --kinds agent.ready,agent.blocked,agent.idle,panel.exited,pane.gone --settle 180000 --blocked-settle 30000 --min-interval 600000 --idle-backoff. Budget: about 6 wake-ups per active pane per hour worst case, usually 1-3; READY can arrive up to about 13 minutes after the turn ended.", "User-present profile (a person is waiting on the result): the same command with --settle 60000 --blocked-settle 15000 --min-interval 120000 and no --idle-backoff. READY arrives within about 3 minutes of the turn ending.", "BUSY carries no action; drop it with --kinds. HEARTBEAT is client-side proof of life and is never shaped by cadence flags; pass --quiet for any monitor that wakes an agent.", "STUCK means real unsubmitted composer text. An agent prompt suggestion (for example a grey Try \"...\" hint) never counts.", "Dead watch: judge death by a non-zero exit or a WATCH ERROR line, not by silence. Re-arm once; if it dies again, file runpane doctor --report.", "Cadence state is held per named consumer; an anonymous --follow with a cadence flag names itself follow-<pid>. 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. JSON kinds and their lines-format text: _ok (WATCH OK, once when armed), _heartbeat (HEARTBEAT, every --heartbeat seconds), _reconnected (WATCH RECONNECTED, after a retried daemon error), _error (WATCH ERROR, a daemon error; the process exits 2 unless --follow retries it), _reset (RESET, the journal restarted or the cursor fell behind; a fresh baseline follows), and _dropped (DROPPED, entries lost to journal truncation). --quiet drops _ok, _heartbeat, and _reconnected; _error, _reset, and _dropped always print.", "Under --follow, JSON entries for panels holding unsubmitted composer text carry heldInputPresent: true, the JSON equivalent of the STUCK line. --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 events (decision D7): about every 3 minutes (jittered) the daemon visits each Pane associated with a live Session (none: no gh at all), finds its PR by branch when no open PR is known yet (gh pr list --head, so unwatched workers' new and reopened PRs are found), runs gh pr view on an open PR, and appends pr.conflicted (PR <pane-name> pane <pane-id> #<number> CONFLICTED: the PR now conflicts with its base), pr.checks (... CHECKS PASSED, or CHECKS FAILED <up to five names>: every check on the head commit finished), and pr.merged (... MERGED). Entries carry pr: {number, url, headOid}, plus checks and failingChecks for pr.checks. They fire on transitions only: the first poll of a PR after the daemon starts only records its state, so re-check conflicts after a restart with gh pr view. pr.conflicted and failed pr.checks bypass --min-interval like BLOCKED. Like JOINED/LEFT, they reach a consumer only under --session or when --kinds lists them. Without gh, or while it is signed out or rate limited, polling backs off (up to an hour) and no PR entries arrive.", "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 opt-in: only a consumer that lists it in --kinds receives it. It bypasses --min-interval, and orchestrators treat it as the completion signal; a READY without a report means look, and maybe nudge."];
             };
             readonly "panes git-status": {
                 readonly name: "panes git-status";
@@ -5681,6 +6590,10 @@ export declare const RUNPANE_CONTRACT: {
                     readonly value: "<message>";
                     readonly required: true;
                     readonly description: "The message to submit.";
+                }, {
+                    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 name: "--yes";
                     readonly required: false;
@@ -5695,9 +6608,69 @@ export declare const RUNPANE_CONTRACT: {
                     readonly required: false;
                     readonly description: "Connect to a specific Pane data directory.";
                 }];
-                readonly examples: readonly ["runpane agents send --pane <pane-id> --text \"Also add a test\" --yes --json"];
+                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 only when Pane saw the message leave the composer.", "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`."];
+                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 report: {
+                readonly name: "report";
+                readonly summary: "Hand back a worker's structured report: state, PR, head commit, summary, and the question when blocked.";
+                readonly details: "Run this as a delegated worker when you finish, fail, or get blocked, as the last step of your task. The orchestrator receives it as an agent.report watch event and treats it as the completion signal.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [{
+                    readonly name: "--state";
+                    readonly value: "<ready|blocked|failed|done>";
+                    readonly required: true;
+                    readonly description: "ready: work is ready for review; done: finished with nothing to review; blocked: needs an answer; failed: could not finish.";
+                }, {
+                    readonly name: "--pr";
+                    readonly value: "<number>";
+                    readonly required: false;
+                    readonly description: "Pull request number.";
+                }, {
+                    readonly name: "--head";
+                    readonly value: "<sha>";
+                    readonly required: false;
+                    readonly description: "Head commit the report is about, 7-40 hex characters.";
+                }, {
+                    readonly name: "--summary";
+                    readonly value: "<text>";
+                    readonly required: false;
+                    readonly description: "Summary text; up to 16,000 characters are kept.";
+                }, {
+                    readonly name: "--summary-file";
+                    readonly value: "<path|->";
+                    readonly required: false;
+                    readonly description: "Read the summary from a file or stdin; the absolute path is kept as summaryPath.";
+                }, {
+                    readonly name: "--question";
+                    readonly value: "<text>";
+                    readonly required: false;
+                    readonly description: "What you need answered; required with --state blocked.";
+                }, {
+                    readonly name: "--pane";
+                    readonly value: "<pane-id>";
+                    readonly required: false;
+                    readonly description: "Pane id when not running inside a Pane terminal (PANE_SESSION_ID).";
+                }, {
+                    readonly name: "--panel";
+                    readonly value: "<panel-id>";
+                    readonly required: false;
+                    readonly description: "Panel id when not running inside a Pane terminal (PANE_PANEL_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 report --state ready --pr 747 --head fc5dce9 --summary-file /tmp/report.md --json", "runpane report --state blocked --question \"Should the migration drop the old column?\""];
+                readonly jsonSchemas: readonly ["reportResult"];
+                readonly notes: readonly ["Inside a Pane terminal the report is for the current panel (PANE_SESSION_ID and PANE_PANEL_ID). Explicit --panel (with an optional --pane) wins; with neither, the command fails with a clear error.", "Each report replaces the panel's previous one and survives a Pane restart.", "Watchers receive agent.report only when they list it in --kinds. REPORT lines skip the --min-interval batch."];
             };
             readonly "sessions list": {
                 readonly name: "sessions list";
@@ -5705,7 +6678,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "List durable named orchestration Sessions.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: false;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions list [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionListResult"];
                 readonly notes: readonly [];
@@ -5716,7 +6694,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Create a durable named orchestration Session and its hidden terminal owner.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5727,7 +6710,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Read one durable named orchestration Session.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: false;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions get --session <id|name> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5738,7 +6726,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Update a Session overview from structured JSON.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5749,7 +6742,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Switch the durable terminal agent for a named Session.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5760,7 +6758,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Associate a user-visible Pane with a named Session. `panes create` and `panes adopt` already do this automatically when run inside a Session orchestrator; use this for existing Panes or after `--no-associate`.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5771,7 +6774,12 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Detach a Pane from a named Session.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: true;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 readonly examples: readonly ["runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]"];
                 readonly jsonSchemas: readonly ["sessionResult"];
                 readonly notes: readonly [];
@@ -5782,9 +6790,138 @@ export declare const RUNPANE_CONTRACT: {
                 readonly details: "Read a live status, activity, git, and pull request overview for a named Session.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: false;
-                readonly arguments: readonly [];
+                readonly arguments: readonly [{
+                    readonly name: "--pane-dir";
+                    readonly value: "<path>";
+                    readonly required: false;
+                    readonly description: "Connect to a specific Pane data directory.";
+                }];
                 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 "lock acquire": {
+                readonly name: "lock acquire";
+                readonly summary: "Acquire a named lock on a resource shared between agents, such as one test account, optionally waiting for it.";
+                readonly details: "Run this before using a resource that only one agent may use at a time, such as a shared test account, and release it when done. The owner is the calling Pane and panel ($PANE_SESSION_ID and $PANE_PANEL_ID, or --pane/--panel). The lock is scoped to the owner's Session when its Pane belongs to one, so two Sessions can each hold `testing-account`; otherwise it is global. It succeeds when the lock is free, expired, or already yours (which renews the TTL). Otherwise it returns ok:false with heldBy and expiresAt at once, or with --wait blocks in the daemon until the lock is released, expires, or its owner's panel exits or Pane is archived.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [{
+                    readonly name: "--name";
+                    readonly value: "<name>";
+                    readonly required: true;
+                    readonly description: "Lock name: 1-128 letters, digits, \".\", \"_\", or \"-\".";
+                }, {
+                    readonly name: "--ttl";
+                    readonly value: "<duration>";
+                    readonly required: true;
+                    readonly description: "How long the lock is held before it expires, such as 90s, 30m, or 2h; at most 24h. Acquire again before it runs out to renew.";
+                }, {
+                    readonly name: "--wait";
+                    readonly value: "<milliseconds>";
+                    readonly required: false;
+                    readonly description: "Wait this long for the lock to come free. The CLI waits in daemon calls of up to 120 seconds each.";
+                }, {
+                    readonly name: "--note";
+                    readonly value: "<text>";
+                    readonly required: false;
+                    readonly description: "What the lock is for, shown to other agents. Required outside a Pane terminal, where it also names the owner.";
+                }, {
+                    readonly name: "--pane";
+                    readonly value: "<pane-id>";
+                    readonly required: false;
+                    readonly description: "Act for this Pane instead of $PANE_SESSION_ID.";
+                }, {
+                    readonly name: "--panel";
+                    readonly value: "<panel-id>";
+                    readonly required: false;
+                    readonly description: "Act for this panel instead of $PANE_PANEL_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 lock acquire --name testing-account --ttl 30m --wait 1800000 --note \"call QA\" --json", "runpane lock acquire --name staging-db --ttl 10m --json"];
+                readonly jsonSchemas: readonly ["lockAcquireRequest", "lockAcquireResult"];
+                readonly notes: readonly ["Exit status is 0 only when the lock is yours; ok:false (exit 1) means another owner holds it, named by heldBy until expiresAt.", "Release the lock as soon as you are done with the resource: `runpane lock release --name <name>`. If you interrupt a waiting acquire, the lock can still be granted to you for up to two minutes; release it or let the TTL expire.", "Pane releases the lock when its TTL runs out, when the owner panel exits, or when the owner Pane is archived. Quitting Pane does not release it; locks survive a restart."];
+            };
+            readonly "lock release": {
+                readonly name: "lock release";
+                readonly summary: "Release a named lock you hold, or force-release another owner's lock.";
+                readonly details: "Only the owner can release a lock. --force releases another owner's lock, for example a stuck worker's; use --session to name a Session-scoped lock from outside that Session.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [{
+                    readonly name: "--name";
+                    readonly value: "<name>";
+                    readonly required: true;
+                    readonly description: "Lock name.";
+                }, {
+                    readonly name: "--force";
+                    readonly required: false;
+                    readonly description: "Release the lock even though another owner holds it.";
+                }, {
+                    readonly name: "--session";
+                    readonly value: "<id|name>";
+                    readonly required: false;
+                    readonly description: "Session whose lock to release; defaults to the caller's Session, or global.";
+                }, {
+                    readonly name: "--note";
+                    readonly value: "<text>";
+                    readonly required: false;
+                    readonly description: "Outside a Pane terminal, the note the lock was acquired with.";
+                }, {
+                    readonly name: "--pane";
+                    readonly value: "<pane-id>";
+                    readonly required: false;
+                    readonly description: "Act for this Pane instead of $PANE_SESSION_ID.";
+                }, {
+                    readonly name: "--panel";
+                    readonly value: "<panel-id>";
+                    readonly required: false;
+                    readonly description: "Act for this panel instead of $PANE_PANEL_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 lock release --name testing-account --json", "runpane lock release --name testing-account --session \"<session-id-or-name>\" --force --json"];
+                readonly jsonSchemas: readonly ["lockReleaseResult"];
+                readonly notes: readonly ["released:false with ok:true means no such lock was held. ok:false with reason not-owner (exit 1) means another owner holds it."];
+            };
+            readonly "lock list": {
+                readonly name: "lock list";
+                readonly summary: "List held named locks, optionally only one Session's.";
+                readonly details: "List every held lock, or with --session the locks scoped to that Session plus those its Panes hold. `runpane sessions overview` includes the same Session locks.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: false;
+                readonly arguments: readonly [{
+                    readonly name: "--session";
+                    readonly value: "<id|name>";
+                    readonly required: false;
+                    readonly description: "Named Session id or exact name.";
+                }, {
+                    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 lock list --json", "runpane lock list --session \"<session-id-or-name>\" --json"];
+                readonly jsonSchemas: readonly ["lockListResult"];
                 readonly notes: readonly [];
             };
         };