@justjoshn/pi-pstack 0.15.36-pi.1 → 0.15.36-pi.11

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 (135) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/README.md +26 -21
  3. package/agents/ci-watcher.md +28 -0
  4. package/agents/thermo-nuclear-code-quality-review.md +23 -0
  5. package/assets/logo.png +0 -0
  6. package/automations/benny/FOR_AGENTS.md +2 -1
  7. package/automations/benny/README.md +2 -2
  8. package/automations/benny/skills/setup-benny/SKILL.md +10 -9
  9. package/automations/benny/templates/reproduce-automation-prompt.md +1 -1
  10. package/automations/benny/templates/triage-automation-prompt.md +1 -1
  11. package/bin/pstack-routines-supervisor +9 -0
  12. package/docs/guide/01-setup.md +2 -2
  13. package/docs/guide/07-overnight.md +1 -1
  14. package/docs/guide/09-make-it-yours.md +1 -1
  15. package/docs/guide/10-recipes-and-pitfalls.md +1 -1
  16. package/docs/native-gaps.md +14 -8
  17. package/docs/parity-reverse-engineering.md +94 -0
  18. package/docs/parity-status.md +113 -0
  19. package/package.json +41 -6
  20. package/packaging/install-supervisor-unit.sh +164 -0
  21. package/packaging/launchd/com.pstack.routines-supervisor.plist.example +24 -0
  22. package/packaging/systemd/pstack-routines-supervisor.service.example +15 -0
  23. package/skills/architect/SKILL.md +1 -1
  24. package/skills/architect/references/runner-prompt.md +1 -1
  25. package/skills/arena/SKILL.md +4 -4
  26. package/skills/check-compiler-errors/SKILL.md +23 -0
  27. package/skills/create-skill/SKILL.md +515 -29
  28. package/skills/fix-ci/SKILL.md +29 -0
  29. package/skills/fix-merge-conflicts/SKILL.md +32 -0
  30. package/skills/get-pr-comments/SKILL.md +23 -0
  31. package/skills/how/SKILL.md +1 -1
  32. package/skills/ketchup/SKILL.md +2 -2
  33. package/skills/ketchup-video/SKILL.md +2 -2
  34. package/skills/loop-on-ci/SKILL.md +50 -0
  35. package/skills/make-bot-ui/SKILL.md +2 -2
  36. package/skills/make-pr-easy-to-review/SKILL.md +59 -0
  37. package/skills/new-branch-and-pr/SKILL.md +29 -0
  38. package/skills/no-inline-imports/SKILL.md +12 -0
  39. package/skills/poteto-help/SKILL.md +4 -4
  40. package/skills/poteto-mode/SKILL.md +2 -2
  41. package/skills/poteto-mode/playbooks/bug-fix.md +1 -1
  42. package/skills/poteto-mode/playbooks/feature.md +1 -1
  43. package/skills/poteto-mode/playbooks/hillclimb.md +1 -1
  44. package/skills/poteto-mode/playbooks/multi-phase-plan.md +2 -2
  45. package/skills/poteto-mode/playbooks/orchestrate.md +2 -2
  46. package/skills/poteto-mode/playbooks/perf-issue.md +1 -1
  47. package/skills/poteto-mode/playbooks/refactoring.md +1 -1
  48. package/skills/pr-review-canvas/SKILL.md +176 -0
  49. package/skills/pr-review-canvas/renderer.js +170 -0
  50. package/skills/pr-review-canvas/styles.css +96 -0
  51. package/skills/pr-review-canvas/template.html +18 -0
  52. package/skills/reflect/SKILL.md +2 -2
  53. package/skills/review-and-ship/SKILL.md +41 -0
  54. package/skills/run-smoke-tests/SKILL.md +42 -0
  55. package/skills/setup-pstack/SKILL.md +13 -13
  56. package/skills/statechart/scripts/test/cli.test.ts +1 -1
  57. package/skills/swarm/SKILL.md +2 -2
  58. package/skills/thermo-nuclear-code-quality-review/SKILL.md +192 -0
  59. package/skills/typescript-exhaustive-switch/SKILL.md +10 -0
  60. package/skills/verify-this/SKILL.md +74 -0
  61. package/skills/weekly-review/SKILL.md +32 -0
  62. package/skills/what-did-i-get-done/SKILL.md +31 -0
  63. package/skills/why/SKILL.md +2 -2
  64. package/skills/workflow-from-chats/SKILL.md +50 -0
  65. package/src/child-env.ts +15 -2
  66. package/src/index.ts +18 -3
  67. package/src/loop.ts +63 -14
  68. package/src/mode.ts +31 -7
  69. package/src/path-skills.ts +104 -0
  70. package/src/paths.ts +18 -0
  71. package/src/pi-command.ts +12 -0
  72. package/src/plan.ts +109 -24
  73. package/src/rule.ts +4 -4
  74. package/src/sections.ts +21 -2
  75. package/src/subscriptions/durable-store.ts +531 -0
  76. package/src/subscriptions/durable-types.ts +69 -0
  77. package/src/subscriptions/ensure-supervisor.ts +67 -0
  78. package/src/subscriptions/index.ts +310 -282
  79. package/src/subscriptions/supervisor-main.ts +134 -0
  80. package/src/subscriptions/supervisor.ts +325 -0
  81. package/src/subscriptions/webhook.ts +82 -21
  82. package/src/task/card.ts +29 -0
  83. package/src/task/models.ts +7 -0
  84. package/src/task/progress.ts +112 -0
  85. package/src/task/records.ts +7 -9
  86. package/src/task/registry.ts +7 -3
  87. package/src/task/runner.ts +112 -23
  88. package/src/task/tool.ts +112 -43
  89. package/src/task/worktree.ts +5 -3
  90. package/src/todo.ts +8 -3
  91. package/scripts/live-e2e.mjs +0 -257
  92. package/test/aliases.test.ts +0 -57
  93. package/test/ask.test.ts +0 -85
  94. package/test/autocomplete.test.ts +0 -39
  95. package/test/e2e/aliases.e2e.test.ts +0 -81
  96. package/test/e2e/ask.e2e.test.ts +0 -135
  97. package/test/e2e/harness.ts +0 -179
  98. package/test/e2e/host.e2e.test.ts +0 -193
  99. package/test/e2e/lifecycle.e2e.test.ts +0 -99
  100. package/test/e2e/mode.e2e.test.ts +0 -160
  101. package/test/e2e/package.e2e.test.ts +0 -67
  102. package/test/e2e/task.e2e.test.ts +0 -734
  103. package/test/e2e/todo.e2e.test.ts +0 -59
  104. package/test/fixtures/cursor-askquestion-calls.json +0 -806
  105. package/test/fixtures/fake-pi.mjs +0 -96
  106. package/test/fixtures/image-model.ts +0 -16
  107. package/test/fixtures/list-models.ts +0 -15
  108. package/test/fixtures/readonly-shell-exit.ts +0 -17
  109. package/test/fixtures/scripted-model.ts +0 -113
  110. package/test/loop.test.ts +0 -209
  111. package/test/mode.test.ts +0 -143
  112. package/test/plan.test.ts +0 -126
  113. package/test/readonly-shell-security.test.ts +0 -84
  114. package/test/readonly-shell.test.ts +0 -44
  115. package/test/records.test.ts +0 -143
  116. package/test/registry.test.ts +0 -18
  117. package/test/resources.test.ts +0 -162
  118. package/test/rule.test.ts +0 -92
  119. package/test/scripts.test.ts +0 -182
  120. package/test/sections.test.ts +0 -56
  121. package/test/subscriptions-cron.test.ts +0 -60
  122. package/test/subscriptions.test.ts +0 -598
  123. package/test/task-agents.test.ts +0 -49
  124. package/test/task-card.test.ts +0 -34
  125. package/test/task-fork.test.ts +0 -233
  126. package/test/task-format.test.ts +0 -65
  127. package/test/task-model.test.ts +0 -141
  128. package/test/task-runner.test.ts +0 -259
  129. package/test/task-schema.test.ts +0 -50
  130. package/test/task-status.test.ts +0 -155
  131. package/test/task-worktree.test.ts +0 -106
  132. package/test/todo.test.ts +0 -74
  133. package/test/visualize.test.ts +0 -152
  134. package/tsconfig.json +0 -5
  135. package/vitest.config.ts +0 -16
