@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.
- package/agents/plan-reviewer.md +5 -1
- package/dist/legion.js +1 -1
- package/dist/skills/legion-architect/SKILL.md +4 -3
- package/dist/skills/legion-architect/references/acceptance.md +14 -4
- package/dist/skills/legion-architect/references/decomposition.md +4 -3
- package/dist/skills/legion-architect/references/design-gate.md +24 -5
- package/dist/skills/legion-architect/references/wake-routing.md +1 -1
- package/dist/skills/legion-controller/SKILL.md +2 -6
- package/dist/skills/legion-controller/references/consolidation.md +3 -4
- package/dist/skills/legion-controller/references/daily-report.md +3 -4
- package/dist/skills/legion-controller/references/finding-asks.md +4 -4
- package/dist/skills/legion-controller/references/session.md +2 -1
- package/dist/skills/legion-controller/references/slack-mentions.md +2 -2
- package/dist/skills/legion-controller/references/triage.md +2 -2
- package/dist/skills/legion-controller/references/wakes.md +2 -2
- package/dist/skills/legion-controller/references/weekly-audit.md +3 -4
- package/dist/skills/legion-retro/SKILL.md +9 -3
- package/dist/skills/legion-worker/SKILL.md +15 -13
- package/dist/skills/legion-worker/references/ci-checks.md +20 -3
- package/dist/skills/legion-worker/references/conflicts-and-rewrites.md +14 -43
- package/dist/skills/legion-worker/references/foreign-path.md +1 -1
- package/dist/skills/legion-worker/references/merge-gate.md +39 -39
- package/dist/skills/legion-worker/references/plan-tests.md +40 -0
- package/dist/skills/legion-worker/references/pr-body.md +33 -12
- package/dist/skills/legion-worker/references/tools.md +49 -75
- package/dist/skills/legion-worker/references/withheld-capability.md +11 -7
- package/dist/skills/simplify-settled-diff/SKILL.md +1 -1
- 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
|
-
|
|
52
|
-
|
|
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
|
|
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
|
|
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
|
|
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`).
|
|
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
|
-
|
|
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
|
|
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
|
|
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 (*
|
|
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
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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`).
|
|
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.
|
|
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
|
|
147
|
-
|
|
148
|
-
- `redis-cli` —
|
|
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:
|
|
188
|
-
|
|
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
|
|
215
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
374
|
-
|
|
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.
|
|
457
|
-
|
|
458
|
-
|
|
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
|
|
466
|
-
|
|
467
|
-
terminating pod's grace period can be
|
|
468
|
-
|
|
469
|
-
**The phase lies in the other direction too, and that one is worse.** A
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
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
|
|
482
|
-
|
|
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.**
|
|
487
|
-
|
|
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,
|
|
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:
|
|
506
|
-
|
|
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
|
|
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
|
|
524
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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>`:
|
|
559
|
-
|
|
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.
|
|
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
|
|
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
|
|
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:
|
|
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.
|
|
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
|
|
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,
|
|
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
|
|
137
|
-
`packages/dispatch`
|
|
138
|
-
(`bun run e2e -- e2e/<one spec file>`) —
|
|
139
|
-
of the default selection,
|
|
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.
|
|
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
|
|
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
|
|