#1051 — per-estate mosaic-brain installer

Last updated: 2026-08-05

Objective

Codify estate-derived, repository-backed ~/.mosaic support with secret exclusions, non-destructive migration, doctor diagnostics/fixes, and credential-contract terminal-class handling. Live broker grants and live read/write round-trips remain gated on MC-CRED-01.

Sources and bindings

Provider issue: HOMELAB git.mosaicstack.dev, GET /api/v1/repos/mosaicstack/stack/issues/1051, application/json;charset=utf-8.
Issue requirements: R1–R8 read directly on 2026-08-05.
MC-CRED caller contract: v1.5, SHA-256 4cecba3386b37431d4a075205c6dfe43555c7673922fed61b84f43cac1a6ae92 at the 2026-08-05 re-derivation. Earlier moving bindings were v1.5 710d22d61a93a4b9c70fc55506a023a675a110417fa7a6e72dc051c0d9fe8237, v1.4 27f20158561ae8292f3bfc926b5e97f398de93db6a1cf65fcc215d08811d39af/d12ad4595b7aef078e392988a07ab5cb00244440775c9c733dc825746d7ac67b, and v1.3 8cfa4853d2b0b0e8cc9e792fa8411310e16d7704c06e0af9d9a57155131d8086.
Fleet doctrine: SHA-256 026b43322e0551ef15b646a9f30d3a6aef58c662a810b732be2a03b1ecf7d36e at intake.
Intake base was HOMELAB provider next = 4df478cdd150fdf8d52ea109f02ade5d85017acd; main = 5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc. On 2026-08-05 mos-claude ruled that L0 trunk-based gate 15 requires all three lanes to retarget to main; next remains a non-merging integration branch. Never weaken or patch pr-merge.sh.

Scope

In now

R2/Q1 target-host estate derivation using one registry.
R5 both-axis refusal parity and disagreement failure.
R6 exact secret exclusions and no secret-bearing diagnostics.
R7 detection plus non-destructive, collision-safe migration/reporting.
R8 doctor checks and approved-seam fix orchestration.
Red-first tests over all four contract terminal classes and stable reason codes.

Gated / excluded

R3 live grant: waits for working MC-CRED-01.
R4 live seat-owned read/write round-trip: waits for working MC-CRED-01.
No independent token lookup, grant helper, or shared-credential fallback.
No phase renumbering; C1 owns the phase machine and provides the P5→P7 seam.
No age/size reaping or deletion.

Owner authority ruling and resolver seam

Binding addendum: /home/hermes/agent-work/tl-mosaic/CHARTER-MB-BRAIN-01-ADDENDUM.md; re-read after compaction.
HOMELAB durable lane-archive owner and user-namespace brain owner are the human provider account selected by local estate policy (operator ruling: jason.woltje) with a required GLPI queue as the standing remediation process. The brain target is therefore <policy-owner>/mosaic-brain on the estate host, not <installer-source-org>/mosaic-brain. Framework source remains operator-agnostic: the actual login and queue are local policy, not hardcoded open-source context.
Provider lookup is anonymous because the ruled owner is public. It requires exact allowlisted login plus a same-invocation public known-good control, private 404 control, and generated absent 404 control. It sends no Authorization header and never widens token scope.
Provider active is deliberately ignored: non-admin reads return false for demonstrably active accounts. Resolvability + exact login + public visibility are the gate.
Private and absent principals both return anonymous 404. The fail-closed reason is owner-not-resolvable, never owner-not-found.
Caller owner strings and validated=true are ignored. Migration consumes only an injected source-of-truth resolver result. Owner grammar is NFKC-stable, ASCII allowlisted, exact-policy matched, and mission-seat class is excluded.

Plan

Pre-register acceptance tests and observe each requirement RED for its own missing behavior.
Commit the red tests before implementation.
Implement a narrow brain provisioning/doctor helper that consumes broker JSON outcomes and the shared estate registry without credential resolution.
Implement safe migration and exact brain skeleton/ignore policy.
Integrate the helper into C1's P7 seam and mosaic doctor after C1 lands/rebase.
Run focused, package, installer, lint, typecheck, format, and situational security tests.
Run independent code and security reviews in parallel; remediate and re-review.
Push after HOMELAB queue guard, open the reviewed PR to main, and preserve merge order C1 → MC-CRED → MB-BRAIN. Do not modify the merge guard; next is non-merging integration only.
Re-take CI measurement at the rebased exact head; do not rework code solely because base evidence moved.

