stack/docs/reports/qa/2026-08-16-1264-unattended-first-start.md

#1264 Unattended Fleet First-Start Verification

Status: IN PROGRESS — review remediation complete locally; push/re-review pending | Executor: goals | Date: 2026-08-16 | Target: isolated local fixtures only

Objective

Verify that a named fleet seat launched through a systemd-equivalent, no-TTY environment on a clean host reaches its runtime boundary without an interactive Mosaic identity wizard. Preserve standalone wizard behavior and canonical-roster ownership of exact seat identity.

Source evidence accepted for local verification

Daphne's canary Run-7 report is reachable from jarvis-brain origin/main at 8bf94afeb8c7d5df96cdd4a4508e75a1d2999710, docs/reports/2026-08-16_sbx-canary-greenfield-e2e.md. The earlier local object 6c0b6fc70ae6a179a1b7ff9dedfc54e9adccd19a is not reachable from an origin ref and is not used as shipping provenance. Run 7 measured:

systemd -> start-agent-session.sh -> mosaic yolo pi (PID 3726)
                                  -> child mosaic wizard (PID 3762)

The pane was preserved when Run 7 was captured. Formal review ID 168 records that an authorized rollback occurred later. This task never accessed or altered the canary VM, pane, snapshot, or rollback state. Product behavior is independently tested here with temporary roots and fake runtime executables.

Controls

• Original base: origin/next@476db12b92971634b67fd2057b7577ee5894e449.
• PR: #1268, first pushed head 43fa0477877e0d0f110da8d11c3033b40ddeb191.
• DATABASE_URL remains unset for local tests.
• No runtime/provider credential or token value, VM, installed Mosaic tree, unit, timer, PATH profile, or live tmux session is read or mutated. Standard Gitea/Woodpecker wrappers authenticate metadata reads/writes without exposing credential values.
• Tiny's runtime-preflight and start-agent-session.sh PATH work remain out of scope.
• Held PR #1213 is not a dependency.

Requirements-to-evidence map

Acceptance criterion	Method	Evidence
No-TTY fleet first start avoids wizard and reaches runtime	Exact-source built CLI with piped stdin	CLI GREEN
Missing top-level identity files are initialized from shipped defaults	Exact-byte and 0600 assertions	CLI + filesystem GREEN
Exact seat identity remains roster-owned	Captured argv; name/class mismatch no-side-effect refusals	CLI GREEN
Existing operator identity is never overwritten	Custom bytes/mode with defaults removed	CLI + filesystem GREEN
Concurrent/repeated first start is safe	Four parallel CLIs plus repeated launch	CLI GREEN
Missing/unsafe defaults and destinations fail before partial mutation	Missing, target/dangling symlink, oversized, invalid-root cases	Filesystem/CLI GREEN
Validated USER.md cannot be replaced by an external symlink	Seed, replace, compose at point of use	Composition GREEN
Standalone launch retains wizard	Same built CLI without fleet identity	CLI GREEN
Built-CLI evidence cannot use stale ignored dist/	Build-with-dependencies gate before Vitest	Package script + command gate

Initial RED

Production source remained unchanged after adding the first reproducer. The CLI was built from origin/next@476db12 before the test.

env -u DATABASE_URL pnpm --filter @mosaicstack/mosaic exec vitest run \
  src/commands/launch-first-start.spec.ts

Exit 1; one file and one test failed. Output included:

[mosaic] SOUL.md not found. Running setup wizard...
◆  What would you like to do?
[mosaic] Setup failed. Run: mosaic wizard
AssertionError: expected 1 to be +0

The fake runtime-boundary capture was not created. Complete stdout/stderr was retained at /tmp/1264-red.out during that work session.

Formal-review remediation RED

Daphne's exact-head review ID 168 requested changes at 43fa0477. Before changing production code, new regressions were run against an exact-source build. Four tests failed while the existing 1,568 passed:

1. valid roster name plus mismatched ambient class seeded both files before refusal;
2. dangling SOUL.md allowed USER.md to be published before refusal;
3. dangling USER.md allowed SOUL.md to be published before refusal; and
4. replacing a securely validated USER.md with an external symlink was followed by composition.

This establishes that all four reviewer findings were observable on the pushed implementation.

Final GREEN

The production-kind command builds Mosaic and all workspace dependencies before invoking Vitest, because dist/ is ignored and may otherwise be absent or stale:

