gander: record approved design restart policy and implementation plan
This commit is contained in:
1 parent
5fe259f161
commit
4d26003f73
3 files changed
+152
-6
No files matched your search
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
Reference in new issue
Block a user