Acceptance interpretation registered before results

ok/0: complete authoritative evidence only.
refused/10: complete authoritative denial only.
error/20: local contract/control failure; never reinterpret as denial.
indeterminate/30: incomplete/disagreeing evidence; fail closed, never resolve permissively.
Both Git and API axes must return authoritative refused with the same stable reason code for R5. Any axis disagreement is indeterminate. A provider /user login mismatch is first-class provider-identity-mismatch; credential filenames never establish principal identity.
Migration publication requires the durable object to contain the approved snapshot and no overwrite. Automatic path-based source deletion is parked; every source is retained and reported.
Secret exclusion is tested through exact ignore rules, nested secret-shaped paths, bounded UTF-8 content controls, and an approved-scanner gate bound to the exact source snapshot. Without an approved scanner, even benign content is retained and reported rather than committed.

Budget

No explicit token ceiling was supplied. Working cap: 55K tokens for implementation/review and 3 focused remediation attempts per failure class. Reduce optional refactoring and documentation breadth before touching required acceptance scope.

Risks

C1 and MC-CRED branches have not merged into main; integration edits must wait for their exact interfaces or be confined to stable contract seams.
A broker runtime test before MC-CRED lands would either fail for an irrelevant reason or pressure a hand-rolled workaround; contract fixtures are allowed, live capability claims are not.
Migration can lose data through overwrite, cross-device move failure, or partial copy. Implementation must stage, verify resulting bytes, and retain/report source on incomplete transfer.
~/.mosaic is a git repo, while current working state may live under multiple local roots; detection must be explicit and cannot treat age/size as ownership.

Progress / evidence

Charter receipt accepted by tl-mosaic.
Issue #1051 R1–R8 read directly from provider.
Contract re-derived through v1.3, moving v1.4, and v1.5 before R5 integration. v1.5 separates in-scope repository capability from /user identity measurement: 401 is credential-rejected/refused, 403/404 may become identity-not-measured only after in-scope capability succeeds, and 200 login mismatch is refused. identity-not-found is not reachable from validate.
C1 P5→P7 seam receipt read; no brain implementation is in C1.
RED acceptance set committed at cf11c6c86abae073d8b02b4014cd5447ba67f12a; author and committer read back as be-coder-07 and branch reachability was independently verified by tl-mosaic.
Moving-contract REDs observed independently for v1.4 mismatch, R8 prerequisite ordering, owner resolver seam/allowlist, tracked skeleton/no-follow behavior, runtime observation/publication, and provider owner resolution.
Focused implementation includes secure migration, v1.5 write-differential/subject binding, production Git+API refusal parity, provider-backed durable owner resolution that ignores non-admin active, required GLPI standing-process policy, P7 provision orchestration, an internal installer command, and installed mosaic doctor wiring. Latest focused result: 97/97 (secure config 4, store 45, runtime 19, owner resolver 16, provision 5, provision command 3, installed doctor 5).
MC-CRED added the required canonical reverse registry seam ParsedCredentialEstateRegistry.resolveByHost(); the 32-line permissive shim was removed. After exact-head CI proved the cross-PR source dependency was absent, the provider-fetched canonical registry implementation, DTO dependencies, and registry tests were tracked byte-for-byte on this branch so a fresh checkout validates the real seam rather than a stub. A later rebase onto merged MC-CRED should recognize those identical files as upstream.
Identity gotcha measured: inline MOSAIC_GIT_IDENTITY=be-coder-07 controls credential resolution but does not override user.name/user.email inherited from the linked worktree common-dir config (coder-mos1). The first local P7 RED commit was immediately amended before push with command-scoped GIT_AUTHOR_* + GIT_COMMITTER_*; resulting author and committer both read back as be-coder-07. Every subsequent authoring command must carry both identity sets and be verified.
R6 migration reports filename- or content-secret-shaped files without copying them; arbitrary legacy content requires an approved scanner bound to the exact source snapshot, and production currently retains/reports when no approved scanner is configured. .gitignore is canonical allowlisted content only: an existing noncanonical regular file fails closed and is never merged into publication. Symlinked .gitignore, layout directories, and nested migration destinations fail closed; a dirty checkout blocks provisioning before skeleton publication. The brain root is principal-owned mode 0700 before clone and after clone, all memory-bearing layout directories are mode 0700 even under umask 0022, and doctor reports owner-accessible roots as hard unsafe findings.
Provider owner lookup uses manual redirect handling, a five-second abort signal, strict JSON content type/shape, and an incrementally enforced 256 KiB response ceiling.
Security-critical owner policy/registry reads have direct controls for principal UID ownership, file/ancestor permissions, and descriptor-safe regular-file reads.
Automatic source deletion is parked per the shared-Git-identity governance ruling; remotely reachable snapshots still leave and report every source.
Multi-host push-on-write uses an isolated temporary Git index populated from approved in-memory blobs rather than pathname re-reads, verifies each committed blob ID, the exact changed-path allowlist, and both author/committer trailers before push, then reconciles only approved paths into the real checkout index. Real-repository controls prove a clean checkout remains clean, a concurrent non-fast-forward fetch/rebase/push remains clean and preserves both findings, destination-path substitution cannot change committed bytes, and unrelated pre-staged secret-shaped content remains staged but never enters the published commit.
Doctor Git observations preserve three states: clean, dirty, and unmeasurable; failed remote, branch, or status measurements emit hard brain-git-state-indeterminate findings rather than mismatch or ready. The boolean-literal guard sweep covered all MB-BRAIN production files in the 20-file PR population: its only remaining === false guard is the non-nullable isAbsolute() predicate; no nullable boolean measurement guards remain.
Author-run Review 10 and focused 88/88 evidence were declared void when blocker fixes changed the head; neither is an independent gate pass.
Installer shell P7 invocation after C1 + MC-CRED integration; production command is registered but the C1 shell has not yet called it.
Implementation green on merged dependency base.
Independent code review.
Independent security review.
HOMELAB CI terminal green at exact head.
Reviewed PR retargeted to main after C1 and MC-CRED; next remains non-merging integration only.

