feat(pi): pi is found, labelled and fit-checked at start instead of pinned; a pi that lacks a needed feature is refused harness-feature-missing (#1873)
#2010
Lane pi-unpin-s123, slices S1 to S3 of the pi-unpin design: pi is no longer pinned at run time. Jason's ruling, 2026-11-19: no pins on any harness, a check instead.
S1, labels. pi's version and labels come from the binary the pi module finds, not from a pinned string.
S2, the binary. A session runs the pi the module finds: MOSAIC_PI_BIN (absolute and executable), else the first pi on PATH, else the repository's copy. A found pi must be the bin its own package names. The sandbox mounts it by its package directory.
S3, the fit check. Every start runs a sandboxed, offline check on the pi it found. It refuses harness-feature-missing when a flag Mosaic relies on is missing, or when a planted source still loads with the seal flags on. The verdict is kept in memory for the life of the process, per binary. The check is warmed when the launcher is made.
The check's own sandbox. bwrap with --die-with-parent, setpriv's kill-on-parent-exit and an owner check. An outer unshare pid namespace is added when the host allows it. If unshare is missing, older than util-linux 2.36 or refused, the check runs without it and does not refuse. The bwrap command line is the same on both paths.
Leftovers. Scratch dirs carry their owner's pid, start time and pid namespace. A later check removes a dead owner's dirs and stops its leftover check processes: same uid, the dir's path on the command line, owner dead.
Triage host.MOSAIC_PI_BIN joins the spawn path allow list, with every host check kept.
harness-feature-missing is the only new refusal code (approved 2026-11-19). No new verb, grant, role, bus schema change or config format. The fit route is zai / glm-5.3-flash, declared in the pi plugin. No Claude model runs on pi. The pinned package version in package.json, the image tag, the scripts and AGENTS.md are unchanged; those are later slices.
Tests
New: packages/harness/tests/pi-fit.test.mjs, packages/plugins/tests/pi-binary.test.mjs and a pi stand-in. Launcher, sandbox, session and triage-host tests grow.
Lane gate on fb1b8ddeb (old base 6c5ec23b4): 119 files, 1608 pass, 4 fail, 3 skip. The 4 were pickup-launch.test.mjs reds on that base, fixed since on refactor.
Proof runs: test 655 green 50 of 50 on constrained CPUs. Kill-the-owner, 100 runs per path: 0 processes left with unshare; without it, 0 left after the next check.
Lead check in a clean environment on the rebased tip 6ad11e699: 6ad11e699 on base 88d08c843: 652 files, 7037 pass, 1 fail, 10 skip. The one fail is packages/conversation/tests/reader.test.mjs, which fails the same way on the base in this clean environment (Python jsonschema is not installed there).
Review
Eleven rounds by fresh claude-opus-5-5 reviewers. Round 11 approved with no P1 or P2 and three P3s, listed below.
Left for later
A failing setpriv is reported as a bwrap failure.
Three guards in the sweep and probe have no test that fails when they are removed: the uid check, the second start-time read and the probe's own stop.
The sweep stops any same-uid process whose command line names a dead owner's scratch dir. That can include an operator's tail on that path.
Scratch dirs from a pid namespace that has ended are skipped by later sweeps.
The unshare fallback is not proven on a real Ubuntu 24.04 host with the AppArmor user-namespace restriction. Tests use a stand-in unshare that fails the same way.
The fit check runs cold at every bus start, and the first launch on one CPU is slower.
pi 0.85.1 loads ambient skills; packages/discord/src/engine-pi.mjs still names its own pi.
Slices S4 to S6, the lock move to pi 1.5.2 and the periodic harness watch.
## What changes
Lane pi-unpin-s123, slices S1 to S3 of the pi-unpin design: pi is no longer pinned at run time. Jason's ruling, 2026-11-19: no pins on any harness, a check instead.
- **S1, labels.** pi's version and labels come from the binary the pi module finds, not from a pinned string.
- **S2, the binary.** A session runs the pi the module finds: `MOSAIC_PI_BIN` (absolute and executable), else the first `pi` on PATH, else the repository's copy. A found pi must be the bin its own package names. The sandbox mounts it by its package directory.
- **S3, the fit check.** Every start runs a sandboxed, offline check on the pi it found. It refuses `harness-feature-missing` when a flag Mosaic relies on is missing, or when a planted source still loads with the seal flags on. The verdict is kept in memory for the life of the process, per binary. The check is warmed when the launcher is made.
- **The check's own sandbox.** bwrap with `--die-with-parent`, setpriv's kill-on-parent-exit and an owner check. An outer `unshare` pid namespace is added when the host allows it. If unshare is missing, older than util-linux 2.36 or refused, the check runs without it and does not refuse. The bwrap command line is the same on both paths.
- **Leftovers.** Scratch dirs carry their owner's pid, start time and pid namespace. A later check removes a dead owner's dirs and stops its leftover check processes: same uid, the dir's path on the command line, owner dead.
- **Triage host.** `MOSAIC_PI_BIN` joins the spawn path allow list, with every host check kept.
`harness-feature-missing` is the only new refusal code (approved 2026-11-19). No new verb, grant, role, bus schema change or config format. The fit route is zai / glm-5.3-flash, declared in the pi plugin. No Claude model runs on pi. The pinned package version in `package.json`, the image tag, the scripts and AGENTS.md are unchanged; those are later slices.
## Tests
- New: `packages/harness/tests/pi-fit.test.mjs`, `packages/plugins/tests/pi-binary.test.mjs` and a pi stand-in. Launcher, sandbox, session and triage-host tests grow.
- Lane gate on fb1b8ddeb (old base 6c5ec23b4): 119 files, 1608 pass, 4 fail, 3 skip. The 4 were `pickup-launch.test.mjs` reds on that base, fixed since on refactor.
- Proof runs: test 655 green 50 of 50 on constrained CPUs. Kill-the-owner, 100 runs per path: 0 processes left with unshare; without it, 0 left after the next check.
- Lead check in a clean environment on the rebased tip 6ad11e699: 6ad11e699 on base 88d08c843: 652 files, 7037 pass, 1 fail, 10 skip. The one fail is `packages/conversation/tests/reader.test.mjs`, which fails the same way on the base in this clean environment (Python `jsonschema` is not installed there).
## Review
Eleven rounds by fresh claude-opus-5-5 reviewers. Round 11 approved with no P1 or P2 and three P3s, listed below.
## Left for later
- A failing setpriv is reported as a bwrap failure.
- Three guards in the sweep and probe have no test that fails when they are removed: the uid check, the second start-time read and the probe's own stop.
- The sweep stops any same-uid process whose command line names a dead owner's scratch dir. That can include an operator's `tail` on that path.
- Scratch dirs from a pid namespace that has ended are skipped by later sweeps.
- The unshare fallback is not proven on a real Ubuntu 24.04 host with the AppArmor user-namespace restriction. Tests use a stand-in unshare that fails the same way.
- The fit check runs cold at every bus start, and the first launch on one CPU is slower.
- pi 0.85.1 loads ambient skills; `packages/discord/src/engine-pi.mjs` still names its own pi.
- Slices S4 to S6, the lock move to pi 1.5.2 and the periodic harness watch.
version() runs `<bin> --version` with a 5 s timeout and a PATH that finds node, and returns
null when that fails or prints something other than one short printable line. The compaction
count records the found package's own package.json version, else null. Adapter and module
comments say "read from 0.85.1" instead of "pinned". The lookup still honours only the
repository's copy; S2 widens it.
binary.mjs locate() takes MOSAIC_PI_BIN (absolute and executable), else the
first pi on PATH past the repository's node_modules/.bin, else the
repository's copy. The binary must belong to the pi package. mounts() and
installRoots() hold that package directory; the repository's copy keeps the
whole node_modules mount, since its packages are hoisted beside pi. env()
sets MOSAIC_PI_BIN to the binary's path inside the session, and the adapter
and the model-stream branch run it. sessionEnv passes MOSAIC_PI_BIN, and
Triage's SPAWN_PATH_ALLOW takes it with every host check kept.
harness-binary-missing keeps its code; with no pi its message is "no pi
found: set MOSAIC_PI_BIN, put pi on PATH, or run npm ci". A refusal names
the variable, never a host path.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What changes
Lane pi-unpin-s123, slices S1 to S3 of the pi-unpin design: pi is no longer pinned at run time. Jason's ruling, 2026-11-19: no pins on any harness, a check instead.
MOSAIC_PI_BIN(absolute and executable), else the firstpion PATH, else the repository's copy. A found pi must be the bin its own package names. The sandbox mounts it by its package directory.harness-feature-missingwhen a flag Mosaic relies on is missing, or when a planted source still loads with the seal flags on. The verdict is kept in memory for the life of the process, per binary. The check is warmed when the launcher is made.--die-with-parent, setpriv's kill-on-parent-exit and an owner check. An outerunsharepid namespace is added when the host allows it. If unshare is missing, older than util-linux 2.36 or refused, the check runs without it and does not refuse. The bwrap command line is the same on both paths.MOSAIC_PI_BINjoins the spawn path allow list, with every host check kept.harness-feature-missingis the only new refusal code (approved 2026-11-19). No new verb, grant, role, bus schema change or config format. The fit route is zai / glm-5.3-flash, declared in the pi plugin. No Claude model runs on pi. The pinned package version inpackage.json, the image tag, the scripts and AGENTS.md are unchanged; those are later slices.Tests
packages/harness/tests/pi-fit.test.mjs,packages/plugins/tests/pi-binary.test.mjsand a pi stand-in. Launcher, sandbox, session and triage-host tests grow.6c5ec23b4): 119 files, 1608 pass, 4 fail, 3 skip. The 4 werepickup-launch.test.mjsreds on that base, fixed since on refactor.6ad11e699:6ad11e699on base88d08c843: 652 files, 7037 pass, 1 fail, 10 skip. The one fail ispackages/conversation/tests/reader.test.mjs, which fails the same way on the base in this clean environment (Pythonjsonschemais not installed there).Review
Eleven rounds by fresh claude-opus-5-5 reviewers. Round 11 approved with no P1 or P2 and three P3s, listed below.
Left for later
tailon that path.packages/discord/src/engine-pi.mjsstill names its own pi.