fix(installer): propagate wizard gateway failures (#1120)

docs/scratchpads/webui-fleet-bridge-plan.md

@@ -1,114 +0,0 @@
-# WebUI Fleet Bridge Planning Scratchpad
-
-**Mode:** Task 0 docs-only decision PR authorized; Task 1 and all executable/runtime work remain blocked.
-**Owner:** Velma
-**Opened:** 2026-08-09
-**Scope:** One enrolled Agent Host launching one native `mosaic claude` OAuth session and streaming it into `apps/web` through `apps/gateway`.
-
-## Objective
-
-Turn the approved direction in `jarvis-brain/docs/scratchpads/MOSAIC-WEBUI-FLEET-BRIDGE.md` into a test-first implementation plan while preserving Fred's harness-home/launcher contract and Scooby's greenfield safety findings.
-
-## Source reconciliation
-
-- Current `origin/main`: `b0f7d26dd9c14d91eaaefc35d6c9fd6618a0bd92`.
-- Current `origin/next`: `4df478cdd150fdf8d52ea109f02ade5d85017acd`.
-- Branches currently diverge (`main` has 11 unique commits; `next` has 13). `next` contains local-tier Redis fix #689; `main` contains later fleet/shell fixes.
-- Fred's three-root harness-home design and promotion stack are not yet fully present on either baseline.
-- Therefore neither current SHA is an acceptable implementation pin. Code may begin only from a Fred-certified reconciled SHA containing the required launcher/home contract and safe Gateway startup prerequisites.
-- The deployed `mosaic.woltje.com` v0.0.20 UI remains reference-only.
-
-## Verified seams
-
-- Current browser chat uses an in-process Pi SDK session.
-- `AgentRuntimeProvider` supports list/tree/stream/send/attach/detach/terminate, but not create/start.
-- `InteractionController` enrolls an already-existing runtime session; it cannot launch one.
-- Hermes is the only runtime provider registered in Gateway.
-- Tmux streaming is explicitly unsupported and remains out of scope.
-- `mosaic claude` is the authoritative launcher and accepts Claude's machine-facing stream-json flags.
-- Installed discovery version: Claude Code 2.1.226. Target Distrobox version must be independently pinned and certified.
-
-## Non-negotiable dependencies
-
-1. Fred approves the machine-facing launcher/seat-home contract before code.
-2. No WebUI/Gateway direct read of lease broker state, daemon socket, or state files (F-V3).
-3. No provider OAuth token leaves the Agent Host.
-4. No local Gateway/Web startup around the KBN/database hold.
-5. Greenfield work runs in a Debian Distrobox with an isolated home.
-6. The initial plan PR targets `next`; Fred binds D1–D15 on its exact head before issue/PRD/tracker completion or implementation work.
-
-## Reproducible evidence
-
-Run from a clean Stack clone:
-
-```bash
-git fetch origin main next
-git rev-parse origin/main origin/next
-git rev-list --left-right --count origin/main...origin/next
-rg -n "interface AgentRuntimeProvider|createSession|streamEvents|terminate" \
-  packages/types/src/agent packages/agent/src apps/gateway/src/agent
-rg -n "AgentService\.prompt|interaction_sessions|createRuntimeTerminationApproval" \
-  apps/gateway/src packages/db/src/schema.ts
-```
-
-Primary inspected source seams:
-
-- `packages/types/src/agent/agent-runtime-provider.ts`
-- `packages/agent/src/{runtime-provider-registry,hermes-runtime-provider,matrix-native-runtime-provider,tmux-fleet-runtime-provider}.ts`
-- `apps/gateway/src/agent/{runtime-provider-registry.service,interaction.controller,durable-session.repository,durable-session.service}.ts`
-- `apps/gateway/src/chat/chat.gateway.ts`
-- `packages/mosaic/src/commands/{launch,interaction}.ts`
-- `packages/mosaic/src/fleet/generated-env-boundary.ts`
-- `packages/db/src/schema.ts`
-- `apps/web/src/app/(dashboard)/chat/page.tsx`
-
-Planning-only investigation transcripts are local and intentionally uncommitted:
-
-- `/tmp/velma-plan-stack-surface.txt`
-- `/tmp/velma-plan-structure.txt`
-- `/tmp/velma-plan-scooby.txt`
-- `/tmp/velma-plan-runtime-contract.txt`
-
-## Source findings that constrain the design
-
-- `interaction_sessions.id` is the stable primary key; there are no create/policy/enrollment/state columns.
-- `interaction_outbox` has a unique `(session_id, idempotency_key)` index and only `pending | processing | delivered`.
-- Baseline `DurableSessionRepository.create()` can replace provider/runtime identity for the same owner; M1 must remove that implicit mutation.
-- Baseline termination approval is Redis-backed and currently consumes separately from PostgreSQL; M1 therefore needs durable authorization acceptance before destructive token deletion/dispatch.
-- Existing interaction HTTP base is `/api/interaction/:agentName`; the plan extends it rather than inventing a second route family.
-- Baseline `launch.ts`/lease launcher still use ambient lookup/literal interpreters. Section 4.1 is non-binding consumer input to Fred's W-F design; W-F's final resolved-launch contract must exist in the certified base before Velma can certify it.
-- Root `pnpm test` is not KBN-safe: it includes PGlite migration and framework-shell/lease-broker suites.
-
-## Independent draft review
-
-Seven adversarial review rounds found and drove explicit fixes for:
-
-- a candidate resolved-seat consumer descriptor and threat model, now explicitly non-binding input to Fred's W-F-owned launcher design;
-- one active launch per stable conversation, exact pending/failed encodings, durable pre-dispatch reservation, CAS activation, and crash lookup without a migration;
-- generation-bound enrollment, command/event revalidation, `SIGHUP` config epochs, and stale-epoch rejection;
-- Redis/PostgreSQL exact-stop crash safety via non-destructive verify, durable authorization acceptance, atomic claim/`GETDEL`, and same-operation status reconciliation;
-- sequence gaps/reorder limits, deterministic UUIDv5 completion, and Gateway restart fail-closed behavior;
-- shared streaming redaction before host ring/transport and again before Gateway persistence/browser;
-- D2/D12-selected path-free provenance and a separate safe browser DTO—never raw or hashed path strings;
-- exact F-V3 boundary: bridge has no broker API, while Fred's sealed launcher may enforce broker policy internally;
-- migration-free focused tests in Tasks 1–8, with live OAuth, repository transaction, Gateway/Web, and Playwright restricted to the Fred/Scooby-certified Task 9 path;
-- candidate private/public commitment and artifact-binding mechanisms that W-F may accept, simplify, replace, or defer;
-- JCS event-digest recomputation and equal/different duplicate handling in both accepted and future-buffer states;
-- a safe browser presentation DTO for host/workspace/seat/persona labels, readiness, and connection state;
-- explicit `OnApplicationBootstrap` create/stop recovery enumeration with no auto-launch;
-- all POSIX/Windows/UNC/file/tilde path classes in the streaming redactor and definitive failed-stop response semantics;
-- the full 14-column canonical task schema, fake-only Task 5 repository tests, migration-free certified Task 9 DB test, server-owned operation correlations/routes, and exact merged-SHA smoke;
-- per-commit independent review, queue guards, exact-head PR review, squash merge, exact merged-next SHA/CI wait, worktree-bound smoke, issue-state readback, and reviewed tracker-closure PR with its own merged-next CI;
-- a private DB URL loader captured/exported per session without recording or echoing the credential;
-- an attached Task 9 implementation branch, provider-filtered exact issue-state readback, and machine-verified smoke JSON binding source/worktree/deployed SHA;
-- a capped, duplicate-key-rejecting, exact-key/type smoke schema so report extensions or JSON boolean/float coercion cannot smuggle data or fake child-count evidence.
-
-The plan remains deliberately **decision-PR-ready, not implementation-ready**. Fred authorized only Task 0's initial two-document PR on `next`. He must still return every Section 2 value, replace all `[FRED-GATE]` entries, certify storage/startup, and provide the W-F-dependent `IMPLEMENTATION_BASE_SHA` before Task 0 closes or Task 1 starts.
-
-## Current status
-
-- Gitea principal verified as `velma`; helper and API wrapper resolution are fail-closed and correct.
-- Fred authorized the initial Task 0 docs-only PR in `comms/20260809T094952Z__from-fred__ec0e85.md` and confirmed its `next` lane/W-F descriptor corrections in `comms/20260809T095437Z__from-fred__4ee79d.md`.
-- Provisional decisions: D1/D8/D9/D10/D13/D14 approved; D4 tool labels exactly `{Read, Grep, Glob}`; D5/D12 provisional; D11 remains a single-operator seam; D2/D3/D6/D7 and `IMPLEMENTATION_BASE_SHA` are `BLOCKED-ON-W-F`.
-- Awaiting exact plan-PR-head review and Fred's complete D1–D15 binding contract.
-- No source code, database, deployment, or live runtime changes made.

packages/mosaic/__tests__/integration/unified-wizard.test.ts

@@ -193,16 +193,19 @@ describe('Unified wizard (runWizard with default skipGateway)', () => {
       'Your timezone': 'UTC',
     });
 
-    await runWizard({
+    await expect(
-      mosaicHome: tmpDir,
+      runWizard({
-      sourceDir: tmpDir,
+        mosaicHome: tmpDir,
-      prompter,
+        sourceDir: tmpDir,
-      configService: createConfigService(tmpDir, tmpDir),
+        prompter,
-      skipGatewayNpmInstall: true,
+        configService: createConfigService(tmpDir, tmpDir),
-    });
+        skipGatewayNpmInstall: true,
+      }),
+    ).rejects.toThrow('Gateway configuration failed');
 
     const logs = prompter.getLogs();
     expect(logs.some((line) => line.includes('Gateway did not become healthy'))).toBe(true);
+    expect(logs.some((line) => line.includes('Gateway configuration failed'))).toBe(true);
     expect(logs.some((line) => line.includes('Installation Summary'))).toBe(false);
     expect(logs.some((line) => line.includes('Mosaic is ready.'))).toBe(false);
     expect(gatewayConfigMock).toHaveBeenCalledTimes(1);

packages/mosaic/src/stages/quick-start.ts

@@ -68,8 +68,6 @@ export async function quickStartPath(
 
   // Gateway config + bootstrap
   if (!options.skipGateway) {
-    const headlessRun = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
-
     try {
       const configResult = await gatewayConfigStage(prompter, state, {
         host: options.gatewayHost ?? 'localhost',
@@ -81,11 +79,9 @@ export async function quickStartPath(
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
-        if (headlessRun) {
+        const message = 'Gateway configuration failed — aborting wizard.';
-          prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
+        prompter.warn(message);
-          process.exit(1);
+        throw new Error(message);
-        }
-        return;
       }
 
       const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
@@ -93,9 +89,9 @@ export async function quickStartPath(
         port: configResult.port,
       });
       if (!bootstrapResult.completed) {
-        prompter.warn('Admin bootstrap failed — aborting wizard.');
+        const message = 'Admin bootstrap failed — aborting wizard.';
-        process.exit(1);
+        prompter.warn(message);
-        return;
+        throw new Error(message);
       }
       finalizeResult.showSummary();
     } catch (err) {

packages/mosaic/src/wizard.ts

@@ -348,18 +348,21 @@ async function runFinishPath(
         providerType: state.providerType,
       });
 
-      if (configResult.ready && configResult.host && configResult.port) {
+      if (!configResult.ready || !configResult.host || !configResult.port) {
-        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+        const message = 'Gateway configuration failed — aborting wizard.';
-          host: configResult.host,
+        prompter.warn(message);
-          port: configResult.port,
+        throw new Error(message);
-        });
-        if (!bootstrapResult.completed) {
-          prompter.warn('Admin bootstrap failed — aborting wizard.');
-          process.exit(1);
-          return;
-        }
-        finalizeResult.showSummary();
       }
+      const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+        host: configResult.host,
+        port: configResult.port,
+      });
+      if (!bootstrapResult.completed) {
+        const message = 'Admin bootstrap failed — aborting wizard.';
+        prompter.warn(message);
+        throw new Error(message);
+      }
+      finalizeResult.showSummary();
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;
@@ -420,9 +423,9 @@ async function runHeadlessPath(
       });
 
       if (!configResult.ready || !configResult.host || !configResult.port) {
-        prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
+        const message = 'Gateway configuration failed in headless mode — aborting wizard.';
-        process.exit(1);
+        prompter.warn(message);
-        return;
+        throw new Error(message);
       }
 
       const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
