@openparachute/hub 0.6.2 → 0.6.3-rc.1

package/src/module-ops-client.ts

@@ -0,0 +1,457 @@
+/**
+ * CLI client for the module-ops HTTP API (`POST /api/modules/:short/<op>`).
+ *
+ * This is the credential + transport seam that Phase 3 of the
+ * hub-as-supervisor unification (design 2026-06-01 §3.1) will repoint
+ * `parachute start/stop/restart <svc>` onto: instead of touching pidfiles
+ * directly (`commands/lifecycle.ts`), those verbs become authenticated calls
+ * to the running hub's in-process Supervisor over loopback.
+ *
+ * **Phase 1 is additive.** This file ADDS the client + its tests; it does NOT
+ * repoint any existing CLI command. `parachute start/stop/restart/install/
+ * upgrade` stay on the detached `lifecycle.ts` path until the Phase 3 cutover.
+ *
+ * ## The credential (§3.1)
+ *
+ * The on-box caller's proof of operator authority is `~/.parachute/operator.token`
+ * — a hub-issued JWT carrying `parachute:host:admin` under the default `admin`
+ * scope-set, which is exactly the scope `api-modules-ops.ts` gates on. We READ
+ * it via `useOperatorTokenWithAutoRotate` (which validates against the hub DB +
+ * issuer and opportunistically re-mints a within-7d-of-expiry token in place);
+ * we never mint a parallel token, so there is no second SQLite writer racing
+ * the running hub. The token is presented as `Authorization: Bearer` to the
+ * loopback hub.
+ *
+ * No operator token on disk → an actionable error ("no operator token — run
+ * `parachute auth rotate-operator`"), never a raw 401.
+ *
+ * ## Sync vs async ops
+ *
+ * `start` / `stop` / `restart` / `uninstall` are synchronous: the handler does
+ * the work inline and returns the new state in the body. `install` / `upgrade`
+ * return `202 { operation_id }` and the client polls
+ * `GET /api/modules/operations/:id` to a terminal state. This client handles
+ * both: a 202-with-operation_id response is polled to completion; any other
+ * 2xx body is returned as-is.
+ */
+
+import type { Database } from "bun:sqlite";
+import { OperatorTokenExpiredError, useOperatorTokenWithAutoRotate } from "./operator-token.ts";
+
+/** Loopback hub base URL when none is injected. The hub pins 1939 (canonical-ports). */
+export const DEFAULT_HUB_BASE_URL = "http://127.0.0.1:1939";
+
+/** Default poll interval + ceiling for async operations. */
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_POLL_TIMEOUT_MS = 120_000;
+
+/**
+ * Default ceiling for the single `GET /api/modules` read in {@link fetchModuleStates}.
+ * `status` is a read-only health snapshot — a hub whose request handler is wedged
+ * (accepts the TCP connection but never answers) must not hang it. Bounded so the
+ * caller degrades to a "couldn't read live module state" note instead of stalling.
+ */
+const DEFAULT_STATES_FETCH_TIMEOUT_MS = 3_000;
+
+/** Module-op verbs the client can drive against `POST /api/modules/:short/<op>`. */
+export type ModuleOp = "start" | "stop" | "restart" | "install" | "upgrade" | "uninstall";
+
+/**
+ * Thrown when no `operator.token` exists on disk. The CLI surfaces
+ * `.message` directly — it's already actionable. Distinct error class so a
+ * caller can branch on "needs bootstrap" vs "hub said no."
+ */
+export class NoOperatorTokenError extends Error {
+  override name = "NoOperatorTokenError";
+  constructor() {
+    super(
+      "no operator token — run `parachute auth rotate-operator` to mint one (looked for ~/.parachute/operator.token)",
+    );
+  }
+}
+
+/**
+ * Thrown when the hub answers a module-op with a non-2xx status. Carries the
+ * HTTP status + the parsed `{ error, error_description }` body so the CLI can
+ * render the hub's own message (e.g. `not_installed`, `insufficient_scope`).
+ */
+export class ModuleOpHttpError extends Error {
+  override name = "ModuleOpHttpError";
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string, description: string) {
+    super(`${code}: ${description}`);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Thrown when an async operation reaches `failed`, or polling times out. */
+export class ModuleOpFailedError extends Error {
+  override name = "ModuleOpFailedError";
+}
+
+/** Terminal shape returned to the caller — the hub's response body. */
+export interface ModuleOpResult {
+  /** HTTP status of the initiating POST (200 sync, 202 async). */
+  readonly status: number;
+  /** Parsed JSON body. For async ops, the terminal operation record. */
+  readonly body: unknown;
+  /** Operation id when the op was async (202); undefined for sync ops. */
+  readonly operationId?: string;
+}
+
+export interface DriveModuleOpDeps {
+  /** Open hub DB handle — used to validate / auto-rotate the operator token. */
+  readonly db: Database;
+  /** Hub issuer (origin) the operator token's `iss` is validated against. */
+  readonly issuer: string;
+  /** Loopback hub base URL. Defaults to {@link DEFAULT_HUB_BASE_URL}. */
+  readonly baseUrl?: string;
+  /** configDir override (where operator.token lives). Defaults to `configDir()`. */
+  readonly configDir?: string;
+  /** Optional JSON body for the POST (e.g. `{ channel }` on install/upgrade). */
+  readonly body?: unknown;
+  /**
+   * fetch seam. Production passes the global `fetch`; tests inject a fake that
+   * asserts the Authorization header + returns canned responses without a
+   * real socket.
+   */
+  readonly fetch?: typeof fetch;
+  /** Clock seam for the operator-token rotation check. */
+  readonly now?: () => Date;
+  /** Sleep seam for the async-op poll loop. Tests stub to advance instantly. */
+  readonly sleep?: (ms: number) => Promise<void>;
+  /** Poll interval for async ops, ms. Default 1000. */
+  readonly pollIntervalMs?: number;
+  /** Poll ceiling for async ops, ms. Default 120000. */
+  readonly pollTimeoutMs?: number;
+  /**
+   * Per-request ceiling for the {@link fetchModuleStates} `GET /api/modules` read,
+   * ms. Default {@link DEFAULT_STATES_FETCH_TIMEOUT_MS} (3000). Bounds `status`
+   * against a wedged hub handler; tests inject a short value to exercise the
+   * timeout-degrade path without a real wall-clock wait.
+   */
+  readonly statesFetchTimeoutMs?: number;
+}
+
+/**
+ * Read the operator token (auto-rotating if near expiry) and return the bearer
+ * to present onward. Throws {@link NoOperatorTokenError} when none is on disk,
+ * and re-throws {@link OperatorTokenExpiredError} unchanged (its message is
+ * already the actionable "run rotate-operator" shape).
+ */
+export async function resolveOperatorBearer(deps: DriveModuleOpDeps): Promise<string> {
+  const used = await useOperatorTokenWithAutoRotate(deps.db, {
+    issuer: deps.issuer,
+    ...(deps.configDir !== undefined ? { configDir: deps.configDir } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  });
+  if (!used) throw new NoOperatorTokenError();
+  return used.token;
+}
+
+/**
+ * Drive a module-op end-to-end: read the operator token, POST it as Bearer to
+ * the loopback hub, and (for async ops that return 202 + operation_id) poll
+ * `GET /api/modules/operations/:id` to a terminal state.
+ *
+ * Throws:
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx (carries status + code).
+ *   - {@link ModuleOpFailedError} — async op reached `failed`, or poll timed out.
+ */
+export async function driveModuleOp(
+  short: string,
+  op: ModuleOp,
+  deps: DriveModuleOpDeps,
+): Promise<ModuleOpResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+
+  const bearer = await resolveOperatorBearer(deps);
+
+  const headers: Record<string, string> = { authorization: `Bearer ${bearer}` };
+  const init: RequestInit = { method: "POST", headers };
+  if (deps.body !== undefined) {
+    headers["content-type"] = "application/json";
+    init.body = JSON.stringify(deps.body);
+  }
+
+  const res = await doFetch(`${baseUrl}/api/modules/${short}/${op}`, init);
+  const body = await parseJsonSafe(res);
+
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+
+  // Async op (install / upgrade): 202 + { operation_id } → poll to terminal.
+  if (res.status === 202) {
+    const operationId = extractOperationId(body);
+    if (!operationId) {
+      // 202 means "accepted, poll for completion" — but with no operation_id
+      // there's nothing to poll. Silently returning the 202 would strand the
+      // caller on an incomplete op; surface it as a hard failure instead.
+      throw new ModuleOpFailedError("hub returned 202 but no operation_id in body");
+    }
+    const terminal = await pollOperation(operationId, bearer, baseUrl, doFetch, deps);
+    return { status: res.status, body: terminal, operationId };
+  }
+
+  // Sync op (start / stop / restart / uninstall) — body is the final state.
+  return { status: res.status, body };
+}
+
+/**
+ * Poll `GET /api/modules/operations/:id` until `succeeded` / `failed` or the
+ * timeout elapses. Returns the terminal operation record on success; throws
+ * {@link ModuleOpFailedError} on `failed` or timeout, {@link ModuleOpHttpError}
+ * on a non-2xx poll response.
+ */
+async function pollOperation(
+  operationId: string,
+  bearer: string,
+  baseUrl: string,
+  doFetch: typeof fetch,
+  deps: DriveModuleOpDeps,
+): Promise<unknown> {
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const intervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const timeoutMs = deps.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  const now = deps.now ?? (() => new Date());
+  const deadline = now().getTime() + timeoutMs;
+  const url = `${baseUrl}/api/modules/operations/${operationId}`;
+
+  while (true) {
+    const res = await doFetch(url, {
+      method: "GET",
+      headers: { authorization: `Bearer ${bearer}` },
+    });
+    const body = await parseJsonSafe(res);
+    if (res.status < 200 || res.status >= 300) {
+      const { error, error_description } = asErrorBody(body);
+      throw new ModuleOpHttpError(res.status, error, error_description);
+    }
+    const status = extractOpStatus(body);
+    if (status === "succeeded") return body;
+    if (status === "failed") {
+      const errMsg = extractOpError(body) ?? "operation failed";
+      throw new ModuleOpFailedError(errMsg);
+    }
+    if (now().getTime() >= deadline) {
+      throw new ModuleOpFailedError(
+        `operation ${operationId} did not complete within ${timeoutMs}ms (last status: ${status ?? "unknown"})`,
+      );
+    }
+    await sleep(intervalMs);
+  }
+}
+
+/** Terminal shape returned by {@link fetchModuleLogs}. */
+export interface ModuleLogsResult {
+  /** The short name the logs belong to. */
+  readonly short: string;
+  /** Buffered lines, oldest-first (each includes its trailing newline). */
+  readonly lines: string[];
+  /** The same lines joined — the tail-blob shape `parachute logs` will print. */
+  readonly text: string;
+}
+
+/**
+ * Read a supervised module's recent output from the hub's per-module ring
+ * buffer (`GET /api/modules/:short/logs`, §6.5). Additive — this does NOT wire
+ * into the `parachute logs` CLI command (that cutover is Phase 3); it's the
+ * transport+credential seam Phase 3 will call.
+ *
+ * Reuses the same operator.token→Bearer path as {@link driveModuleOp} (read,
+ * never mint). The buffer replay includes the boot/crash lines that preceded
+ * the call — the must-have that a connect-time stream would miss.
+ *
+ * Throws:
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx (e.g. `not_supervised`).
+ */
+export async function fetchModuleLogs(
+  short: string,
+  deps: DriveModuleOpDeps,
+): Promise<ModuleLogsResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const bearer = await resolveOperatorBearer(deps);
+
+  const res = await doFetch(`${baseUrl}/api/modules/${short}/logs`, {
+    method: "GET",
+    headers: { authorization: `Bearer ${bearer}` },
+  });
+  const body = await parseJsonSafe(res);
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+  const b = (body ?? {}) as { lines?: unknown; text?: unknown };
+  const lines = Array.isArray(b.lines)
+    ? b.lines.filter((l): l is string => typeof l === "string")
+    : [];
+  const text = typeof b.text === "string" ? b.text : lines.join("");
+  return { short, lines, text };
+}
+
+/**
+ * One module's run-state as read from `GET /api/modules` — the subset
+ * `parachute status` needs to render a module row from the RUNNING supervisor
+ * (design §6.4 module rows). Snake-case mirrors the wire shape (`api-modules.ts`
+ * `ModuleWireShape`); we keep only the supervisor-derived fields here.
+ */
+export interface ModuleStateSnapshot {
+  readonly short: string;
+  readonly installed: boolean;
+  readonly installed_version: string | null;
+  /**
+   * Supervisor run-status (`running` / `stopped` / `crashed` / `starting` /
+   * `restarting`), or null when the module isn't tracked by the supervisor
+   * (e.g. never booted, skipped at boot, or no supervisor on this hub).
+   */
+  readonly supervisor_status: string | null;
+  readonly pid: number | null;
+  /**
+   * Structured start-error the supervisor recorded (missing-dependency /
+   * started-but-unbound). Passed through verbatim so `status` can render the
+   * SAME friendly missing-dependency note the detached path shows (#188).
+   */
+  readonly supervisor_start_error: unknown | null;
+}
+
+/** Terminal shape returned by {@link fetchModuleStates}. */
+export interface ModuleStatesResult {
+  /** Whether the running hub has a supervisor wired in (`supervisor_available`). */
+  readonly supervisorAvailable: boolean;
+  /** Per-module supervisor snapshots, keyed by short name in array order. */
+  readonly modules: ModuleStateSnapshot[];
+}
+
+/**
+ * Read the RUNNING hub's per-module supervisor states via `GET /api/modules`
+ * (design §6.4 module rows). The operator token's `admin` scope-set carries
+ * `parachute:host:auth` (the scope `/api/modules` gates on), so the same
+ * read-never-mint operator-token→Bearer path {@link driveModuleOp} uses
+ * authenticates this read.
+ *
+ * Used by `parachute status` on a UNIT-MANAGED box to source module rows from
+ * the live supervisor instead of pidfiles. It is read-only and BOUNDED: the
+ * single `GET /api/modules` carries an `AbortSignal.timeout` (default
+ * {@link DEFAULT_STATES_FETCH_TIMEOUT_MS}) so a hub that accepts the TCP
+ * connection but never answers (wedged request handler) can't hang `status` —
+ * the preceding `/health` probe is bounded too, but this read needs its own
+ * ceiling. The CALLER is responsible for degrading gracefully (hub down → don't
+ * call this; no token → catch {@link NoOperatorTokenError}) so `status` never
+ * hangs/crashes.
+ *
+ * Throws (all caught + degraded to a "couldn't read live module state" note by
+ * the `status` caller — see `buildSupervisorRows`):
+ *   - {@link NoOperatorTokenError} — no operator.token on disk.
+ *   - {@link OperatorTokenExpiredError} — token fully expired (actionable msg).
+ *   - {@link ModuleOpHttpError} — hub answered non-2xx, OR the bounded fetch
+ *     timed out / aborted (surfaced as a synthetic `request_timeout` so the
+ *     caller degrades with a message via its existing non-2xx catch, exactly as
+ *     it does for a real HTTP error — never a hang).
+ */
+export async function fetchModuleStates(deps: DriveModuleOpDeps): Promise<ModuleStatesResult> {
+  const doFetch = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? DEFAULT_HUB_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = deps.statesFetchTimeoutMs ?? DEFAULT_STATES_FETCH_TIMEOUT_MS;
+  const bearer = await resolveOperatorBearer(deps);
+
+  let res: Response;
+  try {
+    res = await doFetch(`${baseUrl}/api/modules`, {
+      method: "GET",
+      // `/api/modules` parses the scheme-cased `Bearer ` prefix; match it exactly.
+      headers: { authorization: `Bearer ${bearer}` },
+      // Bound the read so a wedged hub handler degrades `status` rather than
+      // hanging it. AbortSignal.timeout fires `AbortError` once the ceiling
+      // elapses (or the fetch errors for another transport reason).
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    // Timeout/abort or transport failure → re-shape as a ModuleOpHttpError so the
+    // `status` caller degrades through the SAME non-2xx catch it uses for an HTTP
+    // error (a "couldn't read live module state" note + exit 0), never hangs.
+    const aborted =
+      err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+    const description = aborted
+      ? `module-states read timed out after ${timeoutMs}ms`
+      : `module-states read failed (${err instanceof Error ? err.message : String(err)})`;
+    throw new ModuleOpHttpError(0, "request_timeout", description);
+  }
+  const body = await parseJsonSafe(res);
+  if (res.status < 200 || res.status >= 300) {
+    const { error, error_description } = asErrorBody(body);
+    throw new ModuleOpHttpError(res.status, error, error_description);
+  }
+  const b = (body ?? {}) as { modules?: unknown; supervisor_available?: unknown };
+  const supervisorAvailable = b.supervisor_available === true;
+  const modules: ModuleStateSnapshot[] = Array.isArray(b.modules)
+    ? b.modules
+        .filter((m): m is Record<string, unknown> => !!m && typeof m === "object")
+        .map((m) => ({
+          short: typeof m.short === "string" ? m.short : "",
+          installed: m.installed === true,
+          installed_version: typeof m.installed_version === "string" ? m.installed_version : null,
+          supervisor_status: typeof m.supervisor_status === "string" ? m.supervisor_status : null,
+          pid: typeof m.pid === "number" ? m.pid : null,
+          supervisor_start_error:
+            m.supervisor_start_error !== undefined ? (m.supervisor_start_error ?? null) : null,
+        }))
+    : [];
+  return { supervisorAvailable, modules };
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return undefined;
+  }
+}
+
+function asErrorBody(body: unknown): { error: string; error_description: string } {
+  if (body && typeof body === "object") {
+    const b = body as Record<string, unknown>;
+    const error = typeof b.error === "string" ? b.error : "error";
+    const error_description =
+      typeof b.error_description === "string" ? b.error_description : "request failed";
+    return { error, error_description };
+  }
+  return { error: "error", error_description: "request failed" };
+}
+
+function extractOperationId(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const id = (body as Record<string, unknown>).operation_id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return undefined;
+}
+
+function extractOpStatus(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const s = (body as Record<string, unknown>).status;
+    if (typeof s === "string") return s;
+  }
+  return undefined;
+}
+
+function extractOpError(body: unknown): string | undefined {
+  if (body && typeof body === "object") {
+    const e = (body as Record<string, unknown>).error;
+    if (typeof e === "string" && e.length > 0) return e;
+  }
+  return undefined;
+}
+
+// Re-export so CLI callers can catch the expired-token case without a second
+// import from operator-token.ts.
+export { OperatorTokenExpiredError };

