From 4d26003f731a6eec439df6a48cacc3ef482a59c8 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Tue, 20 Oct 2026 14:21:39 -0500 Subject: [PATCH] gander: record approved design restart policy and implementation plan --- BUILD-LOG.md | 2 + agents/gander/work/queue-196/DESIGN.md | 35 +++++-- agents/gander/work/queue-196/PLAN.md | 121 +++++++++++++++++++++++++ 3 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 agents/gander/work/queue-196/PLAN.md diff --git a/BUILD-LOG.md b/BUILD-LOG.md index a3a964fa5..5f988fdf2 100644 --- a/BUILD-LOG.md +++ b/BUILD-LOG.md @@ -5178,3 +5178,5 @@ Before: managed project/thread verbs had no Console conversation area. After: fi 2026-10-20 19:09:44 UTC | Gander row 196 #1694 design phase | Before: tester TCP reaches every local uid and human proofs do not bind the socket peer. After: design draft at agents/gander/work/queue-196/DESIGN.md inventories listeners, proposes private tester HTTP and SO_PEERCRED binding, aligns the per-request principal contract with Morgana and Gizmoduck, and lists migration, tests, mutants and same-uid limits. Python versus other credential options and Console provenance require Duckworth ruling. Documentation only. No product code, suite, live probe, secret access or deployment. 2026-10-20 19:16:20 UTC | Gander row 196 #1694 design r2 | Before: Duckworth r1 requested concurrent helper-fd evidence (B1) and selected O1 with interpreter, proof-only and image conditions. After: design adds eight concurrent genuine proof processes plus a racing copier, M20 swapped socket and post-helper socket survival, root-owned system ELF pinning and activation evidence, safe gid validation, cap traffic without helpers, and unchanged P19 R2 text. Mos accepted socket-only tester access (mos-1015 via sage-1363); any authenticated browser relay is a separate row. Documentation coverage checks passed. No product code, suites or live action. + +2026-10-20 19:21:19 UTC | Gander row 196 #1694 design approval and N5 | Before: Duckworth approved r2 (duckworth-0009, cb6d840df) with a nonblocking interpreter-upgrade note. After: r3 chooses startup safety revalidation, appends actual interpreter identity to bus/peercred-starts.jsonl and retains old activation evidence. Operator re-pin uses the next reviewed copy, respecting already-active refusal. Added task-by-task PLAN.md for inline implementation and independent manifest review. Documentation checks passed. No product code, suites or live action. diff --git a/agents/gander/work/queue-196/DESIGN.md b/agents/gander/work/queue-196/DESIGN.md index c457a198a..1d0e1aa5e 100644 --- a/agents/gander/work/queue-196/DESIGN.md +++ b/agents/gander/work/queue-196/DESIGN.md @@ -1,6 +1,6 @@ # Row 196: the human boundary across uids and humans -Gander, 2026-10-20. Revision 2, addressing Duckworth's r1 review. Gitea #1694, P19 333. +Gander, 2026-10-20. Revision 3, recording approved r2 and N5. Gitea #1694, P19 333. Base: `96f243faf`, branch `gander/row196`. Design approval latest-by 2026-10-22, landing latest-by 2026-10-24 and before federation R3. This document authorizes no live action. @@ -191,10 +191,29 @@ No PATH lookup, caller-selected interpreter or helper. Invoke the resolved binar `-I -S`, a minimal environment and the absolute helper path in the same pinned copy. Activation preflight records the interpreter's resolved path, version and file identity/hash -in its gate evidence. The bus validates and pins the resolved executable at startup before -opening broker.sock. The gate must report the same interpreter used by that bus. Missing, -unsafe or changed resolution refuses the new activation, never falling back to PATH. No -secret values are recorded. Test system-owned interpreter checks through injected metadata. +in its gate evidence. The bus validates and pins the resolved executable at each startup +before opening broker.sock. The activation gate must report the same interpreter used by +that bus. Missing, unsafe or changed resolution during that activation refuses it, never +falling back to PATH. No secret values are recorded. Test system-owned interpreter checks +through injected metadata. + +N5 decision: a later bus restart repeats the safety/version/support checks and accepts a +safe system interpreter installed by an OS upgrade. It does not compare against an old +activation hash. Before opening the listener, append a startup receipt with timestamp, +copy path, resolved interpreter path, version and file identity/hash to +`/bus/peercred-starts.jsonl` (0600 in the checked 0700 bus directory). Refuse an +unsafe receipt file or failed append. Never edit the old activation evidence. The startup +receipt identifies the binary now in use, so the old receipt remains a historical fact. +If an upgraded interpreter fails the checks, startup fails closed until a safe supported +system interpreter is restored by the operator. There is no shim or O4 auto-fallback. + +Operator re-pin after an interpreter change: in the next authorized window, prepare the +next reviewed copy with `scripts/stack-copy.sh copy NEW`, then run +`scripts/stack-release.sh activate NEW BUSINESS --tester-socket` with that instance's existing +flags and selector, first with --plan. NEW must differ from the active copy because activate +refuses already-active. Record the interpreter in the new activation evidence and compare it +with the bus startup receipt. A routine OS update alone does not authorize a re-pin or unit +restart. A bus restart does not rewrite config, pointer or activation history. Preflight helper and SO_PEERCRED support too. The helper lives under packages/bus/src so stack-copy's closure includes it. Copies remain immutable. Document Python >=3.10 on bus @@ -262,7 +281,7 @@ Use short TMPDIR paths so the longest Unix socket path stays under 108 bytes. | T7 consumer migration | Render/plan/activate/rehearse fixture carries socket flag in unit and pointer. Explicit conversion removes port. Unsupported/inherited mismatch refuses before unit calls. Rollback disables unsupported tester, never opens TCP | M15 keep inherited tester port, M16 restore TCP on downgrade | | T8 gates and identity | bus.tester false refuses tester calls. SSO owner/user wiring uses only claims verified for that request's live session. Expired/logged-out or replaced session cannot reuse an earlier mapped id. User kind never becomes owner from its id. R3 integration maps subject, denies missing/invalid grants and owner overlap, broken access file leaves terminal owner working | M17 bypass tester switch, M18 turn user kind into owner by id | | T9 isolation limits | Two scratch instances have different sockets and matching tree paths. Foreign-uid stand-in refuses. Record that no real uid boundary was exercised | M19 choose default instance socket | -| T10 interpreter and cap path | Activation evidence records the same pinned root-owned system ELF that the bus uses. Scripts, home paths and unsafe owners/modes refuse. Cap calls complete without invoking the helper, proven with a helper spy that fails if called | M21 bypass interpreter safety, M22 invoke helper for cap traffic | +| T10 interpreter and cap path | Activation evidence records the same pinned root-owned system ELF that the bus uses. Scripts, home paths and unsafe owners/modes refuse. Simulated OS replacement followed by startup accepts a safe replacement and appends its actual identity without changing the old receipt, refuses an unsafe replacement or unsafe/unwritable receipt. Cap calls complete without invoking the helper, proven with a helper spy that fails if called | M21 bypass interpreter safety, M22 invoke helper for cap traffic, M23 retain stale interpreter identity after restart | Tests for new policy stay in the bus, WebUI and CLI packages. R3 provides the real user/grant half of T8 in its candidate, with its own gate. This row tests the shared verifier's user @@ -307,3 +326,7 @@ with the live-session and unchanged P19 R2 conditions. B1 adds concurrent T2, M2 survival checks. N2's detached-Console limit remains in R1. N3's gid validation and N4's operator window warning are included. Mos's tester-access ruling is recorded above. No product code begins before design approval. +Duckworth approved revision 2 in duckworth-0009, review at +`cb6d840df:agents/duckworth/work/row196/REVIEW-r2.md`. N5 permits either restart policy. +Revision 3 selects safety revalidation with a new append-only startup receipt, and gives the +operator a re-pin path that respects the existing already-active refusal. diff --git a/agents/gander/work/queue-196/PLAN.md b/agents/gander/work/queue-196/PLAN.md new file mode 100644 index 000000000..ad0e05db3 --- /dev/null +++ b/agents/gander/work/queue-196/PLAN.md @@ -0,0 +1,121 @@ +# Row 196 Human Boundary Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking. + +**Goal:** Bind human proofs to their actual Unix peers and make tester HTTP private to the instance uid. + +**Architecture:** The bus reads kernel credentials through a pinned system Python helper only for proof envelopes. One principal verifier keeps the human walk and supplies Console provenance for federation R3. Tester HTTP moves to a private filesystem socket. Release tools migrate the flags explicitly. + +**Tech Stack:** Linux, Node 24 and 26, Python >=3.10 standard library, existing Node test runner and shell release tools. + +**Spec:** `agents/gander/work/queue-196/DESIGN.md`, approved r2 at 5fe259f16, with N5 restart policy added in r3. + +## Global Constraints + +- Work in the existing gander/row196 worktree. Plain node_modules symlink. No new package dependency. +- No live files, credentials, listeners, units, second uid or external authentication service. +- Helpers: proof envelopes only, at most 16 concurrent, one second timeout, 256-byte strict output. +- Root-owned system Python ELF at resolved /usr/bin/python3, never PATH or a home/shim path. +- console/ 0700, tester.sock 0600, Unix pathname at most 107 bytes. +- One principal and transient cap per request. R3 owns user access policy and user-cli integration. +- Mos accepted socket-only tester access. No TCP relay or control-board change. +- Single test files run freely. Ask Sage before any suite. Stop and report two failures in a gate run. +- Commit code only after applicable suites pass. Sage owns the final gate and manifest queue moves. + +## Review Focus + +- Connection overlap and disconnect: helpers must retain the correct Socket object and release capacity on every exit. +- OS interpreter replacement: restart records the actual safe binary, while old receipts remain unchanged. +- Long or unsafe instance paths: refuse before binding or stopping any service. +- Rollback/recovery: distinguish intentional tester disablement from restoration of an old saved TCP unit. +- CLI nonce respawn and session expiry: direct-parent provenance must survive correct Console spawning and refuse stale identity. + +## Task 1: kernel credentials and interpreter evidence + +Files: create `packages/bus/src/peercred.mjs`, `packages/bus/src/peercred.py`, +`packages/bus/src/interpreter.mjs`; tests in `packages/bus/tests/peercred.test.mjs` and +`packages/bus/tests/interpreter.test.mjs`, with subprocess fixtures under `packages/bus/fixtures/`. + +Interfaces: `inspectInterpreter()` returns a validated immutable record of path, version, +device, inode and sha256. `recordInterpreterStart(directory, record)` appends the actual startup +identity safely. `createPeerReader({interpreter})` returns `{read(socket),close()}`. read resolves +to `{pid,uid,gid}` from that exact socket, or refuses. Test-only injected OS/process operations +do not become product flags or environment overrides. + +- [ ] Write interpreter safety, receipt replacement and cap-independent helper tests (T3/T10). +- [ ] Run each new test file alone and record the expected missing-module failures. +- [ ] Implement system interpreter validation and startup receipt append with no-follow, owner/type/mode checks. +- [ ] Write T2's eight-process barrier plus racing copier, wrong-fd case and post-helper socket exchange. +- [ ] Implement fd-3 helper, strict result validation, bounded async reader and helper shutdown. +- [ ] Run `node --test packages/bus/tests/interpreter.test.mjs` and separately `node --test packages/bus/tests/peercred.test.mjs`. +- [ ] Confirm process/socket cleanup, eight distinct kernel PIDs, copier refusal and original receipt preservation. + +## Task 2: principal provenance and bus dispatch + +Files: modify `packages/bus/src/{human,tester,server,runtime}.mjs`, create +`packages/bus/src/principal.mjs`, add `packages/bus/tests/principal.test.mjs`, and extend +`packages/bus/tests/human.test.mjs`. Extend server/runtime test files after inspecting their fixtures. + +Interfaces: `verifyPrincipal(request, {peer,...trustedPathsAndProcessReaders})` returns +`{kind,business,id}`. Human maps to the business human, tester to tester, user to its verified +Console proof id. No roles or grants. Server obtains peer metadata from Task 1 only after +envelope validation and only for proofs. Existing cap dispatch never invokes the helper. +Future user binding stays refused without R3's trusted integration. + +- [ ] Write T4/T5/T6/T8 process-table tests, including changed ancestry, distinct nonce namespaces and kind confusion. +- [ ] Run the focused new file and confirm expected failure before implementing the verifier. +- [ ] Parameterize the nonce/path portion of the existing human walk and retain all marker/binary/launch checks. +- [ ] Wire peer metadata, interpreter startup receipt and one-request cleanup into runtime/server. +- [ ] Test cap requests with a failing helper spy (M22), and test async refusal/close cleanup. +- [ ] Run each affected bus test file alone. Record any base fixture changes needed for real peer identity. + +## Task 3: tester Unix HTTP and Console nonce spawning + +Files: modify `packages/webui/src/{cli,serve,bus}.mjs`, create +`packages/webui/src/tester-socket.mjs` and `packages/cli/src/tester-http.mjs`; add focused +`packages/webui/tests/tester-socket.test.mjs` and `packages/cli/tests/tester-http.test.mjs`. +Extend existing WebUI transport tests. + +Interfaces: `startTesterSocket({dataRoot,...handlerOptions})` owns the private listener and +cleanup. `testerRequest({dataRoot,method,path,body})` uses the fixed logical origin and bounded +Unix HTTP. Console human child spawning supplies its initial nonce, preserving agent markers. +R3 reuses that spawn pattern for its user-cli. + +- [ ] Write T1/T3/T9 socket permission, unsafe-path, wrong-origin and instance separation tests. +- [ ] Confirm the new focused files fail, then implement --tester-socket and refusal of --tester-port. +- [ ] Keep tester principal, write allowlist and cookie/header refusals intact. Add no browser relay. +- [ ] Write and implement the initial-nonce Console spawn test and the helper request timeout test. +- [ ] Run each new or changed test file alone, verifying cleanup and no tester TCP bind. + +## Task 4: release migration and operator evidence + +Files: modify `scripts/{webui-service,stack-release}.sh`, inspect +`scripts/stack-copy.sh` closure, extend `packages/cli/tests/stack-release.test.mjs` and its +render fixtures. Update `docs/TOOLS.md` and package READMEs with the implementation. + +Interfaces: `activate ID BUSINESS --tester-socket` explicitly replaces inherited tester-port +flags. Pointer and unit argv agree. Candidate support and interpreter preflight run before +any unit stop. Activation gate evidence records the same interpreter as the bus startup receipt. + +- [ ] Write T7 explicit conversion, inherited mismatch and unsupported-target refusal fixtures. +- [ ] Run only the affected test file, then implement flag rendering, plan output and rollback disabling unsupported tester. +- [ ] Preserve old-copy recovery behavior and report restored old security state accurately. +- [ ] Add rehearsal scratch socket and T10 interpreter gate identity comparison. +- [ ] Verify same-copy activation refusal is preserved. Document N5's next-reviewed-copy re-pin path. +- [ ] Run the affected file alone, shell syntax checks, and inspect remaining tester-port references by purpose. + +## Task 5: mutants, approved suites and manifest + +Files: add the row's mutation runner and receipts under `agents/gander/work/queue-196/`. +Append BUILD-LOG phase receipts. No SESSIONS or queue file edits. + +- [ ] Exercise M1-M23 against isolated scratch copies. Record killer test, restored hash and cleanup for each. +- [ ] Run focused tests on Node 24 and 26, including the concurrent T2 case and socket lifetime checks. +- [ ] Send Sage the scope and estimated duration, obtain the suite slot, then run approved bus/WebUI/CLI suites. +- [ ] Let Sage own the scripts/test-*.sh gate. Stop on the repository's two-failure rule. +- [ ] Build the exact changed-path manifest with acceptance evidence, search results, limits and consumer audit. +- [ ] Commit/push the verified candidate only after applicable suites pass. Send Duckworth and Sage path, commit and hashes for manifest review. + +Execution stays with Gander in this worktree. No new agent delegation. Duckworth reviews +the manifest independently. Push is only to gander/row196. No merge, re-pin or deployment +is authorized by this plan.