@justjoshn/pi-pstack-v2 0.1.7 → 0.2.1

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 (64) hide show
  1. package/README.md +19 -7
  2. package/docs/guide/01-setup.md +6 -6
  3. package/docs/guide/02-poteto-mode.md +1 -1
  4. package/docs/guide/07-overnight.md +3 -3
  5. package/docs/pi-mechanisms.md +35 -53
  6. package/package.json +5 -3
  7. package/skills/arena/SKILL.md +5 -5
  8. package/skills/automate-me/SKILL.md +2 -2
  9. package/skills/benchmark-checklist/SKILL.md +1 -1
  10. package/skills/control-cli/SKILL.md +1 -1
  11. package/skills/figure-it-out/SKILL.md +1 -1
  12. package/skills/how/SKILL.md +2 -2
  13. package/skills/interrogate/SKILL.md +2 -2
  14. package/skills/maintain-verification-skill/SKILL.md +1 -1
  15. package/skills/make-bot-ui/SKILL.md +2 -2
  16. package/skills/no-comments/SKILL.md +1 -1
  17. package/skills/poteto-help/SKILL.md +3 -3
  18. package/skills/poteto-mode/SKILL.md +9 -9
  19. package/skills/poteto-mode/playbooks/autopilot-full.md +5 -5
  20. package/skills/poteto-mode/playbooks/babysit.md +1 -1
  21. package/skills/poteto-mode/playbooks/bug-fix.md +1 -1
  22. package/skills/poteto-mode/playbooks/eval.md +3 -3
  23. package/skills/poteto-mode/playbooks/feature.md +2 -2
  24. package/skills/poteto-mode/playbooks/hillclimb.md +1 -1
  25. package/skills/poteto-mode/playbooks/opening-a-pr.md +1 -1
  26. package/skills/poteto-mode/playbooks/perf-issue.md +1 -1
  27. package/skills/poteto-mode/playbooks/refactoring.md +1 -1
  28. package/skills/poteto-mode/playbooks/shipping.md +2 -2
  29. package/skills/poteto-mode/playbooks/worktree-cleanup.md +1 -1
  30. package/skills/poteto-mode/worker.md +1 -1
  31. package/skills/recall/SKILL.md +3 -3
  32. package/skills/review-and-ship/SKILL.md +1 -1
  33. package/skills/setup-pstack/SKILL.md +2 -2
  34. package/skills/show-me-your-work/SKILL.md +2 -2
  35. package/skills/statechart/SKILL.md +1 -1
  36. package/skills/statechart/references/render.md +1 -1
  37. package/skills/swarm/SKILL.md +4 -4
  38. package/skills/workflow-from-chats/SKILL.md +1 -1
  39. package/src/gondolin/bash.ts +51 -0
  40. package/src/gondolin/fs-operations.ts +56 -0
  41. package/src/gondolin/grep.ts +96 -0
  42. package/src/gondolin/index.ts +58 -0
  43. package/src/gondolin/paths.ts +34 -0
  44. package/src/gondolin/search.ts +67 -0
  45. package/src/gondolin/tools.ts +40 -0
  46. package/src/gondolin/vm.ts +65 -0
  47. package/src/index.ts +31 -130
  48. package/src/jobs.ts +58 -315
  49. package/src/subagent/agents/poteto-agent.md +1 -1
  50. package/src/subagent/agents/worker.md +5 -0
  51. package/src/subagent/dispatch.ts +2 -2
  52. package/src/subagent/index.ts +33 -2
  53. package/src/subagent/render-call.ts +4 -2
  54. package/src/subagent/run-single.ts +9 -7
  55. package/src/subagent/schema.ts +28 -2
  56. package/src/subagent/types.ts +7 -0
  57. package/src/subagent/wake-jobs.ts +69 -0
  58. package/src/credentials.ts +0 -171
  59. package/src/git.ts +0 -94
  60. package/src/paths.ts +0 -16
  61. package/src/requests.ts +0 -182
  62. package/src/sandbox.ts +0 -284
  63. package/src/sweep.ts +0 -187
  64. package/src/transcript.ts +0 -79
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  pstack for Pi. The package ships pstack's skills, playbooks, principles, agent roles, scripts, and guide, plus the cursor-team-kit skills that pstack depends on. It is for people who want `/skill:poteto-mode` and its workflow in Pi. Each Cursor mechanism is replaced with a Pi one.
4
4
 
5
5
  - Delegated Pi workers run through the packaged `subagent` tool, which starts each `pi` in its own tmux session.
6
- - Long-running commands run in a sandbox via `tmux_run`, Seatbelt on macOS and bubblewrap on Linux and WSL2. There are no permission prompts.
6
+ - Pi's built-in tools (`read`, `write`, `edit`, `bash`, `ls`, `find`, `grep`) and `!` shell commands run inside a Gondolin micro-VM, ported from Pi's `gondolin` example extension. There are no permission prompts.
7
7
  - Plans are files, and checklists live in `TODO.md`.
8
8
  - Watchers, dev servers, and heartbeat ticks run through `tmux_run`, never as background shell jobs.
9
9
 
@@ -17,10 +17,16 @@ pi install npm:@justjoshn/pi-pstack-v2
17
17
 
18
18
  Built and tested against Pi 1.5.2. Do not install another pstack package alongside it. Skill names collide, and Pi keeps only the first it finds.
19
19
 
20
+ npm 11.20 and later warn that `ssh2` and `cpu-features` have install scripts not yet covered by `allowScripts`. Both come from Gondolin, through its SSH support. Their scripts only try to compile optional native speedups, which pstack does not need. The VM boots without either build. Only the root `package.json` in Pi's npm directory can hold `allowScripts`, so this package cannot answer for you. After installing, deny both once. npm keeps the entry across `pi update`.
21
+
22
+ ```sh
23
+ cd ~/.pi/agent/npm && npm install-scripts deny ssh2 cpu-features
24
+ ```
25
+
20
26
  ## Requirements
21
27
 
22
28
  - tmux. Pi's `docs/tmux.md` covers the extended-keys setup.
23
- - A sandbox. macOS has Seatbelt built in. On Linux and WSL2, install bubblewrap (`bwrap`). Jobs refuse to start without one.
29
+ - QEMU, for the Gondolin VM (`brew install qemu` on macOS). Gondolin downloads its guest image on first use.
24
30
  - bun and `gh`, for the scripts some skills run, such as `watch-pr` and `statechart`.
25
31
  - `jq` and `rg` (ripgrep), for `worktree-audit.sh` and the `pr-review-canvas` skill.
26
32
 
@@ -36,18 +42,24 @@ Type `/skill:poteto-help` with a question if you are unsure which skill fits.
36
42
 
37
43
  ## What it adds
38
44
 
39
- The package adds the upstream `subagent` tool (tmux-backed), `tmux_run`, `tmux_jobs`, and one slash command. Every skill runs as `/skill:<name>`. `/pstack-mode <skill>` keeps a skill in the system prompt every turn, pstack's Custom Mode, until `/pstack-mode off`.
45
+ The package adds the upstream `subagent` tool (tmux-backed), `tmux_run`, `tmux_jobs`, the Gondolin tool routing, and two slash commands. Every skill runs as `/skill:<name>`. `/pstack-mode <skill>` keeps a skill in the system prompt every turn, pstack's Custom Mode, until `/pstack-mode off`. `/gondolin` shows the session's VM.
40
46
 
41
47
  | Tool | Does |
42
48
  | --- | --- |
43
49
  | `subagent` | Upstream subagent extension: delegates to specialized agents as separate `pi` processes, each started in tmux. |
44
- | `tmux_run` | Runs a sandboxed shell command in tmux. Optionally wakes your session when it exits, or repeats it as a heartbeat. |
50
+ | `tmux_run` | Runs a shell command on the host in tmux. Optionally wakes your session when it exits, or repeats it as a heartbeat. |
45
51
  | `tmux_jobs` | Lists, tails, waits on, or stops this session's jobs. |