Exact-head CI dependency remediation

Pipeline #2222 at a50b5a6b ran the sole pull-request-eligible workflow (ci, 1/3 defined workflows) and failed typecheck with two TS2307 errors before lint, format, or tests could execute.
History establishes that the imports are intentional: commit 2451c2f introduced both consumers, while the contemporaneous registry-seam report explicitly called the local 32-line implementation a disposable scaffold and required MC-CRED's canonical parser. This was a deliberate cross-PR dependency, not a wrong import or forgotten shim add.
RED-first root typecheck reproduced the two missing-module errors. The fix tracks the provider-fetched MC-CRED registry, its two DTO dependencies, its unit test, and the result DTO dependency. Three DTO files remain byte-identical to fbff4ffa; author review found that the canonical parser accepted a trailing-slash origin which MB-BRAIN consumers concatenate into double-slash URLs, so the parser and test are intentionally hardened here pending propagation to MC-CRED.
R7 removed the tracked registry module and root typecheck returned RED with three missing-module errors (the two production consumers plus the registry unit test); restoring the same SHA-256 returned typecheck to 45/45 tasks.
With the suppressing typecheck failure removed, lint ran 25/25 tasks and formatting passed. Full tests actually ran: 1,607/1,614 passed; the seven failures are the four pre-registered P7 integration tests intentionally held for C1/MC-CRED integration plus the three previously disclosed ambient update-banner CLI smoke failures. No test was weakened. Build ran 25/25 tasks.
Author review's trailing-slash finding was reproduced RED (https://git.example.invalid/ accepted), then fixed by requiring the configured source to equal URL.origin; the control reran GREEN. Security review reported risk none with zero findings; final code re-review remains required after remediation.
This is a second instance of the #1068 suppression class: an early integrity failure prevented every downstream stage carrying behavioral evidence from running while the workflow's aggregate failure looked like a completed check. Workflow reordering remains #1068 scope and is not changed here.

Completion language

After reviewed merge to main, only: believed-fixed, pending jarvis validation. Issue #1051 remains open until W-jarvis validates the installed result.

14 KiB Raw Blame History Unescape Escape