@@ -430,9 +433,9 @@ async function runHeadlessPath(
         port: configResult.port,
       });
       if (!bootstrapResult.completed) {
-        prompter.warn('Admin bootstrap failed — aborting wizard.');
+        const message = 'Admin bootstrap failed — aborting wizard.';
-        process.exit(1);
+        prompter.warn(message);
-        return;
+        throw new Error(message);
       }
       finalizeResult.showSummary();
     } catch (err) {
@@ -477,18 +480,21 @@ async function runKeepPath(
         skipInstall: options.skipGatewayNpmInstall,
       });
 
-      if (configResult.ready && configResult.host && configResult.port) {
+      if (!configResult.ready || !configResult.host || !configResult.port) {
-        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+        const message = 'Gateway configuration failed — aborting wizard.';
-          host: configResult.host,
+        prompter.warn(message);
-          port: configResult.port,
+        throw new Error(message);
-        });
-        if (!bootstrapResult.completed) {
-          prompter.warn('Admin bootstrap failed — aborting wizard.');
-          process.exit(1);
-          return;
-        }
-        finalizeResult.showSummary();
       }
+      const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
+        host: configResult.host,
+        port: configResult.port,
+      });
+      if (!bootstrapResult.completed) {
+        const message = 'Admin bootstrap failed — aborting wizard.';
+        prompter.warn(message);
+        throw new Error(message);
+      }
+      finalizeResult.showSummary();
     } catch (err) {
       prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
       throw err;

tools/install.sh

@@ -762,9 +762,12 @@ if [[ "$FLAG_CHECK" == "false" ]]; then
         if "$MOSAIC_CMD" wizard; then
           ok "Wizard complete."
         else
-          warn "Wizard exited non-zero."
+          fail "Wizard failed; installation is incomplete."
+          echo "  Completed: framework and CLI installation"
+          echo "  Failed: gateway configuration or admin bootstrap"
           echo "  You can retry with: ${C}mosaic wizard${RESET}"
           echo "  Or run gateway install alone: ${C}mosaic gateway install${RESET}"
+          exit 1
         fi
       fi
     else