@sjawhar/pi-legion 19.30.0 → 19.30.2

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 (28) hide show
  1. package/agents/plan-reviewer.md +5 -1
  2. package/dist/legion.js +1 -1
  3. package/dist/skills/legion-architect/SKILL.md +4 -3
  4. package/dist/skills/legion-architect/references/acceptance.md +14 -4
  5. package/dist/skills/legion-architect/references/decomposition.md +4 -3
  6. package/dist/skills/legion-architect/references/design-gate.md +24 -5
  7. package/dist/skills/legion-architect/references/wake-routing.md +1 -1
  8. package/dist/skills/legion-controller/SKILL.md +2 -6
  9. package/dist/skills/legion-controller/references/consolidation.md +3 -4
  10. package/dist/skills/legion-controller/references/daily-report.md +3 -4
  11. package/dist/skills/legion-controller/references/finding-asks.md +4 -4
  12. package/dist/skills/legion-controller/references/session.md +2 -1
  13. package/dist/skills/legion-controller/references/slack-mentions.md +2 -2
  14. package/dist/skills/legion-controller/references/triage.md +2 -2
  15. package/dist/skills/legion-controller/references/wakes.md +2 -2
  16. package/dist/skills/legion-controller/references/weekly-audit.md +3 -4
  17. package/dist/skills/legion-retro/SKILL.md +9 -3
  18. package/dist/skills/legion-worker/SKILL.md +15 -13
  19. package/dist/skills/legion-worker/references/ci-checks.md +20 -3
  20. package/dist/skills/legion-worker/references/conflicts-and-rewrites.md +14 -43
  21. package/dist/skills/legion-worker/references/foreign-path.md +1 -1
  22. package/dist/skills/legion-worker/references/merge-gate.md +39 -39
  23. package/dist/skills/legion-worker/references/plan-tests.md +40 -0
  24. package/dist/skills/legion-worker/references/pr-body.md +33 -12
  25. package/dist/skills/legion-worker/references/tools.md +49 -75
  26. package/dist/skills/legion-worker/references/withheld-capability.md +11 -7
  27. package/dist/skills/simplify-settled-diff/SKILL.md +1 -1
  28. package/package.json +1 -1
@@ -48,8 +48,10 @@ order. Each is the line `dispatch result` printed when the result was recorded,
48
48
 
49
49
  ## Never waiting on CI
50
50
 
51
- The implementer runs the repository's fast local checks for the paths it changed before the push,
52
- then pushes and completes. It never waits for, watches or polls the pull request's remote CI
51
+ Before the push and the hand-off, the implementer runs the repository's fast local checks for the
52
+ paths it changed: the tests it added or changed, by name, and the build or vet of the packages it
53
+ touched. It runs no whole test suite: CI runs the suites when it pushes, and a red job comes back
54
+ to it (below). Then it pushes and completes. It never waits for, watches or polls the pull request's remote CI
53
55
  (`gh run watch`, `gh pr checks --watch`, `sleep` around `gh run view`) and never sleeps in a loop
54
56
  (the step's spaced reads of the pull request's head after a push are the one sleep this rule
55
57
  allows, and they read no check; `skill://legion-worker`, *Every role pushes its own commits*,
@@ -71,7 +73,12 @@ the pull request conflicts with its base (GitHub shows it `CONFLICTING`), no wor
71
73
  `on: pull_request` runs for any of its activity types, so a body edit re-judges nothing there; a
72
74
  push cures it only once the pull request is mergeable, so the implementer forward-merges a
73
75
  conflicting one first (*Reintegrating the base* in
74
- `skill://legion-worker/references/conflicts-and-rewrites.md`).
76
+ `skill://legion-worker/references/conflicts-and-rewrites.md`). So when a required check has not
77
+ appeared at the head, read `gh pr view <n> --json mergeStateStatus` first. `DIRTY` means the head
78
+ conflicts with its base: GitHub builds no merge ref for it and creates no `pull_request` run, and
79
+ the cure is that forward merge. Other runs can be green beside the missing one, because a
80
+ `pull_request_target` run is built from the base and needs no merge ref, so its pass says nothing
81
+ about whether the head merges.
75
82
 
76
83
  ## The brief for the human
77
84
 
@@ -105,7 +112,7 @@ of these flags takes text and refuses a bare `-`. Text from a file or from stdin
105
112
  stdin (`-`). The command prints the pull request body's line for it, and that line goes into the
106
113
  body unchanged.
107
114
  The surface is **production-like** — the repository's real-process test harness and fixtures, a
108
- sandbox repository, a real browser, a devN stack, staging, or a local stack with real migrations,
115
+ sandbox repository, a real browser, a development stack, staging, or a local stack with real migrations,
109
116
  one that has the resource the change touches — and `--run` or `--observed` carries a **link** to
110
117
  that run, screenshot or e2e; human review does not replace user-facing verification, and a green
