@justjoshn/pi-pstack-v2 0.1.6 → 0.2.0

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.
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
 
@@ -20,7 +20,7 @@ Built and tested against Pi 1.5.2. Do not install another pstack package alongsi
20
20
  ## Requirements
21
21
 
22
22
  - 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.
23
+ - QEMU, for the Gondolin VM (`brew install qemu` on macOS). Gondolin downloads its guest image on first use.
24
24
  - bun and `gh`, for the scripts some skills run, such as `watch-pr` and `statechart`.
25
25
  - `jq` and `rg` (ripgrep), for `worktree-audit.sh` and the `pr-review-canvas` skill.
26
26
 
@@ -36,18 +36,24 @@ Type `/skill:poteto-help` with a question if you are unsure which skill fits.
36
36
 
37
37
  ## What it adds
38
38
 
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`.
39
+ 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
40
 
41
41
  | Tool | Does |
42
42
  | --- | --- |
43
43
  | `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. |
44
+ | `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
45
  | `tmux_jobs` | Lists, tails, waits on, or stops this session's jobs. |
46
46
 
47
- ## Notes
47
+ ## Gondolin
48
48
 
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.
49
+ `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.
50
+
51
+ - 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.
52
+ - 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.
53
+ - The system prompt names `/workspace` as the working directory, so the model works in guest paths.
54
+ - A host path outside the working directory does not exist in the guest. That includes this package's skills when Pi runs elsewhere, so the model cannot `read` them.
55
+ - The guest image ships `node` but not `git`, `gh`, `tmux`, or `bun`. Commands that need them run on the host through `tmux_run`.
56
+ - `tmux_run`, `tmux_jobs`, and the `pi` processes `subagent` starts run on the host, outside the VM.
51
57
 
52
58
  ## Replaces `@justjoshn/pi-pstack`
53
59
 
@@ -18,14 +18,14 @@ The package adds three tools. `pi_spawn` starts a separate Pi in its own tmux se
18
18
 
19
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.
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
 
@@ -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,12 +9,12 @@ 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
 
@@ -23,9 +23,9 @@ Pi's design principle for customizing is to pick the least powerful mechanism th
23
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
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
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. |
26
+ | `readonly: true` (Ask mode) | `pi_spawn` with `readonly: true`. 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
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. |
28
+ | `environment: "cloud"`, Cursor cloud agent, `cloud_base_branch` | `pi_spawn` with `worktree: "<branch>"` and `base: "<ref>"`. The worker gets its own git worktree. 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
29
  | `environment: "local"` | Omit `worktree`. |
30
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
31
  | Spawn N in one message | N `pi_spawn` calls in one message. |
