patchwork-os 0.2.0-alpha.9 → 0.2.0-beta.1

package/dist/index.js

@@ -3,10 +3,15 @@
 // Uses Node 20.6+ native dotenv loader; falls back to manual parse for older Node.
 {
     const { fileURLToPath: _fileURLToPath } = await import("node:url");
-    const envPath = _fileURLToPath(new URL("../.env", import.meta.url));
     try {
         const { readFileSync, existsSync } = await import("node:fs");
-        if (existsSync(envPath)) {
+        // Try both "../.env" (compiled dist/) and ".env" (tsx src/ dev run)
+        const candidates = [
+            _fileURLToPath(new URL("../.env", import.meta.url)),
+            _fileURLToPath(new URL(".env", import.meta.url)),
+        ];
+        const envPath = candidates.find(existsSync);
+        if (envPath) {
             for (const line of readFileSync(envPath, "utf-8").split("\n")) {
                 const m = /^([A-Z_][A-Z0-9_]*)=(.*)$/.exec(line.trim());
                 if (m?.[1] && !process.env[m[1]]) {
@@ -35,14 +40,30 @@ import { getAnalyticsPref, setAnalyticsPref } from "./analyticsPrefs.js";
 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 { PACKAGE_VERSION, semverGt } from "./version.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.
+// Warn only — do not crash interactive or dev flows.
+{
+    const _symlinkInfo = detectWorkspaceSymlinkInstall();
+    if (_symlinkInfo) {
+        process.stderr.write(`\n⚠️  Detected a symlinked global ${PATCHWORK_PACKAGE_NAME} install.\n` +
+            `   Logical root: ${_symlinkInfo.logicalRoot}\n` +
+            `   Real path:    ${_symlinkInfo.realRoot}\n\n` +
+            "   LaunchAgent startup can fail with EPERM when the macOS sandbox\n" +
+            "   cannot access workspace files under ~/Documents through that link.\n\n" +
+            SYMLINK_INSTALL_FIX +
+            "\n");
+    }
+}
 const OPEN_VSX_PUBLISHER = "oolab-labs";
 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.
@@ -71,6 +92,62 @@ async function downloadVsixFromOpenVsx() {
     writeFileSync(tmpPath, Buffer.from(buf));
     return tmpPath;
 }
+// Closes the race where bridge.start() began initialising in parallel with
+// a subcommand's async work — observed in the 2026-04-29 dogfood pass
+// where `recipe install` errors interleaved with bridge "Tools: full"
+// startup logs.
+//
+// Every subcommand `if`-block below dispatches via an `(async () => {...})()`
+// IIFE that ends with `process.exit`. The IIFE invocation returns
+// synchronously, so without this gate, control immediately falls through
+// to the bridge.start() block at end-of-file and starts initialising
+// alongside the subcommand's async work. process.exit fires *eventually*
+// after the await chain, but the bridge has already begun in parallel.
+// Two IIFEs (patchwork no-args dashboard, recipe watch) lack process.exit
+// entirely — without this gate they would run alongside the bridge
+// indefinitely.
+//
+// Single source of truth for "is this argv invoking a subcommand?" — the
+// same list is also used by the unknown-command suggester at L2570.
+const KNOWN_SUBCOMMANDS = [
+    "init",
+    "patchwork-init",
+    "start-all",
+    "install-extension",
+    "gen-claude-md",
+    "print-token",
+    "gen-plugin-stub",
+    "notify",
+    "install",
+    "marketplace",
+    "status",
+    "shim",
+    "recipe",
+    "traces",
+    "suggest",
+    "dashboard",
+    "launchd",
+    "start",
+];
+const __invokedSubcommand = (() => {
+    const sub = process.argv[2];
+    if (!sub || sub.startsWith("-"))
+        return null;
+    // Treat KNOWN_SUBCOMMANDS as the dispatch source. The bare-binary
+    // dashboard launcher (no argv) is handled separately below.
+    return KNOWN_SUBCOMMANDS.includes(sub)
+        ? sub
+        : null;
+})();
+const __invokedBareBinaryDashboard = (() => {
+    if (process.argv[2] && process.argv[2] !== "dashboard")
+        return false;
+    const binName = path.basename(process.argv[1] ?? "");
+    return (binName === "patchwork-os" ||
+        binName === "patchwork" ||
+        binName === "patchwork.js");
+})();
+const __subcommandWillRun = __invokedSubcommand !== null || __invokedBareBinaryDashboard;
 // Handle --version flag — print package version and exit.
 if (process.argv[2] === "--version" || process.argv[2] === "-v") {
     console.log(`claude-ide-bridge ${PACKAGE_VERSION}`);
@@ -97,6 +174,49 @@ if (isStartAll) {
     });
     process.exit(result.status ?? 1);
 }
+// `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.
+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.
+Defaults to full mode so all bridge tools are registered.
+
+Usage: patchwork start [options]
+
+Options:
+  --workspace <path>    Directory to open (default: current directory)
+  --no-dashboard        Skip the web dashboard
+  --dashboard-port <N>  Dashboard port (default: 3200)
+  --notify <topic>      Push notifications via ntfy.sh
+  --vps <user@host>     SSH reverse tunnel for stable claude.ai URL
+  --slim                Slim mode (27 IDE-exclusive tools only — overrides default)
+  --help, -h            Show this help
+
+This is a thin wrapper over \`start-all\`. For advanced flags see:
+  patchwork start-all --help
+`);
+        process.exit(0);
+    }
+    // Default to --full unless caller opted into slim explicitly.
+    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
+    }
+    else if (!args.includes("--full")) {
+        args.push("--full");
+    }
+    const scriptPath = path.resolve(__dirnameTop, "..", "scripts", "start-all.sh");
+    const result = spawnSync("bash", [scriptPath, ...args], {
+        stdio: "inherit",
+    });
+    process.exit(result.status ?? 1);
+}
 function writeRulesFileAtomic(rulesFilePath, content) {
     const tmpPath = `${rulesFilePath}.tmp`;
     writeFileSync(tmpPath, content, { encoding: "utf-8", flag: "wx" });
@@ -248,7 +368,8 @@ if (process.argv[2] === "install") {
     await runInstall(process.argv.slice(3));
     process.exit(0);
 }
-// Handle marketplace subcommand — browse and install community skills
+// 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));
@@ -468,14 +589,20 @@ Options:
 // Handle gen-plugin-stub subcommand — scaffolds a new plugin directory
 if (process.argv[2] === "gen-plugin-stub") {
     const argv = process.argv.slice(3);
-    // Parse args: gen-plugin-stub <dir> [--name <name>] [--prefix <prefix>]
+    // Parse args: gen-plugin-stub <dir> [--name <name>] [--prefix <prefix>] [--ts]
     const dirArg = argv.find((a) => !a.startsWith("--"));
     if (!dirArg) {
-        process.stderr.write("Usage: claude-ide-bridge gen-plugin-stub <output-dir> [--name <org/plugin-name>] [--prefix <toolPrefix>]\n");
+        process.stderr.write("Usage: claude-ide-bridge gen-plugin-stub <output-dir> [--name <org/plugin-name>] [--prefix <toolPrefix>] [--ts]\n");
         process.exit(1);
     }
     const nameIdx = argv.indexOf("--name");
     const prefixIdx = argv.indexOf("--prefix");
+    // --ts emits a TypeScript variant (src/index.ts + tsconfig.json + build
+    // scripts) alongside a compiled-output manifest pointing at index.mjs.
+    // Plugin authors get type-checked tools without changing the hot-reload
+    // contract — `npm run dev` watches src/, emits index.mjs, bridge picks
+    // up the rebuilt artifact via --plugin-watch.
+    const useTypeScript = argv.includes("--ts");
     const pluginName = nameIdx !== -1 && argv[nameIdx + 1]
         ? argv[nameIdx + 1]
         : "my-org/my-plugin";
@@ -509,8 +636,8 @@ if (process.argv[2] === "gen-plugin-stub") {
         minBridgeVersion: "2.1.24",
     };
     writeFileSync(path.join(outDir, "claude-ide-bridge-plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
-    // index.mjs entrypoint
-    const entrypoint = `/**
+    // ── shared tool body — same logic, different surface syntax ──
+    const jsEntrypoint = `/**
  * ${pluginName} — Claude IDE Bridge plugin
  *
  * Each tool must have a name starting with "${toolPrefix}".
@@ -518,7 +645,7 @@ if (process.argv[2] === "gen-plugin-stub") {
  * ctx.config (commandTimeout, maxResultSize), and ctx.logger.
  */
 
-/** @param {import('claude-ide-bridge/plugin').PluginContext} ctx */
+/** @param {import('patchwork-os/plugin').PluginContext} ctx */
 export function register(ctx) {
   ctx.logger.info(${JSON.stringify(`${pluginName} loaded`)}, { workspace: ctx.workspace });
 
@@ -546,70 +673,381 @@ export function register(ctx) {
   };
 }
 `;
-    writeFileSync(path.join(outDir, "index.mjs"), entrypoint, "utf-8");
-    // package.json (optional, for npm publishing)
-    const pkg = {
+    const tsEntrypoint = `/**
+ * ${pluginName} — Claude IDE Bridge plugin
+ *
+ * Each tool must have a name starting with "${toolPrefix}".
+ * The \`ctx\` object provides: ctx.workspace, ctx.workspaceFolders,
+ * ctx.config (commandTimeout, maxResultSize), and ctx.logger.
+ */
+import type { PluginContext } from "patchwork-os/plugin";
+
+interface HelloArgs {
+  name: string;
+}
+
+export function register(ctx: PluginContext) {
+  ctx.logger.info(${JSON.stringify(`${pluginName} loaded`)}, { workspace: ctx.workspace });
+
+  return {
+    tools: [
+      {
+        schema: {
+          name: ${JSON.stringify(`${toolPrefix}Hello`)},
+          description: "Example tool — returns a greeting",
+          inputSchema: {
+            type: "object" as const,
+            required: ["name"] as const,
+            additionalProperties: false as const,
+            properties: {
+              name: { type: "string" as const, description: "Name to greet" },
+            },
+          },
+          annotations: { readOnlyHint: true },
+        },
+        handler: async (args: HelloArgs) => ({
+          content: [
+            {
+              type: "text" as const,
+              text: \`Hello from ${pluginName}, \${args.name}!\`,
+            },
+          ],
+        }),
+      },
+    ],
+  };
+}
+`;
+    // Write entrypoint — TS goes under src/, JS at root.
+    if (useTypeScript) {
+        mkdirSync(path.join(outDir, "src"), { recursive: true });
+        writeFileSync(path.join(outDir, "src", "index.ts"), tsEntrypoint, "utf-8");
+    }
+    else {
+        writeFileSync(path.join(outDir, "index.mjs"), jsEntrypoint, "utf-8");
+    }
+    // tsconfig.json — TS variant only. Emits a single ESM file at index.mjs
+    // so the plugin manifest's entrypoint stays the same shape as the JS
+    // scaffold and --plugin-watch reload semantics don't change.
+    if (useTypeScript) {
+        const tsconfig = {
+            compilerOptions: {
+                target: "ES2022",
+                module: "ES2022",
+                moduleResolution: "Bundler",
+                outDir: ".",
+                rootDir: "src",
+                declaration: false,
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                resolveJsonModule: true,
+                // Emit .mjs so the plugin loader (which expects ESM) picks it up
+                // without relying on package.json "type": "module" alone.
+                // tsc doesn't emit .mjs natively, so package.json's "build" script
+                // does a rename pass — see below.
+            },
+            include: ["src/**/*"],
+            exclude: ["node_modules"],
+        };
+        writeFileSync(path.join(outDir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`, "utf-8");
+    }
+    // package.json — TS variant adds build + dev (watch) scripts.
+    const pkgBase = {
         name: pluginName.replace(/^@[^/]+\//, "").replace(/\//g, "-"),
         version: "0.1.0",
         description: "A Claude IDE Bridge plugin",
         type: "module",
         main: "index.mjs",
-        keywords: ["claude-ide-bridge", "claude-ide-bridge-plugin"],
-        peerDependencies: { "claude-ide-bridge": ">=2.1.24" },
+        keywords: ["patchwork-os", "claude-ide-bridge-plugin"],
+        peerDependencies: { "patchwork-os": ">=0.2.0-alpha.0" },
     };
+    const pkg = useTypeScript
+        ? {
+            ...pkgBase,
+            scripts: {
+                // tsc emits index.js — rename to index.mjs so the loader treats
+                // it as ESM regardless of the consumer's package.json.
+                build: "tsc && mv index.js index.mjs",
+                dev: "tsc --watch",
+                clean: "rm -f index.mjs",
+            },
+            devDependencies: {
+                typescript: "^5.4.0",
+                "patchwork-os": ">=0.2.0-alpha.0",
+            },
+        }
+        : pkgBase;
     writeFileSync(path.join(outDir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+    // README.md — included in both variants. Spells out the hot-reload
+    // contract so plugin authors don't have to read the platform docs to
+    // get started.
+    const readmeBody = useTypeScript
+        ? `# ${pluginName}
+
+A [Claude IDE Bridge](https://github.com/Oolab-labs/patchwork-os) plugin (TypeScript).
+
+## Quick start
+
+\`\`\`sh
+npm install
+npm run dev      # in one terminal — watches src/, emits index.mjs
+
+# In another terminal:
+claude-ide-bridge --plugin . --plugin-watch
+\`\`\`
+
+Edit \`src/index.ts\`. \`tsc --watch\` rebuilds, the bridge hot-reloads, your tool is callable from the live Claude session on the next turn.
+
+## Build for distribution
+
+\`\`\`sh
+npm run build    # emits index.mjs
+npm publish      # publish to npm (optional)
+\`\`\`
+
+When published with the \`claude-ide-bridge-plugin\` keyword, users can install with:
+
+\`\`\`sh
+claude-ide-bridge --plugin ${pluginName.replace(/^@[^/]+\//, "")}
+\`\`\`
+
+## Tool naming
+
+Every tool exposed by this plugin **must** have a \`name\` starting with \`${toolPrefix}\`. The bridge enforces this at load time (\`/^[a-zA-Z][a-zA-Z0-9_]{1,19}$/\`).
+
+## Plugin context
+
+The \`ctx\` argument to \`register()\` provides:
+
+- \`ctx.workspace\` — workspace root path
+- \`ctx.workspaceFolders\` — array of workspace folders
+- \`ctx.config\` — \`{ commandTimeout, maxResultSize }\`
+- \`ctx.logger\` — \`info\` / \`warn\` / \`error\` logging that respects bridge log level
+
+## Live toolsmithing
+
+The whole point of plugins is that you can author tools *while Claude is using the bridge*. Edit \`src/index.ts\`, save, the watcher rebuilds, the bridge reloads — Claude's next turn sees the new tool.
+
+See [documents/live-toolsmithing.md](https://github.com/Oolab-labs/patchwork-os/blob/main/documents/live-toolsmithing.md) for the full narrative.
+`
+        : `# ${pluginName}
+
+A [Claude IDE Bridge](https://github.com/Oolab-labs/patchwork-os) plugin.
+
+## Quick start
+
+\`\`\`sh
+claude-ide-bridge --plugin . --plugin-watch
+\`\`\`
+
+Edit \`index.mjs\`. The bridge hot-reloads on save — your tool is callable from the live Claude session on the next turn. No build step needed for the JS variant.
+
+## Tool naming
+
+Every tool exposed by this plugin **must** have a \`name\` starting with \`${toolPrefix}\`. The bridge enforces this at load time (\`/^[a-zA-Z][a-zA-Z0-9_]{1,19}$/\`).
+
+## Plugin context
+
+The \`ctx\` argument to \`register()\` provides:
+
+- \`ctx.workspace\` — workspace root path
+- \`ctx.workspaceFolders\` — array of workspace folders
+- \`ctx.config\` — \`{ commandTimeout, maxResultSize }\`
+- \`ctx.logger\` — \`info\` / \`warn\` / \`error\` logging that respects bridge log level
+
+## Want types?
+
+Re-scaffold with \`claude-ide-bridge gen-plugin-stub <dir> --ts\` for a TypeScript variant with \`tsc --watch\` build pipeline.
+
+## Live toolsmithing
+
+Edit, save, hot-reload — Claude's next turn sees the new tool. See [documents/live-toolsmithing.md](https://github.com/Oolab-labs/patchwork-os/blob/main/documents/live-toolsmithing.md) for the full narrative.
+`;
+    writeFileSync(path.join(outDir, "README.md"), readmeBody, "utf-8");
     // .gitignore
-    writeFileSync(path.join(outDir, ".gitignore"), "node_modules\n", "utf-8");
-    process.stderr.write(`✓ Plugin stub created at ${outDir}\n`);
+    const gitignore = useTypeScript
+        ? "node_modules\nindex.mjs\nindex.js\n*.tsbuildinfo\n"
+        : "node_modules\n";
+    writeFileSync(path.join(outDir, ".gitignore"), gitignore, "utf-8");
+    process.stderr.write(`✓ Plugin stub created at ${outDir} (${useTypeScript ? "TypeScript" : "JavaScript"})\n`);
     process.stderr.write("\nNext steps:\n");
-    process.stderr.write(`  1. Edit ${path.join(outDir, "index.mjs")} to implement your tools\n`);
-    process.stderr.write(`  2. Run the bridge with: claude-ide-bridge --plugin ${outDir}\n`);
-    process.stderr.write(`  3. Or add to your config: { "plugins": ["${outDir}"] }\n`);
+    if (useTypeScript) {
+        process.stderr.write(`  1. cd ${outDir} && npm install\n`);
+        process.stderr.write(`  2. Edit ${path.join(outDir, "src", "index.ts")} to implement your tools\n`);
+        process.stderr.write(`  3. npm run dev  (in one terminal)\n`);
+        process.stderr.write(`  4. claude-ide-bridge --plugin ${outDir} --plugin-watch  (in another)\n`);
+    }
+    else {
+        process.stderr.write(`  1. Edit ${path.join(outDir, "index.mjs")} to implement your tools\n`);
+        process.stderr.write(`  2. Run the bridge with: claude-ide-bridge --plugin ${outDir} --plugin-watch\n`);
+        process.stderr.write(`  3. Or add to your config: { "plugins": ["${outDir}"] }\n`);
+    }
     process.exit(0);
 }
 // Patchwork: `patchwork recipe list` — enumerate installed recipes.
 if (process.argv[2] === "recipe" && process.argv[3] === "list") {
     (async () => {
-        const { listYamlRecipes } = await import("./recipes/yamlRunner.js");
-        const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-        const recipes = listYamlRecipes(recipesDir);
-        if (recipes.length === 0) {
-            process.stdout.write("No recipes installed. Run `patchwork-os patchwork-init` to install the starter set.\n");
+        const { listInstalledRecipes, printInstalledList } = await import("./commands/recipeInstall.js");
+        const entries = listInstalledRecipes();
+        printInstalledList(entries);
+        process.exit(0);
+    })();
+}
+// Patchwork: `patchwork recipe enable <name>` / `recipe disable <name>` —
+// flip the disabled marker so scheduled triggers (cron/file-watch) take
+// effect (or stop). Manual `recipe run` is unaffected.
+if (process.argv[2] === "recipe" &&
+    (process.argv[3] === "enable" || process.argv[3] === "disable")) {
+    const subcommand = process.argv[3];
+    const name = process.argv[4];
+    if (!name) {
+        process.stderr.write(`Usage: patchwork recipe ${subcommand} <name>\n` +
+            `  See \`patchwork recipe list\` for installed recipe names.\n`);
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const { runRecipeEnable, runRecipeDisable } = await import("./commands/recipeInstall.js");
+            if (subcommand === "enable") {
+                const r = runRecipeEnable(name);
+                process.stdout.write(r.alreadyEnabled
+                    ? `  ℹ ${r.name} is already enabled\n`
+                    : `  ✓ enabled ${r.name}\n`);
+            }
+            else {
+                const r = runRecipeDisable(name);
+                process.stdout.write(r.alreadyDisabled
+                    ? `  ℹ ${r.name} is already disabled\n`
+                    : `  ✓ disabled ${r.name}\n`);
+            }
+            process.exit(0);
         }
-        else {
-            process.stdout.write(`Installed recipes (${recipes.length}):\n\n`);
-            for (const r of recipes) {
-                const desc = r.description ? `  ${r.description}` : "";
-                process.stdout.write(`  ${r.name.padEnd(28)} [${r.trigger}]${desc}\n`);
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe uninstall <name>` — remove an installed recipe
+// directory and all its files. Sister to `recipe install`. Idempotent on
+// success (subsequent uninstalls error with "no installed recipe").
+if (process.argv[2] === "recipe" && process.argv[3] === "uninstall") {
+    const name = process.argv[4];
+    if (!name) {
+        process.stderr.write("Usage: patchwork recipe uninstall <name>\n" +
+            "  See `patchwork recipe list` for installed recipe names.\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const { runRecipeUninstall } = await import("./commands/recipeInstall.js");
+            const r = runRecipeUninstall(name);
+            if (!r.ok) {
+                process.stderr.write(`Error: ${r.error}\n`);
+                process.exit(1);
             }
-            process.stdout.write(`\nRun a recipe: patchwork-os recipe run <name>\n`);
+            process.stdout.write(`  ✓ Uninstalled ${name} (${r.installDir})\n`);
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
         }
-        process.exit(0);
     })();
 }
 // Patchwork: `patchwork recipe run <name>` — runs a recipe locally or via
 // 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 localFlag = args.includes("--local");
-    const name = args.find((a) => !a.startsWith("--"));
-    if (!name) {
-        process.stderr.write("Usage: patchwork recipe run <name> [--local]\n");
+    const usage = "Usage: patchwork recipe run <name-or-file> [--local] [--dry-run] [--step <id>] [--var KEY=VALUE]\n";
+    let localFlag = false;
+    let dryRun = false;
+    let recipeRef;
+    let step;
+    const vars = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        const currentArg = arg;
+        if (currentArg === "--local") {
+            localFlag = true;
+            continue;
+        }
+        if (currentArg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (currentArg === "--step" || currentArg.startsWith("--step=")) {
+            const value = currentArg === "--step"
+                ? args[++i]
+                : currentArg.slice("--step=".length);
+            if (!value) {
+                process.stderr.write(`Error: --step requires a value\n${usage}`);
+                process.exit(1);
+            }
+            step = value;
+            continue;
+        }
+        if (currentArg === "--var" || currentArg.startsWith("--var=")) {
+            const assignment = currentArg === "--var" ? args[++i] : currentArg.slice("--var=".length);
+            if (!assignment) {
+                process.stderr.write(`Error: --var requires KEY=VALUE\n${usage}`);
+                process.exit(1);
+            }
+            const eqIndex = assignment.indexOf("=");
+            if (eqIndex <= 0) {
+                process.stderr.write(`Error: invalid --var assignment "${assignment}" (expected KEY=VALUE)\n${usage}`);
+                process.exit(1);
+            }
+            const key = assignment.slice(0, eqIndex);
+            const value = assignment.slice(eqIndex + 1);
+            vars[key] = value;
+            continue;
+        }
+        if (currentArg.startsWith("--")) {
+            process.stderr.write(`Error: unknown option ${currentArg}\n${usage}`);
+            process.exit(1);
+        }
+        if (!recipeRef) {
+            recipeRef = currentArg;
+            continue;
+        }
+        process.stderr.write(`Error: unexpected argument ${currentArg}\n${usage}`);
+        process.exit(1);
+    }
+    if (!recipeRef) {
+        process.stderr.write(usage);
         process.exit(1);
     }
+    const recipeArg = recipeRef;
     (async () => {
         try {
-            // Try bridge first (requires --claude-driver subprocess).
+            const seedVars = Object.keys(vars).length > 0 ? vars : undefined;
+            const explicitFile = (() => {
+                try {
+                    const resolved = path.resolve(recipeArg);
+                    return existsSync(resolved) && statSync(resolved).isFile();
+                }
+                catch {
+                    return false;
+                }
+            })();
             const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
             const lock = localFlag ? null : findBridgeLock();
-            if (lock) {
+            if (lock && !dryRun && !step && !explicitFile) {
                 const res = await fetch(`http://127.0.0.1:${lock.port}/recipes/run`, {
                     method: "POST",
                     headers: {
                         Authorization: `Bearer ${lock.authToken}`,
                         "Content-Type": "application/json",
                     },
-                    body: JSON.stringify({ name }),
+                    body: JSON.stringify({
+                        name: recipeArg,
+                        ...(seedVars ? { vars: seedVars } : {}),
+                    }),
                 });
                 const body = (await res.json());
                 if (!body.ok) {
@@ -622,43 +1060,64 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
                     // else: fall through to local runner below
                 }
                 else {
-                    process.stdout.write(`  ✓ enqueued recipe "${name}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
+                    process.stdout.write(`  ✓ enqueued recipe "${recipeArg}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
                         "    Watch progress on the dashboard Tasks page or via listClaudeTasks.\n");
                     process.exit(0);
                     return;
                 }
             }
-            // No bridge — run locally using the YAML runner.
-            const { loadYamlRecipe, runYamlRecipe } = await import("./recipes/yamlRunner.js");
-            const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-            const bundledDir = fileURLToPath(new URL("../templates/recipes", import.meta.url));
-            const candidates = [
-                path.join(recipesDir, `${name}.yaml`),
-                path.join(recipesDir, `${name}.yml`),
-                path.join(recipesDir, `${name}.json`),
-                path.join(bundledDir, `${name}.yaml`),
-                path.join(bundledDir, `${name}.yml`),
-            ];
-            let recipePath;
-            for (const c of candidates) {
-                if (existsSync(c)) {
-                    recipePath = c;
-                    break;
-                }
-            }
-            if (!recipePath) {
-                process.stderr.write(`Error: recipe "${name}" not found in ${recipesDir}\n` +
-                    "  Run `patchwork-os recipe list` to see available recipes.\n");
-                process.exit(1);
+            const { runRecipe, runRecipeDryPlan, summarizeRecipeExecution, formatRunReport, extractRunLogStepResults, } = await import("./commands/recipe.js");
+            if (dryRun) {
+                const plan = await runRecipeDryPlan(recipeArg, {
+                    ...(step ? { step } : {}),
+                    ...(seedVars ? { vars: seedVars } : {}),
+                });
+                process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+                process.exit(0);
                 return;
             }
-            process.stdout.write(`  Running recipe "${name}" locally…\n`);
-            const recipe = loadYamlRecipe(recipePath);
+            process.stdout.write(step
+                ? `  Running step "${step}" from recipe "${recipeArg}" locally…\n`
+                : `  Running recipe "${recipeArg}" locally…\n`);
             const workdir = lock?.workspace || process.cwd();
-            const result = await runYamlRecipe(recipe, { workdir });
-            process.stdout.write(`  ✓ ${result.stepsRun} step(s) completed\n`);
-            if (result.outputs.length > 0) {
-                process.stdout.write(`  Output written to:\n${result.outputs.map((o) => `    ${o}`).join("\n")}\n`);
+            const run = await runRecipe(recipeArg, {
+                ...(step ? { step } : {}),
+                ...(seedVars ? { vars: seedVars } : {}),
+                workdir,
+            });
+            if (run.stepSelection) {
+                process.stdout.write(`  Selected step via ${run.stepSelection.matchedBy}: ${run.stepSelection.matchedValue}\n`);
+            }
+            const summary = summarizeRecipeExecution(run.result);
+            process.stdout.write(`${formatRunReport(run.result, run.recipe.name)}\n`);
+            if (summary.errorMessage) {
+                process.stderr.write(`  Error: ${summary.errorMessage}\n`);
+            }
+            // Append to run log so CLI runs appear in ctxQueryTraces + dashboard /runs
+            try {
+                const { RecipeRunLog } = await import("./runLog.js");
+                const runLog = new RecipeRunLog({
+                    dir: path.join(os.homedir(), ".patchwork"),
+                });
+                const startedAt = Date.now();
+                const stepResultsForLog = extractRunLogStepResults(run.result);
+                runLog.appendDirect({
+                    taskId: `cli-${Date.now()}`,
+                    recipeName: run.recipe.name,
+                    trigger: "recipe",
+                    status: summary.ok ? "done" : "error",
+                    createdAt: startedAt,
+                    startedAt,
+                    doneAt: Date.now(),
+                    durationMs: 0,
+                    ...(summary.errorMessage
+                        ? { errorMessage: summary.errorMessage }
+                        : {}),
+                    ...(stepResultsForLog ? { stepResults: stepResultsForLog } : {}),
+                });
+            }
+            catch {
+                // Non-fatal — run log write failure must not abort the CLI
             }
             process.exit(0);
         }
@@ -669,24 +1128,596 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
     })();
 }
 // Handle init subcommand — one-command setup: install extension + write CLAUDE.md + print next steps
-// Patchwork: `patchwork recipe install <file.json>` subcommand.
+// Patchwork: `patchwork recipe install <source>` subcommand.
+// Supports: github:owner/repo, github:owner/repo/subdir, https://github.com/owner/repo,
+//           ./local/path, or legacy <file.json> (single-recipe install).
 if (process.argv[2] === "recipe" && process.argv[3] === "install") {
+    const source = process.argv[4];
+    if (!source) {
+        process.stderr.write("Usage: patchwork recipe install <source>\n" +
+            "  <source> can be:\n" +
+            "    github:owner/repo\n" +
+            "    github:owner/repo/subdir\n" +
+            "    https://github.com/owner/repo\n" +
+            "    ./local/path\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            // Legacy path: bare .json file argument → single-file installer
+            if (source.endsWith(".json") &&
+                !source.startsWith("github:") &&
+                !source.startsWith("http")) {
+                const { installRecipeFromFile } = await import("./recipes/installer.js");
+                const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
+                const result = installRecipeFromFile(path.resolve(source), {
+                    recipesDir,
+                });
+                // alpha.36+ — sidecar `<name>.permissions.json` is no longer written
+                // (was decorative, never read by toolRegistry). Print the suggested
+                // permissions snippet inline so users can hand-merge into settings.
+                process.stdout.write(`  ✓ ${result.action} ${result.installedPath}\n` +
+                    `  ℹ Patchwork does not enforce per-recipe permissions; configure tool gating in ~/.claude/settings.json.\n` +
+                    `    Suggested permissions snippet:\n${result.permissionsJson
+                        .split("\n")
+                        .map((l) => `      ${l}`)
+                        .join("\n")}\n`);
+            }
+            else {
+                // Marketplace install: github:, https://, ./local/
+                const { runRecipeInstall, printInstallResult } = await import("./commands/recipeInstall.js");
+                const result = await runRecipeInstall(source);
+                printInstallResult(result);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork suggest [--since <date>]` — pattern-mine the
+// activity log + run history for "you've been doing X by hand; want to
+// make a recipe?" hints. See documents/strategic/2026-05-02/memory-
+// ecosystem-report.md §6 for the catalog this implements.
+//
+// Three suggestion kinds: co-occurring tool pairs (worth a recipe), tools
+// installed but unused (worth reviewing or pruning), and recipes that
+// always succeed (worth trust-graduating). Read-only — does not change
+// any policy or registry state.
+if (process.argv[2] === "suggest") {
+    (async () => {
+        try {
+            const args = process.argv.slice(3);
+            let sinceDays;
+            for (let i = 0; i < args.length; i++) {
+                const a = args[i];
+                if (a === "--since-days") {
+                    const next = args[i + 1];
+                    if (next)
+                        sinceDays = Number.parseInt(next, 10);
+                    i++;
+                }
+                else if (a === "--help" || a === "-h") {
+                    process.stdout.write("patchwork suggest [--since-days <N>]\n\n" +
+                        "Pattern-mine the activity log + recipe runs for automation hints:\n" +
+                        "  - Co-occurring tool pairs that don't yet appear in any recipe\n" +
+                        "  - Installed tools that haven't been called recently\n" +
+                        "  - Recipes that have succeeded ≥ 10 times in a row (trust-graduation candidates)\n\n" +
+                        "Default lookback window is 7 days. --since-days overrides.\n\n" +
+                        "Read-only — does not modify policy, registry, or run history.\n");
+                    process.exit(0);
+                }
+            }
+            const { ActivityLog } = await import("./activityLog.js");
+            const { RecipeRunLog } = await import("./runLog.js");
+            const { computeAutomationSuggestions } = await import("./automationSuggestions.js");
+            // Side-effect import — populates the tool registry that
+            // computeAutomationSuggestions consults for installed-tool inventory.
+            await import("./recipes/tools/index.js");
+            // Wire up the bridge's standard log paths. The CLI reads from
+            // disk; it doesn't need a running bridge.
+            const patchworkDir = path.join(os.homedir(), ".patchwork");
+            const activityLog = new ActivityLog();
+            // Find the most recent activity log file (any port). For the
+            // suggest CLI we union all of them.
+            const claudeIdeDir = path.join(os.homedir(), ".claude", "ide");
+            try {
+                const entries = await import("node:fs").then((m) => m.readdirSync(claudeIdeDir));
+                for (const name of entries) {
+                    if (/^activity(-\d+)?\.jsonl$/i.test(name)) {
+                        activityLog.setPersistPath(path.join(claudeIdeDir, name));
+                        break; // setPersistPath loads on call; first existing wins
+                    }
+                }
+            }
+            catch {
+                // No activity dir / files — proceed with an empty log; the
+                // suggestions just return fewer / no items.
+            }
+            const recipeRunLog = new RecipeRunLog({ dir: patchworkDir });
+            const opts = {
+                activityLog,
+                recipeRunLog,
+            };
+            if (sinceDays !== undefined && Number.isFinite(sinceDays)) {
+                opts.activitySinceMs = sinceDays * 24 * 60 * 60 * 1000;
+            }
+            const suggestions = computeAutomationSuggestions(opts);
+            if (suggestions.length === 0) {
+                process.stdout.write("No automation suggestions yet. Patchwork mines patterns from the activity log\n" +
+                    "and recipe run history; come back after a few days of use.\n");
+                process.exit(0);
+            }
+            process.stdout.write(`${suggestions.length} suggestion${suggestions.length === 1 ? "" : "s"}:\n\n`);
+            for (const s of suggestions) {
+                const icon = s.kind === "co_occurring_pair"
+                    ? "→"
+                    : s.kind === "installed_but_unused"
+                        ? "·"
+                        : "★";
+                process.stdout.write(`  ${icon} ${s.label}\n`);
+            }
+            process.stdout.write("\nRead-only output. Nothing changed.\n");
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe schema [outputDir]` — write generated recipe schemas to disk.
+// Patchwork: `patchwork traces export [--output <path>]` — bundle the four
+// local trace logs into a single .jsonl.gz so a user can move machines,
+// take a compliance snapshot, or share traces with another tool. See
+// docs/strategic/2026-05-02/memory-ecosystem-report.md items 1, 3, 12 for
+// the durability rationale this PR addresses.
+if (process.argv[2] === "traces" && process.argv[3] === "export") {
+    (async () => {
+        try {
+            const args = process.argv.slice(4);
+            let output;
+            let patchworkDir;
+            let activityDir;
+            for (let i = 0; i < args.length; i++) {
+                const a = args[i];
+                if (a === "--output" || a === "-o") {
+                    output = args[i + 1];
+                    i++;
+                }
+                else if (a === "--patchwork-dir") {
+                    patchworkDir = args[i + 1];
+                    i++;
+                }
+                else if (a === "--activity-dir") {
+                    activityDir = args[i + 1];
+                    i++;
+                }
+                else if (a === "--help" || a === "-h") {
+                    process.stdout.write("patchwork traces export [--output <path>] [--patchwork-dir <dir>] [--activity-dir <dir>]\n\n" +
+                        "Bundles ~/.patchwork/{runs,decision_traces,commit_issue_links}.jsonl\n" +
+                        "and ~/.claude/ide/activity-*.jsonl into a single gzipped JSONL file.\n\n" +
+                        "Output is a manifest line followed by one envelope per row:\n" +
+                        '  {"type":"manifest", ...}\n' +
+                        '  {"source":"runs", "entry":{...}}\n' +
+                        "  ...\n\n" +
+                        "Filter one source with:\n" +
+                        "  gunzip -c traces-export-*.jsonl.gz | jq 'select(.source==\"decision_traces\") | .entry'\n");
+                    process.exit(0);
+                }
+            }
+            const { runTracesExport } = await import("./commands/tracesExport.js");
+            const result = await runTracesExport({
+                ...(output !== undefined && { output }),
+                ...(patchworkDir !== undefined && { patchworkDir }),
+                ...(activityDir !== undefined && { activityDir }),
+            });
+            process.stdout.write(`  ✓ Wrote ${result.outputPath}\n`);
+            process.stdout.write(`    ${result.totalCount} rows from ${result.files.length} file${result.files.length === 1 ? "" : "s"} (${result.totalBytes} bytes read)\n`);
+            for (const f of result.files) {
+                process.stdout.write(`    - ${f.source}: ${f.count} rows  (${f.path})\n`);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork traces import <bundle>` — restore an export bundle
+// into the local patchwork dirs. Closes the half-shipped backup loop.
+if (process.argv[2] === "traces" && process.argv[3] === "import") {
+    (async () => {
+        try {
+            const args = process.argv.slice(4);
+            let input;
+            let patchworkDir;
+            let activityDir;
+            let mode = "append";
+            let dryRun = false;
+            let passphrase;
+            for (let i = 0; i < args.length; i++) {
+                const a = args[i];
+                if (a === "--patchwork-dir") {
+                    patchworkDir = args[i + 1];
+                    i++;
+                }
+                else if (a === "--activity-dir") {
+                    activityDir = args[i + 1];
+                    i++;
+                }
+                else if (a === "--mode") {
+                    const m = args[i + 1];
+                    if (m !== "append" && m !== "overwrite") {
+                        process.stderr.write(`Error: --mode must be "append" or "overwrite" (got: ${m})\n`);
+                        process.exit(1);
+                    }
+                    mode = m;
+                    i++;
+                }
+                else if (a === "--passphrase") {
+                    passphrase = args[i + 1];
+                    i++;
+                }
+                else if (a === "--dry-run") {
+                    dryRun = true;
+                }
+                else if (a === "--help" || a === "-h") {
+                    process.stdout.write("patchwork traces import <bundle> [--mode append|overwrite] [--dry-run]\n" +
+                        "                        [--passphrase <phrase>]\n" +
+                        "                        [--patchwork-dir <dir>] [--activity-dir <dir>]\n\n" +
+                        "Restore a bundle written by `patchwork traces export` into the local\n" +
+                        "patchwork dirs (~/.patchwork/ and ~/.claude/ide/ by default).\n\n" +
+                        "Formats:\n" +
+                        "  .jsonl.gz   Plain gzip bundle — no passphrase required.\n" +
+                        "  .enc        AES-256-GCM encrypted bundle — pass --passphrase.\n\n" +
+                        "Modes:\n" +
+                        "  append     (default) Append rows to existing files.\n" +
+                        "  overwrite  Truncate target files before writing. Use for fresh-machine\n" +
+                        "             restore; never use when there's local data you want to keep.\n");
+                    process.exit(0);
+                }
+                else if (a !== undefined &&
+                    !a.startsWith("--") &&
+                    input === undefined) {
+                    input = a;
+                }
+            }
+            if (!input) {
+                process.stderr.write("Usage: patchwork traces import <bundle> [--passphrase <phrase>] [--mode append|overwrite] [--dry-run]\n");
+                process.exit(1);
+            }
+            // Auto-detect encrypted bundle and decrypt before import.
+            if (passphrase !== undefined || input.endsWith(".enc")) {
+                const { readFileSync } = await import("node:fs");
+                const { isEncryptedTraceBundle, decryptTraceBundle } = await import("./traceEncryption.js");
+                const raw = readFileSync(input);
+                if (isEncryptedTraceBundle(raw)) {
+                    if (!passphrase) {
+                        process.stderr.write("Error: bundle is encrypted — provide --passphrase <phrase>\n");
+                        process.exit(1);
+                    }
+                    const plain = decryptTraceBundle(raw, passphrase);
+                    const { tmpdir } = await import("node:os");
+                    const { writeFileSync } = await import("node:fs");
+                    const tmp = `${tmpdir()}/patchwork-import-${Date.now()}.jsonl.gz`;
+                    writeFileSync(tmp, plain, { mode: 0o600 });
+                    input = tmp;
+                    process.stderr.write("Decryption succeeded.\n");
+                }
+            }
+            const { runTracesImport } = await import("./commands/tracesImport.js");
+            const result = await runTracesImport({
+                input,
+                ...(patchworkDir !== undefined && { patchworkDir }),
+                ...(activityDir !== undefined && { activityDir }),
+                mode,
+                dryRun,
+            });
+            const verb = result.dryRun
+                ? "Would restore"
+                : result.mode === "overwrite"
+                    ? "Restored (overwrite)"
+                    : "Restored (append)";
+            process.stdout.write(`  ${result.dryRun ? "•" : "✓"} ${verb} ${result.totalCount} rows from ${result.inputPath}\n`);
+            process.stdout.write(`    Bundle exportedAt: ${result.exportedAt}\n`);
+            for (const f of result.files) {
+                process.stdout.write(`    - ${f.source}: ${f.count} rows  →  ${f.targetPath}\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 () => {
+        try {
+            const { runSchema } = await import("./commands/recipe.js");
+            const result = await runSchema(path.resolve(outputDir));
+            process.stdout.write(`  ✓ Wrote schemas to ${result.outputDir}\n`);
+            for (const file of result.filesWritten) {
+                process.stdout.write(`    ${file}\n`);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe new <name>` — scaffold a new recipe from template.
+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 {
+        (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") {
     const file = process.argv[4];
     if (!file) {
-        process.stderr.write("Usage: patchwork recipe install <file.json>\n");
+        process.stderr.write("Usage: patchwork recipe lint <file.yaml>\n");
         process.exit(1);
     }
     (async () => {
         try {
-            const { installRecipeFromFile } = await import("./recipes/installer.js");
-            const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-            const result = installRecipeFromFile(path.resolve(file), {
-                recipesDir,
+            const { runLint } = await import("./commands/recipe.js");
+            const result = runLint(path.resolve(file));
+            for (const issue of result.issues) {
+                const prefix = issue.level === "error" ? "✗" : "⚠";
+                process.stderr.write(`  ${prefix} ${issue.message}\n`);
+            }
+            if (result.valid) {
+                process.stdout.write(`  ✓ Valid recipe (${result.warnings} warnings)\n`);
+                process.exit(0);
+            }
+            else {
+                process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+                process.exit(1);
+            }
+        }
+        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);
+    const usage = "Usage: patchwork recipe preflight <file.yaml> [--json] [--watch] [--require-fixtures] [--no-require-write-ack] [--allow-write <tool-or-ns>]\n";
+    let json = false;
+    let watchMode = false;
+    let requireFixtures = false;
+    let requireWriteAck = true;
+    const allowWrites = [];
+    let file;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--watch") {
+            watchMode = true;
+            continue;
+        }
+        if (arg === "--require-fixtures") {
+            requireFixtures = true;
+            continue;
+        }
+        if (arg === "--no-require-write-ack") {
+            requireWriteAck = false;
+            continue;
+        }
+        if (arg === "--allow-write" || arg.startsWith("--allow-write=")) {
+            const value = arg === "--allow-write"
+                ? args[++i]
+                : arg.slice("--allow-write=".length);
+            if (!value) {
+                process.stderr.write(`Error: --allow-write requires a value\n${usage}`);
+                process.exit(1);
+            }
+            allowWrites.push(value);
+            continue;
+        }
+        if (!arg.startsWith("--")) {
+            file = arg;
+        }
+    }
+    if (!file) {
+        process.stderr.write(usage);
+        process.exit(1);
+    }
+    const renderResult = (result) => {
+        if (json) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        for (const issue of result.issues) {
+            const prefix = issue.level === "error" ? "✗" : "⚠";
+            const where = issue.stepId ? ` [${issue.stepId}]` : "";
+            process.stderr.write(`  ${prefix} ${issue.code}${where}: ${issue.message}\n`);
+        }
+        if (result.ok) {
+            process.stdout.write(`  ✓ Preflight passed for ${result.recipe} (${result.plan.steps.length} steps)\n`);
+        }
+        else {
+            const errorCount = result.issues.filter((i) => i.level === "error").length;
+            process.stdout.write(`\n  ${errorCount} error(s) — preflight failed\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runPreflight, runPreflightWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — preflight on save…\n`);
+                const stop = runPreflightWatch({
+                    recipePath: resolvedPath,
+                    requireWriteAck,
+                    requireFixtures,
+                    allowWrites,
+                    onResult: (result) => renderResult(result),
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = await runPreflight(resolvedPath, {
+                requireWriteAck,
+                requireFixtures,
+                allowWrites,
             });
-            process.stdout.write(`  ✓ ${result.action} ${result.installedPath}\n` +
-                `  ℹ permissions snippet written to ${result.installedPath}.permissions.json\n` +
-                `    Review + merge into ~/.claude/settings.json to pre-approve recipe steps.\n`);
-            process.exit(0);
+            renderResult(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);
+    const check = args.includes("--check");
+    const watchMode = args.includes("--watch");
+    const file = args.find((arg) => !arg.startsWith("--"));
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe fmt <file.yaml> [--check] [--watch]\n");
+        process.exit(1);
+    }
+    const renderResult = (result, filePath) => {
+        if (check) {
+            process.stdout.write(result.changed
+                ? "  ✗ File would be reformatted\n"
+                : "  ✓ File is already formatted\n");
+        }
+        else {
+            process.stdout.write(result.changed
+                ? `  ✓ Formatted ${filePath}\n`
+                : `  ✓ Already formatted ${filePath}\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runFmt, runFmtWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — fmt on save…\n`);
+                const stop = runFmtWatch({
+                    recipePath: resolvedPath,
+                    check,
+                    onResult: (result) => {
+                        process.stdout.write(`\n[${new Date().toLocaleTimeString()}] ${resolvedPath}\n`);
+                        renderResult(result, resolvedPath);
+                    },
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = runFmt(resolvedPath, { check });
+            renderResult(result, file);
+            process.exit(check && result.changed ? 1 : 0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe record <file.yaml>` — execute live and record connector fixtures.
+if (process.argv[2] === "recipe" && process.argv[3] === "record") {
+    const args = process.argv.slice(4);
+    const file = args.find((arg) => !arg.startsWith("--"));
+    const fixturesIdx = args.indexOf("--fixtures");
+    const fixturesDir = fixturesIdx >= 0 ? args[fixturesIdx + 1] : undefined;
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe record <file.yaml> [--fixtures <dir>]\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const { runRecord } = await import("./commands/recipe.js");
+            const result = await runRecord(path.resolve(file), {
+                ...(fixturesDir ? { fixturesDir: path.resolve(fixturesDir) } : {}),
+            });
+            for (const issue of result.issues) {
+                const prefix = issue.level === "error" ? "✗" : "⚠";
+                process.stderr.write(`  ${prefix} ${issue.message}\n`);
+            }
+            if (result.recordedFixtures.length > 0) {
+                process.stdout.write(`  ℹ Recorded fixture libraries: ${result.recordedFixtures.join(", ")}\n`);
+            }
+            if (result.valid) {
+                process.stdout.write("  ✓ Recipe fixtures recorded\n");
+                process.exit(0);
+            }
+            process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+            process.exit(1);
         }
         catch (err) {
             process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -694,6 +1725,153 @@ if (process.argv[2] === "recipe" && process.argv[3] === "install") {
         }
     })();
 }
+// Patchwork: `patchwork recipe test <file.yaml>` — validate fixture coverage for mocked execution.
+if (process.argv[2] === "recipe" && process.argv[3] === "test") {
+    const args = process.argv.slice(4);
+    const file = args.find((arg) => !arg.startsWith("--"));
+    const fixturesIdx = args.indexOf("--fixtures");
+    const fixturesDir = fixturesIdx >= 0 ? args[fixturesIdx + 1] : undefined;
+    const watchMode = args.includes("--watch");
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe test <file.yaml> [--fixtures <dir>] [--watch]\n");
+        process.exit(1);
+    }
+    const renderResult = (result) => {
+        for (const issue of result.issues) {
+            const prefix = issue.level === "error" ? "✗" : "⚠";
+            process.stderr.write(`  ${prefix} ${issue.message}\n`);
+        }
+        if (result.requiredFixtures.length > 0) {
+            process.stdout.write(`  ℹ Required fixtures: ${result.requiredFixtures.join(", ")}\n`);
+        }
+        if (result.valid) {
+            process.stdout.write("  ✓ Test passed\n");
+        }
+        else {
+            process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runTest, runTestWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            const resolvedFixtures = fixturesDir
+                ? path.resolve(fixturesDir)
+                : undefined;
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — test on save…\n`);
+                const stop = runTestWatch({
+                    recipePath: resolvedPath,
+                    ...(resolvedFixtures ? { fixturesDir: resolvedFixtures } : {}),
+                    onResult: (result) => {
+                        process.stdout.write(`\n[${new Date().toLocaleTimeString()}] ${resolvedPath}\n`);
+                        renderResult(result);
+                    },
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = await runTest(resolvedPath, {
+                ...(resolvedFixtures ? { fixturesDir: resolvedFixtures } : {}),
+            });
+            renderResult(result);
+            process.exit(result.valid ? 0 : 1);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe watch <file.yaml>` — watch for changes and validate.
+if (process.argv[2] === "recipe" && process.argv[3] === "watch") {
+    const file = process.argv[4];
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe watch <file.yaml>\n");
+        process.exit(1);
+    }
+    (async () => {
+        const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
+        const { runWatch, runLint, runWatchedRecipe, formatRunReport, summarizeRecipeExecution, extractRunLogStepResults, } = await import("./commands/recipe.js");
+        const filePath = path.resolve(file);
+        const lock = findBridgeLock();
+        const workdir = lock?.workspace || process.cwd();
+        const initial = runLint(filePath);
+        if (!initial.valid) {
+            process.stderr.write("  ✗ Recipe has errors - fix before watching\n");
+            for (const issue of initial.issues) {
+                process.stderr.write(`    ${issue.level}: ${issue.message}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`  ✓ Watching ${file} for changes...\n`);
+        }
+        const stop = runWatch({
+            recipePath: filePath,
+            onChange: async () => {
+                process.stdout.write(`\n  Change detected, running...\n`);
+                const watched = await runWatchedRecipe(filePath, { workdir });
+                if (!watched.lint.valid) {
+                    process.stderr.write(`  ✗ Invalid (${watched.lint.errors} errors)\n`);
+                    for (const issue of watched.lint.issues) {
+                        process.stderr.write(`    ${issue.level}: ${issue.message}\n`);
+                    }
+                    return;
+                }
+                if (watched.run?.stepSelection) {
+                    process.stdout.write(`  Selected step via ${watched.run.stepSelection.matchedBy}: ${watched.run.stepSelection.matchedValue}\n`);
+                }
+                if (watched.run) {
+                    process.stdout.write(`${formatRunReport(watched.run.result, watched.run.recipe.name)}\n`);
+                    const summary = summarizeRecipeExecution(watched.run.result);
+                    if (summary.errorMessage) {
+                        process.stderr.write(`  Error: ${summary.errorMessage}\n`);
+                    }
+                    // Append to run log
+                    try {
+                        const { RecipeRunLog } = await import("./runLog.js");
+                        const runLog = new RecipeRunLog({
+                            dir: path.join(os.homedir(), ".patchwork"),
+                        });
+                        const now = Date.now();
+                        const stepResultsForLog = extractRunLogStepResults(watched.run.result);
+                        runLog.appendDirect({
+                            taskId: `watch-${now}`,
+                            recipeName: watched.run.recipe.name,
+                            trigger: "recipe",
+                            status: summary.ok ? "done" : "error",
+                            createdAt: now,
+                            startedAt: now,
+                            doneAt: now,
+                            durationMs: 0,
+                            ...(summary.errorMessage
+                                ? { errorMessage: summary.errorMessage }
+                                : {}),
+                            ...(stepResultsForLog ? { stepResults: stepResultsForLog } : {}),
+                        });
+                    }
+                    catch {
+                        // non-fatal
+                    }
+                }
+            },
+            onError: (err) => {
+                process.stderr.write(`  Error: ${err.message}\n`);
+            },
+        });
+        process.on("SIGINT", () => {
+            process.stdout.write("\n  Stopping watch...\n");
+            stop();
+            process.exit(0);
+        });
+    })();
+}
 if (process.argv[2] === "init") {
     const argv = process.argv.slice(3);
     // Handle init --help
@@ -1383,6 +2561,23 @@ Options:
     }
     process.exit(0);
 }
+// Handle launchd subcommand — install/uninstall macOS LaunchAgent for auto-start
+if (process.argv[2] === "launchd") {
+    const sub = process.argv[3];
+    if (sub === "install") {
+        const { runLaunchdInstall } = await import("./commands/launchd.js");
+        await runLaunchdInstall(process.argv.slice(4));
+    }
+    else if (sub === "uninstall") {
+        const { runLaunchdUninstall } = await import("./commands/launchd.js");
+        await runLaunchdUninstall(process.argv.slice(4));
+    }
+    else {
+        process.stderr.write("Usage: patchwork-os launchd install|uninstall\n");
+        process.exit(1);
+    }
+    process.exit(0);
+}
 // F6: "Did you mean?" for unknown CLI subcommands
 // Patchwork: no-args → terminal dashboard (when invoked as patchwork-os or patchwork).
 {
@@ -1390,7 +2585,7 @@ Options:
     const isPatchworkBin = binName === "patchwork-os" ||
         binName === "patchwork" ||
         binName === "patchwork.js";
-    if (isPatchworkBin && !process.argv[2]) {
+    if (isPatchworkBin && (!process.argv[2] || process.argv[2] === "dashboard")) {
         (async () => {
             const { runDashboard } = await import("./commands/dashboard.js");
             await runDashboard();
@@ -1398,26 +2593,12 @@ Options:
     }
 }
 {
-    const KNOWN_COMMANDS = [
-        "init",
-        "patchwork-init",
-        "start-all",
-        "install-extension",
-        "gen-claude-md",
-        "print-token",
-        "gen-plugin-stub",
-        "notify",
-        "install",
-        "marketplace",
-        "status",
-        "shim",
-        "recipe",
-        "dashboard",
-    ];
+    // Reuses the KNOWN_SUBCOMMANDS list from the top of this file as a single
+    // source of truth for "what subcommand argv tokens are recognized".
     const unknownSub = process.argv[2];
     if (unknownSub &&
         !unknownSub.startsWith("-") &&
-        !KNOWN_COMMANDS.includes(unknownSub)) {
+        !KNOWN_SUBCOMMANDS.includes(unknownSub)) {
         const lev = (a, b) => {
             const dp = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0));
             for (let i = 1; i <= a.length; i++)
@@ -1433,127 +2614,146 @@ Options:
             // biome-ignore lint/style/noNonNullAssertion: dp is fully pre-allocated
             return dp[a.length][b.length];
         };
-        const closest = [...KNOWN_COMMANDS].sort((a, b) => lev(unknownSub, a) - lev(unknownSub, b))[0];
+        const closest = [...KNOWN_SUBCOMMANDS].sort((a, b) => lev(unknownSub, a) - lev(unknownSub, b))[0];
         console.error(`Unknown command: '${unknownSub}'. Did you mean: ${closest}?`);
         process.exit(1);
     }
 }
-const config = parseConfig(process.argv);
-// Patchwork: resolve --model flag (optional, non-invasive) — stashes the
-// configured adapter on globalThis for consumers that opt into the adapter
-// layer. Bridge subprocess driver still works when --model is absent.
-try {
-    const { resolveModel } = await import("./patchworkCli.js");
-    const resolved = resolveModel(process.argv);
-    if (resolved) {
-        globalThis.__patchworkAdapter =
-            resolved.adapter;
-        process.stderr.write(`[patchwork] model adapter initialized: ${resolved.adapter.name}\n`);
-    }
-}
-catch (err) {
-    process.stderr.write(`[patchwork] adapter init failed: ${err instanceof Error ? err.message : String(err)}\n`);
+// Skip the bridge-mode tail entirely when a subcommand IIFE will own the
+// process. `parseConfig` validates argv against the bridge's known-flag list
+// and raises "Unknown option" for subcommand-specific flags (e.g. `recipe
+// new --out .`); without this guard that throw kills the process before
+// the IIFE's microtask runs. The subcommand handles its own arg parsing.
+if (__subcommandWillRun) {
+    // Subcommand IIFE is in flight or about to fire; sit tight until it
+    // process.exits. Empty body — control naturally falls past end-of-file
+    // and Node keeps the process alive on the IIFE's pending microtask.
 }
-// If --analytics flag was passed, persist the preference immediately
-if (config.analyticsEnabled !== null) {
-    setAnalyticsPref(config.analyticsEnabled);
-}
-// Auto-tmux: if requested and not already inside tmux or screen, re-exec inside a tmux session
-if (config.autoTmux &&
-    !process.env.TMUX &&
-    !process.env.STY &&
-    !process.env.ZELLIJ &&
-    !process.env.ZELLIJ_SESSION_NAME) {
-    const ws = config.workspace.replace(/[^a-zA-Z0-9]/g, "").slice(-8);
-    const hash = crypto
-        .createHash("sha256")
-        .update(config.workspace)
-        .digest("hex")
-        .slice(0, 6);
-    const sessionName = `claude-bridge-${ws}${hash}`;
-    // Check if tmux is available
-    const tmuxCheck = spawnSync("which", ["tmux"], { stdio: "ignore" });
-    if (tmuxCheck.status !== 0) {
-        process.stderr.write("WARNING: --auto-tmux requested but tmux is not installed. Running without tmux.\n");
-    }
-    else {
-        // Strip --auto-tmux from argv to avoid infinite re-exec loop
-        const newArgv = process.argv.filter((a) => a !== "--auto-tmux");
-        // Pass each argv token as a separate tmux argument so paths with spaces work correctly
-        const result = spawnSync("tmux", ["new-session", "-d", "-s", sessionName, ...newArgv], { stdio: "inherit", timeout: 5000 });
-        if (result.status === 0) {
-            process.stderr.write(`Bridge launched in tmux session '${sessionName}'.\n`);
-            process.stderr.write(`  Attach with: tmux attach -t ${sessionName}\n`);
-            process.exit(0);
-        }
-        else {
-            // tmux session likely already exists — attach to it or fall through
-            process.stderr.write(`WARNING: Could not create tmux session '${sessionName}' (already exists?). Running without auto-tmux.\n`);
+else {
+    const config = parseConfig(process.argv);
+    // Patchwork: resolve --model flag (optional, non-invasive) — stashes the
+    // configured adapter on globalThis for consumers that opt into the adapter
+    // layer. Bridge subprocess driver still works when --model is absent.
+    try {
+        const { resolveModel } = await import("./patchworkCli.js");
+        const resolved = resolveModel(process.argv);
+        if (resolved) {
+            globalThis.__patchworkAdapter =
+                resolved.adapter;
+            process.stderr.write(`[patchwork] model adapter initialized: ${resolved.adapter.name}\n`);
         }
     }
-}
-// --watch: supervisor mode — spawn this binary as a child (without --watch) and restart on crash
-if (config.watch) {
-    const childArgv = process.argv.filter((a) => a !== "--watch");
-    const STABLE_THRESHOLD_MS = 60_000;
-    const BASE_DELAY_MS = 2_000;
-    const MAX_DELAY_MS = 30_000;
-    let delay = BASE_DELAY_MS;
-    let stopping = false;
-    function runChild() {
-        if (stopping)
-            return;
-        const startAt = Date.now();
-        process.stderr.write("[supervisor] starting bridge\n");
-        const [cmd, ...args] = childArgv;
-        if (!cmd)
-            return;
-        const child = spawn(cmd, args, {
-            stdio: "inherit",
-        });
-        for (const sig of ["SIGTERM", "SIGINT"]) {
-            process.once(sig, () => {
-                stopping = true;
-                child.kill(sig);
-            });
+    catch (err) {
+        process.stderr.write(`[patchwork] adapter init failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    // If --analytics flag was passed, persist the preference immediately
+    if (config.analyticsEnabled !== null) {
+        setAnalyticsPref(config.analyticsEnabled);
+    }
+    // Auto-tmux: if requested and not already inside tmux or screen, re-exec inside a tmux session
+    if (config.autoTmux &&
+        !process.env.TMUX &&
+        !process.env.STY &&
+        !process.env.ZELLIJ &&
+        !process.env.ZELLIJ_SESSION_NAME) {
+        const ws = config.workspace.replace(/[^a-zA-Z0-9]/g, "").slice(-8);
+        const hash = crypto
+            .createHash("sha256")
+            .update(config.workspace)
+            .digest("hex")
+            .slice(0, 6);
+        const sessionName = `claude-bridge-${ws}${hash}`;
+        // Check if tmux is available
+        const tmuxCheck = spawnSync("which", ["tmux"], { stdio: "ignore" });
+        if (tmuxCheck.status !== 0) {
+            process.stderr.write("WARNING: --auto-tmux requested but tmux is not installed. Running without tmux.\n");
         }
-        child.on("exit", (code, signal) => {
-            if (stopping) {
-                process.stderr.write("[supervisor] bridge stopped\n");
+        else {
+            // Strip --auto-tmux from argv to avoid infinite re-exec loop
+            const newArgv = process.argv.filter((a) => a !== "--auto-tmux");
+            // Pass each argv token as a separate tmux argument so paths with spaces work correctly
+            const result = spawnSync("tmux", ["new-session", "-d", "-s", sessionName, ...newArgv], { stdio: "inherit", timeout: 5000 });
+            if (result.status === 0) {
+                process.stderr.write(`Bridge launched in tmux session '${sessionName}'.\n`);
+                process.stderr.write(`  Attach with: tmux attach -t ${sessionName}\n`);
                 process.exit(0);
             }
-            const uptime = Date.now() - startAt;
-            if (uptime >= STABLE_THRESHOLD_MS) {
-                delay = BASE_DELAY_MS; // reset backoff after a stable run
+            else {
+                // tmux session likely already exists — attach to it or fall through
+                process.stderr.write(`WARNING: Could not create tmux session '${sessionName}' (already exists?). Running without auto-tmux.\n`);
             }
-            process.stderr.write(`[supervisor] bridge exited (code=${code ?? signal}), restarting in ${delay / 1000}s\n`);
-            setTimeout(() => {
-                delay = Math.min(delay * 2, MAX_DELAY_MS);
-                runChild();
-            }, delay);
-        });
+        }
     }
-    runChild();
-}
-else {
-    const bridge = new Bridge(config);
-    bridge.start().catch((err) => {
-        const message = err instanceof Error ? err.message : String(err);
-        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)
+    // Skip bridge boot when a subcommand IIFE is doing the work — avoids the
+    // race where bridge.start() began initialising in parallel with the
+    // subcommand's async path. See the KNOWN_SUBCOMMANDS / __subcommandWillRun
+    // gate at the top of this file.
+    if (__subcommandWillRun) {
+        // intentionally empty — subcommand IIFE owns the process from here.
+    }
+    // --watch: supervisor mode — spawn this binary as a child (without --watch) and restart on crash
+    else if (config.watch) {
+        const childArgv = process.argv.filter((a) => a !== "--watch");
+        const STABLE_THRESHOLD_MS = 60_000;
+        const BASE_DELAY_MS = 2_000;
+        const MAX_DELAY_MS = 30_000;
+        let delay = BASE_DELAY_MS;
+        let stopping = false;
+        function runChild() {
+            if (stopping)
+                return;
+            const startAt = Date.now();
+            process.stderr.write("[supervisor] starting bridge\n");
+            const [cmd, ...args] = childArgv;
+            if (!cmd)
                 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`);
+            const child = spawn(cmd, args, {
+                stdio: "inherit",
+            });
+            for (const sig of ["SIGTERM", "SIGINT"]) {
+                process.once(sig, () => {
+                    stopping = true;
+                    child.kill(sig);
+                });
             }
+            child.on("exit", (code, signal) => {
+                if (stopping) {
+                    process.stderr.write("[supervisor] bridge stopped\n");
+                    process.exit(0);
+                }
+                const uptime = Date.now() - startAt;
+                if (uptime >= STABLE_THRESHOLD_MS) {
+                    delay = BASE_DELAY_MS; // reset backoff after a stable run
+                }
+                process.stderr.write(`[supervisor] bridge exited (code=${code ?? signal}), restarting in ${delay / 1000}s\n`);
+                setTimeout(() => {
+                    delay = Math.min(delay * 2, MAX_DELAY_MS);
+                    runChild();
+                }, delay);
+            });
+        }
+        runChild();
+    }
+    else {
+        const bridge = new Bridge(config);
+        bridge.start().catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Error: ${message}\n`);
+            process.exit(1);
         });
-    })
-        .catch(() => { });
-}
+        // 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(() => { });
+    }
+} // end of `else` for `if (__subcommandWillRun)` (bridge-mode block)
 //# sourceMappingURL=index.js.map