@@ -0,0 +1,94 @@
1
+ # Software architecture reconstruction: pstack 0.15.36 and dependencies
2
+
3
+ This is a historical static-analysis record, not proof of current full parity. The repository's `parity/pi-pstack-sar/requirements.md` maps the later SAR report to implementations and checks. Source provenance is published in `package.json.pstackSource`. A passing resource inventory does not prove workflow execution or remote-service behavior.
4
+
5
+ ## Goal
6
+
7
+ Reconstruct the software architecture of `pstack` `0.15.36` and all of its dependencies with the REA MCP server, then map every upstream capability and dependency to Pi's native extension mechanisms in `pi-pstack` with zero dependencies on the upstream `pstack` plugin.
8
+
9
+ ## Sources and REA evidence ledger
10
+
11
+ Every executable package in `pstack` `0.15.36`, its sibling `team-kit` `1.2.0` plugin, and `pi-pstack` `src/` was analyzed in this session with `rea-javascript-application` v1, `rea-analysis-view` v1, and `rea-javascript-application-workflows` v1.
12
+
13
+ | Target | Format | Root SHA-256 | Parent Evidence ID | Summary / View Evidence ID | Files / JS parsed |
14
+ | --- | --- | --- | --- | --- | --- |
15
+ | `pstack/skills/poteto-mode/scripts` (clean cache) | directory | `ab08fdd851002bfdd61fcc3c902bf0e6bb2bbd4b0229b5443e30626e3a788e07` | `ev_bf12ac9c3d463df579c1009ce80a874431c3cc14c168a783114077161d704139` | `ev_5cb366a2d252413ad6fc6350f1644aab7f751bfcfdd86e8af41a18851c99ac29`, `ev_f9e9795252c5470742dd90329b7bc1198882f4f5138e369cadb6a0397a0f5ee0`, `ev_5935daf21a6e6160681b399f1cc7482596cfedd3a7494c859a0e369fa6b0a946` | 15 relevant, 13 JS/TS parsed, 0 failures |
16
+ | `pstack/skills/poteto-mode/scripts` (with `node_modules`) | directory | `5b92deccc760dacf7f0f5278c2c4ecff34b98d87fc70f04fecc2210fcc52980c` | `ev_d6ff54533e36b7719f1b6e18031ee2521ff4368bdabe87f34372f46a1760c3e8` | retained in session bundle | Includes `commander@14.0.0` and `typescript@7.0.2` |
17
+ | `pstack/skills/statechart/scripts` | directory | `2193bf21071d9a8d176d142c5aa0d3257c98de4689e948e21b20957f83616e33` | `ev_5068b39b821b4f8848661475ed4d4e141343d183785cd0d1f48cc4c560700b24` | `ev_ce9ee247f111b881d6c100242cfa0560623e65b11248377553e053fb8b6f62f3`, `ev_bd7036ccd42e670602201871d0feba62dfffde58a1e942edcf879019555c25d2` | 50 relevant, 48 JS/TS parsed, 0 failures |
18
+ | `team-kit/skills/pr-review-canvas` | directory | `2666f69c5a27cb4256a403747f8606c55d68b7ab28556d7f0d3fe6fe359f9b3a` | `ev_2c98abedf7c1c05212d64174a87f0039f79218f72f4b0f1def35f6f3c2327ac9` | `ev_d63a021f7e544b9403b2a48e25bebe7ad59220b82aa1378ffed159e559c2da19`, `ev_2c3f2ede73725fa0fa715e3992b851b3e526d2df85d8e1ef1de50752d04bf93d` | 2 relevant, 1 JS parsed (`renderer.js`), 0 failures |
19
+ | `pi-pstack/src` | directory | `ebb60ef861603834b12d5f9a45f4108759d8c29d0605b38e07560456c0605ce8` | `ev_6fe43d2bbfab36c6763a2d1e940ee728fdbbe2ad2abb9162f70c102ccab8860f` | `ev_f5ea22bb2d470f8108ea52961fdbd0f8411142176ac7db78b0bdeca4c0f0e37e`, `ev_16b3d7080fa763f288e7e5a8291873a3bb1130fd1ad6be06070d51e7d753b71b` | 36 relevant, 36 TS parsed, 0 failures |
20
+ | `pi-pstack/skills/statechart/scripts` | directory | `9b47d92dbdc42204b53f020bdc7f802b6f5fff6220ecbe164dcf263906f2f914` | `ev_a8c8d7db63d2519d306e47d6d724a5119b28a1049a9eddbd73ea6f29dbc94caf` | `ev_1091007aca08202f865c78a8dd7452fa09d54fa0dcb807428f4d5c38732cb39f` | 50 relevant, 48 JS/TS parsed, 0 failures |
21
+ | `pi-pstack/skills/pr-review-canvas` | directory | `2666f69c5a27cb4256a403747f8606c55d68b7ab28556d7f0d3fe6fe359f9b3a` | `ev_e2dd5f48359956b83e32cdf0ac784c770cb97673cf712a4aaf490a27ecc1e8db` | `ev_12653e2b69c57038367443acf5635729793344211a0a13ef80a5c3dfdb1c376f` | 2 relevant, 1 JS parsed, 0 failures |
22
+
23
+ ### Focused module item and trace Evidence IDs
24
+
25
+ - `bootstrap.ts` module item view: `ev_76dece32cf003cb0c2ba0994d5c886d5ff51b2c4dbeabc63e1b01fd5f4df0f42`
26
+ - `check-plan.mjs` module item view: `ev_d8b696f0eebbd0ee8619cb4a70bcfcec7d85d8f7c397a717799db1217e7ec99b`
27
+ - `statechart/scripts/run.ts` module item view: `ev_e43256ff8736be8e4ab9dc0a065c5acc134048f557bf3a9bd0b78ce537a1bc1b`
28
+ - `pr-review-canvas/renderer.js` module item view: `ev_161a445223f452c7cc7f3104399476f625137fc93a3fc5fe4b9bd485742185c4`
29
+ - Outgoing feature trace on `watch-pr/github.ts`: `ev_47b1b4f41568acc919b7b99f7b18014ab564745436bfc493d9bf88ad56f15f29` (18 matched seeds, 27 traced nodes, 28 traced edges)
30
+ - Outgoing feature trace on `statechart/scripts/run.ts`: `ev_b2c06c4cca93538bcb8b18f0570627f9149c127b69b3055b7a4d174dca19e6fd` (7 matched seeds, 115 traced nodes, 194 traced edges)
31
+ - Outgoing feature trace on `pi-pstack/src/index.ts`: `ev_22556088c77e2fa9073d079a7ed0796b2545e2f36a6223d130b2df64a8b04d12` (3 matched seeds, 372 traced nodes, 558 traced edges)
32
+ - Version comparison for `statechart/scripts`: `ev_a220a808b81c474aaaa62752f324f54976d47a43ccc4e7100da1cff2b4c470a4` (`changed: 1`, `added: 0`, `removed: 0`, only `package.json` package name differs)
33
+ - Version comparison for `pr-review-canvas`: `ev_1066025d4b0edd77d4d50a798a4cd11b3581a601509962224fa04546d55d549d` (`changed: 0`, `added: 0`, `removed: 0`, byte-identical SHA-256)
34
+
35
+ ## Architecture of pstack 0.15.36 and its dependency graph
36
+
37
+ ```
38
+ pstack 0.15.36
39
+ ├── skills/ (58 workflow, principle, research, and verification skill directories)
40
+ ├── agents/ (poteto-agent, comment-sicko)
41
+ ├── automations/benny/ (setup-benny, triage-issue-reports, reproduce-and-fix-issues)
42
+ ├── docs/guide/ (10 guide chapters + README)
43
+ └── soft dependencies (vendored into pi-pstack)
44
+ ├── team-kit 1.2.0
45
+ │ ├── skills/ (18 skills, including deslop, control-cli, control-ui, pr-review-canvas)
46
+ │ ├── agents/ (ci-watcher, thermo-nuclear-code-quality-review)
47
+ │ └── rules/ (no-inline-imports, typescript-exhaustive-switch)
48
+ └── create-skill (host built-in skill for authoring and tuning SKILL.md files)
49
+ ```
50
+
51
+ ### Executable script packages inside the skill tree
52
+
53
+ 1. **`skills/poteto-mode/scripts/` (`ev_bf12ac9c3d463df579c1009ce80a874431c3cc14c168a783114077161d704139`)**:
54
+ - `bootstrap.ts` (`ev_76dece32cf003cb0c2ba0994d5c886d5ff51b2c4dbeabc63e1b01fd5f4df0f42`): verifies `node_modules/commander` and runs `bun install --frozen-lockfile` via `Bun.spawnSync` on first run before re-executing the target script.
55
+ - `watch-pr/` (`cli.ts`, `github.ts`, `policy.ts`, `render.ts`, `types.ts`): CLI built on `commander@14.0.0` that polls GitHub PR status, review threads (`REVIEW_THREADS_QUERY`), check runs, and mergeability by spawning `gh` (`ev_47b1b4f41568acc919b7b99f7b18014ab564745436bfc493d9bf88ad56f15f29`).
56
+ - `check-plan.mjs` (`ev_d8b696f0eebbd0ee8619cb4a70bcfcec7d85d8f7c397a717799db1217e7ec99b`): standalone Node script (`node:fs`, `node:process`) that validates multi-phase plan Markdown structure.
57
+ - `worktree-audit.sh`: bash script using `git`, `rg`, `jq`, and BSD or GNU `stat` and `date` to classify git worktrees against Pi session and subagent transcript activity.
58
+ 2. **`skills/statechart/scripts/` (`ev_5068b39b821b4f8848661475ed4d4e141343d183785cd0d1f48cc4c560700b24`)**:
59
+ - `statechart` wrapper, `statechart.ts`, `worker.ts`, `pipeline.ts`, `ir.ts`, `run.ts` (`ev_e43256ff8736be8e4ab9dc0a065c5acc134048f557bf3a9bd0b78ce537a1bc1b`), `frontends/`, `passes/`, and `backends/`.
60
+ - `run.ts` (`ev_b2c06c4cca93538bcb8b18f0570627f9149c127b69b3055b7a4d174dca19e6fd`) resolves Java (`java@temurin-25` through `mise` or `JAVA`) and `tla2tools.jar` (`TLA2TOOLS`), invokes `tlc2.TLC`, parses state graphs and counterexample traces into `ir.ts`, and produces Mermaid charts, reports, and plain-text TLC output. The separate rendering guide and tests use Pele and Mermaid.
61
+ 3. **`skills/pr-review-canvas/` (`ev_2c98abedf7c1c05212d64174a87f0039f79218f72f4b0f1def35f6f3c2327ac9`)**:
62
+ - `renderer.js` (`ev_161a445223f452c7cc7f3104399476f625137fc93a3fc5fe4b9bd485742185c4`), `template.html`, and `styles.css` render an interactive diff review canvas in the browser with zero npm dependencies.
63
+ 4. **`skills/show-me-your-work/scripts/log.sh`**:
64
+ - Appends ISO-8601 timestamped rows to a TSV decision trail while sanitizing tabs, newlines, and spreadsheet-formula prefix characters.
65
+
66
+ ## Pi-native mechanism architecture in pi-pstack
67
+
68
+ REA analysis of `pi-pstack/src` (`ev_6fe43d2bbfab36c6763a2d1e940ee728fdbbe2ad2abb9162f70c102ccab8860f`, trace `ev_22556088c77e2fa9073d079a7ed0796b2545e2f36a6223d130b2df64a8b04d12`) maps each host feature to Pi 1.4.0 native extension mechanisms (`native-gaps.md` documents the remaining lower-level surfaces):
69
+
70
+ | Host capability | `pi-pstack` module | Pi 1.5.0 native mechanism |
71
+ | --- | --- | --- |
72
+ | `/name` skill aliases and completions | `src/aliases.ts`, `src/autocomplete.ts` | `pi.on('input')` rewriting `/name` to `/skill:name`, `ctx.ui.addAutocompleteProvider`, `pi.getCommands()` |
73
+ | Sticky mode (`/mode <skill>`) | `src/mode.ts` | `pi.registerCommand('mode')`, `pi.appendEntry('pstack/mode')`, `ctx.sessionManager.getBranch()`, `stripFrontmatter`, `ctx.ui.setStatus`, `before_agent_start` `systemPromptOptions.sections.pstack_mode` |
74
+ | Plan mode (`/plan`) | `src/plan.ts`, `src/readonly-shell.ts` | `pi.registerCommand('plan')`, `pi.setActiveTools`, `pi.on('tool_call')`, `createBashTool` with `spawnHook` and `@anthropic-ai/sandbox-runtime` |
75
+ | Model rule (`pstack-models.md`) | `src/rule.ts`, `src/sections.ts` | `stripFrontmatter`, `before_agent_start` `systemPromptOptions.sections.pstack_models` and `pstack_host` |
76
+ | `Task` subagents (`fresh`, `resume`, `steer`, `fork`, `fork_turns`, `cloud` worktree, `readonly`, `file_attachments`) | `src/task/tool.ts`, `src/task/runner.ts`, `src/task/records.ts`, `src/task/registry.ts`, `src/task/worktree.ts` | `pi.registerTool`, `parseSessionEntries`, `SessionManager.open`, `SessionManager.forkFrom`, `detectSupportedImageMimeTypeFromFile`, `truncateHead`, `pi --mode rpc`, `pi.on('agent_before_settle')`, `pi.sendMessage` with `pi.registerMessageRenderer('pstack/task')` |
77
+ | `stop_agent` and `agent_status` | `src/task/stop.ts`, `src/task/status.ts` | `pi.registerTool` with MCP `annotations`, process-group signaling (`-pid`), run-lock inspection |
78
+ | `TodoWrite` checklist and widget | `src/todo.ts` | `pi.registerTool` (`executionMode: 'sequential'`), tool-result `details.todos` reconstructed from `ctx.sessionManager.getBranch()`, `ctx.ui.setWidget('pstack-todos')` |
79
+ | `AskQuestion` structured questions | `src/ask.ts` | `pi.registerTool` (`exposure: 'model-only'`, `executionMode: 'sequential'`), `ctx.ui.select`, `ctx.ui.input` |
80
+ | `/loop` and `Loop` tool | `src/loop.ts` | `pi.registerCommand('loop')`, `pi.registerTool`, `pi.on('agent_settled')`, `pi.sendUserMessage(..., { expandPromptTemplates: true })` |
81
+ | Subscriptions and webhook routines (`subscribe_github_pr`, `subscribe_timer`, `subscribe_webhook`, `list_subscriptions`, `unsubscribe`, `/routines`) | `src/subscriptions/*` | `pi.registerTool`, `pi.registerCommand('routines')`, `pi.appendEntry('pstack/subscriptions')`, `pi.sendMessage` with `pi.registerMessageRenderer('pstack/subscription')`, durable supervisor (`pstack-routines-supervisor`) with live-session wake delivery |
82
+ | `visualize` charts | `src/visualize.ts` | `pi.registerTool` rendering Unicode bar and line charts and writing standalone SVG files to the session artifacts directory |
83
+
84
+ ## Parity predicate
85
+
86
+ 1. Every `pstack` `0.15.36` skill (58) and agent (2) exists under `pi-pstack`.
87
+ 2. Every `team-kit` `1.2.0` skill (18), agent (2), and rule (2, as skills plus always-applied host prompt rules) plus `create-skill` (1) exists under `pi-pstack` (79 total skills, 4 agent files).
88
+ 3. `pi-pstack` has no runtime dependency or synchronization against an upstream plugin checkout or cache. Normal package checks need no upstream installation. Passive provenance and optional source-comparison audits do not load upstream code.
89
+ 4. Every host mechanism named in playbooks runs on Pi's native extension APIs (`ExtensionAPI`, `parseSessionEntries`, `SessionManager`, `stripFrontmatter`, `detectSupportedImageMimeTypeFromFile`, `truncateHead`, `createBashTool`, `registerMessageRenderer`, `registerTool`, `registerCommand`).
90
+ 5. Package checks run with `bun run typecheck` and `bun run test` from the package directory. `bun run test:statechart` additionally runs the bundled statechart suite. Set `TLA2TOOLS` and `JAVA` to run real TLC cases. Repository-only checks such as `node scripts/check-pi-mechanisms.mjs` run from the repository root and are not shipped package commands.
91
+
92
+ ## REA coverage notes
93
+
94
+ Static JavaScript and TypeScript semantic graphs report bounded unknowns for dynamic property lookups and cross-function value flows (3,303 in `poteto-mode/scripts`, 12,803 in `statechart/scripts`, 356 in `pr-review-canvas`, and 7,204 in `pi-pstack/src`), and 1 unanalyzed inline script in `pr-review-canvas/template.html`. The Vitest tests cover their asserted extension contracts. They do not prove all runtime behavior, external services, or the separately executed statechart suite. See [`native-gaps.md`](native-gaps.md) for the remaining lower-level Pi 1.5.0 surfaces.
@@ -0,0 +1,113 @@
1
+ # Parity status
2
+
3
+ This page records what `pi-pstack` reproduces from Cursor `pstack` 0.15.36 and its dependencies, what it translates to a native Pi mechanism, and what remains a host difference. It is a status record, not a claim that every workflow has been observed on both hosts.
4
+
5
+ ## Sources
6
+
7
+ - Cursor `pstack` and `cursor-team-kit`: `github.com/cursor/plugins` at `6ea74587e384e1a8035c09ae33a46fe3f881eb9b`. The plugin manifest reports pstack 0.15.36. `package.json.pstackSource.revision` pins `ae5650fe`, this port's capture base; `git log ae5650fe..6ea74587 -- pstack cursor-team-kit` is empty, so both commits name the same plugin content.
8
+ - Installed Cursor CLI at the time of the reference capture: `2026.10.22-27dcf5f`.
9
+ - Native implementation: this package, which pins its upstream provenance in `package.json.pstackSource`.
10
+
11
+ A path and byte comparison of the tracked trees shows every pstack skill, both pstack agents, all 18 team-kit skills, both team-kit agents, and both team-kit rules in this package. Seventeen team-kit skill files are byte-identical; `workflow-from-chats` describes Pi paths instead of Cursor paths. The changed pstack files are host translations. One upstream paragraph has no counterpart: `poteto-help`'s Claude Code install path and its `docs/harness/claude-code.md` adapter, because this package targets Pi only. The two non-portable frontmatter keys Cursor ships (`icon`/`color` on `poteto-mode`, `paths` on `typescript-best-practices`) are kept under `metadata`, the Agent Skills extension point; the port reads both, and it attaches `typescript-best-practices` by path through `src/path-skills.ts`.
12
+
13
+ ## Native translations
14
+
15
+ | Cursor dependency | Pi mechanism |
16
+ | --- | --- |
17
+ | Skill invocation and the slash menu | `pi.getCommands()` plus `/name` to `/skill:name` input rewriting, with TUI completions |
18
+ | Custom Mode | `/mode <skill>`, a branch-persisted entry, the skill attached once on the entering request, and a path-naming reminder in a `pstack_mode` prompt section on every later request |
19
+ | Plan mode | `/plan`, a reduced tool set, `bash_readonly` in an OS sandbox, a `create_plan` artifact under `plans/`, and `/plan build` |
20
+ | Always-applied model rule | `pstack-models.md` read before every request and injected as `pstack_models` |
21
+ | Task subagents | One `pi --mode rpc` process per agent, with resume, steer, fork, `fork_turns`, readonly, attachments, background notices, and local worktrees |
22
+ | Agent types | The four bundled agent Markdown files, loaded into the child system prompt |
23
+ | Project and agent stores | Workspace state folders named in the host system prompt |
24
+ | Todo list | `TodoWrite` with branch reconstruction and a TUI widget |
25
+ | Structured questions | `AskQuestion` over Pi select and input dialogs |
26
+ | `/loop` | `Loop` tool and `/loop` command. A fixed interval is wall-clock from each fire, like Cursor's sleep loop, and accepts the interval first or last (`5m`, `10 minutes`, `every 10 minutes`). An interval-less loop is agent-paced through `Loop` `wake_in`. |
27
+ | Path-scoped skills | `src/path-skills.ts` attaches a loaded skill once per session when the session reads or edits a file matching its `paths`/`globs` (also under `metadata`), the way Cursor files a skill under `fileGlobbed` |
28
+ | Always-applied rules | The two shipped rule bodies are read into `pstack_host` verbatim on every request, not paraphrased |
29
+ | Todo list state | `TodoWrite` writes branch entries, and the current list rides in the `pstack_todos` prompt section on every request, so a compacted context still sees it |
30
+ | Automations | Durable timer, GitHub, and webhook subscriptions with a detached supervisor |
31
+ | `/visualize` | `visualize` tool that returns a Unicode chart and writes an SVG |
32
+ | Benny automation pack | The same text workflows, run through subscriptions instead of the Cursor Automations editor |
33
+
34
+ ## Reference observations
35
+
36
+ A live Cursor CLI session with both plugins loaded produced these contracts.
37
+
38
+ - A foreground `Task` call returned the child's final text, an agent ID, `isBackground: false`, and a duration.
39
+ - A background `Task` call returned `isBackground: true` with no conversation steps, then delivered a completion message naming the title and agent ID. The parent turn resumed from that message.
40
+ - `Task` arguments included `description`, `prompt`, `subagentType`, `model`, `agentId`, `attachments`, `mode`, `environment`, and `machine`.
41
+ - The CLI's model-facing `Task` schema exposes only `description`, `prompt`, `model`, `resume`, `subagent_type`, `file_attachments`, and `run_in_background`. It does not expose `readonly`, `environment`, `cloud_base_branch`, `fork`, or `fork_turns`, so those pstack arguments are inert in that CLI. A live Task started with `readonly: true` wrote a file, which confirms the CLI did not enforce it.
42
+ - Pi exposes those arguments and enforces `readonly`, because the pstack skills use it to keep explorers and reviewers from editing. That is a deliberate correction of the host gap, not literal reproduction of it.
43
+ - A live Task asked for `environment: "cloud"` ran in the same working directory on the same machine, with `environment: SUBAGENT_EXECUTION_ENVIRONMENT_UNSPECIFIED`. In this CLI, the cloud argument was inert too. Pi's local worktree is a stronger isolation than that observation, though still weaker than the documented cloud VM.
44
+
45
+ Pi returns the child's final text with a transcript path and usage, and reports background completion as a `pstack/task` notification. The payload shape differs because the hosts are different; the observable workflow, a subagent result arriving after the parent turn, is preserved.
46
+
47
+ ## Repairs in 0.15.36-pi.11
48
+
49
+ Each code change has a regression in the package suite. Text restorations are recorded here and checked against the reference by the parity audit.
50
+
51
+ - A background completion notice names the subagent by its `description`, the field the Task schema says names it in the UI, instead of 200 characters of prompt. Cursor's own completion block puts the child's prompt in its `title` field; this notice keeps both the name and a prompt excerpt.
52
+ - A foreground Task streams its child's last tool steps and latest line into the running card, throttled and capped, instead of showing a blank wait until the child settles.
53
+ - `/loop` accepts the interval at either end and in unit words (`10 minutes`, `every 10 minutes`), and a bare `/loop` prints usage. A fixed loop keeps wall-clock cadence, so a long run no longer pushes the next tick out.
54
+ - A bare `/plan` enters plan mode, as Cursor's plan command does, and plan mode keeps `stop_agent` so a launched child can still be stopped.
55
+ - Rules that declare `paths`/`globs` attach on Pi when a matching file is read or edited, once per session.
56
+ - The always-applied engineering rules are injected as their shipped text, including "interface fields" and "strict circular-dependency reason".
57
+ - The todo list is in every request's system prompt, so compaction and a branch switch do not leave the model without it.
58
+ - `cloud_base_branch` starts from `origin/<branch>` when that ref exists, as a cloud worker sees only pushed code, and falls back to a local ref.
59
+ - A resume that names a `subagent_type` keeps the recorded type and says the parameter was ignored.
60
+ - A detached `new_session` fire records its own final message as the run output, so `list_subscriptions` shows what the run said instead of `detached run completed`.
61
+ - benny restores the upstream requirement that the pack and referenced configuration are committed before a subscription is enabled, and a sweep reads from the last successful sweep so downtime does not lose reports.
62
+ - The architect runner prompt restores "What matters is independence between candidates."
63
+ - `/ketchup` describes the `visualize` tool as a bar or line chart and delivers screenshots and video the way Pi can (read the image, open the video, name the path).
64
+ - A webhook routine accepts `sessionStrategy: "new_session"`, so an accepted POST starts a fresh detached run with no chat open, the way a Cursor Automation runs, and records its outcome in `list_subscriptions`. Records written before this field existed still load and behave as `wake_self`. Evidence: `test/e2e/subscription-owner.e2e.test.ts` runs the real Pi CLI with the owner closed, POSTs to the bound listener, and finds the detached run's file and its recorded outcome.
65
+ - A timer or webhook routine no longer expires after seven days. Cursor's automation docs define no expiry and describe "always-on agents"; the closest documented cap, 180 days, belongs to cloud agent subscriptions, a different surface. `expiresInHours` still sets one, `0` means none, and a GitHub watch keeps its 7-day default because it is this port's own surface.
66
+ - Each workspace binds its own routines port. With no explicit port, a busy default falls back to an ephemeral port that the workspace reuses and reports in the routine URL, so two workspaces serve routines at once. An explicit `PSTACK_ROUTINES_PORT` still reports a collision as an error. Evidence: the two-workspace case runs two real Pi sessions and supervisors in `test/e2e/subscription-owner.e2e.test.ts`.
67
+ - A mode now matches Cursor's injection. The skill body rides the first request after entry as the same `<skill>` block Pi's own `/skill:name` expansion builds, addressed with Cursor's entry notice, and every later request carries Cursor's reminder shape, which names the skill file. The mode re-sends the body after a restart. Evidence: `test/e2e/mode.e2e.test.ts` reads the real system prompt on the entering turn, on the next turn, and after a restart.
68
+ - Plan mode saves an artifact. A `create_plan` tool writes the plan to `<pstack dir>/plans/<title>-<id8>.plan.md`, the file name shape Cursor uses, and records it on the branch. `/plan build` leaves plan mode and sends the file's content as the next turn, which is Cursor's "Yes, build locally" path without its review menu. Evidence: `test/e2e/plan.e2e.test.ts` drives the real CLI through `/plan`, the tool call, and `/plan build`.
69
+
70
+ ## Repairs in 0.15.36-pi.10
71
+
72
+ Each code change has a regression in the package suite. Text restorations are recorded here and checked against the reference by the parity audit.
73
+
74
+ - The root chat can resume and fork a descendant that a worktree worker started inside that worktree. Unrelated directories remain refused. New records store the owning workspace root; older records are recognized by this workspace's worktree folder.
75
+ - A steering message stranded at settlement is resumed with its recorded images and keeps its own message boundary, instead of joining cleared text and dropping attachments.
76
+ - A full subscription queue refuses a new event with HTTP 503 and `Retry-After` instead of evicting an event already acknowledged with 200.
77
+ - Accepted `new_session` work stays eligible after expiry, so expiry stops new occurrences without stranding accepted work.
78
+ - Task's settle-time notification appends to entries another extension proposed at the boundary instead of replacing them.
79
+ - A `new_session` timer reuses the model, thinking level, and project trust it was created with, whether its owner is live or detached.
80
+ - The upstream `ci-watcher` `model: fast` is restored; `fast` picks the parent model's listed `-fast` variant, else the parent model.
81
+ - A pre-epoch supervisor lock is signaled only when its command line identifies this supervisor, so a reused pid cannot terminate an unrelated process.
82
+
83
+ ## Remaining host differences
84
+
85
+ These are not closed by extension code.
86
+
87
+ - **Background workers stop when the chat exits.** A Pi subagent is a child process of the chat, so quitting or shutting the session stops the agents it started and reports how many. Whether a Cursor background subagent outlives its parent is unobserved; the CLI changelog says cancelling the prompt stops its subagents, and only the cloud-agent product promises work after the laptop closes. A `new_session` subscription fire is Pi's one detached path, and it starts a fresh run rather than continuing a subagent.
88
+ - **A mode carries its body once, then a reminder.** Cursor attaches the skill body on the turn that enters the mode and sends a path-naming reminder every turn after, in a user-message field. Pi rebuilds its prompt per request, so the body rides the first request after entry as a `pstack_mode` section and later requests carry the reminder. A process restart re-sends the body once, since the new process cannot know the conversation already saw it.
89
+ - **A fork needs an idle source.** Cursor exposes `fork` only on its internal and cloud-agent protos, never on the CLI Task schema, and no doc states whether a fork may start while the source runs. A Pi fork runs in the source's directory or worktree, so a running source is refused; the orchestrate playbook says to wait for its completion notification.
90
+ - **Plan mode's restriction is stricter than the host's.** Cursor's inspected CLI carries no client-side plan-mode filter, and its docs recommend stating read-only intent in the prompt, so the restriction on that surface is prompt or backend side; no source shows a plan-mode network rule. Pi enforces a tool allowlist and a sandboxed shell that also denies network, so `gh`, `curl`, and package queries can fail while planning.
91
+ - **No host-managed plan review UI.** The plan is a file the agent writes with `create_plan`, and `/plan build` starts the work from it. Cursor also renders a plan review menu with "build locally", "build in cloud", and "no, propose changes", and can hand the plan to a cloud agent. Pi has no equivalent UI, and its plan review is the file plus the reply.
92
+ - **benny's default cadence still needs its owning session open.** `wake_self` timers and webhook routines park while the owner is offline. A timer or webhook routine created with `sessionStrategy: "new_session"` runs detached with no chat open, but a detached run is one-shot: it must do the work in that run, because a background `Task` ends with it. Cursor automations run in the cloud and can hand work to anything. So benny keeps `wake_self` by default and setup names the tradeoff before switching.
93
+ - **A routines listener is local, one port per workspace.** Cursor hosts each routine URL. Pi binds a loopback port per workspace, so two workspaces serve routines at once only because the default port falls back to an ephemeral one that the workspace then reuses and reports. A sender outside the machine still needs its own forwarding path.
94
+ - **Cloud execution is local.** Cursor documents cloud VMs for its cloud product, but the inspected CLI schema omits `environment` and a requested cloud Task ran on the same machine and directory. Pi's `environment: "cloud"` goes further with a git worktree and a separate local process. Neither runs with the laptop off or provides a remote VM.
95
+ - **Webhook routines are local.** Cursor provides a hosted routine endpoint and an editor panel. Pi serves an authenticated listener on loopback and stores a sender key in a local file. A sender outside the machine needs its own forwarding path.
96
+ - **Slack-triggered automations need an external sender.** The Benny workflows can sweep on a timer or receive a local webhook. The Cursor Automations product and its Slack trigger are not reproduced.
97
+ - **Inline video is not rendered in the reply.** The ketchup-video workflow writes the video and names its path; Pi opens it in the system player instead.
98
+ - **Video attachments have no Pi model input.** Cursor can attach video to a Task. Pi names the video path for the agent instead of decoding the file as text; the agent opens it with a media tool.
99
+ - **Hosted guidance and pages are outside the package.** MCP providers, ticket trackers, browsers, simulators, and Tailscale remain the user's own dependencies, as they are for Cursor.
100
+ - **Background usage cannot enter parent totals.** Pi exposes no API that adds a later notification's usage to the parent session. It stays in the notification details and the child transcript.
101
+
102
+ ## Open evidence
103
+
104
+ The following were not observed end to end and are not claimed.
105
+
106
+ - A real model following every ported skill on both hosts.
107
+ - Authenticated MCP exchanges and provider-specific tool behavior.
108
+ - A successful live Cursor run for each workflow after the reference capture.
109
+ - Reboot survival through a real launchd or systemd unit on both platforms.
110
+ - Multi-workspace webhook routing.
111
+ - Exactly-once external actions in Benny workflows.
112
+
113
+ Passing package tests show the extension contracts hold. They do not replace those observations.
package/package.json CHANGED
@@ -1,13 +1,32 @@
1
1
  {
2
2
  "name": "@justjoshn/pi-pstack",
3
- "version": "0.15.36-pi.1",
4
- "description": "pstack 0.15.36 for Pi: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, and visualize",
3
+ "version": "0.15.36-pi.11",
4
+ "description": "pstack 0.15.36 for Pi with its soft-dependency team-kit skills vendored in: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, and visualize",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
+ "pstackSource": {
8
+ "repository": "https://github.com/cursor/plugins",
9
+ "revision": "ae5650febf4320793844c12c4adaa937f417f8da",
10
+ "path": "pstack",
11
+ "version": "0.15.36",
12
+ "lastChange": "c742dd61706fbacc1b95f1a20b7b988cf096ce6c"
13
+ },
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/just-joshn/pi-customizations.git",
17
+ "directory": "extensions/pi-pstack"
18
+ },
19
+ "homepage": "https://github.com/just-joshn/pi-customizations/tree/main/extensions/pi-pstack#readme",
20
+ "bugs": {
21
+ "url": "https://github.com/just-joshn/pi-customizations/issues"
22
+ },
7
23
  "keywords": [
8
24
  "pi-package",
9
25
  "pstack"
10
26
  ],
