runpane 2.4.29 → 2.4.34

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 +9 -0
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands.d.ts +2 -0
  5. package/dist/commands.d.ts.map +1 -1
  6. package/dist/commands.js +11 -0
  7. package/dist/commands.js.map +1 -1
  8. package/dist/generated/contract.d.ts +327 -20
  9. package/dist/generated/contract.d.ts.map +1 -1
  10. package/dist/generated/contract.js +571 -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 +2 -0
  17. package/dist/localControl.d.ts.map +1 -1
  18. package/dist/localControl.js +101 -2
  19. package/dist/localControl.js.map +1 -1
  20. package/package.json +1 -1
package/dist/generated/contract.js CHANGED
@@ -186,6 +186,42 @@ exports.RUNPANE_CONTRACT = {
186
186
  "paneCreateResult"
187
187
  ]
188
188
  },
189
+ {
190
+ "name": "panes archive",
191
+ "summary": "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.",
192
+ "usage": [
193
+ "runpane panes archive --pane <pane-id> [--source user|agent] [--force] --yes [--json]"
194
+ ],
195
+ "mutates": true,
196
+ "jsonSchemas": [
197
+ "paneArchiveRequest",
198
+ "paneArchiveResult"
199
+ ]
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
+ },
189
225
  {
190
226
  "name": "panels create",
191
227
  "summary": "Create a terminal-backed tool panel inside an existing Pane session.",
@@ -511,6 +547,14 @@ exports.RUNPANE_CONTRACT = {
511
547
  {
512
548
  "name": "--focus",
513
549
  "description": "Explicitly focus the created pane or panel."
550
+ },
551
+ {
552
+ "name": "--pinned",
553
+ "description": "Create the pane already pinned (the UI's favorite/pin star)."
554
+ },
555
+ {
556
+ "name": "--force",
557
+ "description": "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes."
514
558
  }
515
559
  ]
516
560
  },
@@ -530,6 +574,7 @@ exports.RUNPANE_CONTRACT = {
530
574
  " runpane repos add --path <path> [--name <name>]",
531
575
  " runpane panes list [--repo <selector>] [--json]",
532
576
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [--source user|agent] [--focus|--no-focus] [--wait-ready]",
577
+ " runpane panes archive --pane <pane-id> [--source user|agent] [--force] --yes",
533
578
  " runpane panels create --pane <pane-id> --agent <codex|claude> [--source user|agent] [--focus|--no-focus] --yes",
534
579
  " runpane panels list --pane <pane-id> [--json]",
535
580
  " runpane panels output --panel <panel-id> [--limit <count>] [--json]",
@@ -674,8 +719,11 @@ exports.RUNPANE_CONTRACT = {
674
719
  "Commands:",
675
720
  " runpane panes list [--repo <selector>] [--json]",
676
721
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]",
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]",
677
725
  "",
678
- "Run \"runpane help panes list\" or \"runpane help panes create\" for command-specific options."
726
+ "Run \"runpane help panes <command>\" for command-specific options."
679
727
  ],