111
118
  unit suite is not it. A unit or integration test is a regression lock, never a check's result,
@@ -136,6 +143,15 @@ A push moves the head, with no Dispatch write of anyone's, so each check with no
136
143
  recorded again at the new head. `dispatch results --issue <issue>` prints each check with the
137
144
  results recorded against it and the commit each one was recorded at;
138
145
  `dispatch read --issue <issue>` names each requirement of the spec no check serves.
146
+ Where a result's commit stands is read, not stored. A `before_merge` result is compared only with
147
+ the heads of the pull requests attributed to the check's issue, with no fallback to the default
148
+ branch. Dispatch attributes a pull request to the first issue its five ranked sources name in the
149
+ pull request's repository (`packages/envoy/internal/dispatch/delivery/attribution.go`): the issue
150
+ whose external link is the pull request, the issue linked to a GitHub issue its body cites, a key
151
+ in its head branch, a key in its title or body, and a key in its commit messages. So a result reads
152
+ as at another commit (`older` in a client before pi-envoy 17.1.0) when its commit is an earlier
153
+ head, when no attributed head is its commit, as when the pull request is attributed to another
154
+ issue, or when any field of the check changed after it was recorded.
139
155
 
140
156
  **An issue is proved by its own checks.** Approval is gated by the `before_merge` checks of its
141
157
  own Verification document, read at its own head, so a result a child recorded proves nothing for
@@ -165,13 +181,16 @@ and decides there, the only gate on such an issue.
165
181
  What a handoff does carry is `head`, the 40-character lower-case commit its work was done
166
182
  against, which the completion sends to the daemon.
167
183
  - **The tester judges the implementer's results and records its own.** It runs and records no
168
- check with `ci_check`, whose result `dispatch results` derives. A derived fail, or a run that
184
+ check with `ci_check`, whose result `dispatch results` derives from that CI job's run, conclusion
185
+ and `completed_at` at the head, and it runs no check whose `run` is a whole test suite in the pod:
186
+ that check's words are wrong, and the architect rewrites it with `ci_check`. A derived fail, or a run that
169
187
  concluded `skipped`, `neutral` or `cancelled`, is a test failure. A run still going, or GitHub
170
188
  unread, goes in `implementerProof.how` and fails no round. A name no run answers once the head's
171
189
  checks have settled goes to the architect as a finding. It re-runs the
172
190
  implementer's command or drives the same surface independently, and records the verdict in
173
191
  its `test` handoff as `implementerProof` (`{verdict, how}`). The tester runs the
174
- application, not CI again. Try to break the changed surface — wrong and boundary inputs, the
192
+ application, not CI again, and by hand it drives only the changed behaviour on the real surface,
193
+ the negative controls, and named test files that no CI lane selects. Try to break the changed surface — wrong and boundary inputs, the
175
194
  second and the concurrent run, the party it must refuse — judge whether the implementer's tests
176
195
  would catch the ways it breaks, writing the red test for one that none would, and
177
196
  read CI on GitHub at the head you are judging for everything static: lint, types and the unit
@@ -184,13 +203,16 @@ and decides there, the only gate on such an issue.
184
203
  with `implementerProof.verdict: "rejected"`, complete the phase with
185
204
  `verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
186
205
  proving it (a rejected verdict, or `failed > 0`, always comes with the failure recorded in
187
- `failures`). Otherwise record your own result for each `before_merge` check before you complete,
206
+ `failures`). A check whose `run` is a whole test suite is the exception: its words are wrong, so
207
+ while the architect rewrites it, it fails no round, and the tester names it in
208
+ `implementerProof.how` and sends it to the architect. Otherwise record your own result for each
209
+ `before_merge` check before you complete,
188
210
  and put each printed line in the body. A code path whose first execution is after merge — a
189
211
  deploy workflow's inline step, a post-merge helper, a production-only resource — is a check
190
212
  marked `after_merge`, recorded after the merge on a look of the production check by the role
191
213
  the project's `production_check` names — the tester, unless the setting is `off`, where the
192
214
  close opens no check and nothing records it — unless the implementer can execute it against a
193
- devN stack before then; if no surface can reach it, the
215
+ development stack before then; if no surface can reach it, the
194
216
  tester names that missing surface as the blocker instead of passing the phase. Environment or
195
217
  secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
196
218
  its `test` handoff, and only when a check calls for it — never
@@ -210,7 +232,7 @@ and decides there, the only gate on such an issue.
210
232
  between a clean review and the approval, so this is the one slot before the tester and the
211
233
  reviewer read the head; a later round answering a review runs no second pass. It is scoped to
212
234
  the pull request's own diff at that head: nothing applied leaves the head as it is; applied →
213
- the implementer re-runs the repository's checks and the issue's own checks on the applied head
235
+ the implementer re-runs its fast local checks and the issue's own checks on the applied head
214
236
  for the surface the simplify diff touched, since a refactor that "preserves behaviour" is a
215
237
  claim until it is executed, and records each result at that head before it completes.
216
238
  That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
@@ -222,12 +244,11 @@ and decides there, the only gate on such an issue.
222
244
  Record both in the `Thermo` line.
223
245
  - **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
224
246
  `skill://legion-worker`): a wording nit, and any clear fix in a file this pull request touches,
