@openparachute/hub 0.7.3-rc.7 → 0.7.3-rc.9

package/src/commands/wizard-transcription.ts

@@ -0,0 +1,296 @@
+/**
+ * Transcription step for the CLI setup wizard (`parachute setup-wizard` /
+ * `parachute init`).
+ *
+ * Until now the CLI wizard NEVER asked about transcription — it walked
+ * Account → Vault → Expose and stopped, while the browser wizard's vault step
+ * folds a full scribe sub-form (none / cloud + key / local). That divergence
+ * is the "asks different questions in its CLI vs browser forms" root cause from
+ * the onboarding-streamline arc. This module brings the CLI to parity.
+ *
+ * Crucially it follows the arc's "never ask without doing" rule: when the
+ * operator picks a provider we ACTUALLY set it up, or honestly say we couldn't
+ * and point at the alternative — we never record a dead provider string.
+ *
+ *   - **none**  → write nothing; say transcription is off + how to turn it on.
+ *   - **cloud** (groq / openai) → write provider + key (scribe-config.ts), then
+ *     install + start scribe via the hub's own `parachute install scribe`
+ *     one-shot. The very-first scribe boot reads the provider we just wrote.
+ *   - **local** → RAM/platform-gate FIRST (decideLocalProvider). If the box
+ *     can't run a local model (no backend for the platform, or < 2 GB RAM) we
+ *     do NOT write `local` — we explain why + steer to the cloud one-shot. If
+ *     it can, we install scribe, then run scribe's own runnable install routine
+ *     (`parachute-scribe install-backend --provider <onnx-asr|parakeet-mlx>`,
+ *     scribe PR #79) which apt/pip-installs the engine + warm-pulls the model
+ *     and exits non-zero on hard failure. On success we record the resolved
+ *     platform provider; on failure we say so + point at cloud, recording
+ *     nothing.
+ *
+ * Everything that touches the host (subprocess spawn, RAM probe, the prompt)
+ * goes through an injected seam so tests exercise every branch WITHOUT
+ * installing anything or shelling out.
+ */
+
+import { createInterface } from "node:readline/promises";
+import {
+  type ScribeProviderKey,
+  apiKeyEnvFor,
+  clearScribeProvider,
+  decideLocalProvider,
+  readAvailableRamMib,
+} from "../scribe-config.ts";
+
+/** Outcome of one subprocess. Exit code only — stdio is inherited / streamed. */
+export type WizardCommandRunner = (cmd: readonly string[]) => Promise<number>;
+
+export interface TranscriptionStepOpts {
+  /** `~/.parachute` (or the PARACHUTE_HOME override). Where scribe config lives. */
+  configDir: string;
+  /** Log shim — production prints to stdout; tests capture into an array. */
+  log: (line: string) => void;
+  /** Prompt seam — production uses readline; tests inject a scripted queue. */
+  prompt?: (question: string) => Promise<string>;
+  /**
+   * Pre-supply the choice non-interactively (mirrors the wizard's other
+   * run-from-flag escapes). `none` | `local` | a cloud provider name.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud API key (for `groq` / `openai`). */
+  transcribeApiKey?: string;
+  /**
+   * Command runner seam. Production spawns the real binary inheriting stdio;
+   * tests inject a recorder so nothing installs. Receives a full argv —
+   * `["parachute", "install", "scribe", ...]` or
+   * `["parachute-scribe", "install-backend", "--provider", "onnx-asr"]`.
+   */
+  runCommand?: WizardCommandRunner;
+  /** Platform override (test seam). Defaults to the real host platform. */
+  platform?: NodeJS.Platform;
+  /** Available-RAM override in MiB (test seam). Defaults to the real probe. */
+  availableRamMib?: number | null;
+}
+
+/** Default readline prompt (matches wizard.ts's defaultPrompt). */
+async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Default command runner: spawn the binary, inherit stdio so the operator sees
+ * apt/pip progress in real time, resolve to the exit code. Never throws — a
+ * spawn failure (binary not on PATH) surfaces as a non-zero code, which the
+ * caller treats as "couldn't install."
+ */
+const defaultRunCommand: WizardCommandRunner = async (cmd) => {
+  try {
+    const proc = Bun.spawn([...cmd], {
+      stdout: "inherit",
+      stderr: "inherit",
+      stdin: "inherit",
+    });
+    return await proc.exited;
+  } catch {
+    return 127; // ENOENT / spawn failure → "command not found"
+  }
+};
+
+/**
+ * Walk the transcription step. Returns 0 always — a transcription that
+ * couldn't be set up is reported honestly but does NOT fail the wizard (the
+ * operator can finish setup and add it later; it's not a blocking step).
+ */
+export async function walkTranscriptionStep(opts: TranscriptionStepOpts): Promise<number> {
+  const log = opts.log;
+  const prompt = opts.prompt ?? defaultPrompt;
+  const runCommand = opts.runCommand ?? defaultRunCommand;
+  const platform = opts.platform ?? process.platform;
+
+  log("");
+  log("Step — Transcription (scribe)");
+  log("  Parachute can transcribe voice notes + audio attachments. Pick a");
+  log("  transcription engine, or skip and add one later.");
+
+  // Resolve the choice (flag or prompt).
+  const choice = await resolveChoice(opts, prompt, log);
+  if (choice === "none") {
+    log("");
+    log("  Transcription off. Turn it on later with `parachute install scribe`.");
+    return 0;
+  }
+
+  if (choice === "local") {
+    return await handleLocal(opts, prompt, runCommand, platform, log);
+  }
+
+  // Cloud provider (groq / openai).
+  return await handleCloud(opts, choice, prompt, runCommand, log);
+}
+
+type ResolvedChoice = "none" | "local" | "groq" | "openai";
+
+async function resolveChoice(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  log: (l: string) => void,
+): Promise<ResolvedChoice> {
+  if (opts.transcribeMode !== undefined) return opts.transcribeMode;
+  log("");
+  log("  1) None — skip transcription (default)");
+  log("  2) Local — run the engine on this box (no API key, needs ~2 GB RAM)");
+  log("  3) Cloud — Groq or OpenAI (fast, needs an API key, ~$0.04/hr of audio)");
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const raw = (await prompt("  Pick [1]: ")).trim().toLowerCase();
+    if (raw === "" || raw === "1" || raw === "none" || raw === "n") return "none";
+    if (raw === "2" || raw === "local" || raw === "l") return "local";
+    if (raw === "3" || raw === "cloud" || raw === "c") {
+      // Sub-pick which cloud provider.
+      for (let inner = 0; inner < 5; inner++) {
+        const which = (await prompt("  Cloud provider — [g]roq (default) or [o]penai: "))
+          .trim()
+          .toLowerCase();
+        if (which === "" || which === "g" || which === "groq") return "groq";
+        if (which === "o" || which === "openai") return "openai";
+        log(`  Sorry — expected groq or openai (got "${which}"). Try again.`);
+      }
+      log("  Too many invalid entries; skipping transcription.");
+      return "none";
+    }
+    if (raw === "groq" || raw === "g") return "groq";
+    if (raw === "openai" || raw === "o") return "openai";
+    log(`  Sorry — expected 1, 2, or 3 (got "${raw}"). Try again.`);
+  }
+  log("  Too many invalid entries; skipping transcription.");
+  return "none";
+}
+
+async function handleCloud(
+  opts: TranscriptionStepOpts,
+  provider: "groq" | "openai",
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  log: (l: string) => void,
+): Promise<number> {
+  const envKey = apiKeyEnvFor(provider as ScribeProviderKey);
+  let apiKey = opts.transcribeApiKey;
+  if (apiKey === undefined && envKey) {
+    apiKey = (await prompt(`  Paste your ${envKey} (or blank to set later): `)).trim();
+  }
+
+  // Install + start scribe via the EXISTING one-shot path, handing it the
+  // chosen provider + key. `parachute install scribe --scribe-provider <p>
+  // [--scribe-key <k>]` writes the provider into scribe's config + the key into
+  // scribe/.env and starts the module — the same wiring the bare CLI install
+  // does. Passing the provider also suppresses install's own interactive
+  // provider prompt (it's already an explicit choice).
+  const cmd = ["parachute", "install", "scribe", "--scribe-provider", provider];
+  if (envKey && apiKey && apiKey.length > 0) {
+    cmd.push("--scribe-key", apiKey);
+  }
+  log("");
+  log(`  Installing scribe with the ${provider} cloud provider…`);
+  const code = await runCommand(cmd);
+  if (code !== 0) {
+    log(`  ✗ scribe install returned ${code}. Retry: \`${cmd.join(" ")}\`.`);
+    return 0;
+  }
+  if (envKey && !(apiKey && apiKey.length > 0)) {
+    log(
+      `  ✓ Recorded ${provider}. Add ${envKey} later: \`echo '${envKey}=<value>' >> ${opts.configDir}/scribe/.env\` then \`parachute restart scribe\`.`,
+    );
+  } else {
+    log(`  ✓ Scribe installed and running with the ${provider} cloud provider.`);
+  }
+  return 0;
+}
+
+async function handleLocal(
+  opts: TranscriptionStepOpts,
+  prompt: (q: string) => Promise<string>,
+  runCommand: WizardCommandRunner,
+  platform: NodeJS.Platform,
+  log: (l: string) => void,
+): Promise<number> {
+  const ramMib =
+    opts.availableRamMib !== undefined ? opts.availableRamMib : readAvailableRamMib(platform);
+  const decision = decideLocalProvider(platform, ramMib);
+
+  if (!decision.ok) {
+    // Can't install local here — say EXACTLY why + point at the cloud one-shot.
+    // Do NOT record a dead `local` provider string.
+    log("");
+    log(`  ✗ Local transcription isn't possible on this box: ${decision.reason}`);
+    log("");
+    log("  One-shot cloud alternative — get a free Groq key at https://console.groq.com,");
+    log("  then run:");
+    log("    parachute install scribe --scribe-provider groq --scribe-key gsk_…");
+    log("  (or re-run this wizard and choose Cloud).");
+    return 0;
+  }
+
+  const provider = decision.provider as "parakeet-mlx" | "onnx-asr";
+  log("");
+  log(`  This box can run ${provider} locally.`);
+
+  // Confirm before the (slow, apt/pip) install unless pre-supplied.
+  if (opts.transcribeMode === undefined) {
+    const ok = (await prompt(`  Install ${provider} now? [Y/n]: `)).trim().toLowerCase();
+    if (ok === "n" || ok === "no") {
+      log(
+        "  Skipped. Install later with `parachute-scribe install-backend` or re-run this wizard.",
+      );
+      return 0;
+    }
+  }
+
+  // Install the scribe module first, recording the resolved provider so install
+  // doesn't prompt for one. (We UNDO this record below if the engine install
+  // fails — so a failure never leaves a dead provider string.)
+  log("");
+  log("  Installing the scribe module…");
+  const moduleCode = await runCommand([
+    "parachute",
+    "install",
+    "scribe",
+    "--scribe-provider",
+    provider,
+  ]);
+  if (moduleCode !== 0) {
+    clearScribeProvider(opts.configDir);
+    log(`  ✗ scribe module install returned ${moduleCode} — not recording a local provider.`);
+    return 0;
+  }
+
+  // Run scribe's OWN runnable install routine (scribe PR #79). It apt/pip-
+  // installs the engine, warm-pulls the model, and exits non-zero on hard
+  // failure (no engine on PATH, too little RAM on its own re-check, etc.).
+  log("");
+  log(`  Installing the ${provider} engine via scribe (this can take a few minutes)…`);
+  // The `--provider <p>` FLAG form is intentional (not the positional
+  // `install-backend <p>`): scribe's cmdInstallBackend reads it via getFlag
+  // when args[1] starts with "-". If scribe ever moves off its module-level
+  // `args` global, re-confirm this flag is still honored.
+  const code = await runCommand(["parachute-scribe", "install-backend", "--provider", provider]);
+  if (code !== 0) {
+    // HONEST skip — undo the provisional provider record; do NOT leave a dead
+    // provider string scribe can't honor.
+    clearScribeProvider(opts.configDir);
+    log("");
+    log(`  ✗ ${provider} install failed (exit ${code}); not recording it as the provider.`);
+    log(
+      "    Cloud alternative: `parachute install scribe --scribe-provider groq --scribe-key gsk_…`",
+    );
+    return 0;
+  }
+
+  // Engine installed + verified by scribe — keep the provider recorded (the
+  // install step already wrote it) and restart so the running scribe picks it up.
+  log("");
+  log(`  ✓ ${provider} installed and recorded as the transcription provider.`);
+  await runCommand(["parachute", "restart", "scribe"]);
+  return 0;
+}

