stack/docs/scratchpads/828-lease-broker.md

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

1. Load security/testing/docs guidance and inspect existing packages/mosaic architecture.
2. Write the six required tests first and capture RED evidence.
3. Implement minimal broker modules and CLI/runtime integration necessary for product use.
4. Run focused tests with coverage, package gates, then full repository gates/suite.
5. Run author-side review/remediation, commit closes #828, queue guard, push, and open PR through Mosaic wrappers.
6. 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 and lint gates passed after remediation; final package/full-suite/format evidence is recorded below before push.

Coordinator handoff requirements

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