package/src/port-probe.ts

@@ -0,0 +1,50 @@
+/**
+ * Loopback TCP-port readiness probe — the tiny "is something listening on
+ * 127.0.0.1:<port>?" primitive shared by the detached `commands/lifecycle.ts`
+ * start path and the in-process `supervisor.ts` (design 2026-06-01 §6.5).
+ *
+ * Factored out of `lifecycle.ts` so the supervisor can reach the probe without
+ * importing all of lifecycle's heavy graph (hub-db, operator-token,
+ * services-manifest, …) into a module that hub-server / proxy-state / the
+ * module-ops API all depend on. `lifecycle.ts` re-exports `defaultPortListening`
+ * + `PortListeningFn` so its public API is unchanged; both files share THIS
+ * one implementation, so they can't drift.
+ *
+ * `node:net` rather than `Bun.connect` because the latter has no clean
+ * "connection refused → false" without a custom socket handler, and the net
+ * Socket's `error`/`connect` events map directly onto the boolean we want.
+ */
+
+import { Socket } from "node:net";
+
+/**
+ * "Is something listening on this TCP port on loopback?" seam. Pairs with the
+ * spawn-then-die settle to catch the alive-but-never-bound failure shape
+ * (hub#487): a service that lives long enough to clear a liveness check but
+ * never binds its port (port already held by an orphan / a bun-linked
+ * resolution failure that lingers). Tests inject a deterministic stub;
+ * production uses {@link defaultPortListening}.
+ */
+export type PortListeningFn = (port: number) => Promise<boolean>;
+
+/**
+ * Connect-probe: open a TCP socket to 127.0.0.1:<port> and see if it's
+ * accepted. A successful connect means *something* is listening; we close
+ * immediately. Connection refused / timeout means nothing is bound yet.
+ */
+export const defaultPortListening: PortListeningFn = (port) =>
+  new Promise((resolve) => {
+    const socket = new Socket();
+    let settled = false;
+    const done = (listening: boolean) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(listening);
+    };
+    socket.setTimeout(1000);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+    socket.connect(port, "127.0.0.1");
+  });