46
52
 
47
- ## Notes
53
+ ## Gondolin
54
+
55
+ `src/gondolin` is Pi's [`gondolin` example extension](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/gondolin), split into modules in this package's style. It behaves as the example does.
48
56
 
49
- - Jobs never write your Pi agent directory. Each top-level job's Pi gets its own, with a copy of your credentials. The extension syncs refreshed OAuth tokens back to your login.
50
- - A job may write only its own directory, its worktree or working directory, the repository's git directory, and temp directories.
57
+ - Each Pi process boots one VM when its session starts and closes it when the session ends. A `subagent` worker is its own Pi process, so it gets its own VM.
58
+ - The directory Pi started in is mounted at `/workspace`. Writes there reach the host. Every other guest path is the VM's own filesystem, and changes there stay in the VM.
59
+ - The system prompt names `/workspace` as the working directory, so the model works in guest paths.
60
+ - A host path outside the working directory does not exist in the guest, except this package, which is mounted read-only at its host path so the model can `read` the skill files Pi names. The system prompt says so, and says which commands only the host has.
61
+ - The guest image ships `node` but not `git`, `gh`, `tmux`, or `bun`. Commands that need them run on the host through `tmux_run`.
62
+ - `tmux_run`, `tmux_jobs`, and the `pi` processes `subagent` starts run on the host, outside the VM.
51
63
 
52
64
  ## Replaces `@justjoshn/pi-pstack`
53
65
 
@@ -14,18 +14,18 @@ The npm package `@justjoshn/pi-pstack-v2` is not published yet. Once it is, `pi
14
14
 
15
15
  Add `--local` to write the declaration to the project's `.pi/settings.json` instead of your personal settings. `pi list` shows what is installed. Installing adds the skills and tools but starts no workflow. Nothing changes until you send `/skill:poteto-mode` or turn on `/pstack-mode`. Pi runs each skill as `/skill:<name>`, so every command in this guide takes that prefix.
16
16
 
17
- The package adds three tools. `pi_spawn` starts a separate Pi in its own tmux session. `tmux_run` runs a shell command in its own tmux session. `tmux_jobs` lists, waits on, and stops both kinds of job. Pi has no sub-agents and no detached shell, so every parallel worker and every watcher in this guide is one of these jobs.
17
+ The package adds three tools. `subagent` starts separate Pi workers, each in its own tmux session, and returns their reports when they finish. `tmux_run` runs a shell command in its own tmux session. `tmux_jobs` lists, waits on, and stops those shell jobs. Pi has no sub-agents and no detached shell, so every parallel worker in this guide is a `subagent` worker and every watcher is a `tmux_run` job.
18
18
 
19
- **Watch your workers.** `tmux_jobs` with `action: "list"` shows each job and prints a `tail -f` command that follows its output. Use `output` to read a job's log and `wait` to block until jobs finish. Use `stop` to end one. When a job exits, its report arrives in your session as a steering message after the current tool calls finish, so you can keep working or end your turn and wait.
19
+ **Watch your jobs.** `tmux_jobs` with `action: "list"` shows each job and prints a `tail -f` command that follows its output. Use `output` to read a job's log and `wait` to block until jobs finish. Use `stop` to end one. When a job exits, its report arrives in your session as a steering message after the current tool calls finish, so you can keep working or end your turn and wait.
20
20
 
21
- ## Check tmux and the sandbox
21
+ ## Check tmux and Gondolin
22
22
 
23
23
  pstack needs two things on your machine.
24
24
 
25
25
  - **tmux.** Every job runs in a tmux session, and the wake that brings a finished job's report back to your session depends on it.
26
- - **A sandbox.** Pi has no permission popups. Each `pi_spawn` and `tmux_run` job runs inside a sandbox instead, and a job can write only to its own directory, its worktree or working directory, the repository's git directory, and temp directories. macOS has Seatbelt built in. Linux and WSL2 need bubblewrap (`bwrap`). With neither, the tools refuse to start.
26
+ - **QEMU, for Gondolin.** Pi has no permission popups. Pi's built-in tools run inside a Gondolin micro-VM instead, with the directory Pi started in mounted at `/workspace`. Writes there reach your checkout, and every other guest path is the VM's own. Install QEMU (`brew install qemu` on macOS). Gondolin downloads its guest image on first use, and `/gondolin` shows the VM.
27
27
 
28
- The sandbox covers the jobs, not your main session. To contain the main session too, run Pi inside an isolated environment, as Pi's guide to isolated environments describes. Do that before you run anything unattended.
28
+ The VM covers Pi's own tools, not `tmux_run` jobs, which run on your machine. The guest has no `git` or `gh`, so commits, pushes, and PRs go through `tmux_run`. To contain everything, run Pi inside an isolated environment, as Pi's guide to isolated environments describes. Do that before you run anything unattended.
29
29
 
30
30
  ## Pick your models
31
31
 
@@ -43,7 +43,7 @@ The defaults are the same as the `large` budget. Code, prose, and judgment run a
43
43
 
44
44
  You only override what you care about. A role with no line in the file keeps the skill's default. To restore a default, delete that role's line. A rerun of `/skill:setup-pstack` keeps any role whose model differs from the default. When a default changes, a file written before the change still pins the old default until you run `/skill:setup-pstack` again. That run replaces the old defaults it recognizes, tells you which, and keeps your other choices. To drop a pin it does not recognize, delete that role's line or the file first.
45
45
 
46
- You might be wondering what happens if you want a role to follow whatever model you're using. Set it to `inherit-parent` or `auto` and pstack omits the model on that role's `pi_spawn` call, so the spawned Pi runs on your session model. Both values mean the same thing, and neither is a model. For a panel role the value is a list, and one spawned Pi runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/skill:swarm` worker unless a race names a model for each arm.
46
+ You might be wondering what happens if you want a role to follow whatever model you're using. Set it to `inherit-parent` or `auto` and pstack omits the model on that role's `subagent` call, so the worker runs on your session model. Both values mean the same thing, and neither is a model. For a panel role the value is a list, and one spawned Pi runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/skill:swarm` worker unless a race names a model for each arm.
47
47
 
48
48
  ## Accept the verification offers, or don't
49
49
 
@@ -125,7 +125,7 @@ A long chat accumulates context from the last task. When you change subjects, sa
125
125
 
126
126
  ## Give parallel work its own worktree
127
127
 
128
- If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a git worktree per worker. A spawned Pi started with a `worktree` branch gets its own checkout, and its sandbox confines its writes there, so it can install dependencies, run your app, and record video of the result without touching your working tree. A worktree does not isolate ports, so two workers that start the same dev server still collide. Give each its own port. The coordinator does this on its own for parallel code work. You can also ask for a worktree up front:
128
+ If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a git worktree per worker. A spawned Pi started with a `worktree` branch gets its own checkout, and its Gondolin VM mounts only that checkout, so it can install dependencies, run your app, and record video of the result without touching your working tree. A worktree does not isolate ports, so two workers that start the same dev server still collide. Give each its own port. The coordinator does this on its own for parallel code work. You can also ask for a worktree up front:
129
129
 
130
130
  ```text
131
131
  /skill:poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
@@ -1,6 +1,6 @@
1
1
  # Run work while you sleep
2
2
 
3
- This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree inside a sandbox, and a decision log you audit in the morning.
3
+ This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree inside a VM, and a decision log you audit in the morning.
4
4
 
5
5
  ![She waves goodnight from the door while robots keep the factory running, one updating a DECISION LOG wall board under a BUILD LOOP ACTIVE sign.](./images/overnight.jpg)
6
6
 
@@ -33,7 +33,7 @@ Walk through what each line buys you:
33
33
  - "fresh worktree off `<base>`" keeps the run from colliding with anything else you have open.
34
34
  - "don't ask me before committing" pre-answers the permission the agent would otherwise block on.
