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: `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).

## 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.