patchwork-os 0.2.0-beta.0 → 0.2.0-beta.10

package/dist/index.js

@@ -41,7 +41,10 @@ import { Bridge } from "./bridge.js";
 import { isBridgeToolsFileValid, repairBridgeToolsRulesIfStale, } from "./bridgeToolsRules.js";
 import { findEditor, parseConfig } from "./config.js";
 import { detectWorkspaceSymlinkInstall, PATCHWORK_PACKAGE_NAME, SYMLINK_INSTALL_FIX, } from "./installGuard.js";
+import { treeKill } from "./processTree.js";
 import { PACKAGE_VERSION, semverGt } from "./version.js";
+import { ensureCmdShim } from "./winShim.js";
+import { writeFileAtomicSync } from "./writeFileAtomic.js";
 const __dirnameTop = path.dirname(fileURLToPath(import.meta.url));
 // Warn when a symlinked global install is detected (`npm install -g .`).
 // launchctl / sandbox environments can fail through that link with EPERM.
@@ -63,7 +66,7 @@ const OPEN_VSX_NAME = "claude-ide-bridge-extension";
 // CLAUDE.md versioned-block patching moved to ./claudeMdPatch.ts so tests
 // can import the helpers without triggering the top-level CLI side effects
 // at the bottom of this file. Re-exported here for back-compat.