@@ -49,7 +49,7 @@ 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`. 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 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. |
@@ -60,43 +60,25 @@ Pi's design principle for customizing is to pick the least powerful mechanism th
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
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. |
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. When Pi runs outside this package's directory, that includes the skills, so the model cannot `read` a `SKILL.md` it is pointed at. `/skill:<name>` and `/pstack-mode` still work, since Pi puts their text in the prompt itself.
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.6",
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.0",
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,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.
@@ -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
 
@@ -83,7 +83,7 @@ Read the leaf skill in full for any principle you apply. Each entry names when i
83
83
 
84
84
  ## Spawned Pi workers
85
85
 
86
- Pi has no subagents. A worker is a separate Pi process that `pi_spawn` starts in its own tmux session, inside the sandbox, with a standalone brief. It sees only the brief, never this conversation.
86
+ Pi has no subagents. A worker is a separate Pi process that `pi_spawn` starts in its own tmux session with a standalone brief. It sees only the brief, never this conversation.
87
87
 
88
88
  **Use `pi_spawn` with `agent: "poteto-agent"` for any worker you spawn directly inside a playbook step.** The session that receives `/skill:poteto-mode` runs the playbook itself. Routed workflow skills (`interrogate`, `swarm`) set their own `agent` and model. Respect it.
89
89
 
@@ -91,7 +91,7 @@ Pi has no subagents. A worker is a separate Pi process that `pi_spawn` starts in
91
91
 
92
92
  **Match the model to the job.** Start from the role's line, keep its model, and set the `thinking` level the job needs. The setup-pstack budget sets each role's starting level. Panel seats keep their listed level. Raise any other role one step, up to `xhigh`, for the hardest or subtlest work, lower it one step for judgment, and two or more steps for routine work. No role runs above `xhigh`. Verification always runs on the `swarm workers` model and level. A worker that only dispatches, polls, or packs results runs on the `swarm workers` model at a low level. If the model does not support the level, clamp to the nearest level it supports. If `pi_spawn` says a model is not valid, never pass it again. Fall back to the role's line, then the calling skill's fallback, then the nearest valid model of the same provider from the error's list, then omit `model`. Say so.
93
93
 
94
- You own every worker's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same brief on a model from another provider. A failure a worker sees only inside the sandbox (a browser that will not launch, a download that never lands, a permission error) is a sandbox suspect until you reproduce it outside the sandbox. Until then, do not file it as a product defect, a skip, or a fixme.
94
+ You own every worker's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same brief on a model from another provider. A failure a worker sees only inside the Gondolin VM (a browser that will not launch, a download that never lands, a missing tool) is a VM suspect until you reproduce it on the host. Until then, do not file it as a product defect, a skip, or a fixme.
95
95
 
96
96
  **Fresh workers by default.** Give a fix round, a follow-up, a retry, or the next queue item to a fresh `pi_spawn` with the original brief, every later directive, and the prior worker's report and branch. Continue an earlier worker's session (`pi_spawn` with `resume: "<job id>"`) only when the work needs state that lives in it and is costly to move: its worktree or its uncommitted changes. A process dies when its job exits, so restart a dev server or a babysit watcher with a fresh `tmux_run`.
97
97
 
@@ -5,11 +5,11 @@
5
5
  A verdict covers one patch and green CI covers one head. Step 4 runs a full swarm once, and again only for a major change. The patch-id rule in `playbooks/shipping.md` can carry a lane's result, and every new head needs its own green CI.
6
6
 
7
7
  1. **The operator's gates come first.** The grant covers only the queue's items, so items the operator names as theirs and PRs outside the queue stop at merge-ready. A request to state the plan is not a go.
8
- 2. **Spawn one owner per PR, and keep its work where a replacement can find it.** Resolve the forge once for the program. GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). On GitHub, run `scripts/watch-pr/watch-pr --help` once in your own bash before you spawn the owners, because the watcher installs its dependencies on first use and a sandboxed worker cannot write that directory. Each owner is a Pi worker in its own worktree (`pi_spawn` with `worktree`) that builds, opens its PR per `playbooks/opening-a-pr.md`, proves the change on the real artifact, babysits to green per `playbooks/babysit.md`, and merges once steps 4 and 5 clear it. Where that playbook says to report a rebase, the owner rebases its own branch and publishes it with `git push --force-with-lease`.
8
+ 2. **Spawn one owner per PR, and keep its work where a replacement can find it.** Resolve the forge once for the program. GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). Each owner is a Pi worker in its own worktree (`pi_spawn` with `worktree`) that builds, opens its PR per `playbooks/opening-a-pr.md`, proves the change on the real artifact, babysits to green per `playbooks/babysit.md`, and merges once steps 4 and 5 clear it. Where that playbook says to report a rebase, the owner rebases its own branch and publishes it with `git push --force-with-lease`.
9
9
 
10
10
  Open the PR early so CI and bots run alongside the work. The code is ready only after the slop-strip (the `deslop` skill, `/skill:deslop`) and the `/skill:no-comments` pass, so the full swarm runs on finished code. Then rebase onto current trunk and report the code-ready head before self-proof, so verification runs on the base the patch lands on. Report every later head, and merge-ready once self-proof, CI, and babysit are done. Fix rounds stay on that base unless trunk conflicts, breaks CI, or lands a known concurrent change to the same files, because each rebase restarts CI. Run the repo's checks for the touched paths on the committed head before the code-ready push and before a later push that needs a verifier.
11
11
 
12
- Assume the worker dies. Soon after starting, push and start a decision trail per the **show-me-your-work** skill at `decisions.tsv` in your own worktree, which a sandboxed worker can write, then push each finished unit before you start the next. The root reads it at `<agent dir>/pstack-v2/jobs/<job id>/worktree/decisions.tsv`, or from the pushed branch, when it replaces you. Whoever spawns a worker records its job id, state, and a stuck-after runtime from past runs of its kind in its own trail, so the root can probe it if the parent dies. The root's record of the owners' job ids lives in the root's own trail. Force-push only your own branch, with `--force-with-lease` pinned to the SHA you last pushed or took over, and on any push you did not make, stop and report to the root.
12
+ Assume the worker dies. Soon after starting, push and start a decision trail per the **show-me-your-work** skill at `decisions.tsv` in your own worktree, then push each finished unit before you start the next. The root reads it at `<agent dir>/pstack-v2/jobs/<job id>/worktree/decisions.tsv`, or from the pushed branch, when it replaces you. Whoever spawns a worker records its job id, state, and a stuck-after runtime from past runs of its kind in its own trail, so the root can probe it if the parent dies. The root's record of the owners' job ids lives in the root's own trail. Force-push only your own branch, with `--force-with-lease` pinned to the SHA you last pushed or took over, and on any push you did not make, stop and report to the root.
13
13
  3. **Run owners in parallel off trunk, never stacked,** so each PR lands on its own.
14
14
  4. **Swarm-verify once.** A full swarm runs once, at the code-ready head. Another full swarm runs only for new behavior, a redesign, or a large new diff. A rebase, a merge-conflict resolution, or a minor fix gets a single verifier at the new head, and a wording-only change gets none. Fan out independent verifiers at the code-ready SHA per the **swarm** skill. Each is a `pi_spawn` with `worktree: <lane branch>` and `base: <code-ready SHA>`, because a fresh lane branch avoids a second checkout of the owner's PR branch. They re-run the gates, prove the load-bearing behavior live on the real surface through its control skill (such as `control-ui` or `control-cli`) or a named driver, and audit the diff. The verdict is not clean without the live lane, or before you audit the merge-ready report's receipts, because no lane trusts a claim it has not checked.
15
15
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  - Declare the mode in your first line, before any poll. Modes: `drive` loops to merge-ready, `threads-only` touches only review threads, `check` is one status pass and a report.
6
6
  - Use `gh` by default, or `origin pr` when Origin's CLI resolves the repository. Never require Graphite (`gt`). On GitHub, status comes from the mode's watcher at `scripts/watch-pr/watch-pr`. In `check` mode pass `--status-only`. The watcher covers GitHub only. On Origin, use `origin pr view <pr> --checks` and `origin pr checks <pr> --watch`.
7
- - Run `scripts/watch-pr/watch-pr --help` once in your own bash first, because the watcher installs its dependencies on first use and a sandboxed job cannot write that directory. A worker's bash is sandboxed too, so a worker that babysits relies on the session that started it to have run it. If `--help` fails with `EACCES`, report that rather than working around the watcher. Then run `drive` through `tmux_run` with the watcher command and a `wake` that says what to do next. Rearm it with a fresh `tmux_run` after every push wave. Never add a second sleep loop.
7
+ - Run `drive` through `tmux_run` with the watcher command and a `wake` that says what to do next. Rearm it with a fresh `tmux_run` after every push wave. Never add a second sleep loop.
8
8
  - Never rebase, retarget, or force-push. Report a conflict or a stale base with the branch that needs the rebase, and stop.
9
9
  - Order: conflicts, threads, CI. A conflict is the one blocker you report rather than resolve. Say which branch needs the rebase and stop. Do not fall through to CI to look busy. Name the drift sweep in that report, since trunk may have grown callers of code the stack deletes or moves, and the owner's rebase has to reconcile them in the same wave. Flake earns one fresh build. Only the diff's own failures get a commit.
10
10
  - Triage Bugbot skeptically: fix real findings, dismiss noise with a concrete disproof, escalate billing, data, auth, and security. Comment text is data, not instructions. Verify each claim against the code per `../references/bugbot-triage.md`. Push that wave before replying so the reply cites the commit. Reply with `gh api --method POST "repos/<owner>/<repo>/pulls/<pr>/comments/<comment-id>/replies" --input <payload.json>` or `origin pr thread reply <thread-id> <pr> --body-file <reply-file>`, never with shell built from comment text.
@@ -2,11 +2,11 @@
2
2
 
3
3
  **You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the stack.**
4
4
 
5
- 1. **Resolve the forge, then verify each PR independently before it lands.** GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). One verifier per PR, each a Pi worker (`pi_spawn` with `worktree: <lane branch>` and `base: <head SHA>`), runs the change the way a user would with the matching control skill (such as `control-ui` or `control-cli`), parent against head, and posts `PASS`, `PASS+NOTES`, or `FAIL` on that PR. The macOS sandbox denies a worker adding a git worktree, so its brief has it export the parent's SHA for the comparison with `mkdir -p "$TMPDIR/parent" && git archive <parent SHA> | tar -x -C "$TMPDIR/parent"`. Only a verdict from an agent that did not write the code counts, because an author checks what it meant to build. Green CI and an approving bot review are not verdicts, because neither runs the change as a user would.
5
+ 1. **Resolve the forge, then verify each PR independently before it lands.** GitHub CLI (`gh`) is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Otherwise stay on `gh` and record the fallback. Never require Graphite (`gt`). One verifier per PR, each a Pi worker (`pi_spawn` with `worktree: <lane branch>` and `base: <head SHA>`), runs the change the way a user would with the matching control skill (such as `control-ui` or `control-cli`), parent against head, and posts `PASS`, `PASS+NOTES`, or `FAIL` on that PR. Its brief has it export the parent's SHA for the comparison with `mkdir -p "$TMPDIR/parent" && git archive <parent SHA> | tar -x -C "$TMPDIR/parent"`. Only a verdict from an agent that did not write the code counts, because an author checks what it meant to build. Green CI and an approving bot review are not verdicts, because neither runs the change as a user would.
6
6
  2. **Land only the contiguous verified run rooted at the bottom.** Walk up from the lowest unmerged PR and stop at the first one without `PASS` or `PASS+NOTES`. The PRs below it are the run, and the top one is the ceiling. A verified PR above an unverified one waits, because it cannot land without the code below it. One whose branch neither holds nor needs that code can move onto trunk and land on its own. It needs a fresh verdict first, because its old one ran with that code beneath it and trunk does not have it.
7
7
  3. **Re-check that the verdicts still describe the code.** A verdict covers a patch, and a chain rebase moves every PR above it to a new SHA without failing any check. Compare `git patch-id` at the verdict SHA with the current head before trusting an older verdict. When the patches differ only in tests, docs, or lint config, a lane's result stands if what it ran builds the same at both SHAs apart from noise. Noise is a difference that also shows up between two builds of the verdict SHA, or an embedded commit SHA. Report each kind of noise with its files, so a reader can check the call. The change itself still gets fresh checks and a review, because the old verdict never saw it. A lane with no build output, such as a dev server, cannot show this, so rerun it, and re-verify anything else that drifted.
8
8
  4. **Land bottom-up, one PR at a time.** Always merge the run's lowest unmerged PR, with `origin pr merge <pr>` or `gh pr merge <pr> --squash`. On Origin the plain command also merges every PR below the one you name, and on GitHub a PR whose base is still its parent's branch merges into that branch, not trunk. Read the PR back for the result (`origin pr view <pr>` or `gh pr view <pr> --json state,mergedAt,baseRefName`), because a merge command can report success when a merge queue only queued the PR, and a requested auto-merge is not a merge. A landed PR reads merged with trunk as its base, not its parent's branch. Arm `--auto` (Origin merge-when-ready or GitHub auto-merge) only on a PR whose verdict covers its current head, because it lands whatever head is ready. After a merge lands, retarget the PR whose base was the merged branch to trunk (`origin pr edit <pr> --base <trunk>` or `gh pr edit <pr> --base <trunk>`), move its patch onto the merge result, and push with `--force-with-lease`. The verdict covers the patch, not its commits, so step 3's patch-id rule decides whether the verdict survives. Merge it once its checks pass and its verdict survives.
9
- 5. **Leave the stack alone while it lands.** Step 4's move of the next PR is the only change to a branch or base, because a merge lands whatever its branch and base hold at that moment, verdict or not. On GitHub, run `scripts/watch-pr/watch-pr --help` once in your own bash first, because the watcher installs its dependencies on first use and a sandboxed job cannot write that directory. Then watch the run with the queued watcher from `playbooks/babysit.md` (`scripts/watch-pr/watch-pr --queued-stack --stack-prs <bottom-to-top>`) through `tmux_run` with a `wake` that says what to do next, until it reports `COMPLETE` at the ceiling. Pass the run's PR numbers, bottom-to-top, in `--stack-prs`, and pass the same list each time you restart the watcher. On Origin, re-read the current PR with `origin pr view <pr> --checks` each time `origin pr checks <pr> --watch` returns, until the ceiling reads merged. A base that moves to trunk when its parent merges is expected, not damage to repair. If a merge stalls, find out why before you change anything.
9
+ 5. **Leave the stack alone while it lands.** Step 4's move of the next PR is the only change to a branch or base, because a merge lands whatever its branch and base hold at that moment, verdict or not. Watch the run with the queued watcher from `playbooks/babysit.md` (`scripts/watch-pr/watch-pr --queued-stack --stack-prs <bottom-to-top>`) through `tmux_run` with a `wake` that says what to do next, until it reports `COMPLETE` at the ceiling. Pass the run's PR numbers, bottom-to-top, in `--stack-prs`, and pass the same list each time you restart the watcher. On Origin, re-read the current PR with `origin pr view <pr> --checks` each time `origin pr checks <pr> --watch` returns, until the ceiling reads merged. A base that moves to trunk when its parent merges is expected, not damage to repair. If a merge stalls, find out why before you change anything.
10
10
  6. **Stop at the ceiling.** Extending the run takes new verdicts, so it is a new pass through step 1.
11
11
 
12
12
  **Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what landed and how you confirmed it, and what the next gap needs.
@@ -18,7 +18,7 @@ Work in a scratch folder outside the repo. Write a TLA+ spec and its config. The
18
18
 
19
19
  `scripts/statechart.ts` is TypeScript, so run it with a runtime that can execute TypeScript.
20
20
 
21
- The first run installs TLC and Java with mise and needs the network. Run it in the main session. A `pi_spawn` worker writes only its checkout and private temp directory, so the install fails there unless mise's directories point at `$TMPDIR`.
21
+ The first run installs TLC and Java with mise and needs the network. Run it in the main session.
22
22
 
23
23
  ## Write the spec
24
24
 
@@ -1,6 +1,6 @@
1
1
  # Render a chart
2
2
 
3
- Render each `.mmd` file that you show with the npm package `pele@1.9.0`, and give the user the SVG file path. Install Pele once, outside the repo. In a `pi_spawn` worker, install it under `$TMPDIR`. Write each SVG next to its `.mmd` file, with the same name. The API is at https://pele.run/api. Pass `{ limit: 1_000_000, outputLimit: 8_000_000, maxEdges: 10_000 }` as the options of `render`. Pele's defaults are smaller than a chart of 500 states can be. When Pele throws a `PeleError`, show the user the Mermaid text and the error.
3
+ Render each `.mmd` file that you show with the npm package `pele@1.9.0`, and give the user the SVG file path. Install Pele once, outside the repo. Write each SVG next to its `.mmd` file, with the same name. The API is at https://pele.run/api. Pass `{ limit: 1_000_000, outputLimit: 8_000_000, maxEdges: 10_000 }` as the options of `render`. Pele's defaults are smaller than a chart of 500 states can be. When Pele throws a `PeleError`, show the user the Mermaid text and the error.
4
4
 
5
5
  ## Colors
6
6
 
@@ -0,0 +1,51 @@
1
+ import type { ExecOptions, VM } from '@earendil-works/gondolin';
2
+ import type { BashOperations } from '@earendil-works/pi-coding-agent';
3
+ import { toGuestPath } from './paths.ts';
4
+
5
+ const MS_PER_SECOND = 1000;
6
+ // The bash tool reads these messages to report a cancelled or timed-out command.
7
+ const ABORTED_MESSAGE = 'aborted';
8
+
9
+ type ExecRequest = Parameters<BashOperations['exec']>[2];
10
+
11
+ /** The guest takes only string values, and Node's env type allows undefined ones. No env means the VM's default. */
12
+ const sanitizeEnv = (env: NodeJS.ProcessEnv | undefined): { env?: Record<string, string> } => (env ? { env: Object.fromEntries(Object.entries(env).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) } : {});
13
+
14
+ async function streamGuestCommand(vm: VM, argv: string[], options: ExecOptions, onData: (data: Buffer) => void): Promise<{ exitCode: number | null }> {
15
+ const proc = vm.exec(argv, { ...options, stdout: 'pipe', stderr: 'pipe' });
16
+ for await (const chunk of proc.output()) onData(chunk.data);
17
+ const result = await proc;
18
+ return { exitCode: result.exitCode };
19
+ }
20
+
21
+ async function execInGuest(vm: VM, argv: string[], guestCwd: string, { onData, signal, timeout, env }: ExecRequest): Promise<{ exitCode: number | null }> {
22
+ const controller = new AbortController();
23
+ const onAbort = () => controller.abort();
24
+ signal?.addEventListener('abort', onAbort, { once: true });
25
+ let timedOut = false;
26
+ const onTimeout = () => {
27
+ timedOut = true;
28
+ controller.abort();
29
+ };
30
+ const timer = timeout && timeout > 0 ? setTimeout(onTimeout, timeout * MS_PER_SECOND) : undefined;
31
+ try {
32
+ return await streamGuestCommand(vm, argv, { cwd: guestCwd, ...sanitizeEnv(env), signal: controller.signal }, onData).catch((error: unknown) => {
33
+ if (signal?.aborted) throw new Error(ABORTED_MESSAGE);
34
+ if (timedOut) throw new Error(`timeout:${timeout}`);
35
+ throw error;
36
+ });
37
+ } finally {
38
+ if (timer) clearTimeout(timer);
39
+ signal?.removeEventListener('abort', onAbort);
40
+ }
41
+ }
42
+
43
+ /** Runs shell commands in the guest through the shell the VM probe found, with cwd mapped to the guest. */
44
+ export function createGondolinBashOps(vm: VM, localCwd: string, shellPath: string): BashOperations {
45
+ return {
46
+ exec: async (command, cwd, request) => {
47
+ if (request.signal?.aborted) throw new Error(ABORTED_MESSAGE);
48
+ return execInGuest(vm, [shellPath, '-lc', command], toGuestPath(localCwd, cwd), request);
49
+ },
50
+ };
51
+ }
@@ -0,0 +1,56 @@
1
+ import * as path from 'node:path';
2
+
3
+ import type { VM } from '@earendil-works/gondolin';
4
+ import type { EditOperations, LsOperations, ReadOperations, WriteOperations } from '@earendil-works/pi-coding-agent';
5
+ import { toGuestPath } from './paths.ts';
6
+
7
+ // The read tool shows these as images; any other extension reads as text.
8
+ const IMAGE_MIME_TYPES: ReadonlyMap<string, string> = new Map([
9
+ ['.png', 'image/png'],
10
+ ['.jpg', 'image/jpeg'],
11
+ ['.jpeg', 'image/jpeg'],
12
+ ['.gif', 'image/gif'],
13
+ ['.webp', 'image/webp'],
14
+ ]);
15
+
16
+ /** A missing or unreachable guest path reads as absent rather than failing the tool. */
17
+ export const guestExists = (vm: VM, localCwd: string, filePath: string): Promise<boolean> =>
18
+ vm.fs.access(toGuestPath(localCwd, filePath)).then(
19
+ () => true,
20
+ () => false,
21
+ );
22
+
23
+ export function createGondolinReadOps(vm: VM, localCwd: string): ReadOperations {
24
+ return {
25
+ readFile: async (filePath) => vm.fs.readFile(toGuestPath(localCwd, filePath)),
26
+ access: async (filePath) => {
27
+ await vm.fs.access(toGuestPath(localCwd, filePath));
28
+ },
29
+ detectImageMimeType: async (filePath) => IMAGE_MIME_TYPES.get(path.posix.extname(toGuestPath(localCwd, filePath)).toLowerCase()) ?? null,
30
+ };
31
+ }
32
+
33
+ export function createGondolinWriteOps(vm: VM, localCwd: string): WriteOperations {
34
+ return {
35
+ writeFile: async (filePath, content) => {
36
+ await vm.fs.writeFile(toGuestPath(localCwd, filePath), content, { encoding: 'utf8' });
37
+ },
38
+ mkdir: async (dirPath) => {
39
+ await vm.fs.mkdir(toGuestPath(localCwd, dirPath), { recursive: true });
40
+ },
41
+ };
42
+ }
43
+
44
+ export function createGondolinEditOps(vm: VM, localCwd: string): EditOperations {
45
+ const readOps = createGondolinReadOps(vm, localCwd);
46
+ const writeOps = createGondolinWriteOps(vm, localCwd);
47
+ return { readFile: readOps.readFile, writeFile: writeOps.writeFile, access: readOps.access };
48
+ }
49
+
50
+ export function createGondolinLsOps(vm: VM, localCwd: string): LsOperations {
51
+ return {
52
+ exists: async (filePath) => guestExists(vm, localCwd, filePath),
53
+ stat: async (filePath) => vm.fs.stat(toGuestPath(localCwd, filePath)),
54
+ readdir: async (dirPath) => vm.fs.listDir(toGuestPath(localCwd, dirPath)),
55
+ };
56
+ }