27
+ "bin": {
28
+ "pstack-routines-supervisor": "./bin/pstack-routines-supervisor"
29
+ },
11
30
  "engines": {
12
31
  "node": ">=22.19.0"
13
32
  },
@@ -23,10 +42,25 @@
23
42
  "./skills"
24
43
  ]
25
44
  },
45
+ "files": [
46
+ "src",
47
+ "skills",
48
+ "agents",
49
+ "automations",
50
+ "bin",
51
+ "docs",
52
+ "assets",
53
+ "licenses",
54
+ "packaging",
55
+ "README.md",
56
+ "CHANGELOG.md",
57
+ "LICENSE"
58
+ ],
26
59
  "scripts": {
27
60
  "typecheck": "tsc --noEmit -p tsconfig.json",
28
61
  "test": "vitest run",
29
62
  "test:coverage": "vitest run --coverage",
63
+ "test:statechart": "node --disable-warning=ExperimentalWarning --test skills/statechart/scripts/test/*.test.ts",
30
64
  "live:e2e": "node scripts/live-e2e.mjs"
31
65
  },
32
66
  "dependencies": {
@@ -40,12 +74,13 @@
40
74
  "typebox": "*"
41
75
  },
42
76
  "devDependencies": {
43
- "@earendil-works/pi-ai": "1.4.0",
44
- "@earendil-works/pi-agent-core": "1.4.0",
45
- "@earendil-works/pi-coding-agent": "1.4.0",
46
- "@earendil-works/pi-tui": "1.4.0",
77
+ "@earendil-works/pi-ai": "1.5.0",
78
+ "@earendil-works/pi-agent-core": "1.5.0",
79
+ "@earendil-works/pi-coding-agent": "1.5.0",
80
+ "@earendil-works/pi-tui": "1.5.0",
47
81
  "@types/node": "^22.19.0",
48
82
  "@vitest/coverage-v8": "^5.0.2",
83
+ "fast-check": "4.5.3",
49
84
  "typebox": "1.3.27",
50
85
  "typescript": "^7.0.2",
51
86
  "vitest": "^5.0.2"
@@ -0,0 +1,164 @@
1
+ #!/usr/bin/env bash
2
+ # Install a per-workspace user unit so pstack-routines-supervisor survives reboot.
3
+ # Idempotent: re-run overwrites the same unit path and reloads it.
4
+ set -euo pipefail
5
+
6
+ usage() {
7
+ echo "Usage: $0 --workspace <abs-path> [--bin <abs-path>]" >&2
8
+ exit 2
9
+ }
10
+
11
+ workspace=""
12
+ bin=""
13
+ while [[ $# -gt 0 ]]; do
14
+ case "$1" in
15
+ --workspace)
16
+ [[ $# -ge 2 ]] || usage
17
+ workspace=$2
18
+ shift 2
19
+ ;;
20
+ --bin)
21
+ [[ $# -ge 2 ]] || usage
22
+ bin=$2
23
+ shift 2
24
+ ;;
25
+ -h|--help)
26
+ usage
27
+ ;;
28
+ *)
29
+ usage
30
+ ;;
31
+ esac
32
+ done
33
+
34
+ [[ -n "$workspace" ]] || usage
35
+ [[ "$workspace" = /* ]] || {
36
+ echo "error: --workspace must be an absolute path" >&2
37
+ exit 2
38
+ }
39
+ [[ -d "$workspace" ]] || {
40
+ echo "error: workspace is not a directory: $workspace" >&2
41
+ exit 1
42
+ }
43
+
44
+ here=$(cd "$(dirname "$0")" && pwd)
45
+ if [[ -z "$bin" ]]; then
46
+ bin=$(cd "$here/../bin" && pwd)/pstack-routines-supervisor
47
+ fi
48
+ [[ "$bin" = /* ]] || {
49
+ echo "error: --bin must be an absolute path" >&2
50
+ exit 2
51
+ }
52
+ [[ -x "$bin" ]] || {
53
+ echo "error: supervisor bin missing or not executable: $bin" >&2
54
+ exit 1
55
+ }
56
+
57
+ # Short content hash so labels stay stable across re-runs for the same path.
58
+ safe_hash=$(printf '%s' "$workspace" | shasum -a 256 | cut -c1-12)
59
+ os=$(uname -s)
60
+
61
+ install_darwin() {
62
+ local label="com.pstack.routines-supervisor.${safe_hash}"
63
+ local plist_dir="$HOME/Library/LaunchAgents"
64
+ local plist="$plist_dir/${label}.plist"
65
+ local uid domain
66
+ uid=$(id -u)
67
+ domain="gui/${uid}"
68
+
69
+ mkdir -p "$plist_dir"
70
+ cat >"$plist" <<EOF
71
+ <?xml version="1.0" encoding="UTF-8"?>
72
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
73
+ <plist version="1.0">
74
+ <dict>
75
+ <key>Label</key>
76
+ <string>${label}</string>
77
+ <key>ProgramArguments</key>
78
+ <array>
79
+ <string>${bin}</string>
80
+ <string>--workspace</string>
81
+ <string>${workspace}</string>
82
+ </array>
83
+ <key>WorkingDirectory</key>
84
+ <string>${workspace}</string>
85
+ <key>KeepAlive</key>
86
+ <true/>
87
+ <key>RunAtLoad</key>
88
+ <true/>
89
+ <key>StandardOutPath</key>
90
+ <string>/tmp/pstack-routines-supervisor-${safe_hash}.log</string>
91
+ <key>StandardErrorPath</key>
92
+ <string>/tmp/pstack-routines-supervisor-${safe_hash}.err</string>
93
+ </dict>
94
+ </plist>
95
+ EOF
96
+
97
+ launchctl bootout "${domain}/${label}" 2>/dev/null || true
98
+ if launchctl bootstrap "$domain" "$plist" 2>/dev/null; then
99
+ launchctl enable "${domain}/${label}" 2>/dev/null || true
100
+ launchctl kickstart -k "${domain}/${label}" 2>/dev/null || true
101
+ else
102
+ # Older launchctl: load -w is enough for KeepAlive + RunAtLoad.
103
+ launchctl unload -w "$plist" 2>/dev/null || true
104
+ launchctl load -w "$plist"
105
+ fi
106
+
107
+ echo "Installed launchd agent: $plist"
108
+ echo " label: $label"
109
+ echo " bin: $bin"
110
+ echo " workspace: $workspace"
111
+ echo "Uninstall:"
112
+ echo " launchctl bootout ${domain}/${label} 2>/dev/null || launchctl unload -w \"$plist\""
113
+ echo " rm -f \"$plist\""
114
+ }
115
+
116
+ install_linux() {
117
+ local unit_name="pstack-routines-supervisor-${safe_hash}.service"
118
+ local unit_dir="$HOME/.config/systemd/user"
119
+ local unit="$unit_dir/$unit_name"
120
+
121
+ mkdir -p "$unit_dir"
122
+ cat >"$unit" <<EOF
123
+ [Unit]
124
+ Description=pstack durable routines supervisor (${safe_hash})
125
+ After=default.target
126
+
127
+ [Service]
128
+ Type=simple
129
+ WorkingDirectory=${workspace}
130
+ ExecStart=${bin} --workspace ${workspace}
131
+ Restart=on-failure
132
+ RestartSec=3
133
+
134
+ [Install]
135
+ WantedBy=default.target
136
+ EOF
137
+
138
+ systemctl --user daemon-reload
139
+ systemctl --user enable --now "$unit_name"
140
+
141
+ echo "Installed systemd user unit: $unit"
142
+ echo " unit: $unit_name"
143
+ echo " bin: $bin"
144
+ echo " workspace: $workspace"
145
+ echo "If no login session is open after reboot, enable linger so the user unit still starts:"
146
+ echo " loginctl enable-linger \"$(id -un)\""
147
+ echo "Uninstall:"
148
+ echo " systemctl --user disable --now $unit_name"
149
+ echo " rm -f \"$unit\""
150
+ echo " systemctl --user daemon-reload"
151
+ }
152
+
153
+ case "$os" in
154
+ Darwin)
155
+ install_darwin
156
+ ;;
157
+ Linux)
158
+ install_linux
159
+ ;;
160
+ *)
161
+ echo "error: unsupported OS: $os (need Darwin or Linux)" >&2
162
+ exit 1
163
+ ;;
164
+ esac
@@ -0,0 +1,24 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3
+ <plist version="1.0">
4
+ <dict>
5
+ <key>Label</key>
6
+ <string>com.pstack.routines-supervisor</string>
7
+ <key>ProgramArguments</key>
8
+ <array>
9
+ <string>/absolute/path/to/node_modules/@justjoshn/pi-pstack/bin/pstack-routines-supervisor</string>
10
+ <string>--workspace</string>
11
+ <string>/absolute/path/to/your/repo</string>
12
+ </array>
13
+ <key>WorkingDirectory</key>
14
+ <string>/absolute/path/to/your/repo</string>
15
+ <key>KeepAlive</key>
16
+ <true/>
17
+ <key>RunAtLoad</key>
18
+ <true/>
19
+ <key>StandardOutPath</key>
20
+ <string>/tmp/pstack-routines-supervisor.log</string>
21
+ <key>StandardErrorPath</key>
22
+ <string>/tmp/pstack-routines-supervisor.err</string>
23
+ </dict>
24
+ </plist>
@@ -0,0 +1,15 @@
1
+ # Does not require root. Reboot survival needs linger enabled for the user when no login session is open.
2
+
3
+ [Unit]
4
+ Description=pstack durable routines supervisor
5
+ After=default.target
6
+
7
+ [Service]
8
+ Type=simple
9
+ WorkingDirectory=/absolute/path/to/your/repo
10
+ ExecStart=/absolute/path/to/node_modules/@justjoshn/pi-pstack/bin/pstack-routines-supervisor --workspace /absolute/path/to/your/repo
11
+ Restart=on-failure
12
+ RestartSec=3
13
+
14
+ [Install]
15
+ WantedBy=default.target
@@ -28,7 +28,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst
28
28
 
29
29
  Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt.
30
30
 
31
- Take the runners from the `architect runners` line in the model rule (`~/.pi/agent/pstack/pstack-models.md`), in place of the `arena runners` line. If the rule or that line is missing, use `claude-opus-5-5:xhigh` and `grok-4.7:xhigh`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
31
+ Take the runners from the `architect runners` line in the model rule at the path the system prompt names, in place of the `arena runners` line. If the rule or that line is missing, use `claude-opus-5-5:xhigh` and `grok-4.7[effort=xhigh,fast=true]`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
32
32
 
33
33
  Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.
34
34
 
@@ -1,6 +1,6 @@
1
1
  # Architect runner prompt
2
2
 
3
- The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates.
3
+ The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates. Worktrees and scratch directories share the host machine. Use the distinct ports, output directories, and writable cache paths assigned in the brief for concurrent runtime candidates. Report a missing assignment before starting a conflicting process. If the design requires stronger machine isolation, report it as unavailable.
4
4
 
5
5
  You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first. That's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
6
6
 
@@ -14,18 +14,18 @@ Every candidate gets the same prompt, so the prompt is the contract.
14
14
 
15
15
  1. State the artifact each candidate is producing.
16
16
  2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
17
- 3. Pick the runners. Use the `arena runners` line in `~/.pi/agent/pstack/pstack-models.md`. If the rule or that line is missing, default to one each on `claude-opus-5-5:xhigh` and `grok-4.7:xhigh`. An `auto` or `inherit-parent` entry in this line means the parent model, so omit `model` for it. If the Task tool rejects a configured entry, run that seat on its family's default and say so. Families go by the model id after the provider: `claude-*` and `grok-*`. If the family has no default, or the Task tool rejects that default, use the closest valid slug of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `model` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section of the **poteto-mode** skill.
18
- 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.
17
+ 3. Pick the runners. Use the `arena runners` line in the model rule at the path the system prompt names. If the rule or that line is missing, default to one each on `claude-opus-5-5:xhigh` and `grok-4.7[effort=xhigh,fast=true]`. An `auto` or `inherit-parent` entry in this line means the parent model, so omit `model` for it. If the Task tool rejects a configured entry, run that seat on its family's default and say so. Families go by the model id after the provider: `claude-*` and `grok-*`. If the family has no default, or the Task tool rejects that default, use the closest valid slug of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `model` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level (the `:<level>` suffix), and fast or standard speed when the model has a `-fast` variant, for the job, per the Subagents section of the **poteto-mode** skill.
18
+ 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill. Worktrees share this machine. Assign distinct ports, output directories, and writable cache paths for concurrent runtime candidates. If stronger machine isolation is required, report it as unavailable.
19
19
 
20
20
  ## Phase B: Fan out
21
21
 
22
- Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected.
22
+ Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected. When the project is a git repository, pass `environment: "cloud"` so each candidate runs in its own worktree; otherwise keep each candidate's writes under its own output path.
23
23
 
24
24
  If a candidate produces no output, proceed with N-1 and note the dropout.
25
25
 
26
26
  ## Phase C: Cross-judge
27
27
 
28
- After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in `~/.pi/agent/pstack/pstack-models.md`. If the rule or that line is missing, choose from `claude-opus-5-5:xhigh` and `grok-4.7:xhigh`. Spawn one readonly judge subagent. The judge is never from the parent's family, as Phase A step 3 defines families. Try only the entries from another family, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. With the default pool, a Claude parent gets `grok-4.7:xhigh`. A parent from any other family gets `claude-opus-5-5:xhigh` first. If the Task tool rejects an entry, use a valid slug of the same model at the closest level or speed from the error message, or move to the next entry when there is none. If no entry from another family runs, try the default pool's entries from another family the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If you do not know the parent's model, try the pool's real slugs in pool order and say that the family check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.
28
+ After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in the model rule at the path the system prompt names. If the rule or that line is missing, choose from `claude-opus-5-5:xhigh` and `grok-4.7[effort=xhigh,fast=true]`. Spawn one readonly judge subagent. The judge is never from the parent's family, as Phase A step 3 defines families. Try only the entries from another family, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. With the default pool, a Claude parent gets `grok-4.7[effort=xhigh,fast=true]`. A parent from any other family gets `claude-opus-5-5:xhigh` first. If the Task tool rejects an entry, use a valid slug of the same model at the closest level or speed from the error message, or move to the next entry when there is none. If no entry from another family runs, try the default pool's entries from another family the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If you do not know the parent's model, try the pool's real slugs in pool order and say that the family check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.
29
29
 
30
30
  ## Phase D: Pick a base
31
31
 
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: check-compiler-errors
3
+ description: Run compile and type-check commands and report failures
4
+ ---
5
+
6
+ # Check compiler errors
7
+
8
+ ## Trigger
9
+
10
+ Compile or type-check failures are blocking local validation or CI.
11
+
12
+ ## Workflow
13
+
14
+ 1. Run the repo's compile and type-check commands.
15
+ 2. Summarize errors by file and type.
16
+ 3. Fix the highest-confidence issues first.
17
+ 4. Re-run checks until clean or blocked.
18
+
19
+ ## Output
20
+
21
+ - Current compile and type-check status
22
+ - Error summary grouped by file and category
23
+ - Fixes applied and remaining blockers