-export { BRIDGE_BLOCK_END, BRIDGE_BLOCK_RE, bridgeBlockStartMarker, extractClaudeMdBlockVersion, patchClaudeMdImport, } from "./claudeMdPatch.js";
+export { BRIDGE_BLOCK_END, bridgeBlockStartMarker, extractClaudeMdBlockVersion, patchClaudeMdImport, replaceAllBridgeBlocks, } from "./claudeMdPatch.js";
 import { extractClaudeMdBlockVersion, patchClaudeMdImport, } from "./claudeMdPatch.js";
 /**
  * Downloads the latest VSIX from Open VSX Registry to a temp file.
@@ -119,7 +122,6 @@ const KNOWN_SUBCOMMANDS = [
     "gen-plugin-stub",
     "notify",
     "install",
-    "marketplace",
     "status",
     "shim",
     "recipe",
@@ -128,6 +130,13 @@ const KNOWN_SUBCOMMANDS = [
     "dashboard",
     "launchd",
     "start",
+    "kill-switch",
+    "panic",
+    "halts",
+    "judgments",
+    "analytics",
+    "doctor",
+    "shadow-scan",
 ];
 const __invokedSubcommand = (() => {
     const sub = process.argv[2];
@@ -139,10 +148,20 @@ const __invokedSubcommand = (() => {
         ? sub
         : null;
 })();
+// bash/zsh set process.env._ to the actual invoked binary path (e.g. /usr/local/bin/patchwork-os).
+// More reliable than argv[1] which resolves to the .js entrypoint via npm global shim.
+function invokedBinaryName() {
+    const fromEnv = process.env._
+        ? path.basename(process.env._).replace(/\.(cmd|js)$/i, "")
+        : "";
+    if (fromEnv && fromEnv !== "node" && fromEnv !== "npm")
+        return fromEnv;
+    return path.basename(process.argv[1] ?? "").replace(/\.js$/, "");
+}
 const __invokedBareBinaryDashboard = (() => {
     if (process.argv[2] && process.argv[2] !== "dashboard")
         return false;
-    const binName = path.basename(process.argv[1] ?? "");
+    const binName = invokedBinaryName();
     return (binName === "patchwork-os" ||
         binName === "patchwork" ||
         binName === "patchwork.js");
@@ -153,6 +172,56 @@ if (process.argv[2] === "--version" || process.argv[2] === "-v") {
     console.log(`claude-ide-bridge ${PACKAGE_VERSION}`);
     process.exit(0);
 }
+// Handle top-level --help / -h / help — print a grouped command index so a
+// first-time user has a discoverable entry point. Without this, bare
+// `patchwork --help` falls through to bridge-daemon arg parsing and errors.
+if (process.argv[2] === "--help" ||
+    process.argv[2] === "-h" ||
+    process.argv[2] === "help") {
+    const binName = path.basename(process.argv[1] ?? "patchwork");
+    process.stdout.write(`${binName} ${PACKAGE_VERSION}\n\n` +
+        `First time? Run:\n` +
+        `  ${binName} init                          # set up ~/.patchwork + Claude Code hooks\n` +
+        `  ${binName} start-all                     # bridge + Claude + dashboard\n\n` +
+        `Get started\n` +
+        `  init [--workspace <dir>]                  Scaffold ~/.patchwork; register CC hooks\n` +
+        `  install-extension                         Install the VS Code / Cursor / Windsurf extension\n` +
+        `  start-all [--no-dashboard]                Launch bridge + Claude --ide + dashboard\n` +
+        `  start-orchestrator                        Multi-IDE-window meta-bridge\n\n` +
+        `Recipes\n` +
+        `  recipe new <name> [-i]                    Scaffold a recipe\n` +
+        `  recipe list                               List installed recipes\n` +
+        `  recipe run <name> [--vars k=v]            Run a recipe by name\n` +
+        `  recipe install <source>                   Install from a path or GitHub source\n` +
+        `  recipe --help                             Full recipe subcommand index\n\n` +
+        `Operate\n` +
+        `  start [--port N] [--workspace <dir>]      Start a single bridge (no tmux)\n` +
+        `  status                                    One-line bridge status (port, uptime)\n` +
+        `  tools [list|search <q>] [--slim] [--json] List tools the bridge would register\n` +
+        `  analytics <show|configure|clear|test>     Manage opt-in telemetry config\n` +
+        `  launchd <install|uninstall|status>        Manage the macOS auto-start LaunchAgent\n\n` +
+        `Diagnose\n` +
+        `  halts [--window 1h|24h|overnight|7d]      Morning summary of recent recipe halts\n` +
+        `  judgments [--window ...] [--recipe N]     Recent judge-step verdicts across runs\n` +
+        `  suggest [--since-days N]                  Recipe + unused-tool suggestions\n` +
+        `  token-efficiency benchmark                Measure token cost across tool sets\n` +
+        `  traces export                             Bundle approval / recipe / decision traces\n` +
+        `  print-token [--port N]                    Print the active bridge auth token\n\n` +
+        `Safety\n` +
+        `  kill-switch <engage|release|status>       Block / resume write-tier tools across bridges\n` +
+        `  panic [--reason "..."]                    Shorthand for kill-switch engage\n\n` +
+        `Daemon (no subcommand)\n` +
+        `  --workspace <dir>                         Start the bridge in foreground\n` +
+        `  --watch                                   Auto-restart supervisor\n` +
+        `  --slim                                    27 IDE-only tools (default: full)\n\n` +
+        `Other\n` +
+        `  --version, -v                             Print package version\n` +
+        `  shim                                      stdio↔WebSocket shim (used by MCP clients)\n` +
+        `  notify <event>                            Notify a running bridge of a CC hook event\n\n` +
+        `Bridge-daemon flags: run \`${binName} --workspace . --help-flags\` for the full list,\n` +
+        `or see https://github.com/Oolab-labs/patchwork-os#readme.\n`);
+    process.exit(0);
+}
 // Handle patchwork-init subcommand — T2 from docs/install-ux-plan.md.
 // Separate from the bridge-only `init` to preserve back-compat. See ADR-0008.
 if (process.argv[2] === "patchwork-init") {
@@ -160,6 +229,13 @@ if (process.argv[2] === "patchwork-init") {
     await runPatchworkInit(process.argv.slice(3));
     process.exit(0);
 }
+// `patchwork-os init` → dashboard setup, not IDE bridge installer.
+// patchwork init / claude-ide-bridge init still go to the bridge path below.
+if (process.argv[2] === "init" && invokedBinaryName() === "patchwork-os") {
+    const { runPatchworkInit } = await import("./commands/patchworkInit.js");
+    await runPatchworkInit(process.argv.slice(3));
+    process.exit(0);
+}
 // Handle start-all subcommand — launches the full 3-pane tmux orchestrator.
 // Also triggered when invoked as `claude-ide-bridge-start` directly.
 const isStartAll = process.argv[2] === "start-all" ||
@@ -168,8 +244,11 @@ if (isStartAll) {
     const startAllArgs = process.argv[2] === "start-all"
         ? process.argv.slice(3)
         : process.argv.slice(2);
-    const scriptPath = path.resolve(__dirnameTop, "..", "scripts", "start-all.sh");
-    const result = spawnSync("bash", [scriptPath, ...startAllArgs], {
+    // Dispatch the cross-platform Node orchestrator (start-all.mjs). The
+    // bash entry-point is kept as a developer shortcut but Windows has no
+    // `bash` on PATH by default, and the .mjs is functionally equivalent.
+    const scriptPath = path.resolve(__dirnameTop, "..", "scripts", "start-all.mjs");
+    const result = spawnSync(process.execPath, [scriptPath, ...startAllArgs], {
         stdio: "inherit",
     });
     process.exit(result.status ?? 1);
@@ -177,14 +256,16 @@ if (isStartAll) {
 // `patchwork start` — opinionated front door over start-all.
 // Defaults to full mode (all tools registered) and the web dashboard, so the
 // doc-promised "patchwork start → everything works" path actually works.
-// Pass-through args still go to start-all.sh; --help short-circuits.
+// Pass-through args still go to start-all.mjs; --help short-circuits.
 if (process.argv[2] === "start") {
     const passthrough = process.argv.slice(3);
     if (passthrough.includes("--help") || passthrough.includes("-h")) {
         process.stdout.write(`patchwork start — Launch the full Patchwork stack
 
-Starts bridge + Claude Code + dashboard in a tmux session.
+Starts bridge + Claude + dashboard via the cross-platform Node orchestrator.
 Defaults to full mode so all bridge tools are registered.
+On macOS/Linux: uses tmux when available, falls back to background mode.
+On Windows: runs natively via the Node orchestrator (no WSL required).
 
 Usage: patchwork start [options]
 
@@ -206,13 +287,20 @@ This is a thin wrapper over \`start-all\`. For advanced flags see:
     const args = [...passthrough];
     const slimIdx = args.indexOf("--slim");
     if (slimIdx >= 0) {
-        args.splice(slimIdx, 1); // strip — start-all.sh has no --slim flag, slim is its default
+        args.splice(slimIdx, 1); // slim is the .mjs default; strip so --full isn't re-added below
     }
     else if (!args.includes("--full")) {
         args.push("--full");
     }
-    const scriptPath = path.resolve(__dirnameTop, "..", "scripts", "start-all.sh");
-    const result = spawnSync("bash", [scriptPath, ...args], {
+    // On non-Windows: auto-detect tmux; fall back to --no-tmux background mode if absent.
+    if (process.platform !== "win32" && !args.includes("--no-tmux")) {
+        const tmuxCheck = spawnSync("which", ["tmux"], { stdio: "ignore" });
+        if (tmuxCheck.status !== 0)
+            args.push("--no-tmux");
+    }
+    // Dispatch to the cross-platform Node orchestrator (see above).
+    const scriptPath = path.resolve(__dirnameTop, "..", "scripts", "start-all.mjs");
+    const result = spawnSync(process.execPath, [scriptPath, ...args], {
         stdio: "inherit",
     });
     process.exit(result.status ?? 1);
@@ -368,12 +456,6 @@ if (process.argv[2] === "install") {
     await runInstall(process.argv.slice(3));
     process.exit(0);
 }
-// Handle marketplace subcommand — browse and install community skills
-if (process.argv[2] === "marketplace") {
-    const { runMarketplace } = await import("./commands/marketplace.js");
-    await runMarketplace(process.argv.slice(3));
-    process.exit(0);
-}
 // Handle tools subcommand — search/list tools without a bridge connection
 if (process.argv[2] === "tools") {
     const { runToolsCommand } = await import("./commands/tools.js");
@@ -884,6 +966,33 @@ Edit, save, hot-reload — Claude's next turn sees the new tool. See [documents/
     }
     process.exit(0);
 }
+// Patchwork: `patchwork recipe` (no subcommand) / `recipe --help` — print
+// the subcommand index. Without this branch, `patchwork recipe` falls through
+// to the bridge daemon, leaving subcommands completely undiscoverable from
+// the CLI (the only way to find them today is to read CLAUDE.md or source).
+if (process.argv[2] === "recipe" &&
+    (process.argv[3] === undefined ||
+        process.argv[3] === "--help" ||
+        process.argv[3] === "-h" ||
+        process.argv[3] === "help")) {
+    process.stdout.write(`Usage: patchwork recipe <subcommand> [args...]\n\n` +
+        `Subcommands:\n` +
+        `  new <name>         Scaffold a recipe (interactive with -i)\n` +
+        `  list               List installed recipes (workspace + user)\n` +
+        `  run <name>         Run a recipe by name\n` +
+        `  install <src>      Install a recipe from a path or GitHub source\n` +
+        `  uninstall <name>   Remove an installed recipe\n` +
+        `  enable <name>      Re-enable a disabled recipe\n` +
+        `  disable <name>     Pause a recipe (scheduled triggers stop firing)\n` +
+        `  preflight <file>   Static-validate a recipe YAML before running\n` +
+        `  doctor <name|file> Diagnose a recipe: lint + policy + recent halts\n` +
+        `  lint <file>        Run all lint checks on a recipe YAML\n` +
+        `  fmt <file>         Format a recipe YAML in place\n` +
+        `  schema             Print the recipe JSON Schema\n` +
+        `  audit-env <recipe> Check {{env.FOO}} vars are present in environment\n\n` +
+        `Run \`patchwork recipe <subcommand> --help\` for subcommand-specific options.\n`);
+    process.exit(0);
+}
 // Patchwork: `patchwork recipe list` — enumerate installed recipes.
 if (process.argv[2] === "recipe" && process.argv[3] === "list") {
     (async () => {
@@ -959,11 +1068,13 @@ if (process.argv[2] === "recipe" && process.argv[3] === "uninstall") {
 // a running bridge's /recipes/run endpoint if one is available.
 if (process.argv[2] === "recipe" && process.argv[3] === "run") {
     const args = process.argv.slice(4);
-    const usage = "Usage: patchwork recipe run <name-or-file> [--local] [--dry-run] [--step <id>] [--var KEY=VALUE]\n";
+    const usage = "Usage: patchwork recipe run <name-or-file> [--local] [--dry-run] [--step <id>] [--var KEY=VALUE] [--attempt <id>] [--ledger-dir <path>]\n";
     let localFlag = false;
     let dryRun = false;
     let recipeRef;
     let step;
+    let attemptId;
+    let ledgerDir;
     const vars = {};
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -990,6 +1101,29 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
             step = value;
             continue;
         }
+        if (currentArg === "--attempt" || currentArg.startsWith("--attempt=")) {
+            const value = currentArg === "--attempt"
+                ? args[++i]
+                : currentArg.slice("--attempt=".length);
+            if (!value) {
+                process.stderr.write(`Error: --attempt requires a value\n${usage}`);
+                process.exit(1);
+            }
+            attemptId = value;
+            continue;
+        }
+        if (currentArg === "--ledger-dir" ||
+            currentArg.startsWith("--ledger-dir=")) {
+            const value = currentArg === "--ledger-dir"
+                ? args[++i]
+                : currentArg.slice("--ledger-dir=".length);
+            if (!value) {
+                process.stderr.write(`Error: --ledger-dir requires a value\n${usage}`);
+                process.exit(1);
+            }
+            ledgerDir = value;
+            continue;
+        }
         if (currentArg === "--var" || currentArg.startsWith("--var=")) {
             const assignment = currentArg === "--var" ? args[++i] : currentArg.slice("--var=".length);
             if (!assignment) {
@@ -1036,7 +1170,7 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
             })();
             const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
             const lock = localFlag ? null : findBridgeLock();
-            if (lock && !dryRun && !step && !explicitFile) {
+            if (lock && !dryRun && !step && !explicitFile && !attemptId) {
                 const res = await fetch(`http://127.0.0.1:${lock.port}/recipes/run`, {
                     method: "POST",
                     headers: {
@@ -1079,9 +1213,37 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
                 ? `  Running step "${step}" from recipe "${recipeArg}" locally…\n`
                 : `  Running recipe "${recipeArg}" locally…\n`);
             const workdir = lock?.workspace || process.cwd();
+            // PR5c — resume support: when --attempt is given, mint or reuse a
+            // stable id and point the runner at a disk-backed effect ledger.
+            // `--attempt new` always mints a fresh id; any other value is
+            // taken verbatim (so the user can re-run the same attempt and
+            // skip already-completed write tools).
+            let resolvedAttempt;
+            let resolvedLedgerDir;
+            if (attemptId !== undefined) {
+                resolvedAttempt =
+                    attemptId === "new"
+                        ? `mr_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+                        : attemptId;
+                // Validate at the CLI boundary so an invalid id fails loudly
+                // before any side effects run (and before it lands in the run
+                // log or hashed into a ledger scope key).
+                try {
+                    const { assertValidManualRunId } = await import("./recipes/idempotencyKey.js");
+                    assertValidManualRunId(resolvedAttempt);
+                }
+                catch (err) {
+                    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+                    process.exit(1);
+                }
+                resolvedLedgerDir = ledgerDir ?? path.join(os.homedir(), ".patchwork");
+                process.stdout.write(`  Attempt id: ${resolvedAttempt} (ledger: ${resolvedLedgerDir})\n`);
+            }
             const run = await runRecipe(recipeArg, {
                 ...(step ? { step } : {}),
                 ...(seedVars ? { vars: seedVars } : {}),
+                ...(resolvedAttempt && { manualRunId: resolvedAttempt }),
+                ...(resolvedLedgerDir && { ledgerDir: resolvedLedgerDir }),
                 workdir,
             });
             if (run.stepSelection) {
@@ -1401,8 +1563,9 @@ if (process.argv[2] === "traces" && process.argv[3] === "import") {
                     }
                     const plain = decryptTraceBundle(raw, passphrase);
                     const { tmpdir } = await import("node:os");
+                    const { join: pathJoin } = await import("node:path");
                     const { writeFileSync } = await import("node:fs");
-                    const tmp = `${tmpdir()}/patchwork-import-${Date.now()}.jsonl.gz`;
+                    const tmp = pathJoin(tmpdir(), `patchwork-import-${Date.now()}.jsonl.gz`);
                     writeFileSync(tmp, plain, { mode: 0o600 });
                     input = tmp;
                     process.stderr.write("Decryption succeeded.\n");
@@ -1434,6 +1597,513 @@ if (process.argv[2] === "traces" && process.argv[3] === "import") {
         }
     })();
 }
+// `patchwork kill-switch engage|release|status` — issue #422 step 3.
+//
+// Discovers the running bridge via lock file, POSTs /kill-switch with
+// Bearer auth, and surfaces structured errors (env-locked, no-bridge,
+// wedged-bridge). Multi-bridge fan-out: iterates ALL live `isBridge:true`
+// locks and engages/releases each (v2-B2 from #422).
+//
+// v2-I4: mandatory 10s deadline per request. No silent fallback on
+// timeout/ECONNREFUSED/non-2xx — error message + exit non-zero.
+if (process.argv[2] === "kill-switch") {
+    const sub = process.argv[3];
+    if (!sub || (sub !== "engage" && sub !== "release" && sub !== "status")) {
+        process.stderr.write('Usage: patchwork kill-switch <engage|release|status> [--reason "..."]\n' +
+            "\n" +
+            "  engage   Block all write-tier tool calls across every running bridge.\n" +
+            "  release  Resume writes.\n" +
+            "  status   Print engaged/locked state per running bridge.\n" +
+            "\n" +
+            "Exits non-zero if any bridge is unreachable or env-locked.\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            // Parse optional flags early so --force-local can be used without a bridge.
+            const args = process.argv.slice(4);
+            const reasonIdx = args.findIndex((a) => a === "--reason" || a === "-m");
+            const reason = reasonIdx >= 0 && reasonIdx + 1 < args.length
+                ? args[reasonIdx + 1]
+                : undefined;
+            // v2-I4: --force-local writes flags.json directly when no live bridge
+            // is reachable. The running bridge's fs.watch (v2-S1) picks up the
+            // change within ~100ms; without a running bridge this is "effective
+            // next boot" — which is still better than a silent noop.
+            const forceLocal = args.includes("--force-local");
+            // v2-B2: enumerate ALL live bridge locks (not just the first).
+            const { findAllLiveBridges } = await import("./bridgeLockDiscovery.js");
+            const liveLocks = findAllLiveBridges();
+            if (liveLocks.length === 0) {
+                if (forceLocal && (sub === "engage" || sub === "release")) {
+                    // --force-local: write flags.json directly. The running bridge's
+                    // fs.watch picks this up within ~100ms; if the bridge is wedged
+                    // or not started, this is effective on next start.
+                    const { setFlag, KILL_SWITCH_WRITES } = await import("./featureFlags.js");
+                    const engage = sub === "engage";
+                    setFlag(KILL_SWITCH_WRITES, engage, true);
+                    // Audit in a sibling CLI-only JSONL (v2-I10: bridge-only writes
+                    // go to decision_traces.jsonl; CLI fallback is distinct).
+                    const os = await import("node:os");
+                    const path = await import("node:path");
+                    const fs = await import("node:fs");
+                    const cliTraceFile = path.join(process.env.PATCHWORK_HOME ??
+                        path.join(os.default.homedir(), ".patchwork"), "decision_traces.cli.jsonl");
+                    const dir = path.dirname(cliTraceFile);
+                    if (!fs.existsSync(dir))
+                        fs.mkdirSync(dir, { recursive: true });
+                    const entry = JSON.stringify({
+                        ts: new Date().toISOString(),
+                        event: engage ? "engage" : "release",
+                        actor: "cli-force-local",
+                        ...(reason ? { reason } : {}),
+                    });
+                    fs.appendFileSync(cliTraceFile, `${entry}\n`);
+                    process.stdout.write(`  ✓ kill-switch ${engage ? "ENGAGED" : "released"} via --force-local (flags.json written directly).\n` +
+                        "    Running bridges will pick this up via fs.watch within ~100ms.\n");
+                    process.exit(0);
+                }
+                process.stderr.write("No running bridge found.\n" +
+                    "  - For `engage`/`release`, kill-switch has no live target to update.\n" +
+                    "  - Use --force-local to write flags.json directly (bridge fs.watch picks it up).\n" +
+                    "  - Or restart the bridge and re-run this command.\n");
+                process.exit(2);
+            }
+            // v2-I4: 10s per-request deadline. AbortController per call.
+            async function callBridge(lock, method, body) {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 10_000);
+                try {
+                    const res = await fetch(`http://127.0.0.1:${lock.port}/kill-switch`, {
+                        method,
+                        headers: {
+                            Authorization: `Bearer ${lock.authToken}`,
+                            "Content-Type": "application/json",
+                        },
+                        ...(body ? { body: JSON.stringify(body) } : {}),
+                        signal: controller.signal,
+                    });
+                    let json;
+                    try {
+                        json = (await res.json());
+                    }
+                    catch {
+                        json = undefined;
+                    }
+                    return {
+                        ok: res.status >= 200 && res.status < 300,
+                        status: res.status,
+                        ...(json ? { json } : {}),
+                    };
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        status: 0,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            if (sub === "status") {
+                let anyFailed = false;
+                for (const lock of liveLocks) {
+                    const result = await callBridge(lock, "GET");
+                    if (!result.ok) {
+                        anyFailed = true;
+                        process.stderr.write(`  ✗ bridge pid=${lock.pid} port=${lock.port} unreachable (${result.error ?? `status ${result.status}`})\n`);
+                        continue;
+                    }
+                    const j = result.json ?? {};
+                    const engaged = j.engaged === true ? "ENGAGED" : "released";
+                    const lockedSuffix = j.locked
+                        ? ` [env-locked: ${j.lockedReason ?? "yes"}]`
+                        : "";
+                    const wsLabel = lock.workspace
+                        ? lock.workspace.split("/").slice(-2).join("/")
+                        : `pid=${lock.pid}`;
+                    process.stdout.write(`  ${engaged}  port=${lock.port} ${wsLabel}${lockedSuffix}\n`);
+                }
+                process.exit(anyFailed ? 2 : 0);
+            }
+            // engage / release: POST to every live bridge, surface aggregate result.
+            const engage = sub === "engage";
+            let anyFailed = false;
+            let anyChanged = false;
+            for (const lock of liveLocks) {
+                const result = await callBridge(lock, "POST", {
+                    engage,
+                    ...(reason ? { reason } : {}),
+                });
+                const wsLabel = lock.workspace
+                    ? lock.workspace.split("/").slice(-2).join("/")
+                    : `pid=${lock.pid}`;
+                if (result.status === 409) {
+                    anyFailed = true;
+                    const lr = result.json?.lockedReason ??
+                        "env-locked at boot";
+                    process.stderr.write(`  ✗ port=${lock.port} ${wsLabel}: cannot ${sub} — ${lr}\n`);
+                    continue;
+                }
+                if (!result.ok) {
+                    anyFailed = true;
+                    process.stderr.write(`  ✗ port=${lock.port} ${wsLabel}: ${result.error ?? `status ${result.status}`}\n`);
+                    continue;
+                }
+                const j = result.json ?? {};
+                const changedTag = j.changed === true ? "" : " (no-op, already in state)";
+                if (j.changed === true)
+                    anyChanged = true;
+                process.stdout.write(`  ✓ port=${lock.port} ${wsLabel}: ${engage ? "ENGAGED" : "released"}${changedTag}\n`);
+            }
+            if (anyFailed) {
+                process.exit(2);
+            }
+            if (!anyChanged) {
+                process.stdout.write(`\n  All ${liveLocks.length} bridge${liveLocks.length === 1 ? "" : "s"} already in target state — no audit emit.\n`);
+            }
+            else {
+                process.stdout.write(`\n  Kill-switch ${engage ? "engaged" : "released"} on ${liveLocks.length} bridge${liveLocks.length === 1 ? "" : "s"}.\n`);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// `patchwork panic` — alias for `patchwork kill-switch engage` (v2-Strong-2).
+//
+// Discoverable under stress (short command, obvious intent). Canonical noun
+// form is `kill-switch engage`; this alias matches it so shell history six
+// months later still makes sense. Does not accept sub-verbs — just runs engage.
+if (process.argv[2] === "panic") {
+    const extra = process.argv.slice(3); // e.g. --reason "..." --force-local
+    // Guard against `panic --help` engaging the kill switch — a real
+    // footgun if you tab-completed the verb to confirm syntax before
+    // committing to the action. `panic` is an alias, so we honor --help
+    // here ourselves rather than forwarding to kill-switch engage.
+    if (extra.includes("--help") || extra.includes("-h")) {
+        console.log('Usage: patchwork panic [--reason "..."] [--force-local]\n\n' +
+            "  Alias for `patchwork kill-switch engage` — blocks all write-tier\n" +
+            "  tool calls across every running bridge. Use --reason to leave a\n" +
+            "  note in the audit trail. Release with `patchwork kill-switch release`.\n");
+        process.exit(0);
+    }
+    // Spawn self with kill-switch engage to reuse the full handler without
+    // duplicating 200+ LOC. Passes through any flags (--reason, --force-local).
+    import("node:child_process").then(({ spawnSync }) => {
+        const self = process.argv[1] ?? process.execPath;
+        const result = spawnSync(process.execPath, [self, "kill-switch", "engage", ...extra], { stdio: "inherit" });
+        process.exit(result.status ?? 1);
+    });
+}
+// `patchwork halts` — one-screen morning summary of recent recipe halts.
+//
+// Composes the haltReason field (#441), category aggregator + endpoint
+// (#444), and dashboard pill conventions: queries the live bridge's
+// /runs/halt-summary endpoint over the chosen window and prints a
+// per-category breakdown plus the 5 most-recent halt reasons. Default
+// window is "overnight" (since 6pm yesterday local) so it lines up with
+// "what halted while I was asleep?".
+if (process.argv[2] === "halts") {
+    const args = process.argv.slice(3);
+    const wantHelp = args.includes("--help") || args.includes("-h");
+    if (wantHelp) {
+        process.stdout.write("Usage: patchwork halts [--window <name>] [--recipe <name>] [--json]\n" +
+            "\n" +
+            "  --window 1h | 24h | overnight | 7d | any   (default: overnight)\n" +
+            "  --recipe <name>                            filter to one recipe by name\n" +
+            "  --json                                     emit raw JSON (for scripting)\n" +
+            "\n" +
+            '"overnight" = since 6pm yesterday local time.\n');
+        process.exit(0);
+    }
+    function parseWindow() {
+        const idx = args.findIndex((a) => a === "--window" || a === "-w");
+        const raw = idx >= 0 && idx + 1 < args.length ? args[idx + 1] : "overnight";
+        if (raw === "1h" ||
+            raw === "24h" ||
+            raw === "overnight" ||
+            raw === "7d" ||
+            raw === "any")
+            return raw;
+        process.stderr.write(`Unknown --window value: "${raw}"\n`);
+        process.exit(1);
+    }
+    function windowSinceMs(w) {
+        if (w === "any")
+            return null;
+        if (w === "1h")
+            return 60 * 60 * 1000;
+        if (w === "24h")
+            return 24 * 60 * 60 * 1000;
+        if (w === "7d")
+            return 7 * 24 * 60 * 60 * 1000;
+        const d = new Date();
+        d.setHours(18, 0, 0, 0);
+        if (d.getTime() > Date.now())
+            d.setDate(d.getDate() - 1);
+        return Date.now() - d.getTime();
+    }
+    const window = parseWindow();
+    const wantJson = args.includes("--json");
+    const recipeIdx = args.findIndex((a) => a === "--recipe" || a === "-r");
+    const recipeFilter = recipeIdx >= 0 && recipeIdx + 1 < args.length
+        ? args[recipeIdx + 1]
+        : undefined;
+    (async () => {
+        try {
+            const { findAllLiveBridges } = await import("./bridgeLockDiscovery.js");
+            const liveLocks = findAllLiveBridges();
+            if (liveLocks.length === 0) {
+                process.stderr.write("No running bridge found. Start one with `patchwork start` (or `--driver subprocess`).\n");
+                process.exit(2);
+            }
+            const sinceMs = windowSinceMs(window);
+            const params = [];
+            if (sinceMs != null)
+                params.push(`sinceMs=${sinceMs}`);
+            if (recipeFilter)
+                params.push(`recipe=${encodeURIComponent(recipeFilter)}`);
+            const qs = params.length > 0 ? `?${params.join("&")}` : "";
+            // Walk live bridges in order; first responsive one wins. See the
+            // matching block in the `judgments` handler — findAllLiveBridges
+            // can include stale entries when a recycled PID still answers
+            // `kill(pid, 0)` but the lock points at a dead bridge.
+            let res = null;
+            let lastStatus = 0;
+            for (const lock of liveLocks) {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 10_000);
+                try {
+                    const candidate = await fetch(`http://127.0.0.1:${lock.port}/runs/halt-summary${qs}`, {
+                        headers: { Authorization: `Bearer ${lock.authToken}` },
+                        signal: controller.signal,
+                    });
+                    if (candidate.ok) {
+                        res = candidate;
+                        break;
+                    }
+                    lastStatus = candidate.status;
+                }
+                catch {
+                    /* unreachable lock — try next */
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            if (!res) {
+                process.stderr.write(`No live bridge served /runs/halt-summary (last status: ${lastStatus || "unreachable"}).\n`);
+                process.exit(1);
+            }
+            const summary = (await res.json());
+            if (wantJson) {
+                process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+                process.exit(0);
+            }
+            // Shared label + hint maps (also used by `recipe doctor` and
+            // mirrored in the dashboard) so the wording stays consistent.
+            const { HALT_CATEGORY_LABELS, HALT_CATEGORY_HINTS } = await import("./recipes/haltCategory.js");
+            const windowLabel = {
+                "1h": "last hour",
+                "24h": "last 24h",
+                overnight: "since 6pm yesterday",
+                "7d": "last 7 days",
+                any: "all time",
+            };
+            const recipeSuffix = recipeFilter ? ` · recipe="${recipeFilter}"` : "";
+            process.stdout.write(`Halts — ${windowLabel[window]}${recipeSuffix}\n`);
+            process.stdout.write(`Total: ${summary.total}\n`);
+            if (summary.total === 0) {
+                process.stdout.write("\n  (nothing halted in this window)\n");
+                process.exit(0);
+            }
+            const entries = Object.entries(summary.byCategory).sort(([, a], [, b]) => b - a);
+            process.stdout.write("\nBy category:\n");
+            for (const [cat, count] of entries) {
+                const label = HALT_CATEGORY_LABELS[cat] ?? cat;
+                const hint = HALT_CATEGORY_HINTS[cat];
+                const hintSuffix = hint ? `  — ${hint}` : "";
+                process.stdout.write(`  ${String(count).padStart(3)}  ${label}${hintSuffix}\n`);
+            }
+            if (summary.recent.length > 0) {
+                process.stdout.write("\nMost recent:\n");
+                for (const r of summary.recent) {
+                    // Truncate the reason to ~120 chars so a wide stack trace
+                    // can't blow up the terminal width on phones / narrow panes.
+                    const reason = r.reason.length > 120 ? `${r.reason.slice(0, 117)}…` : r.reason;
+                    process.stdout.write(`  #${r.runSeq}  [${r.category}]  ${reason}\n`);
+                }
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// `patchwork analytics` — manage the self-hosted telemetry collector config.
+// Replaces the brittle "endpoint+secret in launchd plist" pattern with a
+// proper config file the bridge reads at startup.
+if (process.argv[2] === "analytics") {
+    (async () => {
+        const { runAnalyticsCommand } = await import("./commands/analytics.js");
+        const code = await runAnalyticsCommand(process.argv.slice(3));
+        process.exit(code);
+    })();
+}
+// `patchwork judgments` — PR3b sibling of `patchwork halts`. Same window
+// + recipe filter shape; queries /runs/judge-summary and prints a
+// per-verdict breakdown plus the 5 most-recent verdicts.
+if (process.argv[2] === "judgments") {
+    const args = process.argv.slice(3);
+    const wantHelp = args.includes("--help") || args.includes("-h");
+    if (wantHelp) {
+        process.stdout.write("Usage: patchwork judgments [--window <name>] [--recipe <name>] [--json]\n" +
+            "\n" +
+            "  --window 1h | 24h | overnight | 7d | any   (default: overnight)\n" +
+            "  --recipe <name>                            filter to one recipe by name\n" +
+            "  --json                                     emit raw JSON (for scripting)\n" +
+            "\n" +
+            '"overnight" = since 6pm yesterday local time.\n');
+        process.exit(0);
+    }
+    function parseWindow() {
+        const idx = args.findIndex((a) => a === "--window" || a === "-w");
+        const raw = idx >= 0 && idx + 1 < args.length ? args[idx + 1] : "overnight";
+        if (raw === "1h" ||
+            raw === "24h" ||
+            raw === "overnight" ||
+            raw === "7d" ||
+            raw === "any")
+            return raw;
+        process.stderr.write(`Unknown --window value: "${raw}"\n`);
+        process.exit(1);
+    }
+    function windowSinceMs(w) {
+        if (w === "any")
+            return null;
+        if (w === "1h")
+            return 60 * 60 * 1000;
+        if (w === "24h")
+            return 24 * 60 * 60 * 1000;
+        if (w === "7d")
+            return 7 * 24 * 60 * 60 * 1000;
+        const d = new Date();
+        d.setHours(18, 0, 0, 0);
+        if (d.getTime() > Date.now())
+            d.setDate(d.getDate() - 1);
+        return Date.now() - d.getTime();
+    }
+    const window = parseWindow();
+    const wantJson = args.includes("--json");
+    const recipeIdx = args.findIndex((a) => a === "--recipe" || a === "-r");
+    const recipeFilter = recipeIdx >= 0 && recipeIdx + 1 < args.length
+        ? args[recipeIdx + 1]
+        : undefined;
+    (async () => {
+        try {
+            const { findAllLiveBridges } = await import("./bridgeLockDiscovery.js");
+            const liveLocks = findAllLiveBridges();
+            if (liveLocks.length === 0) {
+                process.stderr.write("No running bridge found. Start one with `patchwork start` (or `--driver subprocess`).\n");
+                process.exit(2);
+            }
+            const sinceMs = windowSinceMs(window);
+            const params = [];
+            if (sinceMs != null)
+                params.push(`sinceMs=${sinceMs}`);
+            if (recipeFilter)
+                params.push(`recipe=${encodeURIComponent(recipeFilter)}`);
+            const qs = params.length > 0 ? `?${params.join("&")}` : "";
+            // Walk live bridges in order; the first responsive one wins.
+            // findAllLiveBridges uses `kill(pid, 0)` for liveness, which
+            // returns true for any recycled PID — so liveLocks can contain
+            // stale entries from dead bridges. Previously we picked [0]
+            // unconditionally and surfaced a confusing 404; now we try each
+            // and only fall through to the error path when *all* fail.
+            let res = null;
+            let lastStatus = 0;
+            for (const lock of liveLocks) {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 10_000);
+                try {
+                    const candidate = await fetch(`http://127.0.0.1:${lock.port}/runs/judge-summary${qs}`, {
+                        headers: { Authorization: `Bearer ${lock.authToken}` },
+                        signal: controller.signal,
+                    });
+                    if (candidate.ok) {
+                        res = candidate;
+                        break;
+                    }
+                    lastStatus = candidate.status;
+                }
+                catch {
+                    /* unreachable lock — try next */
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            if (!res) {
+                process.stderr.write(`No live bridge served /runs/judge-summary (last status: ${lastStatus || "unreachable"}).\n`);
+                process.exit(1);
+            }
+            const summary = (await res.json());
+            if (wantJson) {
+                process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+                process.exit(0);
+            }
+            const labels = {
+                approve: "approve",
+                request_changes: "request changes",
+                unparseable: "unparseable",
+            };
+            const windowLabel = {
+                "1h": "last hour",
+                "24h": "last 24h",
+                overnight: "since 6pm yesterday",
+                "7d": "last 7 days",
+                any: "all time",
+            };
+            const recipeSuffix = recipeFilter ? ` · recipe="${recipeFilter}"` : "";
+            process.stdout.write(`Judgments — ${windowLabel[window]}${recipeSuffix}\n`);
+            process.stdout.write(`Total: ${summary.total}\n`);
+            if (summary.total === 0) {
+                process.stdout.write("\n  (no judge steps fired in this window)\n");
+                process.exit(0);
+            }
+            const entries = Object.entries(summary.byVerdict).sort(([, a], [, b]) => b - a);
+            process.stdout.write("\nBy verdict:\n");
+            for (const [verdict, count] of entries) {
+                const label = labels[verdict] ?? verdict;
+                process.stdout.write(`  ${String(count).padStart(3)}  ${label}\n`);
+            }
+            if (summary.recent.length > 0) {
+                process.stdout.write("\nMost recent:\n");
+                for (const r of summary.recent) {
+                    const reason = r.firstReason
+                        ? r.firstReason.length > 120
+                            ? `${r.firstReason.slice(0, 117)}…`
+                            : r.firstReason
+                        : "(no reason)";
+                    process.stdout.write(`  #${r.runSeq}  [${r.verdict}]  ${r.stepId}: ${reason}\n`);
+                }
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
 if (process.argv[2] === "recipe" && process.argv[3] === "schema") {
     const outputDir = process.argv[4] ?? path.join(process.cwd(), "schemas");
     (async () => {
@@ -1453,44 +2123,62 @@ if (process.argv[2] === "recipe" && process.argv[3] === "schema") {
     })();
 }
 // Patchwork: `patchwork recipe new <name>` — scaffold a new recipe from template.
+// With `--interactive`, drops into a connector-aware prompt tree instead.
 if (process.argv[2] === "recipe" && process.argv[3] === "new") {
     const args = process.argv.slice(4);
-    const recipeName = args[0];
-    if (!recipeName) {
-        process.stderr.write("Usage: patchwork recipe new <name> [--template <name>] [--desc <description>] [--out <dir>]\n" +
-            "  --out <dir>  Write the recipe to <dir>/<name>.yaml.\n" +
-            "               Defaults to ~/.patchwork/recipes/ — pass `--out .` to\n" +
-            "               write into the current directory instead.\n");
-        process.stderr.write("\nTemplates:\n");
-        (async () => {
-            const { listTemplates } = await import("./commands/recipe.js");
-            for (const t of listTemplates()) {
-                process.stderr.write(`  ${t}\n`);
-            }
-            process.exit(1);
-        })();
-    }
-    else {
+    const isInteractive = args.includes("--interactive") || args.includes("-i");
+    if (isInteractive) {
         (async () => {
             try {
-                const { runNew } = await import("./commands/recipe.js");
-                const templateIdx = args.indexOf("--template");
-                const template = templateIdx >= 0 ? args[templateIdx + 1] : undefined;
-                const descIdx = args.indexOf("--desc");
-                const description = (descIdx >= 0 ? args[descIdx + 1] : undefined) ??
-                    `Recipe: ${recipeName}`;
+                const { runNewInteractive } = await import("./commands/recipe.js");
+                const { createInterface } = await import("node:readline/promises");
+                const rl = createInterface({
+                    input: process.stdin,
+                    output: process.stdout,
+                });
                 const outIdx = args.indexOf("--out");
                 const outRaw = outIdx >= 0 ? args[outIdx + 1] : undefined;
-                // `--out .` is the common case for "scaffold in cwd" — resolve so
-                // the success message shows the absolute path the user can open.
                 const outputDir = outRaw ? path.resolve(outRaw) : undefined;
-                const result = runNew({
-                    name: recipeName,
-                    description,
-                    ...(template ? { template } : {}),
+                const deps = {
+                    ask: async (q) => (await rl.question(`${q}: `)).trim(),
+                    pickFromList: async (q, options) => {
+                        process.stdout.write(`\n${q}\n`);
+                        options.forEach((opt, i) => {
+                            process.stdout.write(`  ${i + 1}. ${opt}\n`);
+                        });
+                        for (let attempt = 0; attempt < 5; attempt++) {
+                            const raw = (await rl.question(`Choose 1-${options.length}: `)).trim();
+                            const idx = Number.parseInt(raw, 10);
+                            if (Number.isFinite(idx) && idx >= 1 && idx <= options.length) {
+                                return idx;
+                            }
+                            process.stdout.write(`Invalid choice. Enter a number 1-${options.length}.\n`);
+                        }
+                        throw new Error("Too many invalid choices");
+                    },
+                    confirm: async (q) => {
+                        const a = (await rl.question(`${q} [y/N]: `)).trim().toLowerCase();
+                        return a === "y" || a === "yes";
+                    },
+                    preview: (yaml) => {
+                        process.stdout.write("\n--- Preview ---\n");
+                        process.stdout.write(yaml);
+                        process.stdout.write("---\n\n");
+                    },
+                };
+                const result = await runNewInteractive({
+                    deps,
                     ...(outputDir ? { outputDir } : {}),
                 });
+                rl.close();
                 process.stdout.write(`  ✓ Created ${result.path}\n`);
+                if (result.warnings.length > 0) {
+                    process.stdout.write(`\n  ⚠ Lint warnings (recipe still written):\n`);
+                    for (const w of result.warnings) {
+                        process.stdout.write(`    [${w.level}] ${w.message}\n`);
+                    }
+                }
+                process.stdout.write(`\n  Run with: patchwork recipe run ${result.path}\n`);
                 process.exit(0);
             }
             catch (err) {
@@ -1499,6 +2187,53 @@ if (process.argv[2] === "recipe" && process.argv[3] === "new") {
             }
         })();
     }
+    else {
+        const recipeName = args[0];
+        if (!recipeName) {
+            process.stderr.write("Usage: patchwork recipe new <name> [--template <name>] [--desc <description>] [--out <dir>]\n" +
+                "  --interactive (-i)  Run the connector-aware prompt tree instead of using a template.\n" +
+                "  --out <dir>  Write the recipe to <dir>/<name>.yaml.\n" +
+                "               Defaults to ~/.patchwork/recipes/ — pass `--out .` to\n" +
+                "               write into the current directory instead.\n");
+            process.stderr.write("\nTemplates:\n");
+            (async () => {
+                const { listTemplates } = await import("./commands/recipe.js");
+                for (const t of listTemplates()) {
+                    process.stderr.write(`  ${t}\n`);
+                }
+                process.exit(1);
+            })();
+        }
+        else {
+            (async () => {
+                try {
+                    const { runNew } = await import("./commands/recipe.js");
+                    const templateIdx = args.indexOf("--template");
+                    const template = templateIdx >= 0 ? args[templateIdx + 1] : undefined;
+                    const descIdx = args.indexOf("--desc");
+                    const description = (descIdx >= 0 ? args[descIdx + 1] : undefined) ??
+                        `Recipe: ${recipeName}`;
+                    const outIdx = args.indexOf("--out");
+                    const outRaw = outIdx >= 0 ? args[outIdx + 1] : undefined;
+                    // `--out .` is the common case for "scaffold in cwd" — resolve so
+                    // the success message shows the absolute path the user can open.
+                    const outputDir = outRaw ? path.resolve(outRaw) : undefined;
+                    const result = runNew({
+                        name: recipeName,
+                        description,
+                        ...(template ? { template } : {}),
+                        ...(outputDir ? { outputDir } : {}),
+                    });
+                    process.stdout.write(`  ✓ Created ${result.path}\n`);
+                    process.exit(0);
+                }
+                catch (err) {
+                    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+                    process.exit(1);
+                }
+            })();
+        }
+    }
 }
 // Patchwork: `patchwork recipe lint <file.yaml>` — validate recipe against schema.
 if (process.argv[2] === "recipe" && process.argv[3] === "lint") {
@@ -1530,6 +2265,53 @@ if (process.argv[2] === "recipe" && process.argv[3] === "lint") {
         }
     })();
 }
+// Patchwork: `patchwork recipe audit-env <recipe>` — check {{env.FOO}} references are satisfied.
+if (process.argv[2] === "recipe" && process.argv[3] === "audit-env") {
+    const recipeArg = process.argv[4];
+    if (!recipeArg) {
+        process.stderr.write("Usage: patchwork recipe audit-env <recipe> [--env-file <path>] [--workspace <path>]\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const args = process.argv.slice(5);
+            const envFileIdx = args.indexOf("--env-file");
+            const envFile = envFileIdx !== -1 ? args[envFileIdx + 1] : undefined;
+            const workspaceIdx = args.indexOf("--workspace");
+            const workspace = workspaceIdx !== -1 && args[workspaceIdx + 1]
+                ? args[workspaceIdx + 1]
+                : process.cwd();
+            const { runAuditEnv } = await import("./commands/auditEnv.js");
+            const result = await runAuditEnv(recipeArg, {
+                ...(envFile ? { envFile } : {}),
+                workspace,
+            });
+            if (result.warnings.length > 0) {
+                for (const w of result.warnings) {
+                    process.stderr.write(`  ⚠ ${w}\n`);
+                }
+            }
+            if (result.present.length > 0) {
+                for (const v of result.present) {
+                    process.stdout.write(`  ✓ ${v}\n`);
+                }
+            }
+            if (result.missing.length > 0) {
+                for (const v of result.missing) {
+                    process.stderr.write(`  ✗ missing: ${v}\n`);
+                }
+            }
+            if (!result.ok) {
+                process.exit(1);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
 // Patchwork: `patchwork recipe preflight <file.yaml>` — static policy check (lint + plan + writes + fixtures).
 if (process.argv[2] === "recipe" && process.argv[3] === "preflight") {
     const args = process.argv.slice(4);
@@ -1633,6 +2415,79 @@ if (process.argv[2] === "recipe" && process.argv[3] === "preflight") {
         }
     })();
 }
+// `recipe doctor <name|file>` — one-screen "why is this recipe unhealthy
+// + how do I fix it" diagnosis. Composes the static preflight check with
+// the recipe-scoped runtime halt summary from a live bridge (fail-soft:
+// no bridge → static-only). See runRecipeDoctor in commands/recipe.ts.
+if (process.argv[2] === "recipe" && process.argv[3] === "doctor") {
+    const args = process.argv.slice(4);
+    const usage = "Usage: patchwork recipe doctor <name|file.yaml> [--json] [--local]\n\n" +
+        "Diagnoses a recipe: lint + write-policy + plan (static) plus recent\n" +
+        "runtime halts from a live bridge, each mapped to a fix hint.\n" +
+        "--local skips the bridge runtime check. Exits 1 when unhealthy.\n";
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(usage);
+        process.exit(0);
+    }
+    const wantJson = args.includes("--json");
+    const localOnly = args.includes("--local");
+    const ref = args.find((a) => !a.startsWith("--"));
+    if (!ref) {
+        process.stderr.write(usage);
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const { runRecipeDoctor, formatRecipeDoctorReport } = await import("./commands/recipe.js");
+            // Runtime halt fetcher: walk live bridges, query the recipe-scoped
+            // halt summary over the last 7 days. Returns null when no bridge is
+            // reachable so doctor degrades to static-only.
+            const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+            const fetchHalts = localOnly
+                ? undefined
+                : async (recipeName) => {
+                    const { findAllLiveBridges } = await import("./bridgeLockDiscovery.js");
+                    const liveLocks = findAllLiveBridges();
+                    if (liveLocks.length === 0)
+                        return null;
+                    const sinceMs = Date.now() - SEVEN_DAYS_MS;
+                    const qs = `?sinceMs=${sinceMs}&recipe=${encodeURIComponent(recipeName)}`;
+                    for (const lock of liveLocks) {
+                        const controller = new AbortController();
+                        const timer = setTimeout(() => controller.abort(), 10_000);
+                        try {
+                            const res = await fetch(`http://127.0.0.1:${lock.port}/runs/halt-summary${qs}`, {
+                                headers: { Authorization: `Bearer ${lock.authToken}` },
+                                signal: controller.signal,
+                            });
+                            if (res.ok) {
+                                return (await res.json());
+                            }
+                        }
+                        catch {
+                            /* unreachable lock — try next */
+                        }
+                        finally {
+                            clearTimeout(timer);
+                        }
+                    }
+                    return null;
+                };
+            const result = await runRecipeDoctor(ref, { fetchHalts });
+            if (wantJson) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(formatRecipeDoctorReport(result));
+            }
+            process.exit(result.ok ? 0 : 1);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
 // Patchwork: `patchwork recipe fmt <file.yaml>` — format/normalize recipe.
 if (process.argv[2] === "recipe" && process.argv[3] === "fmt") {
     const args = process.argv.slice(4);
@@ -1951,9 +2806,12 @@ Steps performed:
         }
         if (extensionArg2) {
             try {
+                // Windows: editor binaries (code/cursor/windsurf) are `.cmd` shims that
+                // Node's execFileSync can't launch without a shell. See bridgeProcess.ts.
                 execFileSync(editor, ["--install-extension", extensionArg2], {
                     stdio: "pipe",
                     timeout: 30000,
+                    shell: process.platform === "win32",
                 });
                 process.stderr.write(`  ✓ Extension installed via ${editor}\n\n`);
             }
@@ -2082,13 +2940,18 @@ Steps performed:
             process.stderr.write(`  ✓ MCP shim — already registered in ${claudeJsonAbs}\n\n`);
         }
         else {
+            // claude -p spawns the stdio command via Node's child_process, which
+            // can't resolve a bare `.cmd` shim on Windows. Record the `.cmd` form
+            // on win32 so the bridge binary is findable by the spawned process.
             mcpServers["claude-ide-bridge"] = {
-                command: "claude-ide-bridge",
+                command: ensureCmdShim("claude-ide-bridge"),
                 args: ["shim"],
                 type: "stdio",
             };
             claudeJson.mcpServers = mcpServers;
-            writeFileSync(claudeJsonAbs, `${JSON.stringify(claudeJson, null, 2)}\n`);
+            // Atomic — `~/.claude.json` holds every MCP server registration on
+            // the machine. A crash mid-write would brick Claude Code globally.
+            writeFileAtomicSync(claudeJsonAbs, `${JSON.stringify(claudeJson, null, 2)}\n`);
             process.stderr.write(`  ✓ MCP shim — registered in ${claudeJsonAbs}\n     Note: bridge tools are wired via ~/.claude.json (global), not .mcp.json.\n     This is intentional — when VS Code/Windsurf/Cursor launches Claude Code it\n     injects --mcp-config which overrides any project .mcp.json. Only ~/.claude.json\n     is always loaded. You do not need to add anything to .mcp.json.\n\n`);
         }
     }
@@ -2139,7 +3002,9 @@ Steps performed:
         }
         if (added.length > 0 || migrated.length > 0) {
             ccSettings.hooks = ccHooks;
-            writeFileSync(ccSettingsPath, `${JSON.stringify(ccSettings, null, 2)}\n`);
+            // Atomic — `~/.claude/settings.json` holds every CC hook entry; a
+            // crash mid-write loses the user's full hook configuration.
+            writeFileAtomicSync(ccSettingsPath, `${JSON.stringify(ccSettings, null, 2)}\n`);
             const addMsg = added.length > 0
                 ? `  ✓ CC hooks — wired ${added.length} automation hook(s) in ${ccSettingsPath}\n     Added: ${added.join(", ")}\n`
                 : "";
@@ -2180,6 +3045,9 @@ Steps performed:
         execFileSync("claude-ide-bridge", ["--version"], {
             stdio: "pipe",
             timeout: 5000,
+            // Windows: global npm bin is a `.cmd` shim that Node's execFileSync
+            // can't launch without a shell. See bridgeProcess.ts for context.
+            shell: process.platform === "win32",
         });
         shimOnPath = true;
     }
@@ -2239,13 +3107,8 @@ Steps performed:
     let hooksWired = false;
     try {
         const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
-        const sj = JSON.parse(readFileSync(settingsPath, "utf-8"));
-        const hooksObj = sj?.hooks;
-        if (hooksObj && typeof hooksObj === "object") {
-            hooksWired = Object.values(hooksObj).flat().some((e) => typeof e?.command ===
-                "string" &&
-                (e.command ?? "").includes("claude-ide-bridge"));
-        }
+        const { isPreToolUseHookRegistered } = await import("./preToolUseHook.js");
+        hooksWired = isPreToolUseHookRegistered(settingsPath);
     }
     catch {
         /* file may not exist yet — non-fatal */
@@ -2263,8 +3126,11 @@ Steps performed:
                 ? fallbackDocs
                 : null;
         if (target) {
-            const { exec } = await import("node:child_process");
-            exec(`code "${target}"`, { timeout: 3000 }, () => { });
+            // Use execFile with argv (no shell) — exec(`code "${target}"`) was
+            // shell-evaluated and could be injected via `--workspace '"; ...'`
+            // since path.resolve preserves shell metachars. Audit 2026-05-17.
+            const { execFile } = await import("node:child_process");
+            execFile("code", [target], { timeout: 3000 }, () => { });
         }
     }
     // Analytics opt-in prompt — only ask once; skip if preference already set
@@ -2381,9 +3247,11 @@ else if (process.argv[2] === "install-extension") {
     }
     try {
         process.stderr.write(`Installing extension via ${editor}...\n`);
+        // Windows: editor binaries are `.cmd` shims; need shell for resolution.
         execFileSync(editor, ["--install-extension", extensionArg], {
             stdio: "inherit",
             timeout: 30000,
+            shell: process.platform === "win32",
         });
         process.stderr.write("Extension installed successfully.\n");
     }
@@ -2560,6 +3428,88 @@ Options:
     }
     process.exit(0);
 }
+// `patchwork doctor` — run CLI-safe bridge health checks.
+if (process.argv[2] === "doctor") {
+    const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write("Usage: patchwork doctor [--workspace <path>] [--port <n>] [--json]\n\n" +
+            "Runs bridge health checks (workspace, git, lock file, automation policy).\n" +
+            "Exits 1 if any check fails.\n");
+        process.exit(0);
+    }
+    (async () => {
+        try {
+            const workspaceIdx = args.indexOf("--workspace");
+            const workspace = workspaceIdx !== -1 && args[workspaceIdx + 1]
+                ? args[workspaceIdx + 1]
+                : process.cwd();
+            const portIdx = args.indexOf("--port");
+            const portArg = portIdx !== -1 ? args[portIdx + 1] : undefined;
+            const port = portArg !== undefined ? Number(portArg) : undefined;
+            const jsonFlag = args.includes("--json");
+            const { runDoctor } = await import("./commands/doctor.js");
+            const result = await runDoctor({ workspace, port, json: jsonFlag });
+            if (jsonFlag) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                for (const check of result.checks) {
+                    const icon = check.status === "ok" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+                    const detail = check.detail ? `  ${check.detail}` : "";
+                    process.stdout.write(`  ${icon} ${check.name}${detail}\n`);
+                    if (check.suggestion) {
+                        process.stdout.write(`      → ${check.suggestion}\n`);
+                    }
+                }
+            }
+            process.exit(result.ok ? 0 : 1);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// `patchwork shadow-scan` — replay run history through the destructive-tool classifier.
+if (process.argv[2] === "shadow-scan") {
+    const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write("Usage: patchwork shadow-scan [--since <duration|ISO>] [--limit <n>] [--runs-file <path>] [--json]\n\n" +
+            "Replays historical run data through the destructive-tool classifier.\n" +
+            "Exits 1 if any runs would be reclassified.\n\n" +
+            "  --since <duration|ISO>  Lookback window, e.g. '24h', '7d', or ISO date (default: 7d)\n" +
+            "  --limit <n>             Cap the number of runs to scan\n" +
+            "  --runs-file <path>      Override default ~/.claude/ide/runs.jsonl path\n" +
+            "  --json                  Emit JSON output\n");
+        process.exit(0);
+    }
+    (async () => {
+        try {
+            const sinceIdx = args.indexOf("--since");
+            const since = sinceIdx !== -1 ? args[sinceIdx + 1] : undefined;
+            const limitIdx = args.indexOf("--limit");
+            const limitArg = limitIdx !== -1 ? args[limitIdx + 1] : undefined;
+            const limit = limitArg !== undefined ? Number(limitArg) : undefined;
+            const runsFileIdx = args.indexOf("--runs-file");
+            const runsFile = runsFileIdx !== -1 ? args[runsFileIdx + 1] : undefined;
+            const jsonFlag = args.includes("--json");
+            const { runShadowScanCli } = await import("./commands/shadowScan.js");
+            await runShadowScanCli({
+                ...(since !== undefined ? { since } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+                ...(runsFile !== undefined
+                    ? { runsFile, workspace: process.cwd() }
+                    : {}),
+                json: jsonFlag,
+            });
+            // runShadowScanCli sets process.exitCode = 1 on reclassified > 0; no explicit exit needed.
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
 // Handle launchd subcommand — install/uninstall macOS LaunchAgent for auto-start
 if (process.argv[2] === "launchd") {
     const sub = process.argv[3];
@@ -2580,11 +3530,24 @@ if (process.argv[2] === "launchd") {
 // F6: "Did you mean?" for unknown CLI subcommands
 // Patchwork: no-args → terminal dashboard (when invoked as patchwork-os or patchwork).
 {
-    const binName = path.basename(process.argv[1] ?? "");
+    const binName = invokedBinaryName();
     const isPatchworkBin = binName === "patchwork-os" ||
         binName === "patchwork" ||
         binName === "patchwork.js";
     if (isPatchworkBin && (!process.argv[2] || process.argv[2] === "dashboard")) {
+        // First-run guard: if the user hasn't run `patchwork init` yet, launching
+        // the dashboard renders an empty panel with no signpost. Print an
+        // actionable pointer instead and exit cleanly.
+        const cfgPath = path.join(os.homedir(), ".patchwork", "config.json");
+        if (!existsSync(cfgPath) && !process.argv[2]) {
+            process.stdout.write(`No Patchwork config found at ${cfgPath}.\n\n` +
+                `Run \`${binName} init\` to scaffold ~/.patchwork and wire up\n` +
+                `Claude Code hooks, then \`${binName}\` again to open the dashboard.\n\n` +
+                `For just the IDE bridge (no recipes / approval queue), run:\n` +
+                `  ${binName} install-extension\n` +
+                `  ${binName} --workspace .\n`);
+            process.exit(0);
+        }
         (async () => {
             const { runDashboard } = await import("./commands/dashboard.js");
             await runDashboard();
@@ -2662,8 +3625,10 @@ else {
             .digest("hex")
             .slice(0, 6);
         const sessionName = `claude-bridge-${ws}${hash}`;
-        // Check if tmux is available
-        const tmuxCheck = spawnSync("which", ["tmux"], { stdio: "ignore" });
+        // Check if tmux is available (skip on Windows — tmux doesn't exist there)
+        const tmuxCheck = process.platform !== "win32"
+            ? spawnSync("which", ["tmux"], { stdio: "ignore" })
+            : { status: 1 };
         if (tmuxCheck.status !== 0) {
             process.stderr.write("WARNING: --auto-tmux requested but tmux is not installed. Running without tmux.\n");
         }
@@ -2712,7 +3677,12 @@ else {
             for (const sig of ["SIGTERM", "SIGINT"]) {
                 process.once(sig, () => {
                     stopping = true;
-                    child.kill(sig);
+                    // Use treeKill so grandchildren (recipe runners, claude
+                    // subprocesses, extension watchers) are reaped on Windows.
+                    // Bare `child.kill(sig)` maps to TerminateProcess on win32
+                    // and skips descendants → orphaned processes survive a
+                    // supervisor SIGTERM. Audit 2026-05-17.
+                    treeKill(child, sig);
                 });
             }
             child.on("exit", (code, signal) => {
@@ -2740,19 +3710,27 @@ else {
             process.stderr.write(`Error: ${message}\n`);
             process.exit(1);
         });
-        // F5: Silent self-update nudge (fire-and-forget)
-        import("node:child_process")
-            .then(({ exec }) => {
-            exec("npm view claude-ide-bridge version", { timeout: 5000 }, (err, stdout) => {
-                if (err || !stdout)
-                    return;
-                const latest = stdout.trim();
-                if (latest && semverGt(latest, PACKAGE_VERSION)) {
-                    console.log(`\n  Bridge v${latest} available — run: npm update -g claude-ide-bridge\n`);
-                }
-            });
-        })
-            .catch(() => { });
+        // F5: Silent self-update nudge (fire-and-forget).
+        // Skip when running from a source tree (any of: a `.git` sibling of the
+        // package, or __dirnameTop not under a node_modules/). Otherwise a dev
+        // who built locally sees "Bridge v<X> available" pointing at an npm
+        // install path they're not using.
+        const isSourceBuild = existsSync(path.join(__dirnameTop, "..", ".git")) ||
+            !__dirnameTop.includes(`${path.sep}node_modules${path.sep}`);
+        if (!isSourceBuild) {
+            import("node:child_process")
+                .then(({ exec }) => {
+                exec("npm view patchwork-os version", { timeout: 5000 }, (err, stdout) => {
+                    if (err || !stdout)
+                        return;
+                    const latest = stdout.trim();
+                    if (latest && semverGt(latest, PACKAGE_VERSION)) {
+                        console.log(`\n  Patchwork OS v${latest} available — run: npm update -g patchwork-os\n`);
+                    }
+                });
+            })
+                .catch(() => { });
+        }
     }
 } // end of `else` for `if (__subcommandWillRun)` (bridge-mode block)
 //# sourceMappingURL=index.js.map