WI-1 Scratchpad — Authenticated external lease broker

Issue: Gitea #828
Milestone: 188 — Compaction-Refresh Mechanism (M1: Claude + Pi)
Branch: feat/828-lease-broker
Starting HEAD: d801d6c4c8a984d6a95033c49714210018d3d9a8
Session role: Orchestrator coordinating implementation; Mos retains merge authority.

Objective

Implement the ratified WI-1 product lease broker under packages/mosaic/: Linux SO_PEERCRED identity, broker-minted logical session IDs, (pid,starttime) launcher anchors with per-hop /proc starttime revalidation, sibling-substitution rejection, same-PID runtime-generation revocation, crypto-RNG single-use token persistence, and protected Unix-socket posture.

Authority verification

Verified before code on session start; all exact SHA-256 values matched:

BUILD-BRIEF: 89fdbc27ed0e5050dc7b52f3ef2ddaea691edf17fd89d51b15e26fb5ed47171b
SPEC-v5: a6d07ade835758e8488ca10d3b0631caf0beb93ea3a6733631f151b0c2f01433
Ratification: bac58319c9c4028b5b40e1129e0033cdb5a6b7b02033c25f06f4cb77d7779c67
P6 planner ruling: b7bbb6ea6e8d9a5c3366993642ab4e4f65b961af04936dcac20bfbcdcbaf1a09
WI-0 Gate0 evidence: 5d418306fcc597fd514e500bee40d1509f0bf467e46ee13fc5c280ed8274759d

Locked constraints

Build against the ratified design; do not re-derive it.
Product code only in packages/mosaic; Gate0 Python probes are reference prototypes and are not shipped.
Caller-supplied/asserted session_id is refused.
Tokens use the operating-system CSPRNG via Python secrets; never Math.random or model output.
Socket parent directory mode 0700, socket mode 0600 minimum; document distinct-principal deployment as the stronger T-C-closing posture.
Red-first TDD for six named cases; new-code coverage >=85%.
No merge. PR must say closes #828; exact 40-character head handed to Mos for Opus-SECREV and independent review.

Plan

Load security/testing/docs guidance and inspect existing packages/mosaic architecture.
Write the six required tests first and capture RED evidence.
Implement minimal broker modules and CLI/runtime integration necessary for product use.
Run focused tests with coverage, package gates, then full repository gates/suite.
Run author-side review/remediation, commit closes #828, queue guard, push, and open PR through Mosaic wrappers.
Send PR number + exact head SHA to web1:mosaic-100; stop without merging.

Risks / boundaries

Same-UID counterfeit socket replacement remains the disclosed T-C residual unless broker runs under a distinct principal; filesystem modes alone are minimum hardening, not a complete authenticity proof.
.mosaic/orchestrator/mission.json and .mosaic/orchestrator/session.lock were already modified at session start and must not be included in this PR.
Repository Woodpecker pipelines exist; CI is the canonical build path. No manual image build/deploy is in scope.

Progress / evidence

2026-07-18 session start: mandatory mission files and orchestration guides loaded.
STEP 0: all four authority hashes matched; artifacts read in full.
Branch/HEAD confirmed; issue #828 open; Gate0 evidence hash confirmed.
Initial RED: focused Vitest acceptance suite failed 11/11 because the product daemon did not exist; the expected missing-product failure was observed before implementation.
Review-remediation RED: partial/zero-progress state writes, nested corrupt state, symlink state, canonical starttime, and duplicate-anchor generation behavior failed before their fixes. Real socket RED/GREEN runs were executed by the unrestricted parent harness because the delegated worker sandbox denies AF_UNIX.bind().
Product implementation added at packages/mosaic/framework/tools/lease-broker/daemon.py; Gate0 probe scripts were read as references but not copied or shipped.
Independent Codex code review round 1 found 2 blockers + 1 should-fix (connection stall/crash, partial writes, packet-dependent framing); all were remediated with tests.
Independent Codex code review round 2 found 2 blockers + 1 relevant should-fix (half-close contract ambiguity, incomplete persisted-state validation, symlink/non-regular state); all were remediated with tests and documentation. Pre-existing .mosaic/* session dirt remains excluded from the PR.
Unrestricted focused situational suite: 35/35 GREEN.
New Python product module coverage: 90% (356 statements, 36 missed), above the user-required 85%.
Root typecheck: 42/42 Turbo tasks GREEN.
Root lint: 23/23 Turbo tasks GREEN.
Root format check: GREEN.
Package build + suite: 71/71 files and 1,369/1,369 tests GREEN, including framework shell tests.
Full root suite: 43/43 Turbo tasks GREEN after the oversized-frame production race fix.
Focused acceptance suite: 35/35 GREEN in three consecutive unrestricted runs; exact-head instrumented run also 35/35 GREEN.
Exact-head Python product coverage: 90% (365 statements, 37 missed), above the required 85%.
Review-triggered oversized-frame race was fixed in production by bounded drain-to-EOF; tests were not changed.
Commits banked in red/green cadence: d61c5441 (RED contract), deb11df7 (GREEN implementation/docs), 57770e34 (oversized-frame production fix).
Final-review blocker remediated: added a 256-token pending-state cap, deletion on consume/generation revocation, pre-open serialized-size enforcement, and request-wide in-memory rollback for every broker mutation/commit failure while retaining the v1 live-token schema.
Distinct-principal docs now state built-in 0700/0600 is same-principal only; WI-1 does not provide the external identity-preserving proxy/ACL/service boundary needed for the stronger deployment.
Exact Python unit suite: 8/8 GREEN. Unrestricted focused acceptance: 35/35 GREEN.
Exact-head package build/suite: 71/71 files and 1,369/1,369 tests GREEN.
Exact-head Python product coverage: 90% (376 statements, 36 missed), above required 85%.
Root typecheck: 42/42 GREEN. Root lint: 23/23 GREEN. Root format check and git diff --check: GREEN.
Final exact-head rereview found two persistence blockers: post-rename directory-fsync uncertainty and acceptance of impossible persisted token records. RED was captured as three invariant failures plus one missing fail-stop error; commits a94b1220 (RED) and d05465e5 (GREEN) remediate both without weakening tests.
Post-remediation evidence: Python unit suite 10/10, focused real-socket acceptance 35/35, full root suite 43/43 Turbo tasks, broker coverage 90% (395 statements, 38 missed), lint 23/23, typecheck 42/42, format check and git diff --check GREEN.
Independent Codex review of remediation commit d05465e54736c4966294c4af8fbd6a4ad8fe81aa: APPROVE, confidence 0.94, zero findings. Reviewer sandbox could not allocate temp directories; unrestricted parent test evidence above is canonical.
Remediation session: terra review comment 18072 reproduced a SERIAL-ACCEPT DoS; scope is RED regressions plus bounded concurrent connection handling on PR #836, preserving all existing broker security properties.
RED evidence against reviewed daemon: four silent peers delayed registration 3920 ms beyond the 1500 ms bound; 16 silent peers were not reaped within 2500 ms. The first bounded implementation then exposed slot exhaustion by rejecting the valid queued caller with EPIPE; admission was corrected to wait for a reclaimed bounded slot. GREEN evidence: queued-peer test 211 ms; strengthened cap/reap/reclaim test 1118 ms; complete real-socket acceptance 37/37 and Python persistence suite 10/10.

Coordinator handoff requirements

Mandatory Opus-SECREV on the exact PR head; no GPT/terra substitute.
Independent exact-head code review and exact-head RoR before Mos-authorized merge.
Mos retains merge authority; this WI author stops after PR + full 40-character head handoff.

7.8 KiB Raw Blame History