@openparachute/hub 0.7.7-rc.15 → 0.7.7-rc.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.7-rc.15",
+  "version": "0.7.7-rc.17",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
@@ -34,7 +34,6 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@openparachute/door-contract": "workspace:*",
     "@types/bun": "latest",
     "@types/qrcode": "^1.5.6"
   },
@@ -44,6 +43,7 @@
   "dependencies": {
     "@node-rs/argon2": "^2.0.2",
     "@openparachute/depcheck": "0.1.1",
+    "@openparachute/door-contract": "^0.6.0",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode": "^1.5.4"

package/src/__tests__/setup-wizard.test.ts

@@ -219,6 +219,80 @@ describe("deriveWizardState", () => {
     }
   });
 
+  test("real-version vault row with paths:[] is NOT a real vault (e2e boot-spawned-child fix)", async () => {
+    // The Tier-1 e2e wizard-skip root cause. When the hub boot-spawns the vault
+    // MODULE child, vault's selfRegister writes its services.json row at the
+    // REAL package version (e.g. 0.7.4-rc.1, NOT SEED_VERSION) but with
+    // `paths: []` because no vault instance exists yet. The SEED_VERSION
+    // sentinel alone did NOT catch this — a bare `version !== SEED_VERSION`
+    // check read the empty-paths row as a real vault, so the wizard skipped its
+    // vault step and `--vault-name` was ignored. hasRealVault must be
+    // INSTANCE-aware: no mount path → not a real vault (the #478 empty-paths
+    // discrimination findExistingVault already uses).
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.7.4-rc.1",
+              port: 1940,
+              paths: [],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.hasRealVault).toBe(false);
+      expect(s.hasVault).toBe(false);
+      expect(s.step).toBe("vault");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("real-version vault row WITH a mount path IS a real vault (positive control)", async () => {
+    // The counterpart to the empty-paths case: a genuinely-created vault carries
+    // a `/vault/<name>` path at a real version, so hasRealVault must be true and
+    // the wizard advances past the vault step.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      await createUser(db, "owner", "pw");
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.7.4-rc.1",
+              port: 1940,
+              paths: ["/vault/e2e"],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const s = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(s.hasRealVault).toBe(true);
+      expect(s.hasVault).toBe(true);
+      expect(s.step).toBe("expose");
+    } finally {
+      db.close();
+    }
+  });
+
   test("expose step when admin + vault exist but expose mode not set yet (hub#268 Item 2)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
@@ -1712,13 +1786,15 @@ describe("handleSetupVaultPost", () => {
     }
   });
 
