gander: record approved design restart policy and implementation plan

This commit is contained in:
jason.woltje committed 2026-10-20 14:21:39 -05:00
1 parent 5fe259f161
commit 4d26003f73
3 files changed
+152 -6

No files matched your search

+2
View File
@@ -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: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: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.
+29 -6
View File
@@ -1,6 +1,6 @@
# Row 196: the human boundary across uids and humans # 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 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. 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. `-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 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 in its gate evidence. The bus validates and pins the resolved executable at each startup
opening broker.sock. The gate must report the same interpreter used by that bus. Missing, before opening broker.sock. The activation gate must report the same interpreter used by
unsafe or changed resolution refuses the new activation, never falling back to PATH. No that bus. Missing, unsafe or changed resolution during that activation refuses it, never
secret values are recorded. Test system-owned interpreter checks through injected metadata. 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
`<dataRoot>/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 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 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 | | 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 | | 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 | | 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 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 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 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 operator window warning are included. Mos's tester-access ruling is recorded above. No
product code begins before design approval. 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.
+121
View File
@@ -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.