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:

```text
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.

```bash
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:

```text
[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:

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

```bash
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:

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

Final repository gates after remediation:

```text
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:

```text
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:

```text
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.