runpane 2.4.169 → 2.4.170

package/dist/generated/contract.js

@@ -61,7 +61,8 @@ exports.RUNPANE_CONTRACT = {
         "agents": [
             "codex",
             "claude",
-            "cursor"
+            "cursor",
+            "opencode"
         ]
     },
     "agentTemplates": {
@@ -79,6 +80,11 @@ exports.RUNPANE_CONTRACT = {
             "title": "Cursor",
             "command": "cursor-agent --force --trust",
             "description": "Open a Cursor Agent terminal tab and allow the initial input to drive the agent."
+        },
+        "opencode": {
+            "title": "OpenCode",
+            "command": "opencode --auto",
+            "description": "Open an OpenCode terminal tab and allow the initial input to drive the agent."
         }
     },
     "terminalKeys": {
@@ -614,7 +620,7 @@ exports.RUNPANE_CONTRACT = {
             "name": "panels submit",
             "summary": "Send and submit text to a terminal panel, including idle agent composers.",
             "usage": [
-                "runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--source user|agent] --yes [--json] [--pane-dir <path>]"
+                "runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] [--source user|agent] --yes [--json] [--pane-dir <path>]"
             ],
             "mutates": true,
             "toolsets": [
@@ -1191,7 +1197,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "sessions create",
-            "summary": "Create a durable named orchestration Session and its hidden terminal owner.",
+            "summary": "Create a durable named orchestration Session and its hidden terminal owner; JSON isPinned sets the pin star (default false).",
             "usage": [
                 "runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]"
             ],
@@ -1221,7 +1227,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "sessions update",
-            "summary": "Update a Session overview from structured JSON.",
+            "summary": "Update a Session overview from structured JSON; isPinned sets the UI pin star.",
             "usage": [
                 "runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]"
             ],
@@ -1345,6 +1351,38 @@ exports.RUNPANE_CONTRACT = {
                 "lockListResult"
             ],
             "localControl": true
+        },
+        {
+            "name": "sessions unpin",
+            "summary": "Declaratively unpin a named Session using the UI pin state; repeated requests keep the requested state.",
+            "usage": [
+                "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]"
+            ],
+            "mutates": true,
+            "idempotent": true,
+            "toolsets": [
+                "sessions"
+            ],
+            "jsonSchemas": [
+                "sessionResult"
+            ],
+            "localControl": true
+        },
+        {
+            "name": "sessions pin",
+            "summary": "Declaratively pin a named Session using the UI pin state; repeated requests keep the requested state.",
+            "usage": [
+                "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]"
+            ],
+            "mutates": true,
+            "idempotent": true,
+            "toolsets": [
+                "sessions"
+            ],
+            "jsonSchemas": [
+                "sessionResult"
+            ],
+            "localControl": true
         }
     ],
     "flags": {
@@ -1518,7 +1556,7 @@ exports.RUNPANE_CONTRACT = {
             {
                 "name": "--file",
                 "value": "<path>",
-                "description": "File inside the Pane worktree to open; HTML renders in a browser tab."
+                "description": "File inside the Pane worktree to open; supported formats have read-only previews, including HTML source."
             },
             {
                 "name": "--initial-input",
@@ -1789,7 +1827,7 @@ exports.RUNPANE_CONTRACT = {
             },
             {
                 "name": "--pinned",
-                "description": "Accepted for backward compatibility; `panes create` already pins by default."
+                "description": "Request pinning at creation; Session association still clears the first pin. Outside a Session, creation pins by default."
             },
             {
                 "name": "--no-pinned",
@@ -1877,6 +1915,10 @@ exports.RUNPANE_CONTRACT = {
             {
                 "name": "--push",
                 "description": "Before a handoff, commit uncommitted work as WIP and push the branch (never forces)."
+            },
+            {
+                "name": "--interrupt",
+                "description": "Stop the current agent turn, wait for an empty idle composer, then submit and verify the replacement."
             }
         ]
     },
@@ -1901,6 +1943,8 @@ exports.RUNPANE_CONTRACT = {
                 "  runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]",
                 "  runpane sessions get --session <id|name> [--json] [--pane-dir <path>]",
                 "  runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]",
+                "  runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]",
+                "  runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]",
                 "  runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]",
                 "  runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]",
                 "  runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]",
@@ -2239,13 +2283,15 @@ exports.RUNPANE_CONTRACT = {
                 "  --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)",
+                "  --pinned                       Request pinning at creation; first Session association clears it",
+                "  --no-pinned                    Create unpinned (the UI's favorite/pin star)",
                 "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session",
                 "  --pane-dir <path>              Connect to a specific Pane data directory",
                 "  --json                         Print machine-readable output",
                 "  --dry-run                      Validate and preview without creating panes",
-                "  --yes                          Skip confirmation for mutating commands"
+                "  --yes                          Skip confirmation for mutating commands",
+                "",
+                "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."
             ],
             "panes adopt": [
                 "Usage:",
@@ -2450,7 +2496,7 @@ exports.RUNPANE_CONTRACT = {
             ],
             "panels submit": [
                 "Usage:",
-                "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] --yes [--json]",
+                "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] --yes [--json]",
                 "",
                 "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.",
                 "",
@@ -2467,7 +2513,8 @@ exports.RUNPANE_CONTRACT = {
                 "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`",
                 "  --pane-dir <path>              Connect to a specific Pane data directory",
                 "  --json                         Print machine-readable output",
-                "  --yes                          Skip confirmation for this mutating command"
+                "  --yes                          Skip confirmation for this mutating command",
+                "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"
             ],
             "panels wait": [
                 "Usage:",
@@ -2513,7 +2560,7 @@ exports.RUNPANE_CONTRACT = {
                 "Usage:",
                 "  runpane panels open [--pane <pane-id>] (--url <url>|--file <path>) [--title <title>] [--split|--tab] [--focus|--no-focus] [--source user|agent] --yes [--json]",
                 "",
-                "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: .html/.htm files render in a browser tab, other files open in an editor tab. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
+                "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: files open in an editor tab with read-only previews for supported formats, including HTML source. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
                 "",
                 "Options:",
                 "  --pane <pane-id>              Pane to open the tab in; defaults to PANE_SESSION_ID.",
@@ -2561,7 +2608,10 @@ exports.RUNPANE_CONTRACT = {
                 "  --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."
+                "  --json                       Print JSON output.",
+                "",
+                "JSON isPinned: true pins the Session; omitted or false leaves it unpinned.",
+                "Create-time isPinned requires an updated Pane app; on older apps, use sessions pin after creation and read back the result."
             ],
             "sessions get": [
                 "Usage:",
@@ -2583,7 +2633,9 @@ exports.RUNPANE_CONTRACT = {
                 "  --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."
+                "  --json                       Print JSON output.",
+                "",
+                "JSON isPinned: true/false sets the Session pin star. Select the Session with --session, not a session field in JSON."
             ],
             "sessions set-agent": [
                 "Usage:",
@@ -3099,6 +3151,18 @@ exports.RUNPANE_CONTRACT = {
                 "  runpane handoff --template > ~/handoff.md",
                 "  runpane handoff \"claude opus on parsas-macbook-pro\" --note-file ~/handoff.md --push",
                 "  runpane handoff \"codex gpt-5 high on parsa-devbox\" --note-file ~/handoff.md --dry-run"
+            ],
+            "sessions pin": [
+                "Usage:",
+                "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]",
+                "",
+                "Set the named Session pin star on. Repeated requests keep that state. Uses the same Session update path as the UI."
+            ],
+            "sessions unpin": [
+                "Usage:",
+                "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]",
+                "",
+                "Set the named Session pin star off. Repeated requests keep that state. Uses the same Session update path as the UI."
             ]
         },
         "pip": {
@@ -3430,13 +3494,15 @@ exports.RUNPANE_CONTRACT = {
                 "  --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)",
+                "  --pinned                       Request pinning at creation; first Session association clears it",
+                "  --no-pinned                    Create unpinned (the UI's favorite/pin star)",
                 "  --no-associate                 Inside a Session orchestrator, do not associate the new pane with that Session",
                 "  --pane-dir <path>              Connect to a specific Pane data directory",
                 "  --json                         Print machine-readable output",
                 "  --dry-run                      Validate and preview without creating panes",
-                "  --yes                          Skip confirmation for mutating commands"
+                "  --yes                          Skip confirmation for mutating commands",
+                "",
+                "Outside a Session, creation pins by default, including --source agent. Inside a Session (PANE_ORCHESTRATION_SESSION_ID), children default to unpinned to avoid duplicating them in the global pinned list. First Session association clears the creation pin, including --pinned; use panes pin afterward to pin an associated child."
             ],
             "panes adopt": [
                 "Usage:",
@@ -3633,7 +3699,7 @@ exports.RUNPANE_CONTRACT = {
             ],
             "panels submit": [
                 "Usage:",
-                "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] --yes [--json]",
+                "  runpane panels submit --panel <panel-id> (--text <text>|--input-file <path|->) [--as-file-pointer] [--interrupt] --yes [--json]",
                 "",
                 "Sends text to a terminal panel and normalizes the final terminal Enter to CR. Use this for ordinary prompt answers and shell commands.",
                 "",
@@ -3650,7 +3716,8 @@ exports.RUNPANE_CONTRACT = {
                 "  --as-file-pointer              Write the text to a prompt file and submit `Read and follow <path>`",
                 "  --pane-dir <path>              Connect to a specific Pane data directory",
                 "  --json                         Print machine-readable output",
-                "  --yes                          Skip confirmation for this mutating command"
+                "  --yes                          Skip confirmation for this mutating command",
+                "  --interrupt                   Stop the current turn, wait for idle, then submit the replacement"
             ],
             "panels wait": [
                 "Usage:",
@@ -3696,7 +3763,7 @@ exports.RUNPANE_CONTRACT = {
                 "Usage:",
                 "  python -m runpane panels open [--pane <pane-id>] (--url <url>|--file <path>) [--title <title>] [--split|--tab] [--focus|--no-focus] [--source user|agent] --yes [--json]",
                 "",
-                "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: .html/.htm files render in a browser tab, other files open in an editor tab. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
+                "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: files open in an editor tab with read-only previews for supported formats, including HTML source. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
                 "",
                 "Options:",
                 "  --pane <pane-id>              Pane to open the tab in; defaults to PANE_SESSION_ID.",
@@ -3744,7 +3811,10 @@ exports.RUNPANE_CONTRACT = {
                 "  --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."
+                "  --json                       Print JSON output.",
+                "",
+                "JSON isPinned: true pins the Session; omitted or false leaves it unpinned.",
+                "Create-time isPinned requires an updated Pane app; on older apps, use sessions pin after creation and read back the result."
             ],
             "sessions get": [
                 "Usage:",
@@ -3766,7 +3836,9 @@ exports.RUNPANE_CONTRACT = {
                 "  --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."
+                "  --json                       Print JSON output.",
+                "",
+                "JSON isPinned: true/false sets the Session pin star. Select the Session with --session, not a session field in JSON."
             ],
             "sessions set-agent": [
                 "Usage:",
@@ -4213,6 +4285,18 @@ exports.RUNPANE_CONTRACT = {
                 "",
                 "`runpane handoff` ships in the npm package and the Pane app, not in the Python package.",
                 "Run it with Node instead: npx --yes runpane@latest handoff"
+            ],
+            "sessions pin": [
+                "Usage:",
+                "python -m runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]",
+                "",
+                "Set the named Session pin star on. Repeated requests keep that state. Uses the same Session update path as the UI."
+            ],
+            "sessions unpin": [
+                "Usage:",
+                "python -m runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]",
+                "",
+                "Set the named Session pin star off. Repeated requests keep that state. Uses the same Session update path as the UI."
             ]
         }
     },
@@ -4302,6 +4386,8 @@ exports.RUNPANE_CONTRACT = {
             "runpane sessions create --from-json <path|-> [--json] [--pane-dir <path>]",
             "runpane sessions get --session <id|name> [--json] [--pane-dir <path>]",
             "runpane sessions update --session <id|name> --from-json <path|-> [--json] [--pane-dir <path>]",
+            "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]",
+            "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]",
             "runpane sessions set-agent --session <id|name> --agent <codex|claude|cursor> [--json] [--pane-dir <path>]",
             "runpane sessions associate --session <id|name> --pane <pane-id> [--json] [--pane-dir <path>]",
             "runpane sessions detach --session <id|name> [--pane <pane-id>] [--json] [--pane-dir <path>]",
@@ -4337,12 +4423,12 @@ exports.RUNPANE_CONTRACT = {
             "`runpane repos add` registers an existing git repository with the running local Pane daemon. It does not create directories or initialize git repositories by default.",
             "`runpane panes list` lists Pane sessions, optionally scoped to one saved repository.",
             "`runpane panes cost` reports estimated token costs per Pane for the last 30 days, including per-model breakdowns and cache efficiency; unscoped output includes an Unattributed bucket that reconciles against workspace totals.",
-            "`runpane panes create` connects to the running local Pane daemon, resolves the requested saved base repository, creates user-visible Pane sessions backed by Pane-managed worktrees/branches, opens terminal-backed tool tabs, and optionally sends initial input to the started tool. Built-in agent panes and `--source agent` default to background/no-focus unless `--focus` is passed. New Panes are pinned into the UI's favorite/pin set by default, except when the CLI runs inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID`), where child worktrees default to unpinned. Explicit `--pinned` / `--no-pinned` override creation defaults. First Session association clears an existing pin; manual pins applied afterward are preserved. Panes created interactively in the Pane UI are unaffected. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.",
-            "For `panes create --wait-ready`, `initialInput.delivery` says where the prompt went: `taken` or `queued` (from the agent's transcript, its screen, or `argv` for a launch-argument prompt), `in-composer`, or `unknown`. `initialInput.verifiedSubmitted` is true exactly when it is `taken` or `queued`. Routing input does not by itself verify submission.",
+            "`runpane panes create` connects to the running local Pane daemon, resolves the requested saved base repository, creates user-visible Pane sessions backed by Pane-managed worktrees/branches, opens terminal-backed tool tabs, and optionally sends initial input to the started tool. Built-in agent panes and `--source agent` default to background/no-focus unless `--focus` is passed. New Panes are pinned into the UI's favorite/pin set by default, except when the CLI runs inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID`), where child worktrees default to unpinned. Explicit `--pinned` / `--no-pinned` override creation defaults. First Session association clears an existing pin, including an explicit creation pin; use `panes pin` after association to pin a child. This avoids duplicating Session children in the global pinned list. Manual pins applied afterward are preserved. Panes created interactively in the Pane UI are unaffected. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.",
+            "For `panes create --wait-ready`, `initialInput.delivery` says where the prompt went: `taken` or `queued` (from the agent's transcript or its screen), `in-composer`, or `unknown` (`argv` means a prompt was routed at launch but acceptance is not yet observed). `initialInput.verifiedSubmitted` is true exactly when it is `taken` or `queued`. Routing input does not by itself verify submission. CLI readiness is confirmed on consecutive polls. Codex also requires a recognized configured model or context footer below its live composer; its provisional startup composer is not ready. Hidden or unrecognized Codex status lines conservatively time out rather than prove readiness. Cursor launch prompts currently remain unknown because no acceptance probe is available. First-run trust and daemon dialogs return blocked.kind=first-run-dialog with the dialog in blocked.message and a suggestedCommand; while readiness is blocked or times out, launch-argument delivery remains unknown and unverified.",
             "`runpane panes archive` refreshes the configured upstream, reports exact unpushed commit evidence, and refuses unsafe archive operations unless `--force` is used. A branch whose upstream is gone counts as pushed when a merged GitHub pull request has HEAD as its head (`safetyCheck.mergedViaPr`). Add `--dry-run` to inspect the same evidence without archiving. `--remove-worktree` applies the same check and removal to an adopted worktree; local branches are always kept. Successful archives report `worktreeCleanup: completed` once the worktree is gone from its path and from git; `trashDeletion: pending` means its files are still being deleted in the background. `runpane panes archive --session <id|name> --merged` archives every Session Pane that is clean and pushed or merged, and reports a reason for each skipped Pane.",
             "`runpane panes rename` trims and updates a Pane's display name without changing its worktree, branch, panels, or focus, and returns the updated pane summary.",
             "`runpane panes focus` raises the Pane window and selects a Pane (and optionally one of its panels) exactly like clicking it in the UI. Because it steals the user's window focus, run it only on an explicit user request to open, focus, show, or switch to a Pane; never focus a Pane proactively, the same doctrine that keeps `panes create` background/no-focus for `--source agent`.",
-            "`runpane panels open` opens a URL or a file from the Pane worktree as a tab in an existing Pane (default: the calling panel's Pane from `PANE_SESSION_ID`), in split view beside the agent unless `--tab` is passed. HTML files render in a browser tab and other files open in an editor tab; an existing tab showing the same target is reused. It activates the tab inside the Pane but never raises or focuses the Pane window.",
+            "`runpane panels open` opens a URL or a file from the Pane worktree as a tab in an existing Pane (default: the calling panel's Pane from `PANE_SESSION_ID`), in split view beside the agent unless `--tab` is passed. Files open in an editor tab with read-only previews for supported formats, including HTML source; an existing tab showing the same target is reused. It activates the tab inside the Pane but never raises or focuses the Pane window.",
             "`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.",
@@ -4357,6 +4443,7 @@ exports.RUNPANE_CONTRACT = {
             "`sessions create` create a durable named orchestration Session and its hidden terminal owner.",
             "`sessions get` read one durable named orchestration Session.",
             "`sessions update` update a Session overview from structured JSON.",
+            "`sessions pin` and `sessions unpin` set the Session pin star through the existing UI update path. Create JSON accepts `isPinned` (default false); update JSON preserves the pin when the field is omitted.",
             "`sessions set-agent` switch the durable terminal agent for a named Session.",
             "`sessions associate` associate a user-visible Pane with a named Session.",
             "`sessions detach` detach a Pane from a named Session.",
@@ -4378,9 +4465,10 @@ exports.RUNPANE_CONTRACT = {
             "The PyPI package uses `source=pip` for all Python consumers, including pip, pipx, uvx, and `python -m runpane`.",
             "Wrappers should prefer `https://runpane.com/api/download?platform=<platform>&arch=<arch>&format=<format>&version=<version>&channel=<channel>&source=<npm|pip>`.",
             "If the website route cannot satisfy the download, wrappers may fall back to the matching GitHub release asset and print a warning that website attribution may be incomplete for that run.",
-            "Wrappers also emit best-effort lifecycle telemetry to `https://runpane.com/api/runpane/telemetry` for command start/success/failure, download request/success/failure, and GitHub fallback usage.",
-            "Wrapper telemetry uses a persisted anonymous `install_id` in the form `install_<uuid>` and PostHog `distinct_id = install:<install_id>` so distinct wrapper users can be counted with `count(DISTINCT properties.install_id)`.",
-            "Wrapper telemetry must be disabled in CI and when `RUNPANE_TELEMETRY_DISABLED` is set, and must not include raw paths, labels, prompts, raw error text, or environment values."
+            "Wrappers emit best-effort telemetry to `https://runpane.com/api/runpane/telemetry` for command failures, download request/success/failure, and GitHub fallback usage. Routine command starts and successes emit nothing.",
+            "Wrapper telemetry uses a persisted anonymous `install_id` in the form `install_<uuid>` and PostHog `distinct_id = install:<install_id>` so installs reporting failures or downloads can be counted with `count(DISTINCT properties.install_id)`; this is not a count of all CLI users.",
+            "Wrapper telemetry must be disabled in CI, when `RUNPANE_TELEMETRY_DISABLED` is set, and when the local config explicitly disables analytics. It must not include raw paths, labels, prompts, raw error text, or environment values.",
+            "Desktop local control reports useful failures as `runpane_local_control_failed`; normal polling, wait deadlines, and optional agent unavailability emit nothing. Reports contain coarse operation and failure classification only, with a five-minute deduplication interval and a maximum of 20 per hour per app process. Handled CLI failures are ordinary events, not exceptions."
         ],
         "publishingCredentials": [
             "Local implementation, build, and dry-run validation do not need npm or PyPI API tokens.",
@@ -5210,6 +5298,17 @@ exports.RUNPANE_CONTRACT = {
                 "--tab",
                 "--yes",
                 "--json"
+            ],
+            [
+                "panels",
+                "submit",
+                "--panel",
+                "panel-1",
+                "--text",
+                "correction",
+                "--interrupt",
+                "--yes",
+                "--json"
             ]
         ],
         "topLevelHelpIncludes": [
@@ -6216,6 +6315,7 @@ exports.RUNPANE_CONTRACT = {
                                                 "properties": {
                                                     "kind": {
                                                         "enum": [
+                                                            "first-run-dialog",
                                                             "codex-update",
                                                             "agent-prompt",
                                                             "submission_unverified",
@@ -6294,6 +6394,7 @@ exports.RUNPANE_CONTRACT = {
                                                 "properties": {
                                                     "kind": {
                                                         "enum": [
+                                                            "first-run-dialog",
                                                             "codex-update",
                                                             "agent-prompt",
                                                             "submission_unverified",
@@ -8148,6 +8249,9 @@ exports.RUNPANE_CONTRACT = {
                         "user",
                         "agent"
                     ]
+                },
+                "interrupt": {
+                    "type": "boolean"
                 }
             },
             "additionalProperties": false
@@ -8216,6 +8320,10 @@ exports.RUNPANE_CONTRACT = {
                                 "screen",
                                 "argv"
                             ]
+                        },
+                        "message": {
+                            "type": "string",
+                            "description": "Human explanation of delivery; queued means the agent has not read the message yet."
                         }
                     },
                     "additionalProperties": false
@@ -8349,6 +8457,7 @@ exports.RUNPANE_CONTRACT = {
                     "properties": {
                         "kind": {
                             "enum": [
+                                "first-run-dialog",
                                 "codex-update",
                                 "agent-prompt",
                                 "submission_unverified",
@@ -8713,6 +8822,7 @@ exports.RUNPANE_CONTRACT = {
                             "properties": {
                                 "kind": {
                                     "enum": [
+                                        "first-run-dialog",
                                         "codex-update",
                                         "agent-prompt",
                                         "submission_unverified",
@@ -8916,6 +9026,7 @@ exports.RUNPANE_CONTRACT = {
                     "properties": {
                         "kind": {
                             "enum": [
+                                "first-run-dialog",
                                 "codex-update",
                                 "agent-prompt",
                                 "submission_unverified",
@@ -11393,6 +11504,11 @@ exports.RUNPANE_CONTRACT = {
                         "required": false,
                         "description": "Write the prompt or text to a private file under the Pane directory and send the one line `Read and follow <path>` instead."
                     },
+                    {
+                        "name": "--interrupt",
+                        "required": false,
+                        "description": "Interrupt the current turn and wait up to 30 seconds for an empty idle composer before delivering. Escape for Codex/Claude; Ctrl+C for Cursor."
+                    },
                     {
                         "name": "--yes",
                         "required": false,
@@ -11413,7 +11529,8 @@ exports.RUNPANE_CONTRACT = {
                 "examples": [
                     "runpane panels submit --panel <panel-id> --text \"2\" --yes --json",
                     "printf \"echo hello\" | runpane panels submit --panel <panel-id> --input-file - --yes --json",
-                    "runpane panels submit --panel <panel-id> --input-file brief.md --as-file-pointer --yes --json"
+                    "runpane panels submit --panel <panel-id> --input-file brief.md --as-file-pointer --yes --json",
+                    "runpane panels submit --panel <panel-id> --text \"Stop that approach and follow this correction\" --interrupt --yes --json"
                 ],
                 "jsonSchemas": [
                     "panelSubmitRequest",
@@ -11425,7 +11542,8 @@ exports.RUNPANE_CONTRACT = {
                     "Use `panels input` for Ctrl-C, escape sequences, or any workflow requiring exact bytes.",
                     "On `blocked.kind: composer-unknown`, nothing was typed. Check `panels screen`; if the agent is at a prompt Pane does not recognise, use `panels input`.",
                     "For Claude, text starting with `!`, `#`, `/` or `@` is sent unchanged and the result carries a `warnings` entry (for example `leading-bang-runs-shell`), because Claude Code gives those characters a meaning of its own.",
-                    "`--as-file-pointer` writes the text to `<pane-dir>/prompts/<pane-id>/<timestamp>.md` (readable only by you) and sends the one line `Read and follow <path>`; the result includes `promptFile`. Prefer it for long prompts."
+                    "`--as-file-pointer` writes the text to `<pane-dir>/prompts/<pane-id>/<timestamp>.md` (readable only by you) and sends the one line `Read and follow <path>`; the result includes `promptFile`. Prefer it for long prompts.",
+                    "With --interrupt, Pane sends the stop key only while the agent is active, waits for an empty idle composer, then submits. If readiness times out, replacement text is not sent. A queued result is not read yet: delivery.message explains the delay; never resend queued text. Interrupt success requires delivery.state: taken. Unknown agents and occupied composers are rejected without typing."
                 ]
             },
             "panels wait": {
@@ -11643,7 +11761,7 @@ exports.RUNPANE_CONTRACT = {
             "panels open": {
                 "name": "panels open",
                 "summary": "Open a URL or file as a browser/editor tab in a Pane, in split view beside the agent by default.",
-                "details": "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: .html/.htm files render in a browser tab, other files open in an editor tab. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
+                "details": "Opens a tab inside a Pane (default: the Pane of the calling panel, from PANE_SESSION_ID). Use it to show the user an HTML page, plan, report, local dev server, or file beside the conversation. --url opens a browser tab (http, https, or file). --file opens a file inside the Pane worktree: files open in an editor tab with read-only previews for supported formats, including HTML source. Tabs open in split view beside the agent by default; --tab keeps them in the current group. An existing tab showing the same URL or file is reused. Never raises or focuses the Pane window.",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -11663,7 +11781,7 @@ exports.RUNPANE_CONTRACT = {
                         "name": "--file",
                         "value": "<path>",
                         "required": false,
-                        "description": "File inside the Pane worktree, relative or absolute. WSL panes accept Linux, Windows drive, and WSL UNC paths without manual conversion. .html/.htm renders in a browser tab; other files open in an editor tab."
+                        "description": "File inside the Pane worktree, relative or absolute. WSL panes accept Linux, Windows drive, and WSL UNC paths without manual conversion. Files open in an editor tab; supported formats have read-only previews, including HTML source."
                     },
                     {
                         "name": "--title",
@@ -11719,7 +11837,7 @@ exports.RUNPANE_CONTRACT = {
                 ],
                 "notes": [
                     "Prefer this over opening the system browser when showing the user a page, plan, report, or dev server.",
-                    "Write plans and reports as self-contained HTML files, then open them with --file; rerunning the command on the same file reuses its tab.",
+                    "Write plans and reports as self-contained HTML files. Use --url with a file URL to render a page in a live browser, or --file to inspect its read-only source; reopening the same target reuses its tab.",
                     "Opening a tab does not steal window focus; use `panes focus` only on explicit user request."
                 ]
             },
@@ -13121,8 +13239,8 @@ exports.RUNPANE_CONTRACT = {
             },
             "sessions create": {
                 "name": "sessions create",
-                "summary": "Create a durable named orchestration Session and its hidden terminal owner.",
-                "details": "Create a durable named orchestration Session and its hidden terminal owner.",
+                "summary": "Create a durable named orchestration Session and its hidden terminal owner; JSON isPinned sets the pin star (default false).",
+                "details": "Create a durable named orchestration Session and its hidden terminal owner; JSON isPinned sets the pin star (default false).",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -13140,7 +13258,9 @@ exports.RUNPANE_CONTRACT = {
                     "sessionResult"
                 ],
                 "notes": [
-                    "Structured input accepts launchCommand (full command including arguments; empty uses the selected agent default) and profile (Session behavior instructions). Creating/opening a Session submits no automatic prompt. Changes apply on next terminal launch."
+                    "Structured input accepts launchCommand (full command including arguments; empty uses the selected agent default) and profile (Session behavior instructions). Creating/opening a Session submits no automatic prompt. Changes apply on next terminal launch.",
+                    "JSON isPinned: true/false sets the UI pin star. Creation defaults to false; update preserves the pin when omitted.",
+                    "Create-time isPinned requires an updated Pane app. Older apps may ignore the field; use sessions pin after creation and read back the result."
                 ]
             },
             "sessions get": {
@@ -13167,8 +13287,8 @@ exports.RUNPANE_CONTRACT = {
             },
             "sessions update": {
                 "name": "sessions update",
-                "summary": "Update a Session overview from structured JSON.",
-                "details": "Update a Session overview from structured JSON.",
+                "summary": "Update a Session overview from structured JSON; isPinned sets the UI pin star.",
+                "details": "Update a Session overview from structured JSON; isPinned sets the UI pin star.",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -13186,7 +13306,8 @@ exports.RUNPANE_CONTRACT = {
                     "sessionResult"
                 ],
                 "notes": [
-                    "Structured input accepts launchCommand (full command including arguments; empty uses the selected agent default) and profile (Session behavior instructions). Creating/opening a Session submits no automatic prompt. Changes apply on next terminal launch."
+                    "Structured input accepts launchCommand (full command including arguments; empty uses the selected agent default) and profile (Session behavior instructions). Creating/opening a Session submits no automatic prompt. Changes apply on next terminal launch.",
+                    "JSON isPinned: true/false sets the UI pin star. Creation defaults to false; update preserves the pin when omitted."
                 ]
             },
             "sessions set-agent": {
@@ -13694,6 +13815,76 @@ exports.RUNPANE_CONTRACT = {
                     "Model and effort become agent flags: claude --model/--effort, codex -m and -c model_reasoning_effort, cursor-agent --model. Cursor effort is not supported and is rejected before side effects.",
                     "Run it from the checkout being handed off. The receiver works in a new Pane on the destination and pushes back to your branch, so stop changing that branch yourself."
                 ]
+            },
+            "sessions unpin": {
+                "name": "sessions unpin",
+                "summary": "Declaratively unpin a named Session using the UI pin state; repeated requests keep the requested state.",
+                "details": "Declaratively unpin a named Session using the UI pin state; repeated requests keep the requested state.",
+                "requiresPaneDaemon": true,
+                "mutates": true,
+                "arguments": [
+                    {
+                        "name": "--session",
+                        "value": "<id|name>",
+                        "required": true,
+                        "description": "Named Session id or exact name."
+                    },
+                    {
+                        "name": "--json",
+                        "required": false,
+                        "description": "Print JSON output."
+                    },
+                    {
+                        "name": "--pane-dir",
+                        "value": "<path>",
+                        "required": false,
+                        "description": "Connect to a specific Pane data directory."
+                    }
+                ],
+                "examples": [
+                    "runpane sessions unpin --session <id|name> [--json] [--pane-dir <path>]"
+                ],
+                "jsonSchemas": [
+                    "sessionResult"
+                ],
+                "notes": [
+                    "Uses the same Session update path as the UI. The requested pin state is idempotent."
+                ]
+            },
+            "sessions pin": {
+                "name": "sessions pin",
+                "summary": "Declaratively pin a named Session using the UI pin state; repeated requests keep the requested state.",
+                "details": "Declaratively pin a named Session using the UI pin state; repeated requests keep the requested state.",
+                "requiresPaneDaemon": true,
+                "mutates": true,
+                "arguments": [
+                    {
+                        "name": "--session",
+                        "value": "<id|name>",
+                        "required": true,
+                        "description": "Named Session id or exact name."
+                    },
+                    {
+                        "name": "--json",
+                        "required": false,
+                        "description": "Print JSON output."
+                    },
+                    {
+                        "name": "--pane-dir",
+                        "value": "<path>",
+                        "required": false,
+                        "description": "Connect to a specific Pane data directory."
+                    }
+                ],
+                "examples": [
+                    "runpane sessions pin --session <id|name> [--json] [--pane-dir <path>]"
+                ],
+                "jsonSchemas": [
+                    "sessionResult"
+                ],
+                "notes": [
+                    "Uses the same Session update path as the UI. The requested pin state is idempotent."
+                ]
             }
         },
         "managedBlock": [