package/src/commands/wizard.ts

@@ -39,8 +39,10 @@
  */
 
 import { createInterface } from "node:readline/promises";
+import { configDir } from "../config.ts";
 import { CSRF_COOKIE_NAME, CSRF_FIELD_NAME } from "../csrf.ts";
 import { SESSION_COOKIE_NAME } from "../sessions.ts";
+import { type WizardCommandRunner, walkTranscriptionStep } from "./wizard-transcription.ts";
 
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes — generous enough for a slow `bun add` over a flaky connection.
@@ -111,6 +113,29 @@ export interface RunCliWizardOpts {
    * the wizard's.
    */
   exposeMode?: "localhost" | "tailnet" | "public";
+  /**
+   * `~/.parachute` (or the PARACHUTE_HOME override) — where scribe's config
+   * lives. Required for the transcription step to write the chosen provider +
+   * key. Init passes its resolved configDir; when absent the transcription
+   * step is skipped (the wizard can still walk account / vault / expose).
+   */
+  configDir?: string;
+  /**
+   * Pre-supply the transcription answer (non-interactive escape, mirrors the
+   * browser wizard's `scribe_provider`). `none` | `local` | `groq` | `openai`.
+   */
+  transcribeMode?: "none" | "local" | "groq" | "openai";
+  /** Pre-supplied cloud transcription API key (groq / openai). */
+  transcribeApiKey?: string;
+  /**
+   * Test seam: replace the transcription step's subprocess runner so tests
+   * never install scribe / shell out. Threaded into `walkTranscriptionStep`.
+   */
+  transcribeRunCommand?: WizardCommandRunner;
+  /** Test seam: platform override for the transcription step. */
+  platform?: NodeJS.Platform;
+  /** Test seam: available-RAM override (MiB) for the transcription step's gate. */
+  availableRamMib?: number | null;
 }
 
 /** Cookie jar — tiny, in-memory, no persistence across runs. */