-  test("idempotent — second POST while supervisor is running doesn't fire a second `bun add` (N2)", async () => {
+  test("second POST while supervisor is running but vault UNREGISTERED — synthesize success, no 2nd bun add, no double provision (N2 race)", async () => {
     // Reviewer-flagged race: two concurrent POSTs before either seeds
-    // services.json both pass `state.hasVault === false` and each fire
-    // `runInstall` → each fires `bun add -g`. The wizard mirrors the
-    // `handleInstall` guard pattern: if the supervisor already has a
-    // live (starting/running/restarting) state for vault, mark the new
-    // op succeeded synchronously and skip the second install.
+    // services.json both pass `state.hasVault === false`. The supervisor is
+    // already running vault (a prior POST's runInstall spawned it) but the
+    // services.json row hasn't been written yet — so `vaultAlreadyRegistered`
+    // is false. The wizard must NOT fire a second `bun add -g` AND must NOT
+    // fire `provisionVault` (which would `parachute install vault` a second
+    // time in this pre-seed window — reviewer N2). Instead it synthesizes a
+    // succeeded op and lets the in-flight install create the vault.
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -1734,8 +1810,9 @@ describe("handleSetupVaultPost", () => {
       });
       const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
       // Real supervisor with the never-exits spawn stub from makeSupervisor.
-      // Pre-spawn vault so `supervisor.get("vault").status === "starting"`
-      // by the time the wizard's POST runs.
+      // Pre-spawn vault so `supervisor.get("vault").status === "starting"`.
+      // The harness manifest is EMPTY (vault not registered) — the pre-seed
+      // window.
       const supervisor = makeSupervisor();
       await supervisor.start({ short: "vault", cmd: ["bun", "noop"] });
       const runCalls: string[][] = [];
@@ -1743,6 +1820,17 @@ describe("handleSetupVaultPost", () => {
         runCalls.push([...cmd]);
         return 0;
       };
+      // provisionVault must NOT be called in the unregistered race window.
+      const provisionCalls: string[] = [];
+      const provisionVaultImpl = async (name: string) => {
+        provisionCalls.push(name);
+        return {
+          ok: true as const,
+          created: true,
+          entry: { name, url: `https://hub.example/vault/${name}`, version: "1.0.0" },
+          createJson: null,
+        };
+      };
       const post = await handleSetupVaultPost(
         req("/admin/setup/vault", {
           method: "POST",
@@ -1763,17 +1851,17 @@ describe("handleSetupVaultPost", () => {
           supervisor,
           registry: getDefaultOperationsRegistry(),
           run: stubbedRun,
+          provisionVaultImpl,
         },
       );
       expect(post.status).toBe(303);
       const location = post.headers.get("location") ?? "";
       expect(location).toMatch(/^\/admin\/setup\?op=/);
-      // Yield enough for any background runInstall promise to fire if
-      // the guard failed. Then assert: no `bun add` was invoked, and
-      // the op went straight to `succeeded` with the canonical
-      // "already supervised" log line.
+      // Yield for any background promise. Then assert: no `bun add`, NO
+      // provisionVault call (no double-install), op synthesized succeeded.
       await new Promise((r) => setTimeout(r, 50));
       expect(runCalls.length).toBe(0);
+      expect(provisionCalls).toEqual([]);
       const opId = new URL(location, "http://x").searchParams.get("op") ?? "";
       const op = getDefaultOperationsRegistry().get(opId);
       expect(op?.status).toBe("succeeded");
@@ -1783,6 +1871,200 @@ describe("handleSetupVaultPost", () => {
     }
   });
 
+  test("boot-spawned vault child (real version, paths:[]) — wizard create actually provisions the named vault (e2e wizard-skip fix)", async () => {
+    // The exact Tier-1 e2e bug. The hub boot-spawns the vault MODULE child so it
+    // can selfRegister; that child writes a services.json row at the REAL
+    // package version (NOT SEED_VERSION) with `paths: []` because no vault
+    // instance exists yet, AND the supervisor already reports vault "running".
+    // Pre-fix: hasRealVault read the real-version row as a real vault, the
+    // wizard skipped its vault step, and even if it POSTed, the already-
+    // supervised short-circuit synthesized a succeeded op that created NOTHING
+    // — `--vault-name e2e` was silently dropped. Post-fix: the empty-paths row
+    // reads as no-real-vault (hasRealVault=false), the POST is honored, and the
+    // short-circuit drives provisionVault to actually create the named vault.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const { createSession, SESSION_COOKIE_NAME: SC } = await import("../sessions.ts");
+      const session = createSession(db, { userId: user.id });
+      // Boot-spawned child's self-registered row: real version, paths: [].
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.7.4-rc.1",
+              port: 1940,
+              paths: [],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // deriveWizardState must NOT treat the empty-paths real-version row as a
+      // real vault (this is what un-skipped the wizard's vault step).
+      const derived = deriveWizardState({
+        db,
+        manifestPath: h.manifestPath,
+        readExposeStateFn: h.readExposeStateFn,
+      });
+      expect(derived.hasRealVault).toBe(false);
+      expect(derived.step).toBe("vault");
+
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      // Supervisor already running the boot-spawned vault module child.
+      const supervisor = makeSupervisor();
+      await supervisor.start({ short: "vault", cmd: ["bun", "noop"] });
+      const runCalls: string[][] = [];
+      const provisionCalls: string[] = [];
+      const provisionVaultImpl = async (name: string) => {
+        provisionCalls.push(name);
+        return {
+          ok: true as const,
+          created: true,
+          entry: { name, url: `https://hub.example/vault/${name}`, version: "0.7.4-rc.1" },
+          createJson: null,
+        };
+      };
+      const post = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          body: new URLSearchParams({
+            [CSRF_FIELD_NAME]: csrf,
+            mode: "create",
+            vault_name: "e2e",
+          }).toString(),
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE_NAME}=${csrf}; ${SC}=${session.id}`,
+          },
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
+          issuer: "https://hub.example",
+          supervisor,
+          registry: getDefaultOperationsRegistry(),
+          run: async (cmd) => {
+            runCalls.push([...cmd]);
+            return 0;
+          },
+          provisionVaultImpl,
+        },
+      );
+      expect(post.status).toBe(303);
+      const location = post.headers.get("location") ?? "";
+      expect(location).toMatch(/^\/admin\/setup\?op=/);
+      await new Promise((r) => setTimeout(r, 50));
+      // The named vault WAS provisioned (not silently dropped) …
+      expect(provisionCalls).toEqual(["e2e"]);
+      // … and no `bun add -g` fired (module already supervised).
+      expect(runCalls.some((c) => c.join(" ").includes("bun add -g"))).toBe(false);
+      const opId = new URL(location, "http://x").searchParams.get("op") ?? "";
+      const op = getDefaultOperationsRegistry().get(opId);
+      expect(op?.status).toBe("succeeded");
+      expect(op?.log.join("\n")).toContain('vault "e2e" created');
+    } finally {
+      db.close();
+    }
+  });
+
+  test("import mode on an already-supervised box is REJECTED (no empty vault + fake success) — review must-fix", async () => {
+    // On a boot-spawned box (vault module already supervised), the short-circuit
+    // create path provisions an EMPTY vault. An IMPORT request must NOT be run
+    // through it: that would leave an empty vault named after the import target
+    // + a false "vault created" banner (a data-integrity footgun). The wizard
+    // rejects import with an actionable message + a FAILED op instead.
+    const db = openHubDb(hubDbPath(h.dir));
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const { createSession, SESSION_COOKIE_NAME: SC } = await import("../sessions.ts");
+      const session = createSession(db, { userId: user.id });
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              version: "0.7.4-rc.1",
+              port: 1940,
+              paths: [],
+              health: "/health",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const get = handleSetupGet(req("/admin/setup"), {
+        db,
+        manifestPath: h.manifestPath,
+        configDir: h.dir,
+        readExposeStateFn: h.readExposeStateFn,
+        issuer: "https://hub.example",
+        registry: getDefaultOperationsRegistry(),
+      });
+      const csrf = setCookie(get, CSRF_COOKIE_NAME) ?? "";
+      const supervisor = makeSupervisor();
+      await supervisor.start({ short: "vault", cmd: ["bun", "noop"] });
+      const provisionCalls: string[] = [];
+      const post = await handleSetupVaultPost(
+        req("/admin/setup/vault", {
+          method: "POST",
+          headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            cookie: `${CSRF_COOKIE_NAME}=${csrf}; ${SC}=${session.id}`,
+          },
+          body: JSON.stringify({
+            [CSRF_FIELD_NAME]: csrf,
+            mode: "import",
+            vault_name: "fromgit",
+            remote_url: "https://example.com/repo.git",
+            import_mode: "merge",
+          }),
+        }),
+        {
+          db,
+          manifestPath: h.manifestPath,
+          configDir: h.dir,
+          readExposeStateFn: h.readExposeStateFn,
+          issuer: "https://hub.example",
+          supervisor,
+          registry: getDefaultOperationsRegistry(),
+          provisionVaultImpl: async (name: string) => {
+            provisionCalls.push(name);
+            return {
+              ok: true as const,
+              created: true,
+              entry: { name, url: `https://hub.example/vault/${name}`, version: "0.7.4-rc.1" },
+              createJson: null,
+            };
+          },
+        },
+      );
+      expect(post.status).toBe(200);
+      const body = (await post.json()) as { op_id?: string; message?: string };
+      expect(body.message ?? "").toContain("isn't supported");
+      // Import was NOT provisioned (no empty vault created).
+      expect(provisionCalls).toEqual([]);
+      // The op is FAILED, not a fake success.
+      const op = body.op_id ? getDefaultOperationsRegistry().get(body.op_id) : undefined;
+      expect(op?.status).toBe("failed");
+    } finally {
+      db.close();
+    }
+  });
+
   test("create on a SEED-placeholder box: does NOT short-circuit + drives the supervisor to start vault (hub#607 + hub#608)", async () => {
     // hub#607 + hub#608 coupled fresh-operator flow. On an init'd box,
     // services.json already carries a `parachute-vault` placeholder at

package/src/__tests__/wizard-transcription.test.ts

@@ -82,6 +82,41 @@ describe("walkTranscriptionStep — mode resolution (the CLI question)", () => {
     }
   });
 
+  test("non-interactive stdin (no flag) DEFAULTS to none — never hangs on the prompt", async () => {
+    // Headless-hardening: with no `--transcribe-mode` flag AND a closed / non-
+    // interactive stdin, an interactive `prompt("Pick [1]:")` would busy-hang
+    // Bun's readline question() forever (the exact e2e wedge). Transcription is
+    // optional and documented as never-blocking, so resolveChoice DEFAULTS to
+    // "none" (with an honest log line) rather than throwing. We drive the real
+    // defaultPrompt (no `prompt` seam) and force isTTY=false for determinism;
+    // if the guard regressed, this test would HANG instead of passing.
+    const h = makeHarness();
+    const origIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+    try {
+      const r = recordingRunner();
+      const logs: string[] = [];
+      const code = await walkTranscriptionStep({
+        configDir: h.dir,
+        log: (l) => logs.push(l),
+        // no transcribeMode, no prompt seam → real defaultPrompt would be hit
+        runCommand: r.run,
+        platform: "linux",
+      });
+      expect(code).toBe(0);
+      expect(r.cmds).toEqual([]); // nothing installed
+      expect(readCfg(h.dir)).toBeUndefined(); // no provider recorded
+      expect(logs.join("\n")).toContain("not interactive");
+      expect(logs.join("\n")).toContain("Transcription off");
+    } finally {
+      Object.defineProperty(process.stdin, "isTTY", {
+        value: origIsTTY,
+        configurable: true,
+      });
+      h.cleanup();
+    }
+  });
+
   test("interactive prompt: '3' then 'g' chooses groq cloud", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/wizard.test.ts

@@ -655,4 +655,83 @@ describe("runCliWizard", () => {
       "/admin/setup/expose",
     ]);
   });
+
+  test("non-interactive stdin fails fast (no hang) when a required answer is missing", async () => {
+    // Headless-hardening: with stdin closed (cloud-init, `ssh host 'parachute
+    // setup-wizard …'`, run.sh-exec'd stages.sh) an unanswered prompt would
+    // busy-hang Bun's readline question() forever. defaultPrompt now throws a
+    // clear, flag-naming error instead. We drive the real defaultPrompt (no
+    // `prompt` seam) with the account username unsupplied, forcing the account
+    // step to prompt — and force isTTY=false so the assertion is deterministic
+    // regardless of how the test runner's stdin is wired.
+    const { fetchImpl } = makeFakeHub();
+    const origIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+    try {
+      await expect(
+        runCliWizard({
+          hubUrl: "http://127.0.0.1:1939",
+          log: () => {},
+          fetchImpl,
+          sleep: async () => {},
+          // no accountUsername → account step calls the real defaultPrompt.
+          accountPassword: "longpassword",
+          vaultMode: "skip",
+          exposeMode: "localhost",
+        }),
+      ).rejects.toThrow(/stdin is not interactive/);
+    } finally {
+      Object.defineProperty(process.stdin, "isTTY", {
+        value: origIsTTY,
+        configurable: true,
+      });
+    }
+  });
+
+  test("headless runCliWizard with NO --transcribe-mode completes (transcription defaults to none, not a throw)", async () => {
+    // Regression guard for the review must-fix: `runCliWizard` used to forward
+    // its (throwing) `defaultPrompt` into the transcription step, so a headless
+    // run with account/vault/expose all supplied via flags but NO
+    // `--transcribe-mode` would THROW at the transcription step ("cannot prompt
+    // for: Pick [1]:") instead of defaulting to none. The wizard now forwards a
+    // prompt to the transcription step ONLY when a real seam is injected, so
+    // headless hits `resolveChoice`'s undefined-prompt non-TTY guard → none.
+    const { state, fetchImpl } = makeFakeHub();
+    const logs: string[] = [];
+    let ran = false;
+    const origIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
+    try {
+      const code = await runCliWizard({
+        hubUrl: "http://127.0.0.1:1939",
+        log: (l) => logs.push(l),
+        fetchImpl,
+        sleep: async () => {},
+        accountUsername: "admin",
+        accountPassword: "longpassword",
+        vaultMode: "skip",
+        exposeMode: "localhost",
+        configDir: "/tmp/pcli-wizard-headless-none", // triggers the step; none writes nothing
+        // NO transcribeMode, NO prompt seam → headless must default to none.
+        transcribeRunCommand: async () => {
+          ran = true;
+          return 0;
+        },
+      });
+      expect(code).toBe(0); // completed, did NOT throw
+      expect(ran).toBe(false); // none → no scribe install
+      expect(logs.join("\n")).toContain("Transcription off");
+      // Full flow still walked account → vault → expose.
+      expect(state.posted.map((p) => p.path)).toEqual([
+        "/admin/setup/account",
+        "/admin/setup/vault",
+        "/admin/setup/expose",
+      ]);
+    } finally {
+      Object.defineProperty(process.stdin, "isTTY", {
+        value: origIsTTY,
+        configurable: true,
+      });
+    }
+  });
 });

