fix(#1264): bootstrap fleet identity without a TTY

2026-08-16 17:37:32 -05:00
parent 476db12b92
commit 43fa047787
21 changed files with 1255 additions and 11 deletions
@@ -5,6 +5,7 @@
 ## Current procedures

 - [Upgrade safety and recovery](upgrade-safety-and-recovery.md) — installed-CLI and local-PGlite upgrade, rollback, and framework-configuration recovery.
+- [Fleet unattended first start](fleet-unattended-first-start.md) — systemd/no-TTY identity initialization, failure handling, and isolated verification.

 ## Held procedures

@@ -0,0 +1,64 @@
+# Fleet Unattended First-Start Operations
+
+> **Status:** Current after issue #1264 lands. This runbook covers only Mosaic's first-run identity
+> gate; it does not install runtimes or credentials.
+
+## Operational contract
+
+A systemd fleet unit launches under a sanitized environment with no TTY. The generated environment
+sets `MOSAIC_AGENT_NAME`; Mosaic resolves that exact value against the canonical installed roster
+before writing identity files.
+
+If top-level identity contracts are missing, Mosaic atomically seeds them from the shipped generic
+sources:
+
+| Destination            | Source                          | New-file mode |
+| ---------------------- | ------------------------------- | ------------- |
+| `$MOSAIC_HOME/SOUL.md` | `$MOSAIC_HOME/defaults/SOUL.md` | `0600`        |
+| `$MOSAIC_HOME/USER.md` | `$MOSAIC_HOME/defaults/USER.md` | `0600`        |
+
+Creation is no-clobber and safe under concurrent seat starts. Existing regular files remain
+byte-for-byte and mode-for-mode unchanged. The runtime composer then injects the exact roster name
+and class; the generic source files grant no seat authority.
+
+## Failure handling
+
+The fleet path never falls back to an interactive wizard. It exits nonzero before runtime execution
+when:
+
+- `MOSAIC_AGENT_NAME` is not an exact roster member;
+- a missing destination has no safe regular default source;
+- a source or existing destination is a symlink, directory, unavailable, or over the bounded size;
+- the fleet communications helper/roster cannot be validated.
+
+Diagnostics begin with:
+
+```text
+[mosaic] ERROR: unattended fleet identity initialization failed: ...
+```
+
+Repair the exact named source, destination, roster, or helper and retry only that roster member. Do
+not delete or replace an existing personalized `SOUL.md`/`USER.md` merely to clear the check.
+
+## Verification without a live seat
+
+The source gate is:
+
+```bash
+pnpm --filter @mosaicstack/mosaic exec vitest run \
+  src/commands/launch-first-start.spec.ts
+```
+
+It runs the real built CLI in subprocesses with piped stdin, temporary homes, a canonical fixture
+roster, fake runtime/broker executables, and no provider call. It covers no-TTY launch, exact identity,
+private modes, no-clobber, missing/symlink defaults, unknown members, standalone wizard preservation,
+and concurrent first start.
+
+Do not use this fixture as proof that a real provider credential is present or that a package has
+been deployed. Those require separate environment-specific evidence.
+
+## Related
+
+- [User workflow](../../USER-GUIDE/workflows/fleet-unattended-first-start.md)
+- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
+- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)