680
728
  "panes list": [
681
729
  "Usage:",
@@ -714,11 +762,52 @@ exports.RUNPANE_CONTRACT = {
714
762
  " --source <user|agent> Mark mutation source; agent implies background creation",
715
763
  " --no-focus Create in the background without stealing focus",
716
764
  " --focus Explicitly focus the created pane",
765
+ " --pinned Create already pinned (the UI's favorite/pin star)",
717
766
  " --pane-dir <path> Connect to a specific Pane data directory",
718
767
  " --json Print machine-readable output",
719
768
  " --dry-run Validate and preview without creating panes",
720
769
  " --yes Skip confirmation for mutating commands"
721
770
  ],
771
+ "panes archive": [
772
+ "Usage:",
773
+ " runpane panes archive --pane <pane-id> [--source user|agent] [--force] --yes [--json]",
774
+ "",
775
+ "Archives a Pane (session) exactly like the UI Archive action, including removal of its Pane-managed git worktree. Refuses to archive a pane with uncommitted, untracked, or unpushed-to-remote changes unless --force is passed. Waits for worktree removal to finish before returning.",
776
+ "",
777
+ "Options:",
778
+ " --pane <pane-id> Pane/session id to archive",
779
+ " --source <user|agent> Mark mutation source",
780
+ " --force Archive even if the pane has uncommitted, untracked, or unpushed changes",
781
+ " --pane-dir <path> Connect to a specific Pane data directory",
782
+ " --json Print machine-readable output",
783
+ " --yes Skip confirmation for mutating commands"
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
+ ],
722
811
  "panels": [
723
812
  "Terminal-backed panel commands.",
724
813
  "",
@@ -894,6 +983,7 @@ exports.RUNPANE_CONTRACT = {
894
983
  " runpane repos add --path <path> [--name <name>]",
895
984
  " runpane panes list [--repo <selector>] [--json]",
896
985
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [--source user|agent] [--focus|--no-focus] [--wait-ready]",
986
+ " runpane panes archive --pane <pane-id> [--source user|agent] [--force] --yes",
897
987
  " python -m runpane panels create --pane <pane-id> --agent <codex|claude> [--source user|agent] [--focus|--no-focus] --yes",
898
988
  " runpane panels list --pane <pane-id> [--json]",
899
989
  " runpane panels output --panel <panel-id> [--limit <count>] [--json]",
@@ -1027,8 +1117,11 @@ exports.RUNPANE_CONTRACT = {
1027
1117
  "Commands:",
1028
1118
  " runpane panes list [--repo <selector>] [--json]",
1029
1119
  " runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]",
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]",
1030
1123
  "",
1031
- "Run \"runpane help panes list\" or \"runpane help panes create\" for command-specific options."
1124
+ "Run \"runpane help panes <command>\" for command-specific options."
1032
1125
  ],
1033
1126
  "panes list": [
1034
1127
  "Usage:",
@@ -1067,11 +1160,52 @@ exports.RUNPANE_CONTRACT = {
1067
1160
  " --source <user|agent> Mark mutation source; agent implies background creation",
1068
1161
  " --no-focus Create in the background without stealing focus",
1069
1162
  " --focus Explicitly focus the created pane",
1163
+ " --pinned Create already pinned (the UI's favorite/pin star)",
1070
1164
  " --pane-dir <path> Connect to a specific Pane data directory",
1071
1165
  " --json Print machine-readable output",
1072
1166
  " --dry-run Validate and preview without creating panes",
1073
1167
  " --yes Skip confirmation for mutating commands"
1074
1168
  ],
1169
+ "panes archive": [
1170
+ "Usage:",
1171
+ " runpane panes archive --pane <pane-id> [--source user|agent] [--force] --yes [--json]",
1172
+ "",
1173
+ "Archives a Pane (session) exactly like the UI Archive action, including removal of its Pane-managed git worktree. Refuses to archive a pane with uncommitted, untracked, or unpushed-to-remote changes unless --force is passed. Waits for worktree removal to finish before returning.",
1174
+ "",
1175
+ "Options:",
1176
+ " --pane <pane-id>",
1177
+ " --source <user|agent>",
1178
+ " --force",
1179
+ " --pane-dir <path>",
1180
+ " --json",
1181
+ " --yes"
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
+ ],
1075
1209
  "panels": [
1076
1210
  "Terminal-backed panel commands.",
1077
1211
  "",
@@ -1303,6 +1437,7 @@ exports.RUNPANE_CONTRACT = {
1303
1437
  "runpane panes list --repo active --json",
1304
1438
  "runpane panes create --repo active --name issue-252 --agent <agent> --prompt \"Kick off the discussion skill for issue 252\" --source agent --no-focus --wait-ready --yes --json",
1305
1439
  "runpane panes create --from-json panes.json --yes --json",
1440
+ "runpane panes archive --pane <pane-id> --source agent --yes --json",
1306
1441
  "runpane panels list --pane <pane-id> --json",
1307
1442
  "runpane panels output --panel <panel-id> --limit 200 --json",
1308
1443
  "printf 'Continue\\n' | runpane panels input --panel <panel-id> --input-file - --yes --json",
@@ -1324,10 +1459,13 @@ exports.RUNPANE_CONTRACT = {
1324
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.",
1325
1460
  "`runpane panes list` lists Pane sessions, optionally scoped to one saved repository.",
1326
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.",
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`.",
1327
1464
  "`runpane panels list` lists tool panels inside one Pane session.",
1328
1465
  "`runpane panels output` reads bounded recent terminal output from one panel and strips common terminal control noise for agent use.",
1329
1466
  "`runpane panels input` sends exact input bytes to one terminal panel. Prefer `--input-file` for newlines, Ctrl-C, quotes, or shell-sensitive text.",
1330
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.",
1331
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'`."
1332
1470
  ],
1333
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.",
@@ -1465,6 +1603,7 @@ exports.RUNPANE_CONTRACT = {
1465
1603
  "Kick off discussion",
1466
1604
  "--source",
1467
1605
  "agent",
1606
+ "--pinned",
1468
1607
  "--dry-run",
1469
1608
  "--yes",
1470
1609
  "--json"
@@ -1477,6 +1616,33 @@ exports.RUNPANE_CONTRACT = {
1477
1616
  "--yes",
1478
1617
  "--json"
1479
1618
  ],
1619
+ [
1620
+ "panes",
1621
+ "archive",
1622
+ "--pane",
1623
+ "session-1",
1624
+ "--force",
1625
+ "--source",
1626
+ "agent",
1627
+ "--yes",
1628
+ "--json"
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
+ ],
1480
1646
  [
1481
1647
  "panels",
1482
1648
  "list",
@@ -1614,6 +1780,7 @@ exports.RUNPANE_CONTRACT = {
1614
1780
  "runpane repos add",
1615
1781
  "runpane panes list",
1616
1782
  "runpane panes create",
1783
+ "runpane panes archive",
1617
1784
  "runpane panels create",
1618
1785
  "runpane panels list",
1619
1786
  "runpane panels output",
@@ -2061,6 +2228,9 @@ exports.RUNPANE_CONTRACT = {
2061
2228
  "sessionPrompt": {
2062
2229
  "type": "string"
2063
2230
  },
2231
+ "pinned": {
2232
+ "type": "boolean"
2233
+ },
2064
2234
  "tool": {
2065
2235
  "oneOf": [
2066
2236
  {
@@ -2161,7 +2331,8 @@ exports.RUNPANE_CONTRACT = {
2161
2331
  "required": [
2162
2332
  "ok",
2163
2333
  "index",
2164
- "name"
2334
+ "name",
2335
+ "pinned"
2165
2336
  ],
2166
2337
  "properties": {
2167
2338
  "ok": {
@@ -2173,6 +2344,9 @@ exports.RUNPANE_CONTRACT = {
2173
2344
  "name": {
2174
2345
  "type": "string"
2175
2346
  },
2347
+ "pinned": {
2348
+ "type": "boolean"
2349
+ },
2176
2350
  "sessionId": {
2177
2351
  "type": "string"
2178
2352
  },
@@ -2294,6 +2468,7 @@ exports.RUNPANE_CONTRACT = {
2294
2468
  "enum": [
2295
2469
  "codex-update",
2296
2470
  "agent-prompt",
2471
+ "submission_unverified",
2297
2472
  "unknown"
2298
2473
  ]
2299
2474
  },
@@ -2346,6 +2521,12 @@ exports.RUNPANE_CONTRACT = {
2346
2521
  "verifiedSubmitted": {
2347
2522
  "type": "boolean"
2348
2523
  },
2524
+ "staged": {
2525
+ "type": "boolean"
2526
+ },
2527
+ "attempts": {
2528
+ "type": "number"
2529
+ },
2349
2530
  "sentAt": {
2350
2531
  "type": "string"
2351
2532
  },
@@ -2360,6 +2541,7 @@ exports.RUNPANE_CONTRACT = {
2360
2541
  "enum": [
2361
2542
  "codex-update",
2362
2543
  "agent-prompt",
2544
+ "submission_unverified",
2363
2545
  "unknown"
2364
2546
  ]
2365
2547
  },
@@ -2461,7 +2643,8 @@ exports.RUNPANE_CONTRACT = {
2461
2643
  "status",
2462
2644
  "worktreePath",
2463
2645
  "repoId",
2464
- "panelCount"
2646
+ "panelCount",
2647
+ "pinned"
2465
2648
  ],
2466
2649
  "properties": {
2467
2650
  "id": {
@@ -2488,6 +2671,9 @@ exports.RUNPANE_CONTRACT = {
2488
2671
  "panelCount": {
2489
2672
  "type": "number"
2490
2673
  },
2674
+ "pinned": {
2675
+ "type": "boolean"
2676
+ },
2491
2677
  "createdAt": {
2492
2678
  "type": "string"
2493
2679
  },
@@ -2504,6 +2690,204 @@ exports.RUNPANE_CONTRACT = {
2504
2690
  },
2505
2691
  "additionalProperties": false
2506
2692
  },
2693
+ "paneArchiveRequest": {
2694
+ "type": "object",
2695
+ "required": [
2696
+ "paneId"
2697
+ ],
2698
+ "properties": {
2699
+ "paneId": {
2700
+ "type": "string"
2701
+ },
2702
+ "force": {
2703
+ "type": "boolean"
2704
+ },
2705
+ "source": {
2706
+ "enum": [
2707
+ "user",
2708
+ "agent"
2709
+ ]
2710
+ }
2711
+ },
2712
+ "additionalProperties": false
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
+ },
2759
+ "paneArchiveResult": {
2760
+ "oneOf": [
2761
+ {
2762
+ "type": "object",
2763
+ "required": [
2764
+ "ok",
2765
+ "paneId",
2766
+ "archived",
2767
+ "forced",
2768
+ "worktreeCleanup",
2769
+ "safetyCheck"
2770
+ ],
2771
+ "properties": {
2772
+ "ok": {
2773
+ "type": "boolean"
2774
+ },
2775
+ "paneId": {
2776
+ "type": "string"
2777
+ },
2778
+ "archived": {
2779
+ "const": true
2780
+ },
2781
+ "forced": {
2782
+ "type": "boolean"
2783
+ },
2784
+ "worktreeCleanup": {
2785
+ "enum": [
2786
+ "completed",
2787
+ "failed",
2788
+ "timeout",
2789
+ "not-applicable"
2790
+ ]
2791
+ },
2792
+ "worktreePath": {
2793
+ "type": "string"
2794
+ },
2795
+ "safetyCheck": {
2796
+ "type": "object",
2797
+ "required": [
2798
+ "performed"
2799
+ ],
2800
+ "properties": {
2801
+ "performed": {
2802
+ "type": "boolean"
2803
+ },
2804
+ "hasUncommittedChanges": {
2805
+ "type": "boolean"
2806
+ },
2807
+ "hasUntrackedFiles": {
2808
+ "type": "boolean"
2809
+ },
2810
+ "hasUpstream": {
2811
+ "type": "boolean"
2812
+ },
2813
+ "unpushedCommits": {
2814
+ "type": "number"
2815
+ }
2816
+ },
2817
+ "additionalProperties": false
2818
+ }
2819
+ },
2820
+ "additionalProperties": false
2821
+ },
2822
+ {
2823
+ "type": "object",
2824
+ "required": [
2825
+ "ok",
2826
+ "paneId",
2827
+ "blocked",
2828
+ "nextCommand"
2829
+ ],
2830
+ "properties": {
2831
+ "ok": {
2832
+ "const": false
2833
+ },
2834
+ "paneId": {
2835
+ "type": "string"
2836
+ },
2837
+ "blocked": {
2838
+ "type": "object",
2839
+ "required": [
2840
+ "code",
2841
+ "message",
2842
+ "safetyCheck"
2843
+ ],
2844
+ "properties": {
2845
+ "code": {
2846
+ "enum": [
2847
+ "uncommitted-changes",
2848
+ "unpushed-commits",
2849
+ "uncommitted-and-unpushed",
2850
+ "status-unknown"
2851
+ ]
2852
+ },
2853
+ "message": {
2854
+ "type": "string"
2855
+ },
2856
+ "safetyCheck": {
2857
+ "type": "object",
2858
+ "required": [
2859
+ "performed"
2860
+ ],
2861
+ "properties": {
2862
+ "performed": {
2863
+ "type": "boolean"
2864
+ },
2865
+ "hasUncommittedChanges": {
2866
+ "type": "boolean"
2867
+ },
2868
+ "hasUntrackedFiles": {
2869
+ "type": "boolean"
2870
+ },
2871
+ "hasUpstream": {
2872
+ "type": "boolean"
2873
+ },
2874
+ "unpushedCommits": {
2875
+ "type": "number"
2876
+ }
2877
+ },
2878
+ "additionalProperties": false
2879
+ }
2880
+ },
2881
+ "additionalProperties": false
2882
+ },
2883
+ "nextCommand": {
2884
+ "type": "string"
2885
+ }
2886
+ },
2887
+ "additionalProperties": false
2888
+ }
2889
+ ]
2890
+ },
2507
2891
  "panelListResult": {
2508
2892
  "type": "object",
2509
2893
  "required": [
@@ -3035,6 +3419,7 @@ exports.RUNPANE_CONTRACT = {
3035
3419
  "enum": [
3036
3420
  "codex-update",
3037
3421
  "agent-prompt",
3422
+ "submission_unverified",
3038
3423
  "unknown"
3039
3424
  ]
3040
3425
  },
@@ -3320,6 +3705,7 @@ exports.RUNPANE_CONTRACT = {
3320
3705
  "enum": [
3321
3706
  "codex-update",
3322
3707
  "agent-prompt",
3708
+ "submission_unverified",
3323
3709
  "unknown"
3324
3710
  ]
3325
3711
  },
@@ -3416,6 +3802,7 @@ exports.RUNPANE_CONTRACT = {
3416
3802
  "enum": [
3417
3803
  "codex-update",
3418
3804
  "agent-prompt",
3805
+ "submission_unverified",
3419
3806
  "unknown"
3420
3807
  ]
3421
3808
  },
@@ -3442,14 +3829,14 @@ exports.RUNPANE_CONTRACT = {
3442
3829
  "rules": [
3443
3830
  "Start with `runpane doctor --json` to understand wrapper, platform, daemon reachability, and the next safe commands before mutating Pane state.",
3444
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`.",
3445
- "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`.",
3446
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.",
3447
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.",
3448
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.",
3449
3836
  "Use `panels create` for reviewer/helper/clean-context tabs that should stay inside an existing Pane and share that Pane's worktree.",
3450
3837
  "For private background decomposition, use your normal subagent/worktree mechanism instead of Pane.",
3451
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.",
3452
- "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.",
3453
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.",
3454
3841
  "For `agent-context --command`, use canonical spaced names like `panes create`; copied forms like `panes.create` or `runpane panes create` are accepted too.",
3455
3842
  "Use `runpane repos list --json` to find the saved repository when unsure after doctor shows the daemon is reachable.",
@@ -3530,6 +3917,7 @@ exports.RUNPANE_CONTRACT = {
3530
3917
  "--initial-input-file <path|->",
3531
3918
  "--from-json <path|->",
3532
3919
  "--source <user|agent>",
3920
+ "--pinned",
3533
3921
  "--no-focus",
3534
3922
  "--focus",
3535
3923
  "--wait-ready",
@@ -3539,6 +3927,37 @@ exports.RUNPANE_CONTRACT = {
3539
3927
  "--json"
3540
3928
  ]
3541
3929
  },
3930
+ {
3931
+ "name": "panes archive",
3932
+ "summary": "Archive a Pane exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.",
3933
+ "arguments": [
3934
+ "--pane <pane-id>",
3935
+ "--source <user|agent>",
3936
+ "--force",
3937
+ "--yes",
3938
+ "--json"
3939
+ ]
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
+ },
3542
3961
  {
3543
3962
  "name": "panels create",
3544
3963
  "summary": "Create reviewer/helper terminal tabs inside an existing Pane; they share that Pane's worktree.",
@@ -4026,11 +4445,21 @@ exports.RUNPANE_CONTRACT = {
4026
4445
  "required": false,
4027
4446
  "description": "Explicitly focus the created pane."
4028
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
+ },
4029
4453
  {
4030
4454
  "name": "--yes",
4031
4455
  "required": false,
4032
4456
  "description": "Skip confirmation for mutating commands."
4033
4457
  },
4458
+ {
4459
+ "name": "--dry-run",
4460
+ "required": false,
4461
+ "description": "Validate and preview without mutating."
4462
+ },
4034
4463
  {
4035
4464
  "name": "--json",
4036
4465
  "required": false,
@@ -4068,9 +4497,11 @@ exports.RUNPANE_CONTRACT = {
4068
4497
  "`panes create` is for user-visible Pane orchestration, not the agent's default private delegation mechanism.",
4069
4498
  "Register the saved base repository once. Pane creates and owns the worktree/branch for each new Pane.",
4070
4499
  "Use `panels create` instead when a reviewer/helper should share an existing Pane's worktree.",
4071
- "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.",
4072
4501
  "The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.",
4073
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.",
4074
4505
  "When the JSON result includes nextCommand, run it to validate that the terminal produced output before reporting success.",
4075
4506
  "Multi-pane requests are created sequentially today. The --concurrency flag is accepted for compatibility, but agents should not rely on parallel creation.",
4076
4507
  "For POSIX or WSL command chaining, use a custom terminal command like `bash -lc 'cmd1 && cmd2 && cmd3'`.",
@@ -4080,6 +4511,139 @@ exports.RUNPANE_CONTRACT = {
4080
4511
  "If readiness returns blocked, inspect blocked.suggestedCommand rather than guessing which prompt to answer."
4081
4512
  ]
4082
4513
  },
4514
+ "panes archive": {
4515
+ "name": "panes archive",
4516
+ "summary": "Archive a Pane (session) exactly like the UI Archive action, including safe removal of its Pane-managed git worktree.",
4517
+ "details": "Use this to close out a Pane once its PR has merged. Refuses to archive (unless --force) when the pane's branch has uncommitted, untracked, or unpushed-to-remote changes, so an agent cannot silently discard work. A merged and pushed branch has no unpushed commits, so it archives cleanly. Waits for worktree removal to finish before returning.",
4518
+ "requiresPaneDaemon": true,
4519
+ "mutates": true,
4520
+ "arguments": [
4521
+ {
4522
+ "name": "--pane",
4523
+ "value": "<pane-id>",
4524
+ "required": true,
4525
+ "description": "Pane/session id to archive."
4526
+ },
4527
+ {
4528
+ "name": "--source",
4529
+ "value": "<user|agent>",
4530
+ "required": false,
4531
+ "description": "Mutation source; does not change archive safety behavior."
4532
+ },
4533
+ {
4534
+ "name": "--force",
4535
+ "required": false,
4536
+ "description": "Archive even if the pane's branch has uncommitted, untracked, or unpushed changes."
4537
+ },
4538
+ {
4539
+ "name": "--yes",
4540
+ "required": false,
4541
+ "description": "Skip confirmation for mutating commands."
4542
+ },
4543
+ {
4544
+ "name": "--json",
4545
+ "required": false,
4546
+ "description": "Print machine-readable output."
4547
+ }
4548
+ ],
4549
+ "examples": [
4550
+ "runpane panes archive --pane <pane-id> --source agent --yes --json",
4551
+ "runpane panes archive --pane <pane-id> --force --yes --json"
4552
+ ],
4553
+ "jsonSchemas": [
4554
+ "paneArchiveRequest",
4555
+ "paneArchiveResult"
4556
+ ],
4557
+ "notes": [
4558
+ "If the result has ok:false with a blocked field, the pane was NOT archived; inspect blocked.code and rerun with --force if discarding the flagged work is intentional.",
4559
+ "A successful archive waits for the Pane-managed worktree to be removed before returning; check worktreeCleanup in the result for the final outcome.",
4560
+ "Archiving a main-repo Pane (no Pane-managed worktree) always succeeds immediately since nothing is deleted from disk."
4561
+ ]
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
+ },
4083
4647
  "panels list": {
4084
4648
  "name": "panels list",
4085
4649
  "summary": "List tool panels inside a Pane session.",