patchwork-os 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/index.js

@@ -119,7 +119,6 @@ const KNOWN_SUBCOMMANDS = [
     "gen-plugin-stub",
     "notify",
     "install",
-    "marketplace",
     "status",
     "shim",
     "recipe",
@@ -128,6 +127,10 @@ const KNOWN_SUBCOMMANDS = [
     "dashboard",
     "launchd",
     "start",
+    "kill-switch",
+    "panic",
+    "halts",
+    "judgments",
 ];
 const __invokedSubcommand = (() => {
     const sub = process.argv[2];
@@ -139,10 +142,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 +166,44 @@ 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` +
+        `Diagnose\n` +
+        `  halts [--window 1h|24h|overnight|7d]      Morning summary of recent recipe halts\n` +
+        `  traces export                             Bundle approval / recipe / decision traces\n` +
+        `  print-token [--port N]                    Print the active bridge auth token\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 +211,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 +226,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 +238,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 +269,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,13 +438,6 @@ if (process.argv[2] === "install") {
     await runInstall(process.argv.slice(3));
     process.exit(0);
 }
-// Handle marketplace subcommand — DEPRECATED, prints migration message.
-// See issue #279 and src/commands/marketplace.ts for the rationale.
-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");
@@ -885,6 +948,31 @@ 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` +
+        `  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\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 () => {
@@ -960,11 +1048,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];
@@ -991,6 +1081,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) {
@@ -1037,7 +1150,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: {
@@ -1080,9 +1193,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) {
@@ -1435,6 +1576,478 @@ 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") {
+    // 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 extra = process.argv.slice(3); // e.g. --reason "..." --force-local
+        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);
+            }
+            // Single-bridge default: query the first. Multi-bridge users will
+            // typically have one orchestrator anyway; expanding to fan-out is a
+            // follow-up if needed.
+            const lock = liveLocks[0];
+            if (!lock) {
+                process.stderr.write("No running bridge found.\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("&")}` : "";
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 10_000);
+            let res;
+            try {
+                res = await fetch(`http://127.0.0.1:${lock.port}/runs/halt-summary${qs}`, {
+                    headers: { Authorization: `Bearer ${lock.authToken}` },
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!res.ok) {
+                process.stderr.write(`Bridge returned ${res.status} for /runs/halt-summary\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 = {
+                agent_silent_fail: "agent silent-fail",
+                agent_narration_only: "agent narration-only",
+                agent_threw: "agent threw",
+                tool_threw: "tool threw",
+                tool_error: "tool error",
+                kill_switch: "kill-switch blocked",
+                run_level: "run-level halt",
+                unknown: "uncategorised",
+            };
+            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 = labels[cat] ?? cat;
+                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) {
+                    // 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 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 lock = liveLocks[0];
+            if (!lock) {
+                process.stderr.write("No running bridge found.\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("&")}` : "";
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 10_000);
+            let res;
+            try {
+                res = await fetch(`http://127.0.0.1:${lock.port}/runs/judge-summary${qs}`, {
+                    headers: { Authorization: `Bearer ${lock.authToken}` },
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!res.ok) {
+                process.stderr.write(`Bridge returned ${res.status} for /runs/judge-summary\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 () => {
@@ -1454,44 +2067,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) {
@@ -1500,6 +2131,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") {
@@ -2240,13 +2918,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 */
@@ -2581,11 +3254,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();
@@ -2663,8 +3349,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");
         }
@@ -2741,19 +3429,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 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(() => { });
+        }
     }
 } // end of `else` for `if (__subcommandWillRun)` (bridge-mode block)
 //# sourceMappingURL=index.js.map