package/src/setup-wizard.ts

@@ -67,7 +67,13 @@ import {
 } from "./hub-settings.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 import { escapeHtml } from "./oauth-ui.ts";
-import { mintOperatorToken } from "./operator-token.ts";
+import {
+  type IssueOperatorTokenResult,
+  type MintOperatorTokenOpts,
+  issueOperatorToken,
+  mintOperatorToken,
+  readOperatorTokenFile,
+} from "./operator-token.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findService, readManifestLenient } from "./services-manifest.ts";
 import {
@@ -377,6 +383,22 @@ export interface SetupWizardDeps {
    * `readExposeStateFn` seam.
    */
   readExposeStateFn?: () => ExposeState | undefined;
+  /**
+   * Test seam for the fresh-box operator-token closure (design §3.1 /
+   * Phase 3b Deliverable A). After the wizard creates the first admin, it
+   * persists `~/.parachute/operator.token` so the box has a CLI operator
+   * credential the moment it gains an admin — without it, the Phase 3b
+   * per-module verbs (`parachute start/stop/restart <svc>` driving the
+   * supervisor) would 401 on a freshly-bootstrapped box. Production omits
+   * this and uses the real {@link issueOperatorToken}; tests inject a stub
+   * to assert the call (or to make it throw and prove a token-write failure
+   * never fails account creation).
+   */
+  issueOperatorToken?: (
+    db: Database,
+    userId: string,
+    opts: MintOperatorTokenOpts & { dir?: string },
+  ) => Promise<IssueOperatorTokenResult>;
 }
 
 /**
@@ -1888,6 +1910,16 @@ export async function handleSetupAccountPost(
     // any racer who saw it over the operator's shoulder during the
     // window between log-print and form-submit.
     if (requireToken) consumeBootstrapToken();
+    // Fresh-box operator-token closure (design §3.1 / Phase 3b Deliverable A).
+    // The box now has its first admin — persist `operator.token` so it has a
+    // CLI operator credential immediately. Without it, the Phase 3b per-module
+    // verbs (start/stop/restart <svc> driving the supervisor over the
+    // module-ops API) would 401 on a box bootstrapped purely through the
+    // wizard. Runs AFTER the admin row + bootstrap-token are committed so a
+    // half-written admin never gains a token; guarded so an existing token is
+    // never clobbered; wrapped so a token-write failure NEVER fails the
+    // account creation the operator just completed.
+    await ensureOperatorTokenForFirstAdmin(deps, user.id);
     const session = createSession(deps.db, { userId: user.id });
     const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
       secure: isHttpsRequest(req),
@@ -1927,6 +1959,53 @@ export async function handleSetupAccountPost(
   }
 }
 
+/**
+ * Persist `~/.parachute/operator.token` for the just-created first admin
+ * (design §3.1 / Phase 3b Deliverable A). The 3a reviewer flagged that a fresh
+ * `init`→wizard flow ends with NO operator token on disk, so the Phase 3b
+ * per-module verbs — `parachute start/stop/restart <svc>`, which now drive the
+ * supervisor over the host-admin-gated module-ops API — would 401 on such a
+ * box. Minting the token here makes the box have a CLI operator credential the
+ * moment it gains an admin.
+ *
+ * Three invariants:
+ *   - Mints under the `admin` scope-set (the default), which carries
+ *     `parachute:host:admin` — exactly the scope `api-modules-ops.ts` gates on.
+ *     `issueOperatorToken` writes it 0600 (`writeOperatorTokenFile`).
+ *   - Guarded by `readOperatorTokenFile() === null`: never clobber a token an
+ *     operator already minted (`auth set-password` / `rotate-operator`, or a
+ *     prior init).
+ *   - Wrapped in try/catch so a token-write failure NEVER fails the account
+ *     creation the operator just completed — they have an admin row + session
+ *     either way, and `parachute auth rotate-operator` is the documented
+ *     recovery for a missing token.
+ *
+ * Uses `deps.issuer` as the `iss` claim — the same pre-resolved origin the rest
+ * of the wizard's mints use (`handleSetupExposePost`). The hub-server derives
+ * that origin the same way `commands/auth.ts:resolveHubIssuer` does — semantically
+ * equivalent, structurally different: this path takes a pre-resolved `deps.issuer`
+ * while `auth.ts` reads expose-state inline at call time. `start hub` self-heals a
+ * stale `iss` later if the box is exposed after init (hub#481), so an
+ * init-at-loopback mint is correct here.
+ */
+async function ensureOperatorTokenForFirstAdmin(
+  deps: SetupWizardDeps,
+  userId: string,
+): Promise<void> {
+  const issue = deps.issueOperatorToken ?? issueOperatorToken;
+  try {
+    const existing = await readOperatorTokenFile(deps.configDir);
+    if (existing !== null) return;
+    await issue(deps.db, userId, { issuer: deps.issuer, dir: deps.configDir });
+  } catch (err) {
+    // Non-fatal: the admin + session were already committed. Log for the
+    // operator's debugging; they can recover with `parachute auth
+    // rotate-operator` from a shell on the box.
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[setup-wizard] operator-token closure skipped for new admin: ${msg}`);
+  }
+}
+
 /**
  * Static error page surfaced when an `/admin/setup/account` POST arrives
  * after the bootstrap token has already been consumed by a successful