runpane 2.4.174 → 2.4.175

package/dist/generated/contract.js

@@ -305,7 +305,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "workspace list",
-            "summary": "List your machines on Tailscale and whether each has joined workspaces.",
+            "summary": "List the machines on your tailnet, each with its owner, and whether each answers workspaces.",
             "usage": [
                 "runpane workspace list [--json] [--pane-dir <path>]"
             ],
@@ -340,7 +340,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "workspace read",
-            "summary": "Print a file from one of your machines; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
+            "summary": "Print a file from a machine on your tailnet; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
             "usage": [
                 "runpane workspace [<machine>] read <path> [--json]"
             ],
@@ -351,7 +351,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "workspace write",
-            "summary": "Write stdin to a file on one of your machines, creating parent folders.",
+            "summary": "Write stdin to a file on a machine on your tailnet, creating parent folders.",
             "usage": [
                 "runpane workspace [<machine>] write <path> [--json]"
             ],
@@ -403,7 +403,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "panes create",
-            "summary": "Create user-visible Panes (Pane sessions) backed by Pane-managed worktrees for feature/PR work and open terminal-backed tool tabs.",
+            "summary": "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create a Pane (a new worktree) only when the work's branch has no Pane yet; for review, audit, fix or QA on existing work use `panels create --pane <id>`.",
             "usage": [
                 "runpane panes create --repo <selector> --name <name> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options] [--pane-dir <path>]",
                 "runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--source user|agent] [--focus|--no-focus] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options] [--pane-dir <path>]",
@@ -528,7 +528,7 @@ exports.RUNPANE_CONTRACT = {
         },
         {
             "name": "panels create",
-            "summary": "Create a terminal-backed tool panel inside an existing Pane session.",
+            "summary": "Open a new agent or terminal tab inside an existing Pane, sharing its worktree. The default for review, QA, fixes and any other agent on work that already has a Pane.",
             "usage": [
                 "runpane panels create --pane <pane-id> --agent <codex|claude|cursor> [--source user|agent] [--focus|--no-focus] [--wait-ready] --yes [--json] [--pane-dir <path>]",
                 "runpane panels create --pane <pane-id> --tool-command <command> [--agent <codex|claude|cursor>] [--title <title>] [--focus|--no-focus] [--wait-ready] --yes [--json] [--pane-dir <path>]"
@@ -2194,7 +2194,7 @@ exports.RUNPANE_CONTRACT = {
                 "  runpane workspace <machine> <runpane command>      (any command that talks to Pane, e.g. sessions list --json)",
                 "  runpane workspace enable|disable",
                 "",
-                "<machine> is a Tailscale name, unique prefix, or IP. Only machines signed in to your own Tailscale login are reachable.",
+                "<machine> is a Tailscale name, unique prefix, or IP. Your own machines are reachable, and a teammate's machine when its owner set Who can connect to Everyone on tailnet.",
                 "Without <machine>, read, write, and exec route a path that cannot exist here (C:\\... on a Mac) to the one joined machine it fits.",
                 "Commands that only run here (doctor, agent-context, mcp, docs) run there with: runpane workspace <machine> exec -- 'runpane doctor'"
             ],
@@ -2257,7 +2257,7 @@ exports.RUNPANE_CONTRACT = {
                 "  runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]",
                 "  runpane panes create --from-json <path|-> [--yes] [--json]",
                 "",
-                "Creates user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.",
+                "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.",
                 "",
                 "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.",
                 "",
@@ -3068,7 +3068,7 @@ exports.RUNPANE_CONTRACT = {
                 "Usage:",
                 "  runpane workspace list [--json] [--pane-dir <path>]",
                 "",
-                "List your machines on Tailscale and whether each has joined workspaces.",
+                "List the machines on your tailnet, each with its owner, and whether each answers workspaces.",
                 "",
                 "Options:",
                 "  --json                          Print machine-readable output."
@@ -3095,7 +3095,7 @@ exports.RUNPANE_CONTRACT = {
                 "Usage:",
                 "  runpane workspace [<machine>] read <path> [--json]",
                 "",
-                "Print a file from one of your machines; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
+                "Print a file from a machine on your tailnet; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
                 "",
                 "Options:",
                 "  <machine>                       Tailscale machine name, unique prefix, MagicDNS name, or Tailscale IP. Omit it to route a path that cannot exist here to the one joined machine it fits.",
@@ -3106,7 +3106,7 @@ exports.RUNPANE_CONTRACT = {
                 "Usage:",
                 "  runpane workspace [<machine>] write <path> [--json]",
                 "",
-                "Write stdin to a file on one of your machines, creating parent folders.",
+                "Write stdin to a file on a machine on your tailnet, creating parent folders.",
                 "",
                 "Options:",
                 "  <machine>                       Tailscale machine name, unique prefix, MagicDNS name, or Tailscale IP. Omit it to route a path that cannot exist here to the one joined machine it fits.",
@@ -3468,7 +3468,7 @@ exports.RUNPANE_CONTRACT = {
                 "  python -m runpane panes create --repo <selector> --name <name> --tool-command <command> [--agent <codex|claude|cursor>] [--base <ref>] [--branch <name>] [--prompt-file <path|->] [options]",
                 "  runpane panes create --from-json <path|-> [--yes] [--json]",
                 "",
-                "Creates user-visible Panes (Pane sessions) for feature/PR work in a saved repository and opens a terminal-backed tool tab. Pane creates and owns the worktree/branch for each new Pane.",
+                "Creates a Pane in a saved repository and opens a terminal-backed tool tab. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create one only when the work's branch has no Pane yet; for existing work use `runpane panels create --pane <id>`.",
                 "",
                 "A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.",
                 "",
@@ -5809,7 +5809,9 @@ exports.RUNPANE_CONTRACT = {
                         "required": [
                             "name",
                             "os",
-                            "online"
+                            "online",
+                            "owner",
+                            "mine"
                         ],
                         "additionalProperties": false,
                         "properties": {
@@ -5825,6 +5827,14 @@ exports.RUNPANE_CONTRACT = {
                             },
                             "online": {
                                 "type": "boolean"
+                            },
+                            "owner": {
+                                "type": "string",
+                                "description": "Tailscale login of the machine's owner."
+                            },
+                            "mine": {
+                                "type": "boolean",
+                                "description": "Signed in to this machine's own Tailscale login."
                             }
                         }
                     }
@@ -9862,11 +9872,10 @@ exports.RUNPANE_CONTRACT = {
             "rules": [
                 "Start with `runpane doctor --json` to understand wrapper, platform, daemon reachability, and the next safe commands before mutating Pane state.",
                 "In a Pane repository checkout, if `runpane` is not on PATH, build the local wrapper with `pnpm --filter runpane build` and run it with Node 22 or newer, for example `node packages/runpane/dist/cli.js doctor --json`.",
-                "Happy path for any user request to use Pane/RunPane: run `runpane doctor --json`, read `runpane agent-context --json`, resolve or add the saved base repo, create the requested visible Pane with a complete command such as `runpane panes create --repo <repo> --name <name> --agent <agent> --prompt \"<task>\" --source agent --no-focus --wait-ready --yes --json` (the new Pane is pinned by default; add `--no-pinned` for a throwaway Pane, add `--base-branch <ref>` to branch from something other than the repository default, or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`. For long-lived supervision, use `runpane watch --follow` instead of polling wait or screen.",
+                "Happy path for any user request to use Pane/RunPane: run `runpane doctor --json`, read `runpane agent-context --json`, resolve or add the saved base repo, then route by the rule 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane: if the work's branch already has a Pane (find it with `runpane panes list --repo <repo> --json` by matching the PR's head branch against `git -C <worktreePath> branch --show-current`), open a new agent tab in it with `runpane panels create --pane <id> --agent <agent> --initial-input \"<task>\" --source agent --no-focus --wait-ready --yes --json`; only when the branch has no Pane yet, create one with a complete command such as `runpane panes create --repo <repo> --name <name> --agent <agent> --prompt \"<task>\" --source agent --no-focus --wait-ready --yes --json` (the new Pane is pinned by default; add `--no-pinned` for a throwaway Pane, add `--base-branch <ref>` to branch from something other than the repository default, or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`. For long-lived supervision, use `runpane watch --follow` instead of polling wait or screen.",
                 "Treat Pane as the user's visible cockpit for watching/co-driving work. Do not create Panes or panels for private delegation unless the user asked for visible Pane orchestration or the result should appear in the Pane app.",
                 "Register the saved base repository once with `repos add`; do not register a pre-created worktree as a separate repo unless the user explicitly asks.",
-                "Use `panes create` for separate visible Panes (Pane sessions) for feature/PR work. Pane creates and owns the worktree/branch for each new Pane.",
-                "Use `panels create` for reviewer/helper/clean-context tabs that should stay inside an existing Pane and share that Pane's worktree.",
+                "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Use `panes create` only when the work's branch has no Pane yet (new work, or an existing PR with no Pane), since each new Pane creates a worktree. Every later agent for that branch opens as a new tab in its Pane with `panels create --pane <id>`, never a new Pane. Tabs share one checkout: only the implementer changes the branch or HEAD, one writer at a time; review, audit and QA tabs never run `git checkout`, `reset` or `stash`.",
                 "For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.",
                 "Skill routing: Pane's skills live in `<PANE_DIR>/skills/pane-chat/skills/`, and the Pane Chat entry point is `<PANE_DIR>/skills/pane-chat/pane-orchestrator/SKILL.md`; read the skill that matches the request, such as `discussion`, `create-ticket`, `tdd`, `prepare-pr`, or `review`.",
                 "When an agent creates Panes or panels, pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved; `panes create` pins the new Pane into the UI's favorite/pin set by default, so no follow-up `panes pin` call is needed and `--no-pinned` is the opt-out for throwaway Panes.",
@@ -9952,7 +9961,7 @@ exports.RUNPANE_CONTRACT = {
                 },
                 {
                     "name": "panes create",
-                    "summary": "Create user-visible Panes (Pane sessions) backed by Pane-managed worktrees for feature/PR work and open terminal-backed tool tabs.",
+                    "summary": "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create a Pane (a new worktree) only when the work's branch has no Pane yet; for review, audit, fix or QA on existing work use `panels create --pane <id>`.",
                     "arguments": [
                         "--repo <selector>",
                         "--name <name>",
@@ -10033,7 +10042,7 @@ exports.RUNPANE_CONTRACT = {
                 },
                 {
                     "name": "panels create",
-                    "summary": "Create reviewer/helper terminal tabs inside an existing Pane; they share that Pane's worktree.",
+                    "summary": "Open reviewer, QA, fix or helper agent tabs inside an existing Pane; they share that Pane's worktree. The default for any later agent on existing work.",
                     "arguments": [
                         "--pane <pane-id>",
                         "--agent <codex|claude|cursor>",
@@ -10631,8 +10640,8 @@ exports.RUNPANE_CONTRACT = {
             },
             "panes create": {
                 "name": "panes create",
-                "summary": "Create user-visible Panes (Pane sessions) backed by Pane-managed worktrees for feature/PR work and open terminal-backed tool tabs.",
-                "details": "Use this when the user wants separate visible Panes (Pane sessions) for feature or PR work. Select the saved base repository, choose a built-in agent or custom terminal command, and optionally send initial input after the tool starts. Pane creates and owns a git worktree/branch for each new Pane; do not pre-create a git worktree and register it as a separate repo unless the user explicitly asks. For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.",
+                "summary": "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create a Pane (a new worktree) only when the work's branch has no Pane yet; for review, audit, fix or QA on existing work use `panels create --pane <id>`.",
+                "details": "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Use this only when the work's branch has no Pane yet: new work, or an existing PR with no Pane. Each new Pane creates a worktree that checks out, installs and often builds, so creating several at once can freeze the machine. First find the feature's Pane with `runpane panes list --repo <repo> --json` by matching the PR's head branch (`gh pr view <n> --json headRefName`) against `git -C <worktreePath> branch --show-current`. For review, follow-up review, fixes, QA or any other agent on work that already has a Pane, use `runpane panels create --pane <id>` to open a new agent tab in that Pane instead. Select the saved base repository, choose a built-in agent or custom terminal command, and optionally send initial input after the tool starts. Pane creates and owns a git worktree/branch for each new Pane; do not pre-create a git worktree and register it as a separate repo unless the user explicitly asks. For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -10796,10 +10805,9 @@ exports.RUNPANE_CONTRACT = {
                 ],
                 "notes": [
                     "At least one of --agent or --tool-command is required unless --from-json is used.",
-                    "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism.",
+                    "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane: before creating one, find the feature's Pane with `runpane panes list --repo <repo> --json` by matching the PR's head branch (`gh pr view <n> --json headRefName`) against `git -C <worktreePath> branch --show-current`, and add a tab with `panels create --pane <id>` when it exists.",
                     "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.",
                     "`panes create --base <ref> --branch <name> --prompt-file <file>` replaces `git worktree add` plus `panes adopt`: Pane creates the worktree on exactly that branch name. `--branch` is checked with `git check-ref-format --branch` and fails if the branch already exists; `--worktree-name` still names the directory.",
-                    "Use `panels create` instead when a reviewer/helper should share an existing Pane's worktree.",
                     "Agent-created Panes should pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved. `panes create` pins the new Pane by default, so a follow-up `panes pin` call is unnecessary; pass `--no-pinned` for throwaway shells or bulk imports. `--pinned` is still accepted and is now a no-op. Inside a Session orchestrator (`PANE_ORCHESTRATION_SESSION_ID` set), new Panes are associated with that Session automatically; `--no-associate` opts out. A failed association is reported on the item and never undoes the Pane.",
                     "The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.",
                     "Use --initial-input-file for multi-line prompts or shell-sensitive initial input. A long or multi-line prompt is never typed into the shell: on bash, zsh or sh the agent launches with `\"$(cat '<prompt file>')\"` reading a private copy under `<pane-dir>/prompts/<pane-id>/`; on PowerShell, cmd, fish or WSL the prompt is pasted into the agent's composer once it is ready.",
@@ -11651,8 +11659,8 @@ exports.RUNPANE_CONTRACT = {
             },
             "panels create": {
                 "name": "panels create",
-                "summary": "Create a reviewer/helper terminal tab inside an existing Pane.",
-                "details": "Use this to add reviewer, helper, or clean-context tabs to an existing Pane. The new panel shares the existing Pane's worktree and branch; it does not create a separate Pane session. Use `panes create` instead when the user wants a separate visible Pane (Pane session) for feature/PR work. Agent/orchestrator-created panels should pass --source agent or --no-focus so the user stays in the implementation tab. The daemon initializes the terminal immediately and can wait for CLI readiness.",
+                "summary": "Open a new agent tab (reviewer, auditor, QA, fix or helper) inside an existing Pane, sharing its worktree. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane: use this, not panes create, for any later agent on existing work.",
+                "details": "1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. This is the default way to start any later agent on work that already has a Pane, including reviewers, follow-up reviewers, auditors, fix implementers, QA and clean-context helpers. The new tab is a fresh agent that shares the Pane's worktree and branch; it does not create a new worktree. Review, audit and QA tabs never run `git checkout`, `reset` or `stash`, and a fix tab starts only after the previous writer has stopped. Use `panes create` only when the work's branch has no Pane yet. Agent/orchestrator-created panels should pass --source agent or --no-focus so the user stays in the implementation tab. The daemon initializes the terminal immediately and can wait for CLI readiness.",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -13570,8 +13578,8 @@ exports.RUNPANE_CONTRACT = {
             },
             "workspace list": {
                 "name": "workspace list",
-                "summary": "List your machines on Tailscale and whether each has joined workspaces.",
-                "details": "Shows this machine's workspace state, then each of your other Mac, Windows, and Linux machines with its OS, online state, and shell. Only machines signed in to your own Tailscale login appear.",
+                "summary": "List the machines on your tailnet, each with its owner, and whether each answers workspaces.",
+                "details": "Shows this machine's workspace state, then each other Mac, Windows, and Linux machine on your tailnet with its OS, online state, and shell. Your own machines come first; other people's machines carry their owner's login and answer only when their owner lets you in.",
                 "requiresPaneDaemon": false,
                 "mutates": false,
                 "arguments": [
@@ -13591,7 +13599,7 @@ exports.RUNPANE_CONTRACT = {
             "workspace enable": {
                 "name": "workspace enable",
                 "summary": "Put this machine's Pane on your tailnet for runpane workspace (the default when Tailscale is signed in).",
-                "details": "Serves this Pane's daemon with tailscale serve on port 8443 in HTTP proxy mode. Only your own Tailscale login is accepted; nothing is opened to the internet.",
+                "details": "Serves this Pane's daemon with tailscale serve on port 8443 in HTTP proxy mode. Only your own Tailscale login is accepted unless you set Who can connect to Everyone on tailnet; nothing is opened to the internet.",
                 "requiresPaneDaemon": true,
                 "mutates": true,
                 "arguments": [
@@ -13630,7 +13638,7 @@ exports.RUNPANE_CONTRACT = {
             },
             "workspace read": {
                 "name": "workspace read",
-                "summary": "Print a file from one of your machines; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
+                "summary": "Print a file from a machine on your tailnet; any path form works (C:\\..., /mnt/c/..., /home/..., ~/...).",
                 "details": "Reads the same way on every OS. On Windows, /mnt/c/... reaches C:\\... and WSL paths such as /home/<user>/... are read through \\\\wsl.localhost\\<distro>\\. Directories list their entries.",
                 "requiresPaneDaemon": false,
                 "mutates": false,
@@ -13661,7 +13669,7 @@ exports.RUNPANE_CONTRACT = {
             },
             "workspace write": {
                 "name": "workspace write",
-                "summary": "Write stdin to a file on one of your machines, creating parent folders.",
+                "summary": "Write stdin to a file on a machine on your tailnet, creating parent folders.",
                 "details": "Takes the same path forms as workspace read. Content comes from stdin and replaces the file.",
                 "requiresPaneDaemon": false,
                 "mutates": true,