runpane 2.4.30 → 2.4.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/dist/cli.d.ts.map +1 -1
  2. package/dist/cli.js +6 -0
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands.d.ts +1 -0
  5. package/dist/commands.d.ts.map +1 -1
  6. package/dist/commands.js +6 -0
  7. package/dist/commands.js.map +1 -1
  8. package/dist/generated/contract.d.ts +160 -16
  9. package/dist/generated/contract.d.ts.map +1 -1
  10. package/dist/generated/contract.js +296 -7
  11. package/dist/generated/contract.js.map +1 -1
  12. package/dist/installers.d.ts +1 -0
  13. package/dist/installers.d.ts.map +1 -1
  14. package/dist/installers.js +12 -1
  15. package/dist/installers.js.map +1 -1
  16. package/dist/localControl.d.ts +1 -0
  17. package/dist/localControl.d.ts.map +1 -1
  18. package/dist/localControl.js +51 -2
  19. package/dist/localControl.js.map +1 -1
  20. package/package.json +1 -1
package/dist/generated/contract.js CHANGED
@@ -198,6 +198,30 @@ exports.RUNPANE_CONTRACT = {
198
198
  "paneArchiveResult"
199
199
  ]
200
200
  },
201
+ {
202
+ "name": "panes pin",
203
+ "summary": "Declaratively pin a Pane; pinned is the Pane UI's favorite/pin star and repeated requests are idempotent.",
204
+ "usage": [
205
+ "runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]"
206
+ ],
207
+ "mutates": true,
208
+ "jsonSchemas": [
209
+ "panePinRequest",
210
+ "panePinResult"
211
+ ]
212
+ },
213
+ {
214
+ "name": "panes unpin",
215
+ "summary": "Declaratively unpin a Pane; pinned is the Pane UI's favorite/pin star and repeated requests are idempotent.",
216
+ "usage": [
217
+ "runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]"
218
+ ],
219
+ "mutates": true,
220
+ "jsonSchemas": [
221
+ "panePinRequest",
222
+ "panePinResult"
223
+ ]
224
+ },
201
225
  {
202
226
  "name": "panels create",
203
227
  "summary": "Create a terminal-backed tool panel inside an existing Pane session.",
@@ -524,6 +548,10 @@ exports.RUNPANE_CONTRACT = {
524
548
  "name": "--focus",
525
549
  "description": "Explicitly focus the created pane or panel."
526
550
  },
551
+ {
552
+ "name": "--pinned",
553
+ "description": "Create the pane already pinned (the UI's favorite/pin star)."
554
+ },
527
555
  {
528
556
  "name": "--force",
529
557
  "description": "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes."
@@ -692,8 +720,10 @@ exports.RUNPANE_CONTRACT = {
692
720
  " runpane panes list [--repo <selector>] [--json]",
693
721
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]",
694
722
  " runpane panes archive --pane <pane-id> [--force] [--source user|agent] --yes [--json]",
723
+ " runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]",
724
+ " runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]",
695
725
  "",
696
- "Run \"runpane help panes list\", \"runpane help panes create\", or \"runpane help panes archive\" for command-specific options."
726
+ "Run \"runpane help panes <command>\" for command-specific options."
697
727
  ],
698
728
  "panes list": [
699
729
  "Usage:",
@@ -732,6 +762,7 @@ exports.RUNPANE_CONTRACT = {
732
762
  " --source <user|agent> Mark mutation source; agent implies background creation",
733
763
  " --no-focus Create in the background without stealing focus",
734
764
  " --focus Explicitly focus the created pane",
765
+ " --pinned Create already pinned (the UI's favorite/pin star)",
735
766
  " --pane-dir <path> Connect to a specific Pane data directory",
736
767
  " --json Print machine-readable output",
737
768
  " --dry-run Validate and preview without creating panes",
@@ -751,6 +782,32 @@ exports.RUNPANE_CONTRACT = {
751
782
  " --json Print machine-readable output",
752
783
  " --yes Skip confirmation for mutating commands"
753
784
  ],
785
+ "panes pin": [
786
+ "Usage:",
787
+ " runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]",
788
+ "",
789
+ "Declaratively pins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.",
790
+ "",
791
+ "Options:",
792
+ " --pane <pane-id> Pane/session id to pin",
793
+ " --pane-dir <path> Connect to a specific Pane data directory",
794
+ " --json Print machine-readable output",
795
+ " --dry-run Validate and preview without pinning the pane",
796
+ " --yes Skip confirmation for mutating commands"
797
+ ],
798
+ "panes unpin": [
799
+ "Usage:",
800
+ " runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]",
801
+ "",
802
+ "Declaratively unpins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.",
803
+ "",
804
+ "Options:",
805
+ " --pane <pane-id> Pane/session id to unpin",
806
+ " --pane-dir <path> Connect to a specific Pane data directory",
807
+ " --json Print machine-readable output",
808
+ " --dry-run Validate and preview without unpinning the pane",
809
+ " --yes Skip confirmation for mutating commands"
810
+ ],
754
811
  "panels": [
755
812
  "Terminal-backed panel commands.",
756
813
  "",
@@ -1061,8 +1118,10 @@ exports.RUNPANE_CONTRACT = {
1061
1118
  " runpane panes list [--repo <selector>] [--json]",
1062
1119
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]",
1063
1120
  " runpane panes archive --pane <pane-id> [--force] [--source user|agent] --yes [--json]",
1121
+ " runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]",
1122
+ " runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]",
1064
1123
  "",
1065
- "Run \"runpane help panes list\", \"runpane help panes create\", or \"runpane help panes archive\" for command-specific options."
1124
+ "Run \"runpane help panes <command>\" for command-specific options."
1066
1125
  ],
1067
1126
  "panes list": [
1068
1127
  "Usage:",
@@ -1101,6 +1160,7 @@ exports.RUNPANE_CONTRACT = {
1101
1160
  " --source <user|agent> Mark mutation source; agent implies background creation",
1102
1161
  " --no-focus Create in the background without stealing focus",
1103
1162
  " --focus Explicitly focus the created pane",
1163
+ " --pinned Create already pinned (the UI's favorite/pin star)",
1104
1164
  " --pane-dir <path> Connect to a specific Pane data directory",
1105
1165
  " --json Print machine-readable output",
1106
1166
  " --dry-run Validate and preview without creating panes",
@@ -1120,6 +1180,32 @@ exports.RUNPANE_CONTRACT = {
1120
1180
  " --json",
1121
1181
  " --yes"
1122
1182
  ],
1183
+ "panes pin": [
1184
+ "Usage:",
1185
+ " runpane panes pin --pane <pane-id> --yes [--dry-run] [--json]",
1186
+ "",
1187
+ "Declaratively pins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.",
1188
+ "",
1189
+ "Options:",
1190
+ " --pane <pane-id>",
1191
+ " --pane-dir <path>",
1192
+ " --json",
1193
+ " --dry-run",
1194
+ " --yes"
1195
+ ],
1196
+ "panes unpin": [
1197
+ "Usage:",
1198
+ " runpane panes unpin --pane <pane-id> --yes [--dry-run] [--json]",
1199
+ "",
1200
+ "Declaratively unpins a Pane using the Pane UI's favorite/pin star. Repeating the command is idempotent and never changes focus. Use --dry-run to validate and preview without mutating.",
1201
+ "",
1202
+ "Options:",
1203
+ " --pane <pane-id>",
1204
+ " --pane-dir <path>",
1205
+ " --json",
1206
+ " --dry-run",
1207
+ " --yes"
1208
+ ],
1123
1209
  "panels": [
1124
1210
  "Terminal-backed panel commands.",
1125
1211
  "",
@@ -1373,11 +1459,13 @@ exports.RUNPANE_CONTRACT = {
1373
1459
  "`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.",
1374
1460
  "`runpane panes list` lists Pane sessions, optionally scoped to one saved repository.",
1375
1461
  "`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.",
1462
+ "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.",
1376
1463
  "`runpane panes archive` archives a Pane exactly like the UI Archive action, including removal of its Pane-managed git worktree, and refuses (unless `--force`) when the pane's branch has uncommitted, untracked, or unpushed-to-remote changes. It waits for worktree removal to finish before returning and reports the outcome in `worktreeCleanup`.",
1377
1464
  "`runpane panels list` lists tool panels inside one Pane session.",
1378
1465
  "`runpane panels output` reads bounded recent terminal output from one panel and strips common terminal control noise for agent use.",
1379
1466
  "`runpane panels input` sends exact input bytes to one terminal panel. Prefer `--input-file` for newlines, Ctrl-C, quotes, or shell-sensitive text.",
1380
1467
  "`runpane panes create --prompt` is an alias for `--initial-input`; request JSON and daemon payloads should use the canonical `initialInput` field.",
1468
+ "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.",
1381
1469
  "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'`."
1382
1470
  ],
1383
1471
  "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.",
@@ -1515,6 +1603,7 @@ exports.RUNPANE_CONTRACT = {
1515
1603
  "Kick off discussion",
1516
1604
  "--source",
1517
1605
  "agent",
1606
+ "--pinned",
1518
1607
  "--dry-run",
1519
1608
  "--yes",
1520
1609
  "--json"
@@ -1538,6 +1627,22 @@ exports.RUNPANE_CONTRACT = {
1538
1627
  "--yes",
1539
1628
  "--json"
1540
1629
  ],
1630
+ [
1631
+ "panes",
1632
+ "pin",
1633
+ "--pane",
1634
+ "session-1",
1635
+ "--yes",
1636
+ "--json"
1637
+ ],
1638
+ [
1639
+ "panes",
1640
+ "unpin",
1641
+ "--pane",
1642
+ "session-1",
1643
+ "--yes",
1644
+ "--json"
1645
+ ],
1541
1646
  [
1542
1647
  "panels",
1543
1648
  "list",
@@ -2123,6 +2228,9 @@ exports.RUNPANE_CONTRACT = {
2123
2228
  "sessionPrompt": {
2124
2229
  "type": "string"
2125
2230
  },
2231
+ "pinned": {
2232
+ "type": "boolean"
2233
+ },
2126
2234
  "tool": {
2127
2235
  "oneOf": [
2128
2236
  {
@@ -2223,7 +2331,8 @@ exports.RUNPANE_CONTRACT = {
2223
2331
  "required": [
2224
2332
  "ok",
2225
2333
  "index",
2226
- "name"
2334
+ "name",
2335
+ "pinned"
2227
2336
  ],
2228
2337
  "properties": {
2229
2338
  "ok": {
@@ -2235,6 +2344,9 @@ exports.RUNPANE_CONTRACT = {
2235
2344
  "name": {
2236
2345
  "type": "string"
2237
2346
  },
2347
+ "pinned": {
2348
+ "type": "boolean"
2349
+ },
2238
2350
  "sessionId": {
2239
2351
  "type": "string"
2240
2352
  },
@@ -2356,6 +2468,7 @@ exports.RUNPANE_CONTRACT = {
2356
2468
  "enum": [
2357
2469
  "codex-update",
2358
2470
  "agent-prompt",
2471
+ "submission_unverified",
2359
2472
  "unknown"
2360
2473
  ]
2361
2474
  },
@@ -2408,6 +2521,12 @@ exports.RUNPANE_CONTRACT = {
2408
2521
  "verifiedSubmitted": {
2409
2522
  "type": "boolean"
2410
2523
  },
2524
+ "staged": {
2525
+ "type": "boolean"
2526
+ },
2527
+ "attempts": {
2528
+ "type": "number"
2529
+ },
2411
2530
  "sentAt": {
2412
2531
  "type": "string"
2413
2532
  },
@@ -2422,6 +2541,7 @@ exports.RUNPANE_CONTRACT = {
2422
2541
  "enum": [
2423
2542
  "codex-update",
2424
2543
  "agent-prompt",
2544
+ "submission_unverified",
2425
2545
  "unknown"
2426
2546
  ]
2427
2547
  },
@@ -2523,7 +2643,8 @@ exports.RUNPANE_CONTRACT = {
2523
2643
  "status",
2524
2644
  "worktreePath",
2525
2645
  "repoId",
2526
- "panelCount"
2646
+ "panelCount",
2647
+ "pinned"
2527
2648
  ],
2528
2649
  "properties": {
2529
2650
  "id": {
@@ -2550,6 +2671,9 @@ exports.RUNPANE_CONTRACT = {
2550
2671
  "panelCount": {
2551
2672
  "type": "number"
2552
2673
  },
2674
+ "pinned": {
2675
+ "type": "boolean"
2676
+ },
2553
2677
  "createdAt": {
2554
2678
  "type": "string"
2555
2679
  },
@@ -2587,6 +2711,51 @@ exports.RUNPANE_CONTRACT = {
2587
2711
  },
2588
2712
  "additionalProperties": false
2589
2713
  },
2714
+ "panePinRequest": {
2715
+ "type": "object",
2716
+ "required": [
2717
+ "paneId",
2718
+ "pinned"
2719
+ ],
2720
+ "properties": {
2721
+ "paneId": {
2722
+ "type": "string"
2723
+ },
2724
+ "pinned": {
2725
+ "type": "boolean"
2726
+ },
2727
+ "dryRun": {
2728
+ "type": "boolean"
2729
+ }
2730
+ },
2731
+ "additionalProperties": false
2732
+ },
2733
+ "panePinResult": {
2734
+ "type": "object",
2735
+ "required": [
2736
+ "ok",
2737
+ "paneId",
2738
+ "pinned"
2739
+ ],
2740
+ "properties": {
2741
+ "ok": {
2742
+ "const": true
2743
+ },
2744
+ "paneId": {
2745
+ "type": "string"
2746
+ },
2747
+ "pinned": {
2748
+ "type": "boolean"
2749
+ },
2750
+ "dryRun": {
2751
+ "const": true
2752
+ },
2753
+ "favoritePinnedAt": {
2754
+ "type": "string"
2755
+ }
2756
+ },
2757
+ "additionalProperties": false
2758
+ },
2590
2759
  "paneArchiveResult": {
2591
2760
  "oneOf": [
2592
2761
  {
@@ -3250,6 +3419,7 @@ exports.RUNPANE_CONTRACT = {
3250
3419
  "enum": [
3251
3420
  "codex-update",
3252
3421
  "agent-prompt",
3422
+ "submission_unverified",
3253
3423
  "unknown"
3254
3424
  ]
3255
3425
  },
@@ -3535,6 +3705,7 @@ exports.RUNPANE_CONTRACT = {
3535
3705
  "enum": [
3536
3706
  "codex-update",
3537
3707
  "agent-prompt",
3708
+ "submission_unverified",
3538
3709
  "unknown"
3539
3710
  ]
3540
3711
  },
@@ -3631,6 +3802,7 @@ exports.RUNPANE_CONTRACT = {
3631
3802
  "enum": [
3632
3803
  "codex-update",
3633
3804
  "agent-prompt",
3805
+ "submission_unverified",
3634
3806
  "unknown"
3635
3807
  ]
3636
3808
  },
@@ -3657,14 +3829,14 @@ exports.RUNPANE_CONTRACT = {
3657
3829
  "rules": [
3658
3830
  "Start with `runpane doctor --json` to understand wrapper, platform, daemon reachability, and the next safe commands before mutating Pane state.",
3659
3831
  "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`.",
3660
- "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` (or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`.",
3832
+ "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 --pinned --no-focus --wait-ready --yes --json` when it should stay visible (or omit `--pinned`, or use `--tool-command <command>` instead of `--agent <agent>`), then validate with `panels wait` or `panels screen`.",
3661
3833
  "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.",
3662
3834
  "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.",
3663
3835
  "Use `panes create` for separate visible Panes (Pane sessions) for feature/PR work. Pane creates and owns the worktree/branch for each new Pane.",
3664
3836
  "Use `panels create` for reviewer/helper/clean-context tabs that should stay inside an existing Pane and share that Pane's worktree.",
3665
3837
  "For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.",
3666
3838
  "Skill routing: when the user says `discussion`, `plan`, `simple-plan`, `create-plan`, or `implement`, or asks for those behaviors, 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 at https://github.com/dcouple/skills/raw/main/docs/readme-workflow-map.png. For where the local cache and Pane Chat bootstrap live in Pane, reference https://github.com/dcouple/Pane/pull/291. Use GitHub reads against https://github.com/dcouple/skills/tree/main/parsa only to inspect or refresh referenced skill files; do not clone or install it unless the user asks.",
3667
- "When an agent creates Panes or panels, pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved.",
3839
+ "When an agent creates Panes or panels, pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved; add `--pinned` when declaring a Pane that should remain in the UI's favorite/pin set.",
3668
3840
  "Use `runpane agent-context --json` for the full agent-facing CLI context, or `runpane agent-context --command <command> --json` for one detailed command definition.",
3669
3841
  "For `agent-context --command`, use canonical spaced names like `panes create`; copied forms like `panes.create` or `runpane panes create` are accepted too.",
3670
3842
  "Use `runpane repos list --json` to find the saved repository when unsure after doctor shows the daemon is reachable.",
@@ -3745,6 +3917,7 @@ exports.RUNPANE_CONTRACT = {
3745
3917
  "--initial-input-file <path|->",
3746
3918
  "--from-json <path|->",
3747
3919
  "--source <user|agent>",
3920
+ "--pinned",
3748
3921
  "--no-focus",
3749
3922
  "--focus",
3750
3923
  "--wait-ready",
@@ -3765,6 +3938,26 @@ exports.RUNPANE_CONTRACT = {
3765
3938
  "--json"
3766
3939
  ]
3767
3940
  },
3941
+ {
3942
+ "name": "panes pin",
3943
+ "summary": "Declaratively pin a Pane (the Pane UI's favorite/pin star) without changing focus.",
3944
+ "arguments": [
3945
+ "--pane <pane-id>",
3946
+ "--yes",
3947
+ "--dry-run",
3948
+ "--json"
3949
+ ]
3950
+ },
3951
+ {
3952
+ "name": "panes unpin",
3953
+ "summary": "Declaratively unpin a Pane (the Pane UI's favorite/pin star) without changing focus.",
3954
+ "arguments": [
3955
+ "--pane <pane-id>",
3956
+ "--yes",
3957
+ "--dry-run",
3958
+ "--json"
3959
+ ]
3960
+ },
3768
3961
  {
3769
3962
  "name": "panels create",
3770
3963
  "summary": "Create reviewer/helper terminal tabs inside an existing Pane; they share that Pane's worktree.",
@@ -4252,11 +4445,21 @@ exports.RUNPANE_CONTRACT = {
4252
4445
  "required": false,
4253
4446
  "description": "Explicitly focus the created pane."
4254
4447
  },
4448
+ {
4449
+ "name": "--pinned",
4450
+ "required": false,
4451
+ "description": "Create the pane already pinned (the Pane UI's favorite/pin star); does not imply focus."
4452
+ },
4255
4453
  {
4256
4454
  "name": "--yes",
4257
4455
  "required": false,
4258
4456
  "description": "Skip confirmation for mutating commands."
4259
4457
  },
4458
+ {
4459
+ "name": "--dry-run",
4460
+ "required": false,
4461
+ "description": "Validate and preview without mutating."
4462
+ },
4260
4463
  {
4261
4464
  "name": "--json",
4262
4465
  "required": false,
@@ -4294,9 +4497,11 @@ exports.RUNPANE_CONTRACT = {
4294
4497
  "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism.",
4295
4498
  "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.",
4296
4499
  "Use `panels create` instead when a reviewer/helper should share an existing Pane's worktree.",
4297
- "Agent-created Panes should pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved.",
4500
+ "Agent-created Panes should pass `--source agent --no-focus --wait-ready --yes --json` unless the user explicitly wants focus moved; add `--pinned` when the Pane should remain in the UI's favorite/pin set.",
4298
4501
  "The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.",
4299
4502
  "Use --initial-input-file for multi-line prompts or shell-sensitive initial input.",
4503
+ "With --wait-ready, verifiedSubmitted is earned from delivery evidence; routing initial input alone does not imply verified submission.",
4504
+ "If initialInput.blocked.kind is submission_unverified, do not submit again automatically. Inspect initialInput.staged and attempts, then run nextCommand to resolve the ambiguous composer state.",
4300
4505
  "When the JSON result includes nextCommand, run it to validate that the terminal produced output before reporting success.",
4301
4506
  "Multi-pane requests are created sequentially today. The --concurrency flag is accepted for compatibility, but agents should not rely on parallel creation.",
4302
4507
  "For POSIX or WSL command chaining, use a custom terminal command like `bash -lc 'cmd1 && cmd2 && cmd3'`.",
@@ -4355,6 +4560,90 @@ exports.RUNPANE_CONTRACT = {
4355
4560
  "Archiving a main-repo Pane (no Pane-managed worktree) always succeeds immediately since nothing is deleted from disk."
4356
4561
  ]
4357
4562
  },
4563
+ "panes pin": {
4564
+ "name": "panes pin",
4565
+ "summary": "Declaratively pin a Pane; pinned is the Pane UI's favorite/pin star.",
4566
+ "details": "Sets the requested pinned state to true without reading and toggling it. Repeating the command is idempotent and pinning never changes focus.",
4567
+ "requiresPaneDaemon": true,
4568
+ "mutates": true,
4569
+ "arguments": [
4570
+ {
4571
+ "name": "--pane",
4572
+ "value": "<pane-id>",
4573
+ "required": true,
4574
+ "description": "Pane/session id to pin."
4575
+ },
4576
+ {
4577
+ "name": "--yes",
4578
+ "required": false,
4579
+ "description": "Skip confirmation for mutating commands."
4580
+ },
4581
+ {
4582
+ "name": "--dry-run",
4583
+ "required": false,
4584
+ "description": "Validate and preview without mutating."
4585
+ },
4586
+ {
4587
+ "name": "--json",
4588
+ "required": false,
4589
+ "description": "Print machine-readable output."
4590
+ }
4591
+ ],
4592
+ "examples": [
4593
+ "runpane panes pin --pane <pane-id> --yes --json",
4594
+ "runpane panes pin --pane <pane-id> --dry-run --json"
4595
+ ],
4596
+ "jsonSchemas": [
4597
+ "panePinRequest",
4598
+ "panePinResult"
4599
+ ],
4600
+ "notes": [
4601
+ "This is a declarative set, not a toggle: retries leave an already-pinned Pane pinned.",
4602
+ "Pinning does not focus the Pane."
4603
+ ]
4604
+ },
4605
+ "panes unpin": {
4606
+ "name": "panes unpin",
4607
+ "summary": "Declaratively unpin a Pane; pinned is the Pane UI's favorite/pin star.",
4608
+ "details": "Sets the requested pinned state to false without reading and toggling it. Repeating the command is idempotent and unpinning never changes focus.",
4609
+ "requiresPaneDaemon": true,
4610
+ "mutates": true,
4611
+ "arguments": [
4612
+ {
4613
+ "name": "--pane",
4614
+ "value": "<pane-id>",
4615
+ "required": true,
4616
+ "description": "Pane/session id to unpin."
4617
+ },
4618
+ {
4619
+ "name": "--yes",
4620
+ "required": false,
4621
+ "description": "Skip confirmation for mutating commands."
4622
+ },
4623
+ {
4624
+ "name": "--dry-run",
4625
+ "required": false,
4626
+ "description": "Validate and preview without mutating."
4627
+ },
4628
+ {
4629
+ "name": "--json",
4630
+ "required": false,
4631
+ "description": "Print machine-readable output."
4632
+ }
4633
+ ],
4634
+ "examples": [
4635
+ "runpane panes unpin --pane <pane-id> --yes --json",
4636
+ "runpane panes unpin --pane <pane-id> --dry-run --json"
4637
+ ],
4638
+ "jsonSchemas": [
4639
+ "panePinRequest",
4640
+ "panePinResult"
4641
+ ],
4642
+ "notes": [
4643
+ "This is a declarative set, not a toggle: retries leave an already-unpinned Pane unpinned.",
4644
+ "Unpinning does not focus the Pane."
4645
+ ]
4646
+ },
4358
4647
  "panels list": {
4359
4648
  "name": "panels list",
4360
4649
  "summary": "List tool panels inside a Pane session.",