@@ -395,9 +420,14 @@ async function pollOperation(
   }
 }
 
-/** Validate password length up front so we don't bounce off a 400 the operator can't see. */
+/**
+ * Validate password length up front so we don't bounce off a 400 the operator
+ * can't see. Floor is 12 to match the server (`PASSWORD_MIN_LEN`) AND this
+ * wizard's own "min 12 chars" copy at the password prompt — the validator was
+ * stuck at 8, contradicting both (onboarding-streamline hub PR1).
+ */
 function validatePassword(pw: string): string | undefined {
-  if (pw.length < 8) return "Password must be at least 8 characters.";
+  if (pw.length < 12) return "Password must be at least 12 characters.";
   return undefined;
 }
 
@@ -743,6 +773,24 @@ export async function runCliWizard(opts: RunCliWizardOpts): Promise<number> {
     if (code !== 0) return code;
     state = await fetchWizardState(hubUrl, jar, fetchImpl);
   }
+  // Transcription step (onboarding-streamline hub PR1) — the CLI's parity with
+  // the browser wizard's folded scribe sub-form. The hub's setup-state machine
+  // has no "transcription" step (scribe is a module install, not a wizard gate),
+  // so this runs unconditionally between vault and expose rather than off
+  // `state.step`. Skipped without a configDir (nowhere to write scribe config).
+  // Non-fatal: a transcription that couldn't be set up never blocks setup.
+  if (opts.configDir !== undefined) {
+    await walkTranscriptionStep({
+      configDir: opts.configDir,
+      log,
+      prompt,
+      ...(opts.transcribeMode !== undefined ? { transcribeMode: opts.transcribeMode } : {}),
+      ...(opts.transcribeApiKey !== undefined ? { transcribeApiKey: opts.transcribeApiKey } : {}),
+      ...(opts.transcribeRunCommand !== undefined ? { runCommand: opts.transcribeRunCommand } : {}),
+      ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+      ...(opts.availableRamMib !== undefined ? { availableRamMib: opts.availableRamMib } : {}),
+    });
+  }
   if (state.step === "expose") {
     const code = await walkExposeStep(hubUrl, jar, state, ctx);
     if (code !== 0) return code;
@@ -852,6 +900,21 @@ export function parseWizardArgs(args: readonly string[]): ParsedWizardArgs | { e
         }
         out.opts.exposeMode = value;
         break;
+      case "--transcribe-mode":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        if (value !== "none" && value !== "local" && value !== "groq" && value !== "openai") {
+          return { error: `${key} must be one of none, local, groq, openai` };
+        }
+        out.opts.transcribeMode = value;
+        break;
+      case "--transcribe-key":
+        if (!consumeValue()) return { error: `${key} requires a value` };
+        out.opts.transcribeApiKey = value;
+        break;
+      case "--config-dir":
+        if (!consumeValue()) return { error: `${key} requires a path` };
+        out.opts.configDir = value;
+        break;
       default:
         if (a.startsWith("--")) return { error: `unknown argument "${a}"` };
         return { error: `unexpected positional argument "${a}"` };
@@ -877,12 +940,19 @@ export async function runSetupWizardCommand(args: readonly string[]): Promise<nu
         "                              [--bootstrap-token <token>]\n" +
         "                              [--vault-mode create|import|skip] [--vault-name <name>]\n" +
         "                              [--vault-import-url <url>] [--vault-import-pat <pat>] [--vault-import-replace]\n" +
+        "                              [--transcribe-mode none|local|groq|openai] [--transcribe-key <key>]\n" +
+        "                              [--config-dir <path>]\n" +
         "                              [--expose-mode localhost|tailnet|public]",
     );
     return 1;
   }