35
35
  - The heartbeat is a `tmux_run` job, not a pstack skill. A watcher runs with a `wake` message and wakes your session when it exits. A timer runs `sleep <seconds>` with `repeat: true`, and each tick wakes the session with the tick prompt. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses both to re-check the finish condition on events or on a timer. Stop a heartbeat with `tmux_jobs` and `action: "stop"`.
36
- - The sandbox is the permission model. Pi has no permission popups, so a job can write only to its own worktree, the repository's git directory, and temp directories. Run the main session in an isolated environment too, as the [setup page](./01-setup.md#check-tmux-and-the-sandbox) says.
36
+ - The Gondolin VM is the permission model. Pi has no permission popups, so Pi's tools reach only the directory each Pi started in. `tmux_run` jobs run on your machine, so run the main session in an isolated environment too, as the [setup page](./01-setup.md#check-tmux-and-gondolin) says.
37
37
  - The escape hatch lets it stop at a genuine dead end and write up why, which beats eight hours of creative goal reinterpretation.
38
38
 
39
39
  Because you'll review this work after stepping away, `/skill:poteto-mode` routes it through [`/skill:figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases before any code and wires in the decision log.
@@ -94,7 +94,7 @@ A whole program, such as a migration across many packages, has no playbook of it
94
94
 
95
95
  ## Run many projects in parallel
96
96
 
97
- A coordinator session is the Project. It doesn't write code. It directs spawned Pis, each in its own worktree and sandbox, and each one wakes the coordinator with its report when it exits. Run the coordinator inside an isolated environment, as Pi's guide to isolated environments describes, so it can sit through the night. Start your prompts to the coordinator with `/skill:poteto-mode`, and the Pis it spawns follow the playbooks. Each Pi it starts reads [`worker.md`](../../skills/poteto-mode/worker.md) first, so workers hold to the kickoff's bar, decide reversible calls instead of asking you, and open PRs ready for review.
97
+ A coordinator session is the Project. It doesn't write code. It directs spawned Pis, each in its own worktree and VM, and each one wakes the coordinator with its report when it exits. Run the coordinator inside an isolated environment, as Pi's guide to isolated environments describes, so it can sit through the night. Start your prompts to the coordinator with `/skill:poteto-mode`, and the Pis it spawns follow the playbooks. Each Pi it starts reads [`worker.md`](../../skills/poteto-mode/worker.md) first, so workers hold to the kickoff's bar, decide reversible calls instead of asking you, and open PRs ready for review.
98
98
 
99
99
  A few habits help:
100
100
 
@@ -9,34 +9,34 @@ Pi skips sub-agents, permission popups, plan mode, built-in to-dos, and backgrou
9
9
  | Pi rule | What pstack does |
10
10
  | --- | --- |
11
11
  | Spawn Pi instances via tmux. | The packaged `subagent` tool starts each delegated `pi` in its own tmux session (upstream subagent example, with the process launch switched from `child_process.spawn` to tmux). |
12
- | No permission popups. Run in a sandbox. | Every `pi_spawn` and `tmux_run` job runs inside Seatbelt (`sandbox-exec`) on macOS or bubblewrap (`bwrap`) on Linux and WSL2. Writes are limited to the worker's own session directory, its worktree or working directory, the repository's git directory, and temp directories. Pi's own configuration stays read-only. No job runs unsandboxed. |
12
+ | No permission popups. Run in a sandbox. | The packaged `gondolin` extension, Pi's own `gondolin` example, runs `read`, `write`, `edit`, `bash`, `ls`, `find`, `grep`, and `!` shell commands inside a Gondolin micro-VM. The directory Pi started in is mounted at `/workspace`, and writes there reach the host. Every other guest path is the VM's own. |
13
13
  | No plan mode. Write plans to files. | A plan is a Markdown file, such as `plans/<slug>.md`. The human reviews the file. |
14
14
  | No built-in to-dos. Use a TODO.md file. | Each checklist pstack used to keep in a todo tool lives in `TODO.md` at the root of the checkout you work in, as `- [ ]` and `- [x]` lines. It is working state, so never stage it. When the checkout already tracks a `TODO.md`, the checklist is `.pi/TODO.md`. |
15
15
  | No background bash. Use tmux. Full observability, direct interaction. | Watchers, dev servers, long builds, and heartbeat ticks run through `tmux_run`. Nothing uses `&`, `nohup`, `setsid`, or `disown`. Every job is a tmux session you can attach to with the command `tmux_jobs` `list` prints. Its output shows there as it is written, and Ctrl-C there stops it. A job reads no input, so a command that needs an answer typed runs in the root session. |
16
16
 
17
- Pi's design principle for customizing is to pick the least powerful mechanism that meets the need. Skills carry all workflow text. The one extension (`src/index.ts`) exists only for what a skill cannot do: start sandboxed tmux jobs, wake the session when they exit, and put the model-role lines into the system prompt.
17
+ Pi's design principle for customizing is to pick the least powerful mechanism that meets the need. Skills carry all workflow text. The extensions exist only for what a skill cannot do. `src/index.ts` starts tmux jobs, wakes the session when they exit, and puts the model-role lines into the system prompt. `src/subagent` starts workers. `src/gondolin` runs Pi's tools in a VM.
18
18
 
19
19
  ## Vocabulary
20
20
 
21
21
  | Cursor or Claude Code | Pi |
22
22
  | --- | --- |