env -u DATABASE_URL sh -c '
  pnpm --filter @mosaicstack/mosaic... build &&
  pnpm --filter @mosaicstack/mosaic exec vitest run \
    src/commands/fleet-first-start-identity.spec.ts \
    src/commands/launch-first-start.spec.ts \
    src/commands/launch.spec.ts \
    src/commands/compose-contract.spec.ts \
    src/config/file-adapter.test.ts \
    src/cli-smoke.spec.ts
'

Exit 0: 6/6 files, 124/124 tests.

• 12 real-CLI/no-TTY tests cover exact roster name/class, byte-equal 0600 seeds, no-clobber, partial seed, missing/symlink defaults, unknown/padded/blank name, mismatched class, standalone wizard preservation, and four concurrent starts.
• 12 direct filesystem tests cover complete publication, existing operators, idempotence, source prevalidation, target and dangling destination links, invalid roots, oversized input, and unexpected link errors.
• Composition coverage deterministically replaces validated USER.md with an external symlink and requires refusal at point of use.

Full package gate (which rebuilds Mosaic itself after the clean-checkout dependency build):

env -u DATABASE_URL pnpm --filter @mosaicstack/mosaic run test:vitest

Exit 0: 88/88 files, 1,573/1,573 tests.

Focused helper + point-of-use coverage:

2 files, 52/52 tests
Statements 97.97% | Branches 88% | Functions 100% | Lines 97.97%
Exit 0

Final repository gates after remediation:

pnpm preflight    exit 0
pnpm typecheck    45/45 tasks, exit 0
pnpm lint         25/25 tasks, exit 0
pnpm build        25/25 tasks, exit 0
pnpm format:check exit 0
git diff --check  exit 0

Pre-PR targeted shell runs on the unchanged shell surfaces also passed:

bash framework/tools/fleet/test-start-agent-session.sh                 exit 0 locally
bash framework/tools/quality/scripts/test-install-migration.sh         21 passed, 0 failed
bash framework/tools/_scripts/test-mosaic-init-rce.sh                   PASS

The aggregate local test:framework-shell run stopped at invariant_r_unittest.py: installed operator-global Pi is 0.84.2, while the invariant is measured for 0.84.1. Later aggregate stages remain unmeasured except the targeted suites above. Root pnpm test remains locally UNTESTED because this checkout prohibits the PostgreSQL-dependent gateway isolation path.

Review and security evidence

• Initial Codex review found padded-name mutation-before-refusal; it was fixed with three no-side-effect regressions.
• Codex review of the formal-review remediation: approve, confidence 0.88, 6 files, no findings.
• Codex security review of the remediation: risk none, confidence 0.93, 9 files, no findings. Its sandbox could not execute Vitest because Vite attempted a write on a read-only mount; the executor-owned results above are the test evidence.
• Daphne formal review ID 168 at exact head 43fa0477: REQUEST_CHANGES, four blocking groups. All four have red-first regressions and local green remediation. Re-review of the next pushed exact head is necessarily pending until that head exists.

CI evidence and external blocker

Pipeline 2445 ran against exact first head 43fa0477:

• install, sanitization, upgrade guard, typecheck, lint, and format passed;
• Mosaic Vitest passed 88/88, 1,568/1,568; and
• the test step emitted exactly one FAIL: line:

FAIL: host provides 'pi' in the system path; missing-binary cases are not measurable here

That line comes from the inherited test-start-agent-session.sh CI-fit guard, not #1264. Fred filed the correction as PR #1270. Its pipeline 2448 is terminal green and proves the four formerly masked suites execute, but #1270 is not merged, so next still carries the failing chain. A new #1268 pipeline is pending the remediation push. Terminal-green #1268 CI is not claimed.

PR #1268's envelope was read back as user.login=mos-dt-0; its commit is explicitly authored and committed by goals <[email protected]>. No goals Gitea login exists on this host, and no other principal was borrowed. The cross-wrapper principal defect is tracked in #1272.

Explicitly untested

• Canary VM remediation/restart: UNTESTED and prohibited.
• Real Pi authentication/provider prompt and task execution: UNTESTED.
• PR #1213 composition layer: UNTESTED and not required.
• Deployment/published npm behavior: UNTESTED until merge/release.
• Local PostgreSQL execution/migration: UNTESTED and prohibited.

The local gate proves Mosaic crosses its identity boundary and reaches a fake lease-runtime boundary; it does not claim provider readiness, deployment, or a currently running canary seat.