225
- is made in the running round: a later round costs a CI pass and a re-read of the whole
226
- change. A requirement on the `Not proven / risk:` line is unmet, not declared away, unless only
247
+ is made in the running round: a later round costs a CI pass and another review. A requirement on the `Not proven / risk:` line is unmet, not declared away, unless only
227
248
  the deploy can show it and the plan names its observation;
228
249
  the `Fast-follow:` line never carries one, and reads `none` or names only cleanup in files
229
250
  this pull request does not touch. A base frozen for others to stack on is
230
- never rewritten (*Rewriting pushed commits* in
251
+ never rewritten (*A wrong pushed commit* in
231
252
  `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
232
253
  - **GitHub refuses a pull request body over 65,536 characters.** Each verification round links its
233
254
  evidence (the run, the comment) rather than inlining it once the body passes about 48,000
@@ -16,10 +16,10 @@ It then tells that process's role why, in a message on the role's topic. The com
16
16
  turn goes on. A command that fills the memory faster than the guard can stop it still takes the pod
17
17
  past its limit, and that ends every role's turn, not only yours.
18
18
 
19
- In the pod you compile and test the packages your change touches, build the program a check of
20
- your issue drives (`go build ./cmd/legion`), vet the module you changed (`go vet -tags e2e ./...`,
21
- which compiles and runs no test), and, in a package whose tests need Postgres, run only the tests
22
- your change touches by name (`go test -run`). To run Go's race detector, prefix the command with
19
+ In the pod you compile the packages your change touches, run by name the tests you added or
20
+ changed (`go test -run '<TestName>' ./internal/<package>/`, or `bun test` with their files), build
21
+ the program a check of your issue drives (`go build ./cmd/legion`), and vet the module you changed
22
+ (`go vet -tags e2e ./...`, which compiles and runs no test). To run Go's race detector, prefix the command with
23
23
  `CGO_ENABLED=1`: `CGO_ENABLED=1 go test -race -count=1 -run '<TestName>' ./internal/<package>/`.
24
24
  The worker image sets `CGO_ENABLED=0` and carries gcc (both in
25
25
  `packages/daemon/docker/worker.Dockerfile`), and Go refuses `-race` without cgo.
@@ -46,9 +46,7 @@ heavy run goes where your deployment's instructions say.
46
46
  names and migrate it, `packages/envoy/internal/dispatch/store` (`openTestStore`, in its
47
47
  `store_test.go`), `packages/envoy/internal/dispatch/delivery` (`deliveryTestPool`, which also
48
48
  deletes every delivery table's rows) and `packages/envoy/internal/dispatch/redeliver`
49
- (`redeliverTestLeases`). In an empty database of its own, one run of the broker's left 24 tables
50
- on 2026-11-06, and one whole run of the Dispatch store's left 104 on 2026-11-07, a count that
51
- grows with Dispatch's migrations.
49
+ (`redeliverTestLeases`).
52
50
  - Anything that migrates into the database its DSN names, rather than making one per test, needs
53
51
  a database of your own, because a sibling role writing the same one collides with you: the
54
52
  Dispatch browser suite's `DATABASE_URL`, which resets what it is given, and the stage scripts'
@@ -95,9 +93,7 @@ database, any server whose other clients your role cannot stop. Your pod's own t
95
93
  connection on a shared server for a read.
96
94
  - Keep the read-only setting inside one transaction, never on the connection for its whole life. A
97
95
  read-only setting made for the whole session stays on the backend after the connection goes back
98
- to the pool. The next client of that pool gets it, and that client's writes fail. On 2026-11-05
99
- one such read left the setting on a pooled backend, and 1,432 session writes failed over 16
100
- minutes.
96
+ to the pool. The next client of that pool gets it, and that client's writes fail.
101
97
 
102
98
  These three forms do it. Each one holds the transaction read-only, so a write inside it is
103
99
  refused, and each one drops that state when the transaction ends.
@@ -143,10 +139,9 @@ carries the pod's own PostgreSQL server (the section above).
143
139
  `psql`, `flock`, `openssl` and `python3` on `PATH`, and without `docker` too unless a
144
140
  `DATABASE_URL` is given. The image carries `go`, `flock`, `openssl` and `python3`, a
145
141
  `DATABASE_URL` stands in for `docker`,
146
- and `psql` was the one a role had no way to supply — so a role whose change owes that suite can
147
- run it.
148
- - `redis-cli` — no repository of the project speaks Redis today; it is carried anyway, at about a
149
- megabyte, because a second image roll costs more than a megabyte.
142
+ and `psql` was the one a role had no way to supply — so a role can run the local stack as a
143
+ running build, and the specs of that suite its change touches, by file.
144
+ - `redis-cli` — a Redis client, for work that reaches a Redis server.
150
145
  - `sqlite3` — a repository's own SQLite fixture or database has no other way to open from a shell,
151
146
  and Oh My Pi's own profile databases (`~/.omp/profiles/legion/agent/agent.db`, `models.db`,
152
147
  `history.db`) are SQLite too. Your session is not one of them: it is `results.jsonl`,
@@ -169,8 +164,6 @@ after the change that added them; `command -v unzip yq` says whether yours has t
169
164
  program — kislyuk's Python wrapper over `jq`, 3.4.3 in trixie — so an expression written for one
170
165
  does not run on the other, and a recipe you found may be written for the other one.
171
166
 
172
- `model-gateway/apply_test.sh` of theorem-labs/agent-infra calls both.
173
-
174
167
  ## Why a tool the image lacks is an image change, not an install
175
168
 
176
169
  Your role runs as an unprivileged user with no writable system prefix: `/usr/local/bin` and `/opt`
@@ -184,8 +177,8 @@ E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission d
184
177
  ```
185
178
 
186
179
  So that writable `$HOME`, and the issue's disk, are where an install for yourself would go, and on
187
- the mechanics the answer is not a flat no: `redis-cli`, `sqlite3` and `dig` did run from an
188
- extraction prefix under `$HOME` with `LD_LIBRARY_PATH` set, and `psql` did not — Debian's
180
+ the mechanics the answer is not a flat no: an extraction prefix under `$HOME`, with
181
+ `LD_LIBRARY_PATH` set, can run some clients but not `psql` — Debian's
189
182
  `/usr/bin/psql` is a Perl wrapper that loads `PgCommon.pm` through Perl's own search path, which no
190
183
  extraction prefix is on. What rules such an attempt out is not the unpacking: it is the test of
191
184
  `skill://legion-worker/references/withheld-capability.md#the-test-where-it-lands-and-what-it-leaves-resolving`,
@@ -211,17 +204,17 @@ install anything the image does not carry.
211
204
  command you run are named separately, because they are usually different names.
212
205
  `uvx --from httpie@3.2.4 http --version` prints `3.2.4`. Where the project's own name *is* its
213
206
  command's — checked once, never assumed — the short `uvx <name>@<version>` runs it:
214
- `uvx ruff@0.14.0 --version` prints `ruff 0.14.0`, in 1.7 s with the uv cache empty and 0.15 s
215
- warm. A version that does not exist fails closed, exit 1, naming it: `uvx ruff@99.99.99
207
+ `uvx ruff@0.14.0 --version` prints `ruff 0.14.0`. A version that does not exist fails closed,
208
+ exit 1, naming it: `uvx ruff@99.99.99
216
209
  --version` prints `error: No solution found when resolving tool dependencies`, with `cause:
217
210
  Because there is no version of ruff==99.99.99 …`.
218
211
  - `bunx --package <name>@<version> <binary>`, for an npm tool, naming the package and the binary
219
212
  separately because they differ. `bunx --package @biomejs/biome@2.6.3 biome --version` prints
220
- `Version: 2.6.3`, in 0.3 s with bun's cache warm; `bunx --package @biomejs/biome@99.99.99 biome
213
+ `Version: 2.6.3`; `bunx --package @biomejs/biome@99.99.99 biome
221
214
  --version` fails closed, exit 1, with `error: No version matching "99.99.99" found for specifier
222
215
  "@biomejs/biome" (but package exists)`.
223
216
  - `go run <module>@<version>`, for a Go tool. `go run github.com/nats-io/natscli/nats@v0.1.5
224
- --version` prints `v0.1.5`, in 7.2 s with the module cache warm and 103 s on a cold module cache
217
+ --version` prints `v0.1.5`; a cold module cache makes the first run much slower than a warm one
225
218
  — budget for the cold one the first time an issue runs a Go tool. `go run
226
219
  github.com/nats-io/natscli/nats@v99.99.99 --version` fails closed, exit 1, with
227
220
  `go: github.com/nats-io/natscli/nats@v99.99.99: invalid version: unknown revision nats/v99.99.99`.
@@ -238,7 +231,7 @@ Installed 1 package in 12ms
238
231
  6.0.2
239
232
  ```
240
233
 
241
- That whole run is 0.597 s wall, the install included. `--no-project` keeps it off whatever
234
+ `--no-project` keeps it off whatever
242
235
  `pyproject.toml` happens to sit above your working directory, so it behaves the same wherever you
243
236
  type it, and `--with` takes a requirement specifier (`==<version>`), not a runner coordinate
244
237
  (`@<version>`). It is on the sanctioned side for the same reason a `uvx` run is: it fills
@@ -370,8 +363,8 @@ A tool that is neither in the image nor reachable through one of the three runne
370
363
  change: a pull request against cybermonklabs/legion that carries the same name through every site that
371
364
  spells it out, and those sites are not all held by a test.
372
365
 
373
- Do not work from a list of those sites. This page has carried one twice and it was wrong both
374
- times, so take them from the repository instead: grep for a client the image already carries,
366
+ Do not work from a list of those sites. A list goes stale, so take them from the repository
367
+ instead: grep for a client the image already carries,
375
368
  under both of its names — the command and the Debian package that provides it are spelled
376
369
  differently, and different sites spell each — and carry the new name through everything the two
377
370
  find.
@@ -453,24 +446,20 @@ something to count.
453
446
 
454
447
  - **Read the summary your work wrote, never the Job's phase.** A Kubernetes Job that reports
455
448
  `Succeeded` says its container exited 0, and nothing more: read the artefact your work was to
456
- produce, or the log line that proves it ran, before you believe any result. A lane measured
457
- this on 2026-11-01: two pods running a native toolchain died with `Error: Stack overflow.` after 23
458
- seconds, and their Job still reported `Succeeded`, because the process they ran (`rocq repl`)
459
- exits 0 when a command inside it fails. The toolchain is incidental; any interpreter, driver or
460
- wrapper that swallows an inner failure gives the same clean phase over a silent no-result, and
461
- a lane that trusts the phase records it as a run that worked.
449
+ produce, or the log line that proves it ran, before you believe any result. Any interpreter,
450
+ driver or wrapper that exits 0 when a command inside it fails leaves the Job `Succeeded` over a
451
+ silent no-result, and a watcher that trusts the phase records it as a run that worked.
462
452
 
463
453
  Two habits make that phase true. Detect the failure in the text your tool prints and exit
464
454
  non-zero yourself, rather than passing the wrapper's exit code on. And write a verdict that
465
- matters to durable storage as it is produced, not at the end: a node can vanish within a minute
466
- of a pod ending, so an unpersisted log is gone even when nothing killed anything, and a
467
- terminating pod's grace period can be as short as 25 seconds, which is no time to flush.
468
-
469
- **The phase lies in the other direction too, and that one is worse.** A lane measured a Job
470
- reporting `Running` for 23 minutes while its pod count was **zero**: the quota was full, every
471
- pod create was refused (`exceeded quota … requested: requests.cpu=16, used: 198, limited:
472
- 200`), and the controller kept retrying. A watcher reading the phase would have called that
473
- build running all night. **The phase is a request; the pod list is the result.** If you watch
455
+ matters to durable storage as it is produced, not at the end: a node can vanish soon after a
456
+ pod ends, so an unpersisted log is gone even when nothing killed anything, and a
457
+ terminating pod's grace period can be too short to flush.
458
+
459
+ **The phase lies in the other direction too, and that one is worse.** A Job can report
460
+ `Running` while its pod count is **zero**: when the quota is full, every pod create is refused
461
+ (`exceeded quota …`) and the controller keeps retrying, so a watcher that reads the phase calls
462
+ that build running. **The phase is a request; the pod list is the result.** If you watch
474
463
  a Job, watch `kubectl get pods -l batch.kubernetes.io/job-name=<job>`, or watch the marker
475
464
  your own work writes — never the phase alone.
476
465
  - **gVisor.** Every pod runs under gVisor, which does not give a test every interface the Linux
@@ -478,14 +467,12 @@ something to count.
478
467
  and `internal/broker/helper` fail: the helper identifies its peer with `SO_PEERPIDFD`, which
479
468
  gVisor answers `protocol not available` (`PEER_UNIDENTIFIED` in the test output). The
480
469
  terminal-prompt tests of `cmd/agent-secrets` also need terminal job-control ioctls
481
- (`inappropriate ioctl for device`), and the `SigCgt` line of `/proc/<pid>/status`, which the
482
- pods' gVisor lacked on 2026-10-28; upstream gVisor added that line on 2026-09-24, so a node on a
483
- later release may have it. A timing test can fail too: `internal/dispatch/pmdoc`'s linearity
470
+ (`inappropriate ioctl for device`), and the `SigCgt` line of `/proc/<pid>/status`, which older
471
+ gVisor releases lack. A timing test can fail too: `internal/dispatch/pmdoc`'s linearity
484
472
  tests time a call by the process's CPU time, which gVisor counts in 10 ms ticks, so a call under
485
473
  10 ms can measure 0 s and the test reports `+Inf times`.
486
- - **`O_DIRECTORY|O_NOFOLLOW` follows a directory link under gVisor.** A lane measured this on
487
- 2026-11-01, in a pod under gVisor (`uname` 4.19.0-gvisor) against the same probe on an ordinary
488
- kernel, on two filesystems. Almost everything matches: `O_RDONLY|O_NOFOLLOW` on a symlink to a
474
+ - **`O_DIRECTORY|O_NOFOLLOW` follows a directory link under gVisor.** Almost everything matches
475
+ an ordinary kernel: `O_RDONLY|O_NOFOLLOW` on a symlink to a
489
476
  file refuses `ELOOP`, `O_CREAT|O_EXCL|O_NOFOLLOW` on one refuses `EEXIST`, `O_PATH|O_NOFOLLOW`
490
477
  opens the link itself, and the controls (a regular file, a real directory, a free name) succeed
491
478
  on both. One call differs: `openat(dirfd, <a link to a directory>,
@@ -494,7 +481,7 @@ something to count.
494
481
  with `O_DIRECTORY|O_NOFOLLOW` is defeated there while every leaf check still passes, and its
495
482
  tests stay green on a developer's kernel. Dropping `O_DIRECTORY` changes it, because
496
483
  `openat(dirfd, <a link to a directory>, O_RDONLY|O_NOFOLLOW|O_NONBLOCK|O_CLOEXEC)` refuses
497
- `ELOOP` under gVisor too, measured on 2026-11-08 and relied on by `openSessionFileBeneath` in
484
+ `ELOOP` under gVisor too, relied on by `openSessionFileBeneath` in
498
485
  `packages/daemon/cmd/legion/sessions.go`, so what the sandbox follows is the `O_DIRECTORY`
499
486
  combination and not `O_NOFOLLOW` itself. A whole block of such tests failing in a pod is that
500
487
  one property of the environment, not one defect per test. The fix shape holds on both kernels:
@@ -502,11 +489,10 @@ something to count.
502
489
  `O_PATH|O_NOFOLLOW|O_CLOEXEC`, which opens the entry itself on both kernels, and reads the
503
490
  kind from fstat of that handle. The repository's own instance is `mountPointBeneath` in
504
491
  `packages/daemon/internal/launcher/roleinit_linux.go`. `openat2` is not the alternative
505
- there: a lane measured it returning `ENOSYS` under gVisor for every flag combination it
506
- tried, so the handle rule above is the portable check rather than a fallback. The question
492
+ there: gVisor can return `ENOSYS` for it, so the handle rule above is the portable check
493
+ rather than a fallback. The question
507
494
  is not which tool to use but whether anything you run calls `openat2`, which you can read off
508
- the binary (two builds of one tool reporting an identical `--version` differed here, and only
509
- the package version and the checksum told them apart):
495
+ the binary (two builds that report the same `--version` can differ here):
510
496
 
511
497
  ```sh
512
498
  b=$(readlink -f "$(command -v <tool>)")
@@ -520,10 +506,8 @@ something to count.
520
506
  clean result. **An undefined `openat2` symbol proves the binary calls it. Its absence proves
521
507
  nothing**, so the check is a positive test only: a caller can reach the syscall through
522
508
  `syscall(SYS_openat2, …)`, which leaves `syscall` in the table and never `openat2`, and a libc
523
- that exports no `openat2` wrapper produces the symbol for no binary at all — measured on a
524
- glibc 2.39 host, where no binary in `/usr/bin` carries it and `tar` shows 227 undefined
525
- symbols, `openat2` zero and `syscall` one. To establish that a binary is safe rather than
526
- suspect, trace it.
509
+ that exports no `openat2` wrapper produces the symbol for no binary at all. To establish that
510
+ a binary is safe rather than suspect, trace it.
527
511
  - **Set the stack with `ulimit -s`, then read both limits back.** The check, not the number,
528
512
  is the durable part. 131072 is the number for an ordinary job; name a larger one when a tool
529
513
  you run polices its own limit and demands it:
@@ -539,7 +523,7 @@ something to count.
539
523
 
540
524
  The soft limit must equal what you asked for, and the hard limit must be finite and no lower.
541
525
  `unlimited` is refused by name, because it reports `unlimited` and gives 8 MiB.
542
- Three things in that setter each answer a measured failure, and a simpler form breaks one of
526
+ Three things in that setter each answer a failure, and a simpler form breaks one of
543
527
  them. **The soft limit is set first**, because lowering the hard limit below a soft
544
528
  `unlimited` is `EINVAL` — `ulimit -H -s 131072` from that state fails with `cannot modify
545
529
  limit: Invalid argument`, and chained with `&&` the soft set never runs, so the process keeps
@@ -550,33 +534,26 @@ something to count.
550
534
  already finite, that test is false, and a bare `&&` list whose test fails is a non-zero exit
551
535
  status. `set -e` does not abort there, so the script runs to the end and does all of its work
552
536
  — and if that line is the last one in the file, the script exits 1 with everything correct.
553
- Measured: as a last line, `exit=1`; with `|| true`, `exit=0`; and with any command after it,
537
+ As a last line, `exit=1`; with `|| true`, `exit=0`; and with any command after it,
554
538
  `exit=0` either way, which is why it is easy to test and find nothing. And the
555
539
  **fallback** covers a want above the current hard limit, where the soft set fails first.
556
- Measured from three starting states: `unlimited/unlimited` and `8192/unlimited` both end at
540
+ From three starting states: `unlimited/unlimited` and `8192/unlimited` both end at
557
541
  `131072/131072`, and `131072/1048576` ends at `131072/1048576` with the higher hard limit
558
- kept. Do not reduce it to a single `ulimit -s <n>`: that set both limits in a fresh shell
559
- here and left the hard limit `unlimited` in a long-lived one, same binary and same starting
560
- pair, cause unknown — which is why the read-back is the rule and the setter is not.
542
+ kept. Do not reduce it to a single `ulimit -s <n>`: whether it also sets the hard limit
543
+ differs from shell to shell, which is why the read-back is the rule and the setter is not.
561
544
  The ceiling is 128 MiB whichever finite value you choose —
562
545
  gVisor maps the whole stack at exec and caps it at `maxStackSize = 128 << 20` in `MapStack`
563
546
  (`pkg/sentry/mm/syscalls.go`), with `RLIM_INFINITY` falling back to the 8 MiB default — and a
564
547
  larger soft limit costs rather than buys, since glibc sizes a default thread stack from it and
565
- a tool that creates a thread pool can fail to allocate one. A lane measured both on 2026-11-01
566
- in pods under gVisor (4.19.0-gvisor), with a C probe and a second probe in another language:
567
- under `unlimited` the fault came at 7 MiB and 524,150 frames; at 131072 (KiB) both probes
568
- faulted at 127 MiB and 8,388,470 frames. The same probes on an ordinary kernel track the
569
- setting as expected, so this is the sandbox and not the probes.
548
+ a tool that creates a thread pool can fail to allocate one.
570
549
  - **Compare durations within one pod, never across pods.** A gVisor sandbox runs syscall-heavy
571
- work 2.2 to 3.8 times slower than the same work outside it, and a pod lands on whatever node
550
+ work several times slower than the same work outside it, and a pod lands on whatever node
572
551
  the autoscaler provisions, so two pods are two machines, two sets of neighbours and two
573
- moments. Three parts, all measured: within one pod, comparable — run both arms there, as two
552
+ moments. Three parts: within one pod, comparable — run both arms there, as two
574
553
  containers on one node started together, and a difference between them is a difference between
575
554
  the arms; across pods, not comparable; across platforms, not until something measures the gap.
576
555
  Label every figure taken there a gVisor figure. That factor is the cost of syscalls and no
577
- budget for a whole job: a lane measured two real builds of the same work faster in a pod than
578
- on a virtual machine (1,014 s against 1,546 s, and 620 s against 1,117 s), with system time
579
- roughly doubled and user time lower, so compute-bound work can run as fast or faster there.
556
+ budget for a whole job: compute-bound work can run as fast or faster there.
580
557
  - **No Docker.** The image carries no container runtime, so a test that starts one through
581
558
  testcontainers panics `rootless Docker not found`: in `packages/envoy`, the tests that use
582
559
  `internal/tests3` (`internal/dispatch/files`, which `DISPATCH_TEST_NO_CONTAINERS=1` skips) and
@@ -599,10 +576,7 @@ something to count.
599
576
  streams, and each would see the other's connections as a leak.
600
577
  Pick ports no sibling role holds, and keep the store directory off your home. In your own
601
578
  work, run the NATS-backed tests your change touches by name (`go test -run`), as the first
602
- section says. Measured here, as proof of the route and not as a run to repeat:
603
- `go run …@v2.15.1 --version` prints `nats-server: v2.15.1`, and with the two variables set
604
- `go test -count=1 -timeout 40m ./internal/workflow/` runs whole in the pod, with no docker
605
- panic.
579
+ section says.
606
580
  - **The rest, by package**, for a named run the pod does make. A Postgres unpacked from Debian
607
581
  packages (the harness under **The worked case** of `withheld-capability.md`) has only the
608
582
  `C`, `C.utf8` and `POSIX` locales, so its default collation is byte order, and
@@ -95,7 +95,7 @@ toolchain — is where the first condition does the work. `uv run --with pyyaml=
95
95
  passes both: the wheel lands in `UV_CACHE_DIR`, under `wheels-v6/pypi/pyyaml/6.0.2-…`, and
96
96
  `UV_PYTHON_INSTALL_DIR` is never created, because the image's own `python3` served the run. The
97
97
  interpreter is the other run: a project whose `.python-version` names an interpreter uv must fetch
98
- puts about 70 MB under `UV_PYTHON_INSTALL_DIR`, where every role of the issue's pod finds it, while
98
+ puts that interpreter under `UV_PYTHON_INSTALL_DIR`, where every role of the issue's pod finds it, while
99
99
  the cache holds no wheel. A browser download passes too, and for Playwright — the browser driver this
100
100
  repository's own Dispatch suite installs (`playwright install`, `packages/dispatch`'s
101
101
  `e2e:install`) — it passes as it stands, with nothing pointed anywhere: playwright-core resolves
@@ -126,26 +126,30 @@ share): one copy per role, per pod, kept across the role's relaunches in that po
126
126
  the pod is replaced, and charged to the pod's ephemeral-storage limit, which every role of the pod
127
127
  shares and which is smaller than the volume. Moving exactly these writes off that
128
128
  filesystem is what `roleEnvironment` (`packages/daemon/internal/runtime/sandbox/manifest.go`)
129
- exists for, after GKE Autopilot evicted issue pods that charged their caches to it — so an install
129
+ exists for, because a pod whose caches pass its ephemeral-storage limit is evicted — so an install
130
130
  under `$HOME` fails the first condition and is outside the sanctioned form, however little else it
131
131
  changes. The three artefacts above are the whole of that line's ground. Disk is not: every cache is
132
132
  already relocated onto the issue's volume, which has the room for them (`docs/kubernetes.md`, "The
133
133
  tools a role's own work needs", carries the figure), and a sanctioned install is paid once per
134
134
  issue pod, on the issue's own disk, by the issue's roles together.
135
135
 
136
- **The worked case, and the one a role actually meets: the Dispatch e2e stack.** A change to
137
- `packages/dispatch` is proved in the pod by driving the specs it touches, one spec a command
138
- (`bun run e2e -- e2e/<one spec file>`) — except a wall-clock spec, whose three projects are out
139
- of the default selection, so its command names its project:
136
+ **The worked case, and the one a role actually meets: the Dispatch e2e stack.** A spec a role
137
+ added or changed in `packages/dispatch` runs in the pod while it is written, as a development run,
138
+ one spec a command (`bun run e2e -- e2e/<one spec file>`) — a wall-clock spec, whose three
139
+ projects are out of the default selection, with a command that names its project:
140
140
  `bun run e2e -- --project=chromium-alone e2e/heavy-bodies.e2e.ts --workers=1`.
141
141
  `packages/dispatch/AGENTS.md` carries both of those as the three commands to copy as they stand.
142
+ The change's proof is CI's run at the head, never the pod's.
142
143
  CI's `dispatch-browser` job runs one of two lanes, and neither is the whole suite on every pull
143
144
  request. An unlabelled pull request gets the pull-request lane: `chromium`, `iphone`, `stub`
144
145
  and `stub-phone`, held to the rows tagged `@pr`. The full lane - every project over every row,
145
146
  the three `-alone` ones among them - runs on a pull request labelled `full-ci`, on the merge
146
147
  queue and nightly, and the `alone` job that holds the wall-clock rows is gated on it
147
148
  (`if: inputs.lane == 'full'` under `alone:` in `.github/workflows/dispatch-browser.yaml`), so no
148
- unlabelled pull request runs a wall-clock row at all. One spec needs
149
+ unlabelled pull request runs a wall-clock row at all. So a `@pr` row is proved by the pull-request
150
+ lane, and any other row, every wall-clock row among them, by the full lane under `full-ci`, with
151
+ `dispatch-browser` as its check's `ci_check`
152
+ (`skill://legion-architect/references/design-gate.md#a-check-ci-proves`). One spec needs
149
153
  the same stack as all the specs: a Postgres with pgvector. On a digest
150
154
  carrying `legion-testpg`, use the pod's own server
151
155
  (`skill://legion-worker/references/tools.md#the-database-your-tests-use`) and
@@ -56,7 +56,7 @@ An interface or data shape that existed only in an earlier iteration of the curr
56
56
 
57
57
  ## Step 4: Verify behavior is preserved
58
58
 
59
- Run this step only when a fix was applied. Run project-wide typecheck and lint. Run tests matched to blast radius: scoped tests for local changes, broader tests for shared or wide-reach changes, and the full suite when the runner cannot scope tests. A pass that applied nothing left the head as it was, so there is nothing to verify: record `no fix applied; head unchanged, no verification run` in the summary and go to Step 5.
59
+ Run this step only when a fix was applied. Run the typecheck, lint or build of the packages the fixes touched, and the tests that cover the changed code, by name. Run no whole test suite: CI runs each suite when the branch is pushed. A pass that applied nothing left the head as it was, so there is nothing to verify: record `no fix applied; head unchanged, no verification run` in the summary and go to Step 5.
60
60
 
61
61
  Report failures with the check name and relevant output. Fix simplification-caused failures or revert the responsible change; never relax assertions, weaken types, or skip tests.
62
62
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.30.0",
3
+ "version": "19.30.2",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {