runpane 2.4.104 → 2.4.106

package/dist/generated/contract.d.ts

@@ -26,6 +26,10 @@ export declare const RUNPANE_CONTRACT: {
             readonly format: "lines";
             readonly heartbeatSeconds: 60;
             readonly idleAfterMs: 600000;
+            readonly settleMs: 0;
+            readonly blockedSettleMs: 0;
+            readonly minIntervalMs: 0;
+            readonly idleBackoff: false;
             readonly agentsOnly: true;
             readonly includeHeldInputPresence: true;
         };
@@ -128,7 +132,7 @@ export declare const RUNPANE_CONTRACT: {
     }, {
         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>] [--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>] [--include-shells] [--self-test] [--kinds <kind,...>] [--repo <selector>] [--name-contains <text>] [--timeout-ms <ms>] [--from <now|earliest>] [--json]"];
         readonly jsonSchemas: readonly ["workspaceWaitRequest", "workspaceWaitResult"];
     }, {
         readonly name: "panes create";
@@ -210,6 +214,51 @@ export declare const RUNPANE_CONTRACT: {
         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 jsonSchemas: readonly ["panelWaitResult"];
+    }, {
+        readonly name: "sessions list";
+        readonly summary: "List durable named orchestration Sessions.";
+        readonly usage: readonly ["runpane sessions list [--json] [--pane-dir <path>]"];
+        readonly jsonSchemas: readonly ["sessionListResult"];
+    }, {
+        readonly name: "sessions create";
+        readonly summary: "Create a durable named orchestration Session and its hidden terminal owner.";
+        readonly usage: readonly ["runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions get";
+        readonly summary: "Read one durable named orchestration Session.";
+        readonly usage: readonly ["runpane sessions get --session <id|name> [--json] [--pane-dir <path>]"];
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions update";
+        readonly summary: "Update a Session overview from structured JSON.";
+        readonly usage: readonly ["runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions set-agent";
+        readonly summary: "Switch the durable terminal agent for a named Session.";
+        readonly usage: readonly ["runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions associate";
+        readonly summary: "Associate a user-visible Pane with a named Session.";
+        readonly usage: readonly ["runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions detach";
+        readonly summary: "Detach a Pane from a named Session.";
+        readonly usage: readonly ["runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]"];
+        readonly mutates: true;
+        readonly jsonSchemas: readonly ["sessionResult"];
+    }, {
+        readonly name: "sessions overview";
+        readonly summary: "Read a live status, activity, git, and pull request overview for a named Session.";
+        readonly usage: readonly ["runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]"];
+        readonly jsonSchemas: readonly ["sessionOverviewResult"];
     }];
     readonly flags: {
         readonly wrapper: readonly [{
@@ -339,7 +388,7 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--from-json";
             readonly value: "<path|->";
-            readonly description: "Read a full panes.create request JSON payload from a file or stdin.";
+            readonly description: "Read a structured JSON request payload from a file or stdin.";
         }, {
             readonly name: "--timeout-ms";
             readonly value: "<milliseconds>";
@@ -420,10 +469,26 @@ export declare const RUNPANE_CONTRACT: {
             readonly name: "--idle-after";
             readonly value: "<milliseconds>";
             readonly description: "Emit agent.idle after this READY duration; 0 disables idle events.";
+        }, {
+            readonly name: "--settle";
+            readonly value: "<milliseconds>";
+            readonly description: "Follow-only opt-in: emit READY only after the panel stays idle this long; a BUSY inside the window cancels it silently.";
+        }, {
+            readonly name: "--blocked-settle";
+            readonly value: "<milliseconds>";
+            readonly description: "Follow-only opt-in: emit BLOCKED only after the panel stays blocked this long; an in-pane answer inside the window cancels it silently.";
+        }, {
+            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 name: "--body-file";
             readonly value: "<path|->";
             readonly description: "Read diagnostic report evidence from a file or stdin.";
+        }, {
+            readonly name: "--session";
+            readonly value: "<id|name>";
+            readonly description: "Named orchestration Session id or exact name.";
         }];
         readonly localBoolean: readonly [{
             readonly name: "--json";
@@ -473,6 +538,9 @@ export declare const RUNPANE_CONTRACT: {
         }, {
             readonly name: "--self-test";
             readonly description: "Probe the current daemon watch path without advancing a named cursor.";
+        }, {
+            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.";
         }, {
             readonly name: "--report";
             readonly description: "Prepare a redacted doctor report; external filing still requires --yes.";
@@ -480,7 +548,7 @@ 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 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", "  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>|--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] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  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 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>|--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] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  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"];
@@ -494,7 +562,7 @@ export declare const RUNPANE_CONTRACT: {
             readonly "panes cost": readonly ["Usage:", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "", "Reports estimated token costs per Pane for the last 30 days, including per-model and cache-efficiency details.", "", "Options:", "  --repo <selector>              Limit results to one saved repository", "  --pane <pane-id>               Return one Pane, including an idle Pane with zero usage", "  --pane-dir <path>              Connect to a specific Pane data directory", "  --json                         Print machine-readable output"];
             readonly workspace: readonly ["Workspace 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", "  --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"];
+            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)", "  --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; --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"];
@@ -512,6 +580,15 @@ export declare const RUNPANE_CONTRACT: {
             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] --yes [--json]", "", "Options:", "  --panel <panel-id>            Terminal panel id.", "  --strategy <strategy>         Defaults to auto; Codex sends Ctrl+Enter and other panels send Enter.", "  --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."];
+            readonly "sessions update": readonly ["Usage:", "runpane sessions update --session <id|name> --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 set-agent": readonly ["Usage:", "runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--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 associate": readonly ["Usage:", "runpane sessions associate --session <id|name> --pane <pane-id> [--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 detach": readonly ["Usage:", "runpane sessions detach --session <id|name> [--pane <pane-id>] [--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 overview": readonly ["Usage:", "runpane sessions overview --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."];
+            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 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 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>|--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] --yes [--json]", "  runpane panels wait --panel <panel-id> [--for initialized|ready|idle|text] [--json]", "  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."];
@@ -528,7 +605,7 @@ export declare const RUNPANE_CONTRACT: {
             readonly "panes cost": readonly ["Usage:", "  runpane panes cost [--repo <selector>] [--pane <pane-id>] [--json]", "", "Reports estimated token costs per Pane for the last 30 days, including per-model and cache-efficiency details.", "", "Options:", "  --repo <selector>", "  --pane <pane-id>", "  --pane-dir <path>", "  --json"];
             readonly workspace: readonly ["Workspace 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>", "  --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"];
+            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)", "  --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; --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"];
@@ -546,6 +623,15 @@ export declare const RUNPANE_CONTRACT: {
             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] --yes [--json]", "", "Options:", "  --panel <panel-id>            Terminal panel id.", "  --strategy <strategy>         Defaults to auto; Codex sends Ctrl+Enter and other panels send Enter.", "  --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."];
+            readonly "sessions update": readonly ["Usage:", "python -m runpane sessions update --session <id|name> --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 set-agent": readonly ["Usage:", "python -m runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--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 associate": readonly ["Usage:", "python -m runpane sessions associate --session <id|name> --pane <pane-id> [--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 detach": readonly ["Usage:", "python -m runpane sessions detach --session <id|name> [--pane <pane-id>] [--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 overview": readonly ["Usage:", "python -m runpane sessions overview --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."];
+            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 docs: {
@@ -554,8 +640,8 @@ 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 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 help", "runpane <command> --help"];
-        readonly commandDescriptions: readonly ["`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. 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 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.", "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 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'`."];
+        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 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 help", "runpane <command> --help"];
+        readonly commandDescriptions: readonly ["`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. 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 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.", "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 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."];
         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 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.";
@@ -563,7 +649,7 @@ export declare const RUNPANE_CONTRACT: {
         readonly publishingCredentials: readonly ["Local implementation, build, and dry-run validation do not need npm or PyPI API tokens.", "Release publishing should prefer npm Trusted Publishing and PyPI Trusted Publishing from GitHub Actions.", "Fallback `NPM_TOKEN` or `PYPI_API_TOKEN` credentials may be used for first package reservation or manual publication only. They must be supplied through local environment variables or GitHub Actions secrets, never committed, and revoked or rotated after use."];
     };
     readonly testFixtures: {
-        readonly parserSamples: readonly [readonly ["setup"], readonly ["install"], readonly ["install", "client", "--version", "v2.2.8", "--format", "dmg", "--download-dir", "/tmp/pane-downloads", "--dry-run", "--yes"], readonly ["install", "daemon", "--label", "VM", "--prefer-tunnel", "ssh", "--channel", "nightly", "--base-url", "https://example.test", "--pane-dir", "/tmp/pane", "--listen-port", "4555", "--auto-listen-port", "--print-only", "--repo-ref", "main", "--unknown-future-flag", "future-value", "--dry-run", "--verbose"], readonly ["update", "--version", "latest", "--format", "appimage", "--pane-path", "/usr/bin/pane", "--dry-run"], readonly ["doctor", "--pane-path", "/usr/bin/pane", "--format", "zip", "--verbose"], readonly ["doctor", "--json", "--pane-dir", "/tmp/pane"], readonly ["doctor", "--report", "--title", "watch failed", "--body-file", "/tmp/watch-evidence.txt", "--json"], readonly ["watch", "--as", "monitor", "--from", "earliest", "--follow", "--format", "lines", "--heartbeat", "60", "--idle-after", "600000", "--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", "--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 ["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 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", "--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 ["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 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"];
@@ -1806,6 +1892,18 @@ export declare const RUNPANE_CONTRACT: {
                 readonly idleWindowStartMs: {
                     readonly type: "number";
                 };
+                readonly settleMs: {
+                    readonly type: "number";
+                };
+                readonly blockedSettleMs: {
+                    readonly type: "number";
+                };
+                readonly minIntervalMs: {
+                    readonly type: "number";
+                };
+                readonly idleBackoff: {
+                    readonly type: "boolean";
+                };
             };
             readonly additionalProperties: false;
         };
@@ -2902,6 +3000,69 @@ export declare const RUNPANE_CONTRACT: {
             };
             readonly additionalProperties: false;
         };
+        readonly sessionListResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "sessions"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly sessions: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                    };
+                };
+                readonly selectedSessionId: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly sessionResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "session"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly session: {
+                    readonly type: "object";
+                };
+                readonly panelId: {
+                    readonly type: "string";
+                };
+                readonly internalSessionId: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly sessionOverviewResult: {
+            readonly type: "object";
+            readonly required: readonly ["ok", "session", "status", "panes", "activity", "refreshedAt"];
+            readonly properties: {
+                readonly ok: {
+                    readonly const: true;
+                };
+                readonly session: {
+                    readonly type: "object";
+                };
+                readonly status: {
+                    readonly type: "string";
+                };
+                readonly panes: {
+                    readonly type: "array";
+                };
+                readonly activity: {
+                    readonly type: "array";
+                };
+                readonly refreshedAt: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
     };
     readonly agentContext: {
         readonly brief: {
@@ -2989,6 +3150,10 @@ export declare const RUNPANE_CONTRACT: {
                 readonly name: "panels wait";
                 readonly summary: "Wait for terminal initialized, ready, idle, or text state with compact output.";
                 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 commands: {
@@ -3939,38 +4104,91 @@ export declare const RUNPANE_CONTRACT: {
             readonly watch: {
                 readonly name: "watch";
                 readonly summary: "Wait for workspace transitions using the daemon journal.";
-                readonly details: "`runpane watch --follow` is the canonical zero-flag monitor: lines, 60-second heartbeats, 10-minute re-firing IDLE, managed-agent scope, and redacted STUCK detection are follow defaults. Named cursors persist in the Pane data directory.";
+                readonly details: "`runpane watch --follow` is the responsive monitor: lines, 60-second heartbeats, IDLE every 10 minutes, managed-agent scope, redacted STUCK detection, no settle, no batching, all kinds. Expensive consumers (one wake-up per line) opt into the cadence flags. Pane Chat arms them automatically through its pane-orchestrator skill; only your own scripts need to pass them. Named cursors persist in the Pane data directory.";
                 readonly requiresPaneDaemon: true;
                 readonly mutates: false;
                 readonly arguments: readonly [{
                     readonly name: "--as";
                     readonly value: "<consumer-name>";
                     readonly required: false;
-                    readonly description: "Use a persisted named cursor.";
+                    readonly description: "Use a persisted named cursor (at-least-once delivery). Default: PANE_PANEL_ID under --follow when set, otherwise anonymous.";
                 }, {
                     readonly name: "--since";
                     readonly value: "<generation>";
                     readonly required: false;
-                    readonly description: "Use an explicit generation cursor.";
+                    readonly description: "Use an explicit generation cursor instead of a name. Cannot be combined with --as, or with --settle, --blocked-settle, --min-interval.";
+                }, {
+                    readonly name: "--from";
+                    readonly required: false;
+                    readonly value: "<now|earliest>";
+                    readonly description: "Starting point for a new named cursor. Default now (silent baseline); earliest replays the journal.";
                 }, {
                     readonly name: "--follow";
                     readonly required: false;
-                    readonly description: "Continue waiting until interrupted.";
+                    readonly description: "Continue waiting until interrupted. Required by every cadence flag.";
                 }, {
                     readonly name: "--format";
                     readonly value: "<lines|json>";
                     readonly required: false;
-                    readonly description: "Output format; lines is the follow default.";
+                    readonly description: "Output format. Default lines in every mode; --json selects json.";
                 }, {
                     readonly name: "--heartbeat";
                     readonly value: "<seconds>";
                     readonly required: false;
-                    readonly description: "Healthy-silence bound; defaults to 60 under follow.";
+                    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 name: "--idle-after";
                     readonly value: "<milliseconds>";
                     readonly required: false;
-                    readonly description: "Re-firing READY idle interval; defaults to 600000 under follow.";
+                    readonly description: "IDLE fires after a READY panel has stayed idle this long, then re-fires every multiple. Default 600000 under --follow, 0 otherwise.";
+                }, {
+                    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 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 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 name: "--idle-backoff";
+                    readonly required: false;
+                    readonly description: "Opt-in (follow only): IDLE fires at --idle-after, then 30m, 1h, 3h, then daily per panel; any activity resets the schedule. Default off (fixed multiples of --idle-after).";
+                }, {
+                    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 name: "--pane";
+                    readonly required: false;
+                    readonly value: "<pane-id>";
+                    readonly description: "Limit to a Pane; repeatable. Default all managed panes.";
+                }, {
+                    readonly name: "--exclude-pane";
+                    readonly required: false;
+                    readonly value: "<pane-id>";
+                    readonly description: "Exclude a Pane; repeatable.";
+                }, {
+                    readonly name: "--repo";
+                    readonly required: false;
+                    readonly value: "<selector>";
+                    readonly description: "Limit to a saved repository (active, id, path, or name). Default all repositories.";
+                }, {
+                    readonly name: "--name-contains";
+                    readonly required: false;
+                    readonly value: "<text>";
+                    readonly description: "Limit by Pane name substring.";
+                }, {
+                    readonly name: "--agents-only";
+                    readonly required: false;
+                    readonly description: "Limit to CLI agent panels. Default on under --follow.";
                 }, {
                     readonly name: "--all-managed";
                     readonly required: false;
@@ -3979,17 +4197,127 @@ export declare const RUNPANE_CONTRACT: {
                     readonly name: "--include-shells";
                     readonly required: false;
                     readonly description: "Include ordinary shell panels.";
+                }, {
+                    readonly name: "--timeout-ms";
+                    readonly required: false;
+                    readonly value: "<milliseconds>";
+                    readonly description: "Wait timeout per request; 0 polls once. Default 60000, capped at 120000 (the follow loop re-issues requests).";
+                }, {
+                    readonly name: "--limit";
+                    readonly required: false;
+                    readonly value: "<count>";
+                    readonly description: "Maximum entries per response. Default 256.";
+                }, {
+                    readonly name: "--ack-now";
+                    readonly required: false;
+                    readonly description: "At-most-once named-cursor delivery (advance before you act). Default at-least-once.";
+                }, {
+                    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 name: "--no-held-input";
+                    readonly required: false;
+                    readonly description: "Disable redacted STUCK detection in lines follow mode.";
                 }, {
                     readonly name: "--self-test";
                     readonly required: false;
-                    readonly description: "Probe the watch path anonymously without advancing a named cursor.";
+                    readonly description: "Probe the watch path anonymously without advancing a named cursor; run it before arming --follow.";
                 }, {
                     readonly name: "--json";
                     readonly required: false;
                     readonly description: "Emit structured NDJSON; held-input content remains opt-in.";
                 }];
-                readonly examples: readonly ["runpane watch --follow", "runpane watch --as monitor --follow --json"];
-                readonly notes: readonly ["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 --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 "sessions list": {
+                readonly name: "sessions list";
+                readonly summary: "List durable named orchestration Sessions.";
+                readonly details: "List durable named orchestration Sessions.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: false;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions list [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionListResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions create": {
+                readonly name: "sessions create";
+                readonly summary: "Create a durable named orchestration Session and its hidden terminal owner.";
+                readonly details: "Create a durable named orchestration Session and its hidden terminal owner.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions get": {
+                readonly name: "sessions get";
+                readonly summary: "Read one durable named orchestration Session.";
+                readonly details: "Read one durable named orchestration Session.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: false;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions get --session <id|name> [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions update": {
+                readonly name: "sessions update";
+                readonly summary: "Update a Session overview from structured JSON.";
+                readonly details: "Update a Session overview from structured JSON.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions set-agent": {
+                readonly name: "sessions set-agent";
+                readonly summary: "Switch the durable terminal agent for a named Session.";
+                readonly details: "Switch the durable terminal agent for a named Session.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [];
+                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 [];
+            };
+            readonly "sessions associate": {
+                readonly name: "sessions associate";
+                readonly summary: "Associate a user-visible Pane with a named Session.";
+                readonly details: "Associate a user-visible Pane with a named Session.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions detach": {
+                readonly name: "sessions detach";
+                readonly summary: "Detach a Pane from a named Session.";
+                readonly details: "Detach a Pane from a named Session.";
+                readonly requiresPaneDaemon: true;
+                readonly mutates: true;
+                readonly arguments: readonly [];
+                readonly examples: readonly ["runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionResult"];
+                readonly notes: readonly [];
+            };
+            readonly "sessions overview": {
+                readonly name: "sessions overview";
+                readonly summary: "Read a live status, activity, git, and pull request overview for a named Session.";
+                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 examples: readonly ["runpane sessions overview --session <id|name> [--json] [--pane-dir <path>]"];
+                readonly jsonSchemas: readonly ["sessionOverviewResult"];
+                readonly notes: readonly [];
             };
         };
         readonly managedBlock: readonly ["## Pane", "", "The developer is using Pane for this repository. Pane can manage saved repositories and create user-visible Panes with terminal-backed tools for planning, discussion, implementation, and review work.", "", "This managed guidance was created by [runpane.com](https://runpane.com) for the [Pane repository](https://github.com/dcouple/Pane). Do not delete or overwrite this block; the developer uses it for their workflow and it should remain committed to the main repository unless they explicitly ask to remove it.", "", "Pane mental model: a repository is the saved base repo; a Pane is a user-visible feature/PR workspace (Pane session) that normally maps to one Pane-managed git worktree and branch; a panel/tab is a terminal inside one Pane and shares that Pane's worktree; an agent is the CLI process running in a panel.", "", "Default happy path when the user asks you to use Pane or RunPane: run `runpane doctor --json`; read `runpane agent-context --json`; resolve the saved base repository with `runpane repos list --json` or add it once with `runpane repos add --path <repo> --yes --json`; create one visible Pane (Pane session) for the requested feature/PR 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` or the equivalent `--tool-command <command>` form; then validate with `runpane panels wait` or `runpane panels screen` before reporting progress.", "", "Use Pane when the user wants visible Panes or co-drivable parallel feature/PR workspaces. Do not use Pane as your default private delegation mechanism; for private background decomposition, use your normal subagent/worktree workflow.", "", "Register the main/base repository once. Do not register pre-created git worktrees as separate Pane repositories unless the user explicitly asks.", "", "Use `runpane panes create` for separate visible Panes (Pane sessions) for feature/PR work. Use `runpane panels create` for reviewer/helper tabs inside an existing Pane that should share that Pane's worktree.", "", "Typical workflow: register the saved base repository once; create one Pane (Pane session) per feature/PR; use panels/tabs inside that Pane for helper or reviewer agents that should share the worktree; archive the Pane after the PR is done to remove it from active Panes and clean up its managed worktree when applicable.", "", "Skill routing reference: when the user says `discussion`, `plan`, `simple-plan`, `create-plan`, or `implement`, or asks for the behavior those words imply, treat three references as peer context: Pane's local skill cache under `<PANE_DIR>/skills/`, the Pane Chat orchestrator handoff at `<PANE_DIR>/skills/pane-chat/runpane-orchestrator.md` when present, and the [workflow map](https://github.com/dcouple/skills/raw/main/docs/readme-workflow-map.png).", "Use those peer references together to choose the phase: discuss/investigate until the work is clear enough to delegate, then ticket/plan/implement/review/PR-test/teach-back as appropriate. The orchestrator and workflow map may point to different skills; reconcile them with the user's request instead of hardcoding a skill list or treating one reference as subordinate.", "For the Pane implementation source of truth for where the skill cache, cached workflow assets, and Pane Chat bootstrap live, reference [PR #291](https://github.com/dcouple/Pane/pull/291): `main/src/services/skillCacheManager.ts` owns `<PANE_DIR>/skills/`, `.sources/dcouple-skills`, and `pane-chat/runpane-orchestrator.md`; `main/src/services/paneChatManager.ts` owns the tiny bootstrap prompt that tells the selected Pane Chat agent to read that guide.", "Use GitHub reads against the [Parsa skills folder](https://github.com/dcouple/skills/tree/main/parsa) only to inspect or refresh referenced skill files; do not clone/install the repo unless the user asks.", "Do not hardcode a specific assistant brand in workflow guidance. Use the Pane agent or custom tool command the user selected, and use `runpane agents doctor --agent <agent> --repo <selector> --json` only when checking a built-in agent template.", "", "Start with `runpane doctor --json` before taking Pane actions. Use it to understand wrapper/runtime details, daemon reachability, and the next safe commands.", "", "In a Pane repository checkout, if `runpane` is not on PATH, use the built local wrapper with Node 22: `PATH=/opt/homebrew/opt/node@22/bin:$PATH node packages/runpane/dist/cli.js doctor --json`.", "", "Use `runpane agent-context --json` for full Pane CLI context. Use `runpane agent-context --command \"panels wait\" --json` or another command name for detailed schema only when needed.", "", "Default to context-safe validation: after creating Panes or sending terminal input, run `runpane panels wait` or `runpane panels screen` before reporting success. Prefer `runpane panels submit` for normal text plus Enter; use `runpane panels input` only for exact bytes such as Ctrl-C or escape sequences.", "", "Pane terminals draw inline images: sixel, iTerm2 inline images, and the kitty graphics protocol. Tools that need kitty graphics, such as [terminal-browser](https://github.com/zenbu-labs/terminal-browser) and [terminal-doom](https://github.com/dcouple/terminal-doom), run inside a Pane panel. `runpane doctor --json` reports the protocol list under `terminal.graphicsProtocols`.", "", "Common commands:", "- `runpane doctor --json`", "- `runpane agent-context --json`", "- `runpane repos list --json`", "- `runpane repos add --path <repo> --yes --json`", "- `runpane agents doctor --agent <agent> --repo active --json`", "- `runpane panes create --repo active --name <name> --agent <agent> --prompt \"<task>\" --source agent --no-focus --wait-ready --yes --json`", "- `runpane panels create --pane <pane-id> --agent <agent> --source agent --no-focus --wait-ready --yes --json`", "- `runpane panels list --pane <pane-id> --json`", "- `runpane panels screen --panel <panel-id> --limit 80 --json`", "- `runpane panels wait --panel <panel-id> --for ready --timeout-ms 30000 --json`", "- `runpane panels submit --panel <panel-id> --text \"<answer>\" --yes --json`", "- `runpane panels input --panel <panel-id> --input-file <path|-> --yes --json`", "", "WSL note: if `runpane doctor --json` cannot find `/tmp/pane-daemon.../daemon.sock` or `runpane` resolves to a broken Windows shim, Pane may be running on Windows. Try `powershell.exe -NoProfile -Command 'Set-Location $env:TEMP; runpane doctor --json'`, then create Panes through the same PowerShell form using the saved WSL repo name or id. Use `runpane agents doctor --agent <agent> --repo <selector> --json` to diagnose the repo environment Pane will actually use."];