23
- | Subagent, `Task` call, delegate, worker | A Pi instance started with `pi_spawn`. Call it a worker, a spawned Pi, or by its role (explorer, reviewer, runner). Never call it a subagent. |
24
- | `subagent_type: "poteto-agent"`, `"comment-sicko"`, `"ci-watcher"`, `"thermo-nuclear-code-quality-review"` | `pi_spawn` with `agent: "<name>"`. The role text comes from `agents/<name>.md`. |
25
- | `subagent_type: generalPurpose`, `"shell"`, `"explore"` | `pi_spawn` with no `agent`. |
26
- | `readonly: true` (Ask mode) | `pi_spawn` with `readonly: true`. The sandbox denies writes outside the job directory and the edit and write tools are removed. MCP and shell stay available, so a reviewer that needs MCP can still be readonly. Here the network stays open, so readonly stops local writes only. A readonly worker can still change remote state with `gh`, `curl`, or an MCP tool, so the brief says what it must not change. |
27
- | `readonly: false` (agent mode) | Leave `readonly` unset. |
28
- | `environment: "cloud"`, Cursor cloud agent, `cloud_base_branch` | `pi_spawn` with `worktree: "<branch>"` and `base: "<ref>"`. The worker gets its own git worktree, and the sandbox confines its writes there. Cursor cloud agents start from the repository's default branch. A worktree here starts from the session's current `HEAD` unless `base` names another ref, so pass the default branch as `base` to start from it. |
29
- | `environment: "local"` | Omit `worktree`. |
30
- | `run_in_background: true` | Nothing to set. Every `pi_spawn` runs in parallel, and you are woken when it exits. Keep working or end your turn. |
31
- | Spawn N in one message | N `pi_spawn` calls in one message. |
32
- | Nested subagents, launched by a subagent | pstack allows one level, which every pstack workflow fits. The root Pi and the workers it starts have `pi_spawn`. A worker started by another worker does not, and the root refuses a Pi request from one. Every worker keeps `tmux_run` and `tmux_jobs`. |
33
- | `resume` an agent | `pi_spawn` with `resume: "<job id>"` continues that job's Pi session. |
34
- | Steer or stop a running agent | `tmux_jobs` with `action: "stop"`, then a fresh `pi_spawn` with consolidated scope. A print-mode Pi takes no mid-run input. |
35
- | Wait for agents | End your turn and let the wake arrive. `tmux_jobs` `wait` is for a short wait on named jobs. A spawned Pi running in print mode waits for its own jobs automatically before it finishes. |
23
+ | Subagent, `Task` call, delegate, worker | A Pi instance started with the `subagent` tool. Call it a worker, a subagent, or by its role (explorer, reviewer, runner). |
24
+ | `subagent_type: "poteto-agent"`, `"comment-sicko"`, `"ci-watcher"`, `"thermo-nuclear-code-quality-review"` | A subagent call with `agent: "<name>"`. The role text comes from `agents/<name>.md`. |
25
+ | `subagent_type: generalPurpose`, `"shell"`, `"explore"` | A subagent call with `agent: "worker"`, which has every editing tool and no role prompt, or `agent: "scout"` for read-only work. Use `agent: "poteto-agent"` only for a poteto-mode delegate whose brief names poteto-mode's path. |
26
+ | `readonly: true` (Ask mode) | A subagent call with `agent: "scout"`, which has no edit or write tool. MCP and shell stay available, so a reviewer that needs MCP can still be read-only. Its `bash` can still write, and the network stays open. A scout can still change remote state with `gh`, `curl`, or an MCP tool, so the brief says what it must not change. When the role needs another agent, the brief says the worker must not edit. |
27
+ | `readonly: false` (agent mode) | An agent with edit and write tools, such as `poteto-agent`. |
28
+ | `environment: "cloud"`, Cursor cloud agent, `cloud_base_branch` | Before the call, create a worktree on the host with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>`, inside the working directory so the VM can edit it. Then pass that path as the subagent call's `cwd`. Cursor cloud agents start from the repository's default branch, so name the default branch as `<ref>` to start from it. |
29
+ | `environment: "local"` | Omit `cwd`. The worker runs in your working directory. |
30
+ | `run_in_background: true` | A subagent call with a wake message. It returns a job id at once and wakes you with the message and the report when every worker finishes. Without one, the call blocks until its workers finish and returns their reports. |
31
+ | Spawn N in one message | One `subagent` call with `tasks`, up to 8 tasks run 4 at a time. Use a `chain` when each step needs the last one's output, and `{previous}` in a task is the prior step's output. |
32
+ | Nested subagents, launched by a subagent | A worker loads the same extensions, so it has `subagent`, `tmux_run`, and `tmux_jobs` too. Keep to one level, which every pstack workflow fits. |
33
+ | `resume` an agent | Not available. Each worker runs `pi` with no session. A fix round goes to a fresh worker, and passing the prior worker's worktree as `cwd` keeps its uncommitted state. |
34
+ | Steer or stop a running agent | `subagent` with `stop: "<job id>"` for a wake job, or abort a blocking call, then give a fresh worker consolidated scope. A print-mode Pi takes no mid-run input. |
35
+ | Wait for agents | A blocking `subagent` call returns when its workers finish. A wake job wakes you, so end your turn and let the wake arrive. `tmux_jobs` `wait` is for a short wait on named `tmux_run` jobs. A worker running in print mode waits for its own `tmux_run` jobs and wake jobs before it finishes. |
36
36
  | `file_attachments` | List the paths in the brief. |
37
- | `model` slug such as `claude-opus-5-5-xhigh` or `grok-4.7-xhigh-fast` | `pi_spawn` `model: "<provider>/<id>"` and `thinking: "<level>"`. Thinking levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Pi has no fast variant, so a "fast" choice is dropped. |
37
+ | `model` slug such as `claude-opus-5-5-xhigh` or `grok-4.7-xhigh-fast` | `subagent` `model: "<provider>/<id>"` and `thinking: "<level>"`. Thinking levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. A call's model and thinking override the agent's and the session's. Pi has no fast variant, so a "fast" choice is dropped. |
38
38
  | `~/.cursor/rules/pstack-models.mdc`, `~/.claude/rules/pstack-models.md` | `~/.pi/agent/pstack-v2-models.md`, written by `/skill:setup-pstack`. The extension shows its role lines to the model in a `pstack-models` system-prompt section. A role with no line, or a line of `inherit-parent` or `auto`, runs on the session model, so omit `model`. |
39
- | A model slug the Task tool rejects | A model `pi_spawn` rejects. It accepts only `provider/id` values that `pi --list-models` prints, which are the models Pi holds credentials for. Any other model fails at the call with the list of valid ones, before a job or worktree exists, and an omitted model runs on the session model. |
39
+ | A model slug the Task tool rejects | A worker that fails because its model is not valid. Only `provider/id` values that `pi --list-models` prints work, which are the models Pi holds credentials for. An omitted model runs on the session model. |
40
40
  | Open a todolist, `TodoWrite` | Write `TODO.md`. |
41
41
  | Custom Mode (Option+Enter on a slash skill) | `/pstack-mode <skill>`. The extension puts the skill in a `pstack-mode` system-prompt section every turn and records the choice on the session branch, so it survives `/compact`, resume, and `/tree`. `/pstack-mode off` ends it, and the footer shows the active mode. |
42
42
  | `AskQuestion` (multiple-choice popup) | Ask in plain text with numbered options, then end your turn. Pi has no question popups. |
@@ -49,54 +49,36 @@ Pi's design principle for customizing is to pick the least powerful mechanism th
49
49
  | `.cursor/skills/`, `~/.cursor/skills/` | `.pi/skills/`, `~/.pi/agent/skills/`, or the Agent Skills paths `.agents/skills/` and `~/.agents/skills/`. |
50
50
  | `.cursor/rules/*.mdc`, always-applied rules | `AGENTS.md` (project) or `~/.pi/agent/AGENTS.md` (user). |
51
51
  | `~/.cursor/plugins/`, `.cursor-plugin/plugin.json`, `/add-plugin` | A Pi package: `pi install <source>`, listed by `pi list`. |
52
- | Cursor chat transcripts in `~/.cursor/projects/<slug>/agent-transcripts/` | Pi sessions in `~/.pi/agent/sessions/--<cwd with / as ->--/*.jsonl`. Spawned workers keep theirs in `~/.pi/agent/pstack-v2/jobs/<id>/session/`. The extension names the current session's file in a `pstack-session` system-prompt section, and a brief that asks a worker to read it carries that path, because a worker's agent directory is its job's own. |
52
+ | Cursor chat transcripts in `~/.cursor/projects/<slug>/agent-transcripts/` | Pi sessions in `~/.pi/agent/sessions/--<cwd with / as ->--/*.jsonl`. Workers run with no session, so they keep none. The extension names the current session's file in a `pstack-session` system-prompt section, and a brief that asks a worker to read it carries that path, because a worker cannot find it by itself. |
53
53
  | `/create-skill` | Write `SKILL.md` to Pi's skills spec (Agent Skills format) and check it loads with `/skill:<name>`. |
54
54
  | Cursor Automations, routines, webhook wakes, `SendToUser` | A tmux job that runs `pi -p` against a session, or Pi's RPC mode. Secrets come from environment variables the user sets, never from chat. Upstream's dormant benny pack (Slack issue triage, then reproduce-and-fix) runs only on that service, so this package does not ship it. |
55
55
  | Cursor canvas | A self-contained HTML file opened in the browser. |
56
56
  | Cursor Bugbot, agentic security review | Unchanged. They are GitHub reviewers whose comments any harness reads from the forge. |
57
57
  | Cursor's built-in PR tool | `gh`. |
58
58
  | MCP tools | Pi's built-in MCP (`pi mcp list`, `~/.pi/agent/mcp.json`, `.pi/mcp.json`) and Codemode (`"defaultTools": ["+codemode"]` in settings). Workers get a copy of your settings, so they have the same MCP servers and Codemode. |
59
- | Cursor's agent store, project store, project tracker | Files in the checkout: `decisions.tsv` and `plans/`. A worker keeps its `decisions.tsv` in its worktree, which the root reads at `<agent dir>/pstack-v2/jobs/<id>/worktree/`. |
59
+ | Cursor's agent store, project store, project tracker | Files in the checkout: `decisions.tsv` and `plans/`. A worker keeps its `decisions.tsv` in its `cwd`, where the root reads it. |
60
60
  | Orchestrate's `notes.md` | A file at the checkout root, never staged, like `TODO.md`. |
61
61
  | Origin (`origin pr`) | Kept as is when `command -v origin` succeeds and Origin resolves the repository, otherwise `gh`. Graphite is never required. |
62
- | Hold or stand-down order to running agents | `tmux_jobs` `stop` after each worker commits a `wip:` checkpoint, then a fresh `pi_spawn` to release. |
63
- | A lane that needs a simulator, `open`, a local display or socket, or auth that exists only on this machine | Run it in the root session, which is not sandboxed. |
62
+ | Hold or stand-down order to running agents Each worker commits a `wip:` checkpoint, then the `subagent` call is aborted, and a fresh worker releases the hold. |
63
+ | A lane that needs a simulator, `open`, a local display or socket, or auth that exists only on this machine | Run it on the host through `tmux_run`, since Pi's own `bash` runs in the Gondolin VM. |
64
64
 
65
- ## Sandbox details
65
+ ## Gondolin details
66
66
 
67
- - macOS uses a Seatbelt profile. Linux and WSL2 use bubblewrap. With neither available, `pi_spawn` and `tmux_run` refuse to start.
68
- - A job writes only its working directory or worktree, that checkout's git directory, its own private temp directory, and for Pi workers its own `session/` and `nested/` directories. Every other write is denied.
69
- - Both sandboxes enforce the same rules, and `test/parity.test.ts` runs one table of operations inside a real job on each platform and fails on any difference beyond the Linux exceptions listed below.
70
- - A job cannot add or change a git worktree or submodule, apart from the metadata of the worktree it works in, and cannot write the git directory of a nested repository. A job that needs another revision beside its own exports it into its private temp directory with `git archive <sha> | tar -x -C "$TMPDIR/<name>"`.
71
- - bubblewrap can make only existing paths read-only, so before a job starts the root creates any missing `hooks/`, `info/`, `worktrees/`, and `modules/` directory and `config.worktree` file in the git directory, empty, on every platform. Git reads them as nothing.
72
- - Shared temp directories and user caches are not writable, because unsandboxed programs load code cached there, such as Pi's compiled-extension cache. Each job's `TMPDIR`, `XDG_CACHE_HOME`, and npm, bun, pip, uv, Go, Yarn, and Deno caches point at its private temp directory, so installs and builds still work. Those caches are deleted when the job exits, and the rest of its temp directory is kept for the report. Chromium follows `MAC_CHROMIUM_TMPDIR` and zsh follows `TMPPREFIX`, both set to the same directory. On macOS a job finds a `mktemp` first on `PATH` that uses `$TMPDIR`, since the system one prefers the per-user temp directory. A command a worker starts shares the worker's temp directory. On Linux the job also gets a private `/tmp`.
73
- - `cwd` must be inside the session's project, which is the git top level or else the session cwd, or a linked worktree of the same repository. A checkout of another repository is refused even when it sits inside the project, since the job would be handed that repository's git directory. No writable path may contain Pi's agent directory. The model cannot widen its own sandbox by naming another directory.
74
- - Paths an unsandboxed process later executes from stay read-only even inside a writable checkout. Those are the git `hooks/`, `config`, `config.worktree`, and `info/` entries, a configured `core.hooksPath`, and the code entries of every `.pi` directory in the checkout at any depth: `extensions`, `settings.json`, `mcp.json`, and installed packages in `npm` and `git`. Editor and agent-harness configuration also stays read-only at any depth, since editors and agent harnesses run its tasks, hooks, and MCP servers unsandboxed when you open the checkout: `.vscode`, `.idea`, `*.code-workspace`, `.cursorignore`, and every entry of `.cursor` and `.claude` apart from their instruction directories `rules`, `commands`, `worktrees`, `skills`, and `agents`, which a job may still write. Git finds hooks through `.git`, every `.git` pointer file such as a submodule's, every linked worktree's `commondir`, `gitdir`, and `config.worktree`, and submodule git directories, so all of those stay read-only. Every existing directory above a protected path, and `.git` itself, cannot be renamed or replaced. A protected path that is a symlink is guarded at the link as well as its target.
75
- - Code can still appear where none was at launch, because a job can rename a directory it built into place or link a parent elsewhere, and bubblewrap cannot bind what does not exist. At launch the root records every protected path, `.pi` code entry, editor or harness entry, and `.git` entry in the checkout. When the job exits or is stopped, the unsandboxed wrapper sweeps the checkout and moves anything new of those kinds into the job's `quarantine/` directory, and the job's output says so. The sweep never follows a link, and a `.pi` symlink you already had is left alone. Moving, not deleting, keeps a file you created yourself during the job recoverable. On macOS, Seatbelt also denies writing those paths anywhere in the checkout.
76
- - Jobs never write your Pi agent directory, your `auth.json` included. Each top-level job gets its own agent directory, through Pi's `PI_CODING_AGENT_DIR`, shared by every job it starts. It links to your configuration, holds `settings.json` with its local package paths anchored to your real agent directory, and holds a copy of your credentials. In it a job may write only the contents of that copy and Pi's lock directories, so no job can change what another job's Pi loads. On Linux it is a throwaway tmpfs view, so other writes there vanish with the job.
77
- - Pi runs an `auth.json` key that starts with `!` as a command, so the credentials copy holds no command. For a worker's own provider, the root resolves the command once when it starts the worker and puts the resulting key in the copy. Every two seconds, and once more after a job ends, the root carries refreshed OAuth tokens between your `auth.json` and each copy, the later expiry winning, under Pi's lock on both. Only OAuth tokens move, so nothing a job writes as a key or a command reaches your `auth.json`, and a provider you logged out of is never brought back.
78
- - A job cannot reach the services that would start a process for it. It can neither connect to nor serve a Unix socket, so every tmux server, Docker's socket, the session bus, and every other local service are out of reach. Socket pairs, which child processes use for pipes, still work. macOS denies binding and connecting Unix sockets apart from DNS's, and Linux refuses opening one through a seccomp filter, which also refuses io_uring. On macOS it also cannot use LaunchServices (`open`), Apple Events, launchd, or preference writes, and it can signal only processes in its own sandbox. On Linux `/run` and the user's runtime directory are hidden, and the job runs in its own PID namespace.
79
- - When a job exits, its whole process group is killed before cleanup, so no child it left behind acts after cleanup. Stopping a job sends TERM, then KILL after three seconds. On Linux every process in its PID namespace dies with it.
80
- - A Pi worker's own jobs get their own sandbox, so `readonly` holds at any depth, and a resumed worker keeps its `readonly`. On every platform a sandboxed worker writes the job as a request in its `nested/` directory, and the root Pi launches it under a profile built from the paths it validated. The root refuses any request that would write, or run, outside what it granted the top-level worker, so no worker can hand a descendant more than it was given. The root writes results only under the top-level job, never into a worker's directory, and serves requests while it runs. A worker's sandbox keeps `.git/worktrees` read-only, so when a worker passes `worktree` to `pi_spawn`, its request carries the branch and base, and the root creates the worktree from the worker's own checkout before it launches the job. The checkout lands in the job's results directory, `<top-level job>/brokered/<hash>/worktree`, which no worker can write, so no worker can swap in a link for git to check out through. The root creates it only for a worker that may write the repository and only at that path, computes the checkout's protected paths itself, keeps a `readonly` job read-only, creates nothing for a request it refuses, and removes the worktree and any branch it created when it cannot launch the job. If you quit the root Pi, nested requests wait until you resume that session.
81
- - Start the main session sandboxed too when you want it contained. Pi's guide to isolated environments lists the methods, and not all of them need Docker.
67
+ - `src/gondolin` is Pi's `gondolin` example extension, split into modules. It behaves as the example does, and `test/gondolin.test.ts` pins that behavior without booting QEMU.
68
+ - Each Pi process boots one VM when its session starts and closes it at shutdown. Tool calls made while it boots wait for the same VM. A worker that `subagent` starts is its own Pi process, so it gets its own VM, mounted on its own working directory.
69
+ - Paths map to the guest the same way for every tool. A relative path, or a host path inside the working directory, lands under `/workspace`. Any other absolute path names that path in the guest's own filesystem.
70
+ - The system prompt's working-directory line names `/workspace` and the host directory it comes from.
71
+ - `/gondolin` shows the VM id, the host and guest workspaces, and the shell. Commands run in `bash` when the guest has it, and in `/bin/sh` otherwise.
72
+ - QEMU must be installed. Gondolin downloads its guest image on first use.
82
73
 
83
- ## What the sandbox does not cover
74
+ ## What Gondolin does not cover
84
75
 
85
- - Reads and network access stay open, so a job can read anything you can and send it over the network.
86
- - A writer job's changes are code you and the root Pi later run, such as tests, builds, package scripts, Makefiles, `.envrc`, a nested repository with its own `.git`, and instruction files such as `AGENTS.md` and `.pi/skills`. Review a worker's diff before you run or trust it, as with any agent.
87
- - A worker can use a provider whose credential is a `!command` only when that provider is its own model's, since the root resolves only that one. Set a key or log in with OAuth for any other provider a worker needs.
88
- - On Linux a job can create a `.pi` code entry, an editor or harness entry, or a `.git` entry where none existed at launch, since bubblewrap binds only paths that exist and neither Landlock nor seccomp can refuse one name inside a writable directory. macOS denies these while the job runs. On both, the sweep moves them out when the job ends.
89
- - On Linux a job can add new files to its own agent directory, since Pi takes its locks there as new directories and bubblewrap cannot admit only names ending in `.lock`. That directory is a private copy in memory, so the files vanish when the job ends and no other job or the root sees them. macOS denies them.
90
- - On Linux a job takes Pi's credential lock in its own throwaway view, so a job refreshing a token and the root syncing that copy at the same moment can lose that refresh. pstack refreshes a worker's credentials just before starting it, so this needs a worker to outlive its token.
91
- - A job can leave a fake rebase in progress in the git directory, whose steps run if you then run `git rebase --continue`.
92
- - A print-mode run waits for every job it started with a wake message, so one that never exits keeps it running.
93
- - On macOS a job cannot run `ps` or `top`, so it reads the load with `uptime`. A bash here-document fails in a checkout the job cannot write, such as a readonly worker's, so the job changes to `$TMPDIR` first or writes with `printf`.
94
- - Cargo and Maven caches are not redirected to the job's private temp directory, so their downloads fail inside a job.
95
- - Until a job exits, a protected path it created by rename or link still exists, and an unsandboxed process started in that checkout during the job could use it.
96
- - On macOS a job process that detaches into its own session with `setsid` survives `stop` and keeps its sandbox rights, still inside its sandbox. It can keep writing what the job could write, including a protected path after cleanup ran. The credential check still reverts any command key it plants. Linux has no such gap, because the PID namespace ends every process.
97
- - A job can hold the lock on its credentials copy, which pauses token sync for that job until it ends.
98
- - A job's agent directory is read-only apart from its credentials copy and locks, so Pi state a worker would write there does not persist from a worker. That covers an MCP OAuth refresh in `mcp-auth.json`, a model catalog refresh, and package installs. An OAuth MCP server may need a login from the root session first, since a worker cannot save a refreshed token.
76
+ - `tmux_run` jobs, and the `pi` processes `subagent` starts, run on the host. Only Pi's built-in tools run in the VM. A `/workspace` path does not exist on the host, so give `tmux_run` paths relative to the working directory.
77
+ - A host path outside the working directory does not exist in the guest, except this package. The package root is mounted read-only at its host path, so a `SKILL.md`, playbook, or principle that Pi or a skill names by its host path can be read, and writes to it fail. The system prompt names the boundary and points at `tmux_run` and `tmux_jobs` `output` for the rest.
78
+ - The guest image ships `node` but not `git`, `gh`, `tmux`, or `bun`, so the model's `bash` cannot commit, push, or open a PR. Run those through `tmux_run`.
79
+ - A linked worktree's `.git` file points at a git directory outside the mount, so git in the guest cannot use it even after you install git there.
80
+ - Writes under `/workspace` reach the host as they are made. The VM keeps no copy to roll back.
99
81
 
100
82
  ## Jobs on disk
101
83
 
102
- Each job lives in `~/.pi/agent/pstack-v2/jobs/<id>/`: `job.json` (the spec), `brief.md`, `wrapper.sh`, `inventory.json`, `output.log`, `exit`, its private `tmp/`, a top-level job's `agent/`, any `quarantine/`, and for Pi workers `session/`, `nested/`, and `stderr.log`. The job directory is read-only to the job, so a job cannot rewrite its own spec or exit code. The unsandboxed tmux wrapper writes `output.log` and `exit`. A Pi worker can write only `session/` and `nested/`, and the jobs it starts live in `nested/`. Each spawning session runs its own tmux server on a socket in `/tmp/pstack-v2-<uid>/`, named from a hash of the session id. `tmux_jobs` `list` prints a `tail -f` command to follow each job's output and a `tmux attach` command for each running job. A worker's report is every answer it completed, read from its session file, so a reply to a late job notice cannot replace it. A wake is claimed once through a `woken` marker file, so restarting Pi never delivers a report twice.
84
+ Each `tmux_run` job lives in `~/.pi/agent/pstack-v2/jobs/<id>/`: `job.json` (the spec), `wrapper.sh`, `wrapper.pid`, `output.log`, and `exit`. The tmux wrapper writes `output.log` and `exit`. Each spawning session runs its own tmux server on a socket in `/tmp/pstack-v2-<uid>/`, named from a hash of the session id. `tmux_jobs` `list` prints a `tail -f` command to follow each job's output and a `tmux attach` command for each running job. A wake is claimed once through a `woken` marker file, so restarting Pi never delivers a report twice.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@justjoshn/pi-pstack-v2",
3
- "version": "0.1.7",
4
- "description": "Use the pstack skills and workflow in Pi, with the upstream subagent tool spawning Pi in tmux and shell jobs running in tmux.",
3
+ "version": "0.2.1",
4
+ "description": "Use the pstack skills and workflow in Pi, with the upstream subagent tool spawning Pi in tmux, shell jobs running in tmux, and Pi's tools running in a Gondolin micro-VM.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -27,7 +27,8 @@
27
27
  "pi": {
28
28
  "extensions": [
29
29
  "./src/index.ts",
30
- "./src/subagent/index.ts"
30
+ "./src/subagent/index.ts",
31
+ "./src/gondolin/index.ts"
31
32
  ],
32
33
  "skills": [
33
34
  "./skills"
@@ -52,6 +53,7 @@
52
53
  "vitest": "5.1.0"
53
54
  },
54
55
  "dependencies": {
56
+ "@earendil-works/gondolin": "0.14.0",
55
57
  "zod": "^4"
56
58
  }
57
59
  }
@@ -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 from the `arena runners` line in the `pstack-models` system-prompt section. Each entry is a `provider/id` model and a thinking level. If that line is missing, every runner runs on the session model, so omit `model`, and the arena is one model sampled N times. Say so plainly and never present it as a diverse panel. An `auto` or `inherit-parent` entry is the session model, so omit `model` for it. If `pi_spawn` rejects an entry, run that seat on the session model or drop it, keep at least two runners, and say so. Families go by the model id, not the provider, and the longest matching prefix wins: `claude-fable-*`, `claude-*`, and `gemini-*`. Any other model's family is its id before the first hyphen, such as `gpt` or `glm`. Spawn more runners for multiple design directions, and repeat one model when the work is generation-bound, not judgment-sensitive. Pick each worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
18
- 4. Give each candidate its own output location (a git worktree where possible, otherwise a directory inside the project that you pass as `cwd`). A worker cannot write shared `/tmp`. For a worktree, spawn the runner with `worktree: "arena-<slug>-<n>"` and `base: "<ref>"`. The worker commits its output there, and the worktree is at `<agent dir>/pstack-v2/jobs/<job id>/worktree`, per the **separate-before-serializing-shared-state** principle skill.
17
+ 3. Pick the runners from the `arena runners` line in the `pstack-models` system-prompt section. Each entry is a `provider/id` model and a thinking level. If that line is missing, every runner runs on the session model, so omit `model`, and the arena is one model sampled N times. Say so plainly and never present it as a diverse panel. An `auto` or `inherit-parent` entry is the session model, so omit `model` for it. If a runner fails because its model is not valid (`pi --list-models` prints valid ones), rerun that seat on the session model or drop it, keep at least two runners, and say so. Families go by the model id, not the provider, and the longest matching prefix wins: `claude-fable-*`, `claude-*`, and `gemini-*`. Any other model's family is its id before the first hyphen, such as `gpt` or `glm`. Spawn more runners for multiple design directions, and repeat one model when the work is generation-bound, not judgment-sensitive. Pick each worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
18
+ 4. Give each candidate its own output location (a git worktree where possible, otherwise a directory inside the project that you pass as `cwd`). A worker cannot write shared `/tmp`. For a worktree, first run `git worktree add -b arena-<slug>-<n> .pi/worktrees/arena-<slug>-<n> <ref>` on the host with `tmux_run`, inside the working directory so the VM can edit it, and pass that path as the runner's `cwd`. The worker commits its output there, per the **separate-before-serializing-shared-state** principle skill.
19
19
 
20
20
  ## Phase B: Fan out
21
21
 
22
- Spawn all N workers in one message with N `pi_spawn` calls, 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
+ Start all N workers in one `subagent` call with one `tasks` entry per runner and `agent: "worker"`, 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.
23
23
 
24
- Each runner wakes you with its report when it exits. End your turn and let the wakes arrive before Phase C. If a candidate produces no output, proceed with N-1 and note the dropout.
24
+ The call returns when every runner finishes, with their reports. 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, spawn one judge with `pi_spawn` and `readonly: true`, from the `arena cross-judge pool` line in the `pstack-models` system-prompt section. The judge is never from the session model's vendor. A vendor is a family as Phase A step 3 defines families, except that `claude-fable-*` and `claude-*` are one vendor. Use the first entry from another vendor. An `auto` or `inherit-parent` entry is the session model, so it never judges. If you do not know the session model, use the first entry and say that the vendor check did not run. If that line is missing, or `pi_spawn` rejects every entry from another vendor, skip the judge, pick the base alone in Phase D, and say so. While you read in Phase D, the judge scores each candidate, by path label, on each rubric criterion and recommends a base.
28
+ After all Phase B candidates complete, start one judge with `subagent` and `agent: "scout"`, from the `arena cross-judge pool` line in the `pstack-models` system-prompt section. The judge is never from the session model's vendor. A vendor is a family as Phase A step 3 defines families, except that `claude-fable-*` and `claude-*` are one vendor. Use the first entry from another vendor. An `auto` or `inherit-parent` entry is the session model, so it never judges. If you do not know the session model, use the first entry and say that the vendor check did not run. If that line is missing, or every entry from another vendor fails because its model is not valid, skip the judge, pick the base alone in Phase D, and say so. While you read in Phase D, the judge scores each candidate, by path label, on each rubric criterion and recommends a base. Its brief says it must not edit any candidate.
29
29
 
30
30
  ## Phase D: Pick a base
31
31
 
@@ -26,9 +26,9 @@ Update mode changes the rest of the flow:
26
26
 
27
27
  ### 1. Mine their history
28
28
 
29
- Locate the active workspace's sessions before fanning out. They are the `*.jsonl` files in `~/.pi/agent/sessions/--<cwd with / as ->--/` (unless `sessionDir` or `$PI_CODING_AGENT_SESSION_DIR` moves sessions), and each spawned worker keeps its own in `~/.pi/agent/pstack-v2/jobs/<id>/session/`. Keep only jobs whose `job.json` `cwd` is inside this workspace. Use only that directory. Don't glob across `~/.pi/agent/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.
29
+ Locate the active workspace's sessions before fanning out. They are the `*.jsonl` files in `~/.pi/agent/sessions/--<cwd with / as ->--/` (unless `sessionDir` or `$PI_CODING_AGENT_SESSION_DIR` moves sessions). A `subagent` worker runs with no session, so its report appears only as a tool result there. Use only that directory. Don't glob across `~/.pi/agent/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.
30
30
 
31
- Survey recent agent conversations within that scope for recurring patterns. Spawn multiple parallel Pi workers with `pi_spawn` across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each worker's model and thinking level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Each slice mining worker reads sessions from the workspace-scoped path the brief names, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
31
+ Survey recent agent conversations within that scope for recurring patterns. Start parallel Pi workers in one `subagent` call with `tasks` and `agent: "scout"` across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each worker's model and thinking level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Each slice mining worker reads sessions from the workspace-scoped path the brief names, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
32
32
 
33
33
  - Response preferences (length, tone, format, "dumb it down" corrections)
34
34
  - Delegation habits (spawned workers, models, specialized workflows, parallelism)
@@ -14,7 +14,7 @@ For a quick ballpark the user asked for, one run is enough. Still check question
14
14
 
15
15
  - Write down the claim you expect to make, in the words you would ship ("export is 30% faster at p50 on the 60k-row dataset"). The questions test that sentence.
16
16
  - Read the measurement script. Note what it times, counts, and ignores.
17
- - Check the load average with `uptime` and the core count with `nproc`. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report. In the pstack sandbox `ps` and `top` are refused, so report the load from `uptime` and ask the session that started you what is running.
17
+ - Check the load average with `uptime` and the core count with `nproc`. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report. Pi's bash runs in the Gondolin VM, which sees only the guest's load and processes, so read the host's from a `tmux_run` job.
18
18
 
19
19
  ## The questions
20
20
 
@@ -105,6 +105,6 @@ If the CLI needs richer terminal control, use `pty.fork()` or an existing PTY li
105
105
 
106
106
  - Prefer deterministic waits over sleeps. If you must sleep, explain why.
107
107
  - Do not send credentials or destructive commands into a controlled session.
108
- - Keep the harness in `$TMPDIR` (or `/tmp` outside a worker) unless the repo already has a testing/demo harness.
108
+ - Keep the harness in `$TMPDIR` unless the repo already has a testing/demo harness.
109
109
  - Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
110
110
  - Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.
@@ -30,7 +30,7 @@ Decompose into atomic, independently-landable units. Sequence riskiest-unknown-f
30
30
 
31
31
  - Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
32
32
  - For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
33
- - Decide what fans out. Parallelize only across seams, and give each worker its own worktree, with `pi_spawn` `worktree` and `base` (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Spawn each worker with `pi_spawn` and pick its `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
33
+ - Decide what fans out. Parallelize only across seams, and give each worker its own worktree, created on the host with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>` inside the working directory and passed as `cwd` (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Start the workers with one `subagent` call with `tasks` and `agent: "poteto-agent"`, and pick its `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
34
34
  - Write the designed phase list down. That list is what the human reviews.
35
35
 
36
36
  Then execute the design. Add its steps to `TODO.md` as concrete items between the Phase C and Phase D entries. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
@@ -12,10 +12,10 @@ If the scope is ambiguous, state your interpretation and explore. The user can r
12
12
 
13
13
  ## 1. Explain
14
14
 
15
- Spawn one worker with `pi_spawn`, `readonly: true`, and no `agent` or `model`, so it runs on the session model and explores and explains in one pass. Give it the user's question and this brief:
15
+ Start one worker with `subagent`, `agent: "scout"`, and no `model`, so it runs on the session model and explores and explains in one pass. It must not change any file. Give it the user's question and this brief:
16
16
 
17
17
  > You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase.
18
18
 
19
19
  ## 2. Present
20
20
 
21
- When it exits and wakes you with its report, present that report. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
21
+ When the call returns its report, present that report. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
@@ -16,13 +16,13 @@ The scope is what the user names. Otherwise it is the branch diff from its merge
16
16
 
17
17
  ## Fan out
18
18
 
19
- Run Phase A steps 3 and 4 and Phase B of the **arena** skill, with four changes. Read the `interrogate reviewers` line in place of `arena runners`. A worktree is created at spawn from `base`, so uncommitted changes cannot be copied in first. Write the scope's uncommitted diff to a file inside the project (for example `git diff HEAD > .interrogate/scope.patch`, left untracked), name its path in each brief, and tell the adversary to `git apply` it first. Give each adversary its own `worktree` and `base`. Spawn each adversary with `pi_spawn` and no `agent`. In place of the arena task and rationale, give each adversary the scope, the intent, and this brief:
19
+ Run Phase A steps 3 and 4 and Phase B of the **arena** skill, with four changes. Read the `interrogate reviewers` line in place of `arena runners`. A new worktree holds no uncommitted changes. Write the scope's uncommitted diff to a file inside the project (for example `git diff HEAD > .interrogate/scope.patch`, left untracked), name its path in each brief, and tell the adversary to `git apply` it first. Give each adversary its own worktree from the base ref, as arena step 4 creates it, and pass it as `cwd`. Start the adversaries in one `subagent` call with `tasks` and `agent: "worker"`. In place of the arena task and rationale, give each adversary the scope, the intent, and this brief:
20
20
 
21
21
  > Break this change. Prove each finding with a run against the real code, such as a failing test, a repro script, or command output that shows the wrong behavior. For a design or plan, run a prototype or probe the current tree. Keep repros in your own worktree. Report each finding with a title, the exact command, the output it printed, and the output the intent requires. Leave out anything you did not run. That covers style, naming, structure, and risks that need a future change to matter. No findings is a valid result.
22
22
 
23
23
  ## Verify
24
24
 
25
- Each adversary wakes you with its report when it exits. End your turn and let the wakes arrive before you verify.
25
+ The call returns when every adversary finishes, with their reports.
26
26
 
27
27
  Verify each finding per arena Phase F by rerunning its command. Keep a finding when the output shows the failure and the failure breaks the intent. Drop the rest. Merge findings that share a root cause.
28
28
 
@@ -26,7 +26,7 @@ Only edit the verification skill's own directory (its SKILL.md, features/, and a
26
26
 
27
27
  1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
28
28
 
29
- 2. **Source wave.** One readonly worker per feature file, started with one `pi_spawn` call each in a single message so they run concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Workers never drive the app and never edit files. Each exits with that result as its report, which wakes you. End your turn and let the wakes arrive before you reconcile. Return shape: feature summary / source entry points / likely drift or none / one recipe.
29
+ 2. **Source wave.** One `agent: "scout"` worker per feature file, all started in one `subagent` call with `tasks` so they run concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Workers never drive the app and never edit files. The call returns when every worker finishes, with their reports. Return shape: feature summary / source entry points / likely drift or none / one recipe.
30
30
 
31
31
  3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
32
32
 
@@ -23,13 +23,13 @@ Write `bot.md` in that directory. It is the prompt every wake sends before the e
23
23
 
24
24
  ## Choose how the bot wakes
25
25
 
26
- The bot is a Pi session stored in the UI's directory, so a sandboxed job can write it. On each POST the server runs:
26
+ The bot is a Pi session stored in the UI's directory. On each POST the server runs:
27
27
 
28
28
  ```
29
29
  pi -p --session-dir <ui dir>/session --session-id <slug> @<ui dir>/bot.md "<event>"
30
30
  ```
31
31
 
32
- `--session-id` opens the session if it exists and creates it otherwise, so the first wake and every later wake use the same command. The event is the JSON text the browser sent, wrapped as in the last section. Run one wake at a time, so two clicks never write the session together. The woken Pi is a child of the sandboxed server, so it can write only what the server can, which is the project.
32
+ `--session-id` opens the session if it exists and creates it otherwise, so the first wake and every later wake use the same command. The event is the JSON text the browser sent, wrapped as in the last section. Run one wake at a time, so two clicks never write the session together.
33
33
 
34
34
  ## Request secrets
35
35
 
@@ -18,7 +18,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base
18
18
 
19
19
  ## Steps
20
20
 
21
- 1. Spawn a worker with `pi_spawn` and `agent: "comment-sicko"`. Pass the scope. Pick the worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Do not restate its rules.
21
+ 1. Start a worker with `subagent` and `agent: "comment-sicko"`. Pass the scope. Pick the worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Do not restate its rules.
22
22
  2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, trace their symbol or run `/skill:why` on it. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/skill:no-comments`.
23
23
  3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/skill:architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
24
24
  4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
@@ -45,7 +45,7 @@ If cost is the worry, say where the tokens go and how to spend fewer. pstack spe
45
45
 
46
46
  pstack was ported from Cursor and runs on Pi as a Pi package. [How pstack maps onto Pi](../../docs/pi-mechanisms.md) lists what each part uses.
47
47
 
48
- Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/skill:poteto-mode`, `/skill:how`, and `/skill:teach`, spawn Pi workers with `pi_spawn`, some with per-role models, and watchers and heartbeats run through `tmux_run`. Those tools come from this package's extension, so those parts may not work elsewhere.
48
+ Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/skill:poteto-mode`, `/skill:how`, and `/skill:teach`, spawn Pi workers with `subagent`, some with per-role models, and watchers and heartbeats run through `tmux_run`. Those tools come from this package's extension, so those parts may not work elsewhere.
49
49
 
50
50
  ## Start a task with `/skill:poteto-mode`
51
51
 
@@ -53,7 +53,7 @@ Other tools can read the skills, because they use the Agent Skills format. But m
53
53
 
54
54
  `/skill:poteto-mode` attaches the skill to one message, and it fades as the session moves on. To keep it on for the whole session, type `/pstack-mode poteto-mode` instead. That is pstack's Custom Mode. The skill rides in the system prompt every turn, survives `/compact`, and comes back when you resume the session. `/pstack-mode off` ends it. Any pstack skill works as a mode.
55
55
 
56
- Point the user to Pi's skills documentation (`docs/skills.md` in the Pi package, or Pi's docs site) when this comes up. Mid-session, "new task" makes the skill match a fresh playbook. `/skill:poteto-mode` already uses `poteto-agent` for the workers its playbook steps spawn. To get the same style from a worker of your own, spawn it with `pi_spawn` and `agent: "poteto-agent"`.
56
+ Point the user to Pi's skills documentation (`docs/skills.md` in the Pi package, or Pi's docs site) when this comes up. Mid-session, "new task" makes the skill match a fresh playbook. `/skill:poteto-mode` already uses `poteto-agent` for the workers its playbook steps spawn. To get the same style from a worker of your own, start it with `subagent` and `agent: "poteto-agent"`.
57
57
 
58
58
  ## Pick a skill
59
59
 
@@ -138,7 +138,7 @@ Principles are one-rule skills that `/skill:poteto-mode` reads and cites in its
138
138
  | A new model choice had no effect | The file from `/skill:setup-pstack` is read at the start of each turn. Send a new message, and check the role has a line in `~/.pi/agent/pstack-v2-models.md`. |
139
139
  | Runs cost more than expected | See the cost paragraph under Get set up. |
140
140
  | A skill didn't load on its own | Only `/skill:setup-pstack` loads from the user's words. The others load when the user types them or when `/skill:poteto-mode` runs them, and it doesn't run every skill. |
141
- | Parallel workers overwrote each other | Give each worker its own worktree with the `worktree` parameter of `pi_spawn`. |
141
+ | Parallel workers overwrote each other | Give each worker its own worktree. Create it with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>` inside the working directory, then pass that path as the worker's `cwd`. |
142
142
  | An overnight run moved but finished nothing | A `tmux_run` heartbeat needs a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). |
143
143
  | The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. |
144
144