stack/docs/scratchpads/1264-unattended-first-start.md

#1264 — Unattended fleet first start

Tracking

• Issue: mosaicstack/stack#1264
• PR: mosaicstack/stack#1268
• Branch: fix/1264-fleet-unattended-first-start
• Base: origin/next@476db12b92971634b67fd2057b7577ee5894e449
• First pushed head: 43fa0477877e0d0f110da8d11c3033b40ddeb191
• Current remediation worktree: /var/home/jason.woltje/agent-work/1264-review2-remediation
• Coordinator: Fred; reviewer must be neither Fred nor this implementation seat.
• docs/TASKS.md is orchestrator-owned and is not modified by this worker.

The original /var/home/jason.woltje/agent-work/1264-unattended-first-start and first remediation worktrees were removed without force after each pushed head and clean state were verified. The Fred-authorized plain-Git worktree exception was reused for exact-head review remediation because /src remains unavailable.

Objective

A roster-owned fleet seat launched from systemd on a clean host must cross Mosaic's first-run identity gate without a human or TTY, while retaining exact name/class from the canonical roster and preserving the standalone interactive wizard.

Intake and boundaries

• Shipping canary provenance is jarvis-brain origin/main commit 8bf94afeb8c7d5df96cdd4a4508e75a1d2999710. The earlier local 6c0b6fc... object is not used.
• The Run-7 pane was preserved when evidence was captured; formal review records a later authorized rollback. This task never accessed or altered the canary.
• Tiny's concurrent runtime-preflight, start-agent-session.sh, and #1258 PATH seam remain untouched.
• Held PR #1213 is not a dependency.
• No runtime/provider credential values or provider calls, installed-host changes, PostgreSQL, unit, timer, or profile mutation. Tests use temporary roots and fake executables only; Gitea/Woodpecker metadata operations use standard wrappers without exposing credentials.

Requirements and design

• PRD IDs: FCM-REQ-12, AC-FCM-10; FCM-REQ-11 is reserved by #1256.
• A present fleet name must be nonblank, whitespace-exact, and resolve through the canonical roster.
• Any defined ambient class, including blank/whitespace, must canonicalize to the roster class before mutation; only undefined means absent.
• Preflight all destination directory entries with no-follow existence semantics so dangling links fail before counterpart publication.
• Seed only missing top-level files from bounded regular defaults with owner-private, atomic, no-clobber hard links.
• Generic defaults are behavior, not identity or authority.
• Securely consume fleet USER.md through a Linux descriptor at composition time.
• Standalone composition retains the portable tolerant USER read and missing identity retains the wizard.

Progress

• Issue, canary report, Tiny collision state, and PRD read/amended.
• Initial production-kind RED captured with a real built CLI and no TTY.
• Implementation, tests, user/admin/developer docs, QA, and indexes delivered.
• Initial automated review finding (padded name before write) remediated.
• Commit 43fa0477 pushed; PR #1268 opened against next; original worktree removed cleanly.
• Daphne formal review ID 168 completed on exact first head: REQUEST_CHANGES with four groups.
• All four review-168 groups reproduced red before remediation and passed at 9dc90be7.
• Daphne review ID 169 completed on 9dc90be7: review-168 closures confirmed; two new blockers.
• Review-169 portability and blank-class blockers reproduced red and now pass locally.
• Review-169 Codex review approved; security review risk none.
• Commit/push second remediation with explicit goals author/committer; verify remote object/content.
• Daphne exact-new-head re-review.
• Terminal #1268 CI. Pipeline 2445's only FAIL: was the inherited Pi-PATH CI-fit guard; PR #1270's pipeline 2448 is green, but #1270 is not merged.
• Remove the clean remediation worktree after push.

Test evidence

Initial RED

The built origin/next CLI entered mosaic wizard, rendered What would you like to do?, exited 1, and never created the fake runtime-boundary capture.

Formal-review RED

Against exact first-head production code, four new tests failed while 1,568 existing tests passed: class mismatch mutated before refusal; each dangling destination left its counterpart; and a replacement USER.md symlink was consumed by composition. Review-169 RED then proved standalone composition hit the Linux-only reader and three explicit blank/whitespace class cases seeded and launched.

Final local GREEN

• Exact-source focused gate: 6/6 files, 128/128 tests.
• Full exact-source Mosaic Vitest: 88/88 files, 1,577/1,577 tests.
• Helper + point-of-use coverage: 53/53; 97.84% statements/lines, 91.66% branches, 100% functions.
• Root preflight passed; typecheck 45/45, lint 25/25, build 25/25.
• Initial targeted shell gates passed: start-agent-session, install migration 21/21, init-RCE.
• Local aggregate framework shell stops at operator-global Pi 0.84.2 versus measured 0.84.1.
• Local root pnpm test remains unrun because the checkout prohibits its PostgreSQL-dependent path.

The full evidence and command boundaries are in docs/reports/qa/2026-08-16-1264-unattended-first-start.md.

Review / delivery notes

• Review-168 remediation Codex review: approve 0.88; security risk none 0.93.
• Review-169 remediation Codex review: approve 0.90; security risk none 0.90.
• PR envelope reads mos-dt-0; the commit reads goals/goals. No goals Gitea principal exists on this host, so no other principal will be borrowed. Tracked in #1272.
• PR #1270 is pushed, not merged. Do not represent next or #1268 CI as green until measured.