patchwork-os 0.2.0-alpha.34 → 0.2.0-alpha.36

package/dist/index.js

@@ -92,6 +92,61 @@ 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",
+];
+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])
+        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}`);
@@ -489,14 +544,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";
@@ -530,8 +591,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}".
@@ -539,7 +600,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 });
 
@@ -567,25 +628,216 @@ 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.
@@ -597,6 +849,68 @@ if (process.argv[2] === "recipe" && process.argv[3] === "list") {
         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);
+        }
+        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(`  ✓ 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);
+        }
+    })();
+}
 // 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") {
@@ -794,9 +1108,15 @@ if (process.argv[2] === "recipe" && process.argv[3] === "install") {
                 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` +
-                    `  ℹ permissions snippet written to ${result.installedPath}.permissions.json\n` +
-                    `    Review + merge into ~/.claude/settings.json to pre-approve recipe steps.\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/
@@ -812,7 +1132,264 @@ if (process.argv[2] === "recipe" && process.argv[3] === "install") {
         }
     })();
 }
+// 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 () => {
@@ -836,7 +1413,10 @@ 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>]\n");
+        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");
@@ -855,10 +1435,16 @@ if (process.argv[2] === "recipe" && process.argv[3] === "new") {
                 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);
@@ -1962,27 +2548,12 @@ if (process.argv[2] === "launchd") {
     }
 }
 {
-    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",
-        "launchd",
-    ];
+    // 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++)
@@ -1998,127 +2569,146 @@ if (process.argv[2] === "launchd") {
             // 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 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 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);
+                });
             }
+            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