+  // Default configDir from PARACHUTE_HOME (matching the rest of the CLI) so the
+  // standalone `parachute setup-wizard` invocation can run the transcription
+  // step. An explicit `--config-dir` wins.
+  const wizardOpts = { ...parsed.opts };
+  if (wizardOpts.configDir === undefined) wizardOpts.configDir = configDir();
   return await runCliWizard({
-    ...parsed.opts,
+    ...wizardOpts,
     log: (line) => console.log(line),
   });
 }

package/src/hub-origin.ts

@@ -14,6 +14,70 @@
 
 export const HUB_ORIGIN_ENV = "PARACHUTE_HUB_ORIGIN";
 
+/**
+ * The env var carrying the SET of origins the hub legitimately answers on,
+ * comma-separated (multi-origin iss-set, onboarding-streamline 2026-06-25).
+ *
+ * Supervised resource servers (vault, scribe) read this in addition to the
+ * single canonical `PARACHUTE_HUB_ORIGIN` and widen their accepted-`iss` check
+ * from one string to this set — so a token minted under one URL of a
+ * multi-URL box (loopback ∪ `<ip>.sslip.io` ∪ a custom domain behind Caddy)
+ * validates when the resource is reached via another URL of the SAME box. The
+ * signing key is stable + origin-independent, so only the `iss` string varies.
+ *
+ * SECURITY INVARIANT: the value MUST be the hub's `buildHubBoundOrigins`
+ * output — configured issuer ∪ loopback aliases ∪ expose-state public origin ∪
+ * platform origin — published BY THE HUB. It must NEVER contain an unvalidated
+ * request `Host` / `X-Forwarded-Host`. Accepting `iss ∈ this-set` is safe
+ * ONLY because the resource server's JWKS signature verify runs first and
+ * proves the hub minted the token.
+ *
+ * `PARACHUTE_HUB_ORIGIN` (the single canonical origin) is ALWAYS written
+ * alongside this var for back-compat: a resource server on an older
+ * scope-guard that doesn't read `PARACHUTE_HUB_ORIGINS` keeps its existing
+ * single-origin behavior.
+ */
+export const HUB_ORIGINS_ENV = "PARACHUTE_HUB_ORIGINS";
+
+/**
+ * Serialize an origin SET into the comma-separated `PARACHUTE_HUB_ORIGINS`
+ * wire form. Dedupes, drops empties, preserves first-seen order. Returns
+ * `undefined` when nothing survives (caller skips setting the env var so a
+ * resource server falls back to single-origin behavior). Pair with
+ * `buildHubBoundOrigins` to produce `origins`.
+ */
+export function serializeHubOrigins(origins: readonly string[]): string | undefined {
+  const seen = new Set<string>();
+  for (const raw of origins) {
+    if (typeof raw !== "string") continue;
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (trimmed.length > 0) seen.add(trimmed);
+  }
+  if (seen.size === 0) return undefined;
+  return Array.from(seen).join(",");
+}
+
+/**
+ * Parse the comma-separated `PARACHUTE_HUB_ORIGINS` wire form back into an
+ * origin array. Tolerant of surrounding whitespace + trailing slashes + empty
+ * segments. The resource-server inverse of `serializeHubOrigins`; lives here
+ * (rather than only in the consumer adapters) so the hub's own injection tests
+ * can round-trip against the canonical parser. Returns `[]` for an
+ * absent/empty/garbage value.
+ */
+export function parseHubOrigins(raw: string | undefined): string[] {
+  if (!raw) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const seg of raw.split(",")) {
+    const trimmed = seg.trim().replace(/\/+$/, "");
+    if (trimmed.length === 0 || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
 export interface DeriveHubOriginOpts {
   /** Explicit user override (e.g., `--hub-origin`). Wins over everything else. */
   override?: string;

package/src/jwt-sign.ts

@@ -55,9 +55,20 @@ export interface SignAccessTokenOpts {
   clientId: string;
   /**
    * Hub origin — sets the `iss` claim. Required: every consumer (vault,
-   * scribe, channel) validates `iss` against `PARACHUTE_HUB_ORIGIN`, and a
-   * missing claim is rejected. Callers derive this via `deriveHubOrigin()`
-   * or thread it from `OAuthDeps.issuer`.
+   * scribe, agent) validates `iss`, and a missing claim is rejected. Callers
+   * derive this via `deriveHubOrigin()` or thread it from `OAuthDeps.issuer`
+   * (the per-request origin from `resolveIssuer`).
+   *
+   * Multi-origin iss-set (onboarding-streamline 2026-06-25): consumers no
+   * longer pin `iss` to a SINGLE `PARACHUTE_HUB_ORIGIN`. The hub publishes the
+   * SET of origins it legitimately answers on via `PARACHUTE_HUB_ORIGINS`
+   * (`buildHubBoundOrigins` — issuer ∪ loopback ∪ expose-state ∪ platform),
+   * and a scope-guard ≥0.5.0 consumer accepts `iss` ∈ that set. So a token
+   * minted here with one URL of a multi-URL box validates when the resource is
+   * reached via another URL of the SAME box. Mint stays per-request as-is: the
+   * canonical configured origin (the intended Caddy/zero-SSH deploy) is minted
+   * on every request AND is a member of the published set, so mint and validate
+   * already align — no clamp needed here.
    */
   issuer: string;
   /**

package/src/scribe-config.ts

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { totalmem } from "node:os";
 import { dirname, join } from "node:path";
 import { parseEnvFile, upsertEnvLine, writeEnvFile } from "./env-file.ts";
 
@@ -60,6 +61,118 @@ export type ScribeProviderKey = (typeof SCRIBE_PROVIDERS)[number]["key"];
 /** Default provider scribe falls back to when the config doesn't pick one. */
 export const SCRIBE_DEFAULT_PROVIDER: ScribeProviderKey = "parakeet-mlx";
 
+/**
+ * Resolve the "local" choice to the CORRECT platform backend. The setup
+ * wizard (browser + CLI) lets the operator pick "local" without knowing the
+ * engine name; this picks the one that actually runs here.
+ *
+ *   - macOS  → `parakeet-mlx` (Apple Silicon MLX)
+ *   - Linux  → `onnx-asr`     (cross-platform Sherpa-ONNX)
+ *   - other  → `null`         (no local backend — steer to cloud)
+ *
+ * Mirrors scribe's own `platformLocalProvider` (parachute-scribe
+ * src/install-backend.ts) so hub and scribe can't drift on the mapping.
+ * Fixes the long-standing bug where the wizard mapped `local` UNCONDITIONALLY
+ * to `parakeet-mlx`, which silently fails on every Linux box (the common
+ * DigitalOcean / VPS deploy).
+ */
+export function platformLocalProvider(
+  platform: NodeJS.Platform,
+): "parakeet-mlx" | "onnx-asr" | null {
+  if (platform === "darwin") return "parakeet-mlx";
+  if (platform === "linux") return "onnx-asr";
+  return null;
+}
+
+/**
+ * Minimum available RAM (MiB) below which a local ASR model would be
+ * OOM-killed. Mirrors scribe's `MIN_RAM_MIB` (parachute-scribe
+ * src/install-backend.ts) — the 1 GB DigitalOcean droplet is the box this
+ * guards against; a local Parakeet/ONNX model needs ~2 GB to load.
+ */
+export const MIN_RAM_MIB = 2048;
+
+/**
+ * Available RAM in MiB, or `null` when it can't be determined.
+ *
+ * Linux: reads `MemAvailable` from `/proc/meminfo` (the honest figure — free
+ * plus reclaimable cache), matching scribe's probe so the two layers agree on
+ * the same droplet. Falls back to `MemFree` on very old kernels that predate
+ * MemAvailable.
+ *
+ * Non-Linux: falls back to `os.totalmem()` (there's no MemAvailable analogue;
+ * total is a coarse upper bound but enough to keep a tiny VM from offering
+ * local). macOS dev boxes comfortably clear the floor, so the coarseness is
+ * harmless there.
+ *
+ * Sync by design: the wizard's provider-decision path is synchronous, and the
+ * `/proc/meminfo` read is a tiny file. Tests inject `availableRamMib` directly
+ * to exercise the gate without touching the real host.
+ */
+export function readAvailableRamMib(platform: NodeJS.Platform = process.platform): number | null {
+  if (platform === "linux") {
+    try {
+      const text = readFileSync("/proc/meminfo", "utf8");
+      const avail = /^MemAvailable:\s+(\d+)\s*kB/m.exec(text);
+      const free = /^MemFree:\s+(\d+)\s*kB/m.exec(text);
+      const kb = avail ? Number(avail[1]) : free ? Number(free[1]) : null;
+      if (kb === null || !Number.isFinite(kb)) return null;
+      return Math.floor(kb / 1024);
+    } catch {
+      return null;
+    }
+  }
+  // Non-Linux: total physical memory as a coarse fallback.
+  try {
+    const bytes = totalmem();
+    if (!Number.isFinite(bytes) || bytes <= 0) return null;
+    return Math.floor(bytes / (1024 * 1024));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide whether a LOCAL transcription provider is offerable / acceptable on
+ * this host, and if not, why + what to steer to. Both wizard surfaces (browser
+ * POST handler + CLI) consult this BEFORE recording a `local` choice so we
+ * never write a dead provider string that scribe can't run.
+ *
+ * `ok: false` carries a `reason` (shown inline) and a `steerTo` cloud provider
+ * the caller should redirect to.
+ */
+export interface LocalProviderDecision {
+  ok: boolean;
+  /** The resolved platform backend when `ok` (parakeet-mlx / onnx-asr). */
+  provider?: "parakeet-mlx" | "onnx-asr";
+  /** Human-readable reason when `ok` is false (no local backend / too little RAM). */
+  reason?: string;
+  /** Cloud provider to redirect to when local is unavailable. */
+  steerTo?: "groq";
+}
+
+export function decideLocalProvider(
+  platform: NodeJS.Platform,
+  availableRamMib: number | null,
+): LocalProviderDecision {
+  const provider = platformLocalProvider(platform);
+  if (provider === null) {
+    return {
+      ok: false,
+      reason: `No local transcription backend runs on "${platform}". Use a cloud provider instead.`,
+      steerTo: "groq",
+    };
+  }
+  if (availableRamMib !== null && availableRamMib < MIN_RAM_MIB) {
+    return {
+      ok: false,
+      reason: `This box has ${availableRamMib} MiB available RAM, below the ${MIN_RAM_MIB} MiB a local ASR model needs (it would be OOM-killed). Use a cloud provider instead — groq is fast (~$0.04/hr of audio).`,
+      steerTo: "groq",
+    };
+  }
+  return { ok: true, provider };
+}
+
 export function isKnownScribeProvider(value: string): value is ScribeProviderKey {
   return SCRIBE_PROVIDERS.some((p) => p.key === value);
 }
@@ -136,6 +249,38 @@ export function writeScribeProvider(configDir: string, provider: ScribeProviderK
   renameSync(tmp, path);
 }
 
+/**
+ * Remove `transcribe.provider` from scribe's config.json (preserving every
+ * other key). Used by the wizard's local-install path to UNDO a provisional
+ * provider record when the engine install fails — so we never leave a dead
+ * provider string scribe can't honor. A no-op when the file or the
+ * `transcribe` block is absent.
+ */
+export function clearScribeProvider(configDir: string): void {
+  const path = scribeConfigPath(configDir);
+  if (!existsSync(path)) return;
+  let current: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    current = parsed as Record<string, unknown>;
+  } catch {
+    return; // malformed → leave it; auto-wire repairs on next run
+  }
+  const transcribe = current.transcribe;
+  if (typeof transcribe !== "object" || transcribe === null || Array.isArray(transcribe)) {
+    return;
+  }
+  // Drop `provider` from the transcribe block (destructure-omit, no `delete`).
+  const { provider: _dropped, ...block } = transcribe as Record<string, unknown>;
+  const { transcribe: _omit, ...rest } = current;
+  const next: Record<string, unknown> =
+    Object.keys(block).length === 0 ? rest : { ...rest, transcribe: block };
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
 /**
  * Idempotent upsert of a single `KEY=value` into `<configDir>/scribe/.env`.
  * Used for the API-key prompt result. Other lines (auto-wire keys, manual