package/src/account-api.ts

@@ -33,6 +33,12 @@
  * ownership gate the cloud twin runs per-vault is trivially satisfied here.
  */
 import type { Database } from "bun:sqlite";
+// NOTE: this is a VALUE import — hub can't run without
+// `@openparachute/door-contract` resolving at runtime, so it's a real
+// `^0.6.0` runtime `dependency` (package.json, mirroring `@openparachute/depcheck`)
+// and NOT a `workspace:*` devDependency. The published hub tarball doesn't ship
+// `packages/`, so the npm-installed hub resolves door-contract from the registry.
+// See RELEASING.md → "Releasing door-contract".
 import {
   type AccountBootstrap,
   type ParachuteAccountDescriptor,

package/src/commands/wizard-transcription.ts

@@ -72,6 +72,14 @@ export interface TranscriptionStepOpts {
 
 /** Default readline prompt (matches wizard.ts's defaultPrompt). */
 async function defaultPrompt(question: string): Promise<string> {
+  // Non-TTY guard (headless-hardening): unlike wizard.ts's required-step
+  // prompts (which throw), the transcription step is optional and must NEVER
+  // block setup. On a closed / non-interactive stdin, return the empty answer
+  // — which the callers already treat as a benign default (a blank cloud API
+  // key means "set it later"; a blank local-install confirm takes the [Y]
+  // default). `resolveChoice` short-circuits to "none" before ever reaching
+  // here without a flag; this covers the flag-supplied-mode downstream prompts.
+  if (!process.stdin.isTTY) return "";
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     return await rl.question(question);
@@ -139,6 +147,22 @@ async function resolveChoice(
   log: (l: string) => void,
 ): Promise<ResolvedChoice> {
   if (opts.transcribeMode !== undefined) return opts.transcribeMode;
+  // Non-TTY guard (headless-hardening): with no `--transcribe-mode` flag AND a
+  // closed / non-interactive stdin (cloud-init, ssh heredoc, the e2e
+  // container), the real `defaultPrompt`'s `prompt("Pick [1]:")` would busy-hang
+  // forever on Bun's `readline/promises` question() — the exact wedge that
+  // timed out the Tier-1 e2e. Transcription is optional / opt-in and documented
+  // as NEVER blocking setup, so we DEFAULT to "none" (not throw — unlike the
+  // required account / vault / expose prompts in wizard.ts) with an honest log
+  // line. Guarded on `opts.prompt === undefined` so an injected prompt seam (a
+  // scripted test queue, or a caller supplying its own reader) is still honored
+  // — the wedge only exists for the real readline-backed default prompt.
+  if (opts.prompt === undefined && !process.stdin.isTTY) {
+    log("");
+    log("  stdin is not interactive — defaulting transcription to none.");
+    log("  Turn it on later with `parachute install scribe` (or re-run with --transcribe-mode).");
+    return "none";
+  }
   log("");
   log("  1) None — skip transcription (default)");
   log("  2) Local — run the engine on this box (no API key, needs ~2 GB RAM)");

package/src/commands/wizard.ts

@@ -156,8 +156,24 @@ interface FetchSetupResult {
 /**
  * Default readline prompt. Lives at module scope so tests can inject a
  * deterministic alternative through `opts.prompt`.
+ *
+ * Non-TTY guard (headless-hardening): Bun's `readline/promises` `question()`
+ * NEVER settles when stdin is closed / not a terminal (cloud-init, `ssh
+ * <host> 'parachute setup-wizard …'`, the e2e container's `run.sh`-exec'd
+ * stages.sh) — it busy-waits forever, wedging the wizard until the outer job
+ * timeout kills it. So when stdin is not interactive we FAIL FAST with an
+ * actionable message naming the flag that would have answered the prompt,
+ * rather than blocking on a prompt no one can ever answer. Account / vault /
+ * expose are required steps, so a missing answer here is fatal (the
+ * transcription step, being optional, defaults to "none" instead — see
+ * wizard-transcription.ts).
  */
 async function defaultPrompt(question: string): Promise<string> {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      `stdin is not interactive, so the wizard cannot prompt for: ${question.trim()}\nRe-run non-interactively by passing the corresponding flag (e.g. --account-username / --account-password / --vault-mode / --vault-name / --expose-mode / --transcribe-mode), or run in a real terminal.`,
+    );
+  }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
     return await rl.question(question);
@@ -224,6 +240,14 @@ async function setupFetch(
     // Don't auto-follow — the wizard returns 303 to /admin/setup, and
     // we want to inspect the Location header rather than chase it.
     redirect: "manual",
+    // Per-request 30s ceiling so a wedged hub call TRIPS instead of
+    // suspending forever. `pollOperation` (below) bounds the whole op with
+    // POLL_TIMEOUT_MS, but that deadline is only checked BETWEEN fetches — a
+    // single fetch that never resolves would defeat it. AbortSignal.timeout
+    // makes each individual call fail-fast; a real hub responds in well under
+    // 30s. Test-injected fetch stubs ignore the signal, so this is inert in
+    // unit tests.
+    signal: AbortSignal.timeout(30_000),
   });
   const bodyText = await res.text();
   // Collect Set-Cookie. Try `getAll` first (Bun + node18+ supported it
@@ -783,7 +807,16 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     await walkTranscriptionStep({
       configDir: opts.configDir,
       log,
-      prompt,
+      // Only forward a REAL injected prompt seam — NOT the resolved
+      // `prompt` (which is the throwing `defaultPrompt` when the caller
+      // supplied none). Passing the default here would defeat
+      // `resolveChoice`'s `opts.prompt === undefined` non-TTY guard: on a
+      // headless box with no `--transcribe-mode`, the transcription step
+      // would call the throwing default mid-wizard instead of defaulting to
+      // `none`. With the seam forwarded only when present, headless runs hit
+      // the guard (default none) and interactive/test runs still get their
+      // reader.
+      ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
       ...(opts.transcribeMode !== undefined ? { transcribeMode: opts.transcribeMode } : {}),
       ...(opts.transcribeApiKey !== undefined ? { transcribeApiKey: opts.transcribeApiKey } : {}),
       ...(opts.transcribeRunCommand !== undefined ? { runCommand: opts.transcribeRunCommand } : {}),

package/src/setup-wizard.ts

@@ -41,6 +41,7 @@ import type { Database } from "bun:sqlite";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { recordLoginUnlock } from "./admin-lock.ts";
+import { provisionVault } from "./admin-vaults.ts";
 import { type OperationsRegistry, runInstall, specFor } from "./api-modules-ops.ts";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import {
@@ -307,15 +308,34 @@ export function deriveWizardState(deps: {
   // phantom `vaults[]` row at SEED_VERSION); both surfaces must agree that a
   // placeholder is not a real vault.
   const vaultIsPlaceholder = vaultEntry !== undefined && vaultEntry.version === SEED_VERSION;
+  // hub#607-followup (the e2e wizard-skip bug): the SEED_VERSION check alone is
+  // NOT sufficient to distinguish "real vault" from "module installed, no
+  // instance". When the hub boot-spawns the vault module child, vault's
+  // `selfRegister` writes its services.json row at the REAL package version
+  // (e.g. 0.7.4-rc.1) but with `paths: []` (no vault instance created yet) —
+  // defeating the SEED_VERSION sentinel. A bare `version !== SEED_VERSION`
+  // check then read that empty-paths row as a real vault, so the wizard
+  // SILENTLY SKIPPED its vault step and `--vault-mode create --vault-name` was
+  // ignored (the operator finished setup with no vault). Make the check
+  // INSTANCE-aware: a real vault also requires at least one mount path. This is
+  // the SAME empty-paths discrimination `findExistingVault` /
+  // `listVaultInstanceNames` already use (#478) — a servable instance carries a
+  // canonical `/vault/<name>` path; a self-registered-but-uncreated row has
+  // `paths: []` and must read as "no real vault yet." A SEED_VERSION seed row
+  // carries `/vault/default`, so it's caught by `vaultIsPlaceholder` above and
+  // unaffected by this clause.
+  const vaultHasInstancePath = vaultEntry !== undefined && vaultEntry.paths.length > 0;
   // INVARIANT (B5 re-enterable vault step): hasRealVault means "a real
-  // instance row exists" — placeholder excluded here, skip-marker excluded
-  // below (skip flips hasVault, never hasRealVault). THREE sites key on this
-  // same placeholder logic and must move together: this derivation,
-  // handleSetupGet's `?step=vault` re-entry gate, and handleSetupVaultPost's
-  // already-provisioned short-circuit. Changing one without the others
-  // either re-opens a provisioning form over a real vault or dead-ends the
-  // post-skip re-entry path.
-  const hasRealVault = vaultEntry !== undefined && !vaultIsPlaceholder;
+  // instance row exists" — placeholder excluded here, empty-paths excluded via
+  // vaultHasInstancePath, skip-marker excluded below (skip flips hasVault,
+  // never hasRealVault). THREE sites key on this same `hasRealVault` value and
+  // must move together: this derivation, handleSetupGet's `?step=vault`
+  // re-entry gate, and handleSetupVaultPost's already-provisioned short-circuit
+  // — all three read `deriveWizardState(...).hasRealVault`, so tightening it
+  // here moves all three at once. Changing the meaning here without checking
+  // those consumers either re-opens a provisioning form over a real vault or
+  // dead-ends the post-skip re-entry path.
+  const hasRealVault = vaultEntry !== undefined && !vaultIsPlaceholder && vaultHasInstancePath;
   // hub#168 Cut 2: `setup_vault_skipped === "true"` advances the wizard
   // past the vault step even when no vault row exists. The operator
   // explicitly chose Skip; the module is installed (Cut 1) but no
@@ -416,6 +436,14 @@ export interface SetupWizardDeps {
   registry?: OperationsRegistry;
   /** Test seam: stub `bun add` / `bun remove` runner. */
   run?: (cmd: readonly string[]) => Promise<number>;
+  /**
+   * Test seam: provision a vault for the already-supervised short-circuit in
+   * `handleSetupVaultPost`. Production omits this and uses the real
+   * {@link provisionVault} (which shells to `parachute-vault create <name>
+   * --json`). Tests inject a stub so the short-circuit can be asserted without
+   * spawning the vault CLI.
+   */
+  provisionVaultImpl?: typeof provisionVault;
   /**
    * Test seam: stub the bun-link detection used by `runInstall` to
    * short-circuit `bun add -g` when a package is already linked
@@ -2305,45 +2333,130 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   const registry = deps.registry;
   const vaultSpec = specFor(FIRST_VAULT_SHORT);
 
-  // Idempotent short-circuit: if the supervisor is already running (or
-  // mid-spawn) for vault — i.e. a previous POST already kicked off
-  // `runInstall` and beat us to spawning — return a synthesized
-  // succeeded op instead of firing a second `bun add -g`. Mirrors the
-  // pattern in `handleInstall` (api-modules-ops.ts). Without this,
-  // two concurrent POSTs both pass `state.hasVault === false` (the
-  // services.json seed is the only signal that step exits, and it's
-  // written by `runInstall` *after* `bun add` returns), and each
-  // fires its own install — wasted work and a possible race on the
-  // seed/spawn writes. Low risk on first-boot in practice, but the
-  // fix is cheap and matches the API surface's posture.
+  // Already-supervised handling: is the vault MODULE child already under the
+  // supervisor (running / starting / restarting)? Two ways that happens:
+  //   (a) the concurrent-POST race this guard was written for — a prior POST
+  //       already fired `runInstall` and beat us to spawning the module; and
+  //   (b) the boot-spawned-child case the Tier-1 e2e exposed — the hub started
+  //       the vault module on boot so it could `selfRegister`, but NO vault
+  //       INSTANCE has been created yet (its services.json row carries
+  //       `paths: []`, which is exactly why `hasRealVault` was false above and
+  //       we reached this create path).
+  // When the module is already supervised we must NOT fire a second
+  // `bun add -g` / `runInstall`. The three create/import sub-cases are handled
+  // below (import → reject; create+registered → provision the instance;
+  // create+unregistered → let the in-flight install create it).
   const supervisorState = deps.supervisor.get(FIRST_VAULT_SHORT);
-  if (
+  const alreadySupervised =
     supervisorState?.status === "running" ||
     supervisorState?.status === "starting" ||
-    supervisorState?.status === "restarting"
-  ) {
+    supervisorState?.status === "restarting";
+
+  // MUST-FIX (review of #768): import-during-setup on an already-supervised box
+  // isn't supported yet. On such a box (now the normal init'd-box path that
+  // reaches this vault form) `provisionVault` only creates an EMPTY vault —
+  // running it for an IMPORT request and reporting success would leave the
+  // operator with an empty vault named after their import target plus a false
+  // "vault created" banner (a data-integrity footgun). Reject with an
+  // actionable message instead. Known limitation — see CHANGELOG; the fuller
+  // fix (run the mirror-import follow-up after provision) is deferred because
+  // it isn't exercised by the e2e and can't be verified end-to-end here.
+  if (alreadySupervised && rawMode === "import") {
+    const detail =
+      "importing a vault during setup isn't supported yet on a box whose vault module is already running. Create the vault here instead, then import into it with `parachute vault …` or the admin UI.";
     if (registry) {
-      const op = registry.create("install", FIRST_VAULT_SHORT);
+      const rejectOp = registry.create("install", FIRST_VAULT_SHORT);
       registry.update(
-        op.id,
-        { status: "succeeded" },
-        `${FIRST_VAULT_SHORT} already supervised (status=${supervisorState.status})`,
+        rejectOp.id,
+        { status: "failed", error: detail },
+        `vault import unsupported on an already-supervised box: ${detail}`,
       );
       if (form.isJson) {
-        return jsonOkResponse({ op_id: op.id, step: "vault", message: "vault already supervised" });
+        return jsonOkResponse({ op_id: rejectOp.id, step: "vault", message: detail });
       }
-      return redirect(`/admin/setup?op=${encodeURIComponent(op.id)}`);
+      return redirect(`/admin/setup?op=${encodeURIComponent(rejectOp.id)}`);
     }
     if (form.isJson) {
-      return jsonOkResponse({ step: "vault", message: "vault already supervised" });
+      return jsonErrorResponse(409, "Import not supported here", detail);
     }
-    return redirect("/admin/setup");
+    return badRequestPage("Import not supported here", detail);
   }
 
+  // NIT (reviewer N2): only provision if vault is ALREADY registered in
+  // services.json. If it isn't, we're in the narrow pre-seed window of a
+  // CONCURRENT create POST whose `runInstall` spawned the module but hasn't
+  // written its row yet — firing `provisionVault` here would run
+  // `parachute install vault` a SECOND time. In that case we synthesize
+  // success below and let the in-flight install create the vault.
+  const vaultAlreadyRegistered =
+    findService(vaultSpec.manifestName, deps.manifestPath) !== undefined;
+
   const op = registry
     ? registry.create("install", FIRST_VAULT_SHORT)
     : { id: cryptoRandomId(), status: "pending" as const, log: [] as string[] };
-  if (registry) {
+
+  if (alreadySupervised && vaultAlreadyRegistered) {
+    // Case (b): supervised module, real-version row with `paths: []` (no
+    // instance). Provision the named vault via the shipped admin-SPA path
+    // (`parachute-vault create <name> --json`, idempotent + name-validated).
+    // FIRE-AND-FORGET, matching the normal `void runInstall` path: return the
+    // op_id immediately and mark the op from the BACKGROUND result. This keeps
+    // the POST fast so the CLI's 30s per-request ceiling only bounds the quick
+    // POST/poll round-trip — a slow cold `parachute-vault create` on a sluggish
+    // VPS is polled to completion within POLL_TIMEOUT_MS (5 min), never aborted
+    // mid-create. No `bun add -g` fires (module already supervised).
+    const provision = deps.provisionVaultImpl ?? provisionVault;
+    if (registry) {
+      registry.update(
+        op.id,
+        { status: "running" },
+        `${FIRST_VAULT_SHORT} already supervised (status=${supervisorState?.status}) — creating vault "${vaultName}"`,
+      );
+      void provision(vaultName, { issuer: deps.issuer, manifestPath: deps.manifestPath })
+        .then((provisioned) => {
+          if (provisioned.ok) {
+            registry.update(
+              op.id,
+              { status: "succeeded" },
+              provisioned.created
+                ? `vault "${vaultName}" created`
+                : `vault "${vaultName}" already exists`,
+            );
+          } else {
+            registry.update(
+              op.id,
+              { status: "failed", error: provisioned.message },
+              `vault create failed: ${provisioned.message}`,
+            );
+          }
+        })
+        .catch((err) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          registry.update(op.id, { status: "failed", error: msg }, `vault create failed: ${msg}`);
+        });
+    } else {
+      // No registry (test-only path): provision synchronously so the vault is
+      // actually created; there's no op to poll.
+      const provisioned = await provision(vaultName, {
+        issuer: deps.issuer,
+        manifestPath: deps.manifestPath,
+      });
+      if (!provisioned.ok) {
+        console.warn(`[setup-wizard] vault create failed: ${provisioned.message}`);
+      }
+    }
+  } else if (alreadySupervised) {
+    // Case (a): supervised but NOT yet registered — the pre-seed window of a
+    // concurrent create POST. Synthesize success; the in-flight `runInstall`
+    // creates the vault (reviewer N2 — the original guard's job).
+    if (registry) {
+      registry.update(
+        op.id,
+        { status: "succeeded" },
+        `${FIRST_VAULT_SHORT} already supervised (status=${supervisorState?.status}) — a concurrent install is provisioning the vault`,
+      );
+    }
+  } else if (registry) {
     // hub#267: thread the typed name through `PARACHUTE_VAULT_NAME` so
     // vault's first-boot path (vault#342) names the created vault
     // accordingly.