@mycompbox/compbox-cli 1.18.0 → 1.19.0

package/index.js

@@ -5635,6 +5635,130 @@ function interviewFieldKeysFor(definition) {
   return out;
 }
 
+// ../shared/dist/interview-completion.js
+var TARGET_COMPLIANCE_TIER = "pass";
+function meetsComplianceTarget(compliance) {
+  return !compliance || compliance.tier === TARGET_COMPLIANCE_TIER;
+}
+function buildAuditFeedback(compliance) {
+  const ordered = [
+    ...compliance.issues.filter((i) => i.tier === "critical"),
+    ...compliance.issues.filter((i) => i.tier === "advisory")
+  ].slice(0, 8);
+  const list = ordered.length > 0 ? ordered.map((i) => `- ${i.message}`).join("\n") : "- (no specific issues returned; expand the required fields with more concrete detail)";
+  return `The epic request you just produced scored ${String(compliance.overall)}/100 (tier: ${compliance.tier}). It must reach 90/100 with ZERO critical issues before the interview can finish. Fix these:
+${list}
+
+If you can resolve these by EXPANDING what the employee already told you \u2014 a longer, more complete and concrete problemStatement / proposedSolution / impactAssessment / description that comfortably clear the length minimums \u2014 re-emit the completion JSON now with richer fields. Do NOT re-ask something you already have an answer for. Only if you genuinely need NEW information from the employee, ask ONE focused question to get it.`;
+}
+var OPTIONAL_DRAFT_KEYS = [
+  "successMetrics",
+  "targetAudience",
+  "alternatives",
+  "dependencies",
+  "estimatedEffort"
+];
+function isEpicRequestDraft(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  const nonEmpty = (x) => typeof x === "string" && x.trim().length > 0;
+  const requiredOk = nonEmpty(v.title) && nonEmpty(v.problemStatement) && nonEmpty(v.proposedSolution) && nonEmpty(v.impactAssessment) && nonEmpty(v.description);
+  if (!requiredOk)
+    return false;
+  for (const key of OPTIONAL_DRAFT_KEYS) {
+    if (key in v && v[key] !== void 0 && typeof v[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function stripTrailingCommas(json) {
+  return json.replace(/,(\s*[}\]])/g, "$1");
+}
+function escapeRawControlCharsInStrings(json) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (const ch of json) {
+    if (escaped) {
+      out += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      out += ch;
+      escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      out += ch;
+      continue;
+    }
+    if (inString && (ch === "\n" || ch === "\r" || ch === "	")) {
+      out += ch === "\n" ? "\\n" : ch === "\r" ? "\\r" : "\\t";
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+function completionJsonCandidates(text) {
+  const candidates = [];
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  if (fenced?.[1])
+    candidates.push(fenced[1]);
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{"))
+    candidates.push(trimmed);
+  const first = text.indexOf("{");
+  const last = text.lastIndexOf("}");
+  if (first !== -1 && last > first)
+    candidates.push(text.slice(first, last + 1));
+  return candidates;
+}
+function toDraft(parsed) {
+  const draft = {
+    title: parsed.title,
+    problemStatement: parsed.problemStatement,
+    proposedSolution: parsed.proposedSolution,
+    impactAssessment: parsed.impactAssessment,
+    description: parsed.description
+  };
+  for (const key of OPTIONAL_DRAFT_KEYS) {
+    const raw = parsed[key];
+    if (typeof raw === "string" && raw.trim().length > 0) {
+      draft[key] = raw;
+    }
+  }
+  return draft;
+}
+function extractCompletionJson(text) {
+  for (const candidate of completionJsonCandidates(text)) {
+    for (const variant of [
+      candidate,
+      stripTrailingCommas(candidate),
+      escapeRawControlCharsInStrings(candidate),
+      escapeRawControlCharsInStrings(stripTrailingCommas(candidate))
+    ]) {
+      try {
+        const parsed = JSON.parse(variant);
+        if (isEpicRequestDraft(parsed))
+          return toDraft(parsed);
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function looksLikeCompletionAttempt(text) {
+  const hasObject = /```(?:json)?\s*\{/i.test(text) || text.trim().startsWith("{");
+  if (!hasObject)
+    return false;
+  return /"(?:done|title|problemStatement|proposedSolution|impactAssessment|description)"\s*:/i.test(text);
+}
+var COMPLETION_REPAIR_INSTRUCTION = 'Your last message looked like a completion but I could NOT parse it as a valid JSON object with all required fields. Re-emit ONLY a single valid JSON object inside a ```json code fence \u2014 no other text \u2014 with every string value properly escaped (escape any internal double-quotes as \\" and any line breaks as \\n), and make sure title, problemStatement, proposedSolution, impactAssessment, and description are all present and non-empty:\n```json\n{"done": true, "title": "...", "problemStatement": "...", "proposedSolution": "...", "impactAssessment": "...", "description": "..."}\n```';
+
 // src/utils/config-store.ts
 var CONFIG_DIR_ENV = "COMPBOX_CONFIG_DIR";
 var PROJECT_DIR_ENV = "COMPBOX_PROJECT_DIR";
@@ -5779,8 +5903,8 @@ async function promptText(question, options = {}) {
   const rendered = defaultValue !== void 0 ? `${question} [${defaultValue}]: ` : question;
   const rl = readline.createInterface({ input: stdin, output: stdout });
   try {
-    const answer = await new Promise((resolve2) => {
-      rl.question(rendered, resolve2);
+    const answer = await new Promise((resolve3) => {
+      rl.question(rendered, resolve3);
     });
     const trimmed = answer.trim();
     if (trimmed.length === 0 && defaultValue !== void 0) {
@@ -5792,7 +5916,7 @@ async function promptText(question, options = {}) {
   }
 }
 function promptSecret(question) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const rl = readline.createInterface({
       input: stdin,
       output: stdout,
@@ -5804,7 +5928,7 @@ function promptSecret(question) {
     rl.question("", (answer) => {
       rl.close();
       stdout.write("\n");
-      resolve2(answer.trim());
+      resolve3(answer.trim());
     });
   });
 }
@@ -5842,7 +5966,7 @@ async function promptConfirm(question, defaultYes = true) {
 }
 
 // src/utils/loopback.ts
-var LOOPBACK_IMPACT = "your work will NOT reach the cloud (mycompbox.web.app)";
+var LOOPBACK_IMPACT = "your work will NOT reach the cloud (mycompbox.com)";
 var LOOPBACK_NOTICE = `This is a LOCAL dev endpoint \u2014 ${LOOPBACK_IMPACT}. Use \`compbox login --url <cloud-url>\` for production.`;
 function isLoopbackHostname(hostname3) {
   let host = hostname3.trim().toLowerCase();
@@ -5882,6 +6006,7 @@ function isLoopbackUrl(rawUrl) {
 }
 
 // src/commands/login.ts
+var DEFAULT_BASE_URL = "https://mycompbox.com";
 async function resolveBaseUrl(option) {
   if (option && option.trim().length > 0) {
     return option.trim();
@@ -5890,19 +6015,40 @@ async function resolveBaseUrl(option) {
   if (existing && existing.trim().length > 0) {
     return existing.trim();
   }
-  const entered = await promptText("Central CompBox API URL: ");
-  if (entered.length === 0) {
-    throw new Error("A central API URL is required.");
-  }
-  return entered;
+  const entered = await promptText(`CompBox URL [${DEFAULT_BASE_URL}]: `);
+  return entered.length === 0 ? DEFAULT_BASE_URL : entered;
 }
 var loginCommand = new Command5("login").description("Authenticate to central CompBox and store your pairing config").option("--url <url>", "Central CompBox API base URL").option("--email <email>", "Account email (otherwise prompted)").option(
   "--password <password>",
   "Account password (otherwise prompted; prefer the prompt to keep it out of shell history)"
-).option("--token-name <name>", "Name for the generated API token").action(async (options) => {
+).option("--token-name <name>", "Name for the generated API token").option(
+  "--api-token <token>",
+  "Sign in with an existing CompBox API token (st_...) from web Settings \u2192 API Keys \u2014 use this if you sign in with Google"
+).action(async (options) => {
   try {
     const baseUrl = await resolveBaseUrl(options.url);
     const client = new AuthClient(baseUrl);
+    if (options.apiToken && options.apiToken.trim().length > 0) {
+      const token = options.apiToken.trim();
+      console.log(chalk6.gray(`
+Verifying the API token against ${baseUrl}...`));
+      const me = await client.getMe(token);
+      updateConfig({
+        apiBaseUrl: client.baseUrl,
+        apiToken: token,
+        userId: me.id,
+        email: me.email,
+        userName: me.name
+      });
+      console.log(chalk6.green(`
+\u2714 Paired as ${me.name} <${me.email}> using your API token`));
+      console.log(chalk6.gray(`  Central URL:  ${client.baseUrl}`));
+      console.log("\n" + chalk6.bold("Next step:"));
+      console.log(
+        chalk6.gray("  Run `compbox configure` to select your AI mode, pair this device, and write the MCP config.")
+      );
+      return;
+    }
     const email = options.email && options.email.trim().length > 0 ? options.email.trim() : await promptText("Email: ");
     if (email.length === 0) {
       throw new Error("Email is required.");
@@ -5952,7 +6098,17 @@ Authenticating to ${baseUrl}...`));
       console.error(chalk6.red(`
 Login failed: ${error.message}`));
       if (error.status === 401) {
-        console.error(chalk6.yellow("Tip: double-check your email and password."));
+        console.error(
+          chalk6.yellow(
+            "Tip: double-check your email and password. If you sign in with Google, use `compbox login --api-token <st_...>` with a key from web Settings \u2192 API Keys."
+          )
+        );
+      } else if (error.status === 403) {
+        console.error(
+          chalk6.yellow(
+            "Tip: if you just signed up, open the verification link we emailed you, then run `compbox login` again."
+          )
+        );
       } else if (error.status === 0) {
         console.error(chalk6.yellow("Tip: verify the central API URL and your network connection."));
       }
@@ -5969,7 +6125,7 @@ Login failed: ${error.message}`));
 // src/commands/configure.ts
 import { Command as Command6 } from "commander";
 import chalk7 from "chalk";
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { hostname as hostname2 } from "os";
 
 // src/utils/keychain.ts
@@ -6300,16 +6456,57 @@ var MailboxClient = class {
     const data = res.data;
     return data.data;
   }
+  /**
+   * The person's saved API key for one job sent with "Run with: My API key".
+   * Kept in memory and passed to Claude Code's environment only — never
+   * written to disk or logged.
+   */
+  async getAiKey(machineToken, jobId) {
+    let res;
+    try {
+      res = await this.http.post(
+        `/api/v1/jobs/${jobId}/ai-key`,
+        {},
+        { headers: { Authorization: `Bearer ${machineToken}` } }
+      );
+    } catch (error) {
+      throw toMailboxError(error, "ai-key request failed");
+    }
+    if (res.status < 200 || res.status >= 300) {
+      throw errorFromResponse(res, "ai-key failed");
+    }
+    const data = res.data;
+    return data.data;
+  }
+  /** Reports what a run on the person's API key spent. */
+  async reportAiUsage(machineToken, jobId, usage) {
+    let res;
+    try {
+      res = await this.http.post(`/api/v1/jobs/${jobId}/ai-usage`, usage, {
+        headers: { Authorization: `Bearer ${machineToken}` }
+      });
+    } catch (error) {
+      throw toMailboxError(error, "ai-usage request failed");
+    }
+    if (res.status < 200 || res.status >= 300) {
+      throw errorFromResponse(res, "ai-usage failed");
+    }
+  }
 };
 
 // src/utils/mcp-config-writer.ts
 import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
-import { dirname as dirname2, join as join6 } from "path";
+import { basename, dirname as dirname2, join as join6 } from "path";
 var DEFAULT_MCP_CONFIG_FILENAME = ".mcp.json";
 var DEFAULT_SERVER_KEY = "compbox";
 var MCP_SERVER_PACKAGE = "@mycompbox/compbox-mcp";
 function resolveInstalledMcpBundle(opts) {
   const exists = opts?.exists ?? existsSync6;
+  const self = opts && "self" in opts ? opts.self : process.argv[1];
+  if (self && basename(self) === "compbox.cjs") {
+    const sibling = join6(dirname2(self), "compbox-mcp.cjs");
+    if (exists(sibling)) return sibling;
+  }
   const prefixes = [];
   if (opts?.prefix) prefixes.push(opts.prefix);
   if (process.env.HOMEBREW_PREFIX) prefixes.push(process.env.HOMEBREW_PREFIX);
@@ -6454,6 +6651,100 @@ function findBrew(deps = {}) {
   return pathProbe() ? "brew" : null;
 }
 
+// src/utils/autostart.ts
+import { execFileSync as execFileSync3 } from "node:child_process";
+import { mkdirSync as mkdirSync4, realpathSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join7 } from "node:path";
+var LAUNCHD_LABEL = "com.mycompbox.agent-runner";
+var SYSTEMD_UNIT = "compbox-agent-runner.service";
+function scriptInstallPath(home = homedir3()) {
+  return join7(home, ".compbox", "bin", "compbox.cjs");
+}
+function isScriptInstall(entry = process.argv[1], home = homedir3()) {
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(scriptInstallPath(home));
+  } catch {
+    return false;
+  }
+}
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function launchdPlist(opts) {
+  const args = [opts.node, opts.script, "run"].map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(opts.path)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(opts.logFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(opts.logFile)}</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(opts) {
+  const quote = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  return `[Unit]
+Description=CompBox Agent Runner
+
+[Service]
+ExecStart=${quote(opts.node)} ${quote(opts.script)} run
+Environment=${quote(`PATH=${opts.path}`)}
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+function installAutostart() {
+  const home = homedir3();
+  const script = scriptInstallPath(home);
+  const node = process.execPath;
+  const path3 = process.env.PATH ?? "/usr/bin:/bin";
+  if (process.platform === "darwin") {
+    const plistPath = join7(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+    const logFile = join7(home, ".compbox", "agent-runner.log");
+    mkdirSync4(dirname3(plistPath), { recursive: true });
+    writeFileSync4(plistPath, launchdPlist({ node, script, path: path3, logFile }));
+    const domain = `gui/${String(process.getuid?.() ?? 0)}`;
+    try {
+      execFileSync3("launchctl", ["bootout", domain, plistPath], { stdio: "ignore" });
+    } catch {
+    }
+    execFileSync3("launchctl", ["bootstrap", domain, plistPath], { stdio: "pipe" });
+    return `it starts at every login (stop it with \`launchctl bootout ${domain} ${plistPath}\`; log: ${logFile})`;
+  }
+  if (process.platform === "linux") {
+    const unitPath = join7(home, ".config", "systemd", "user", SYSTEMD_UNIT);
+    mkdirSync4(dirname3(unitPath), { recursive: true });
+    writeFileSync4(unitPath, systemdUnit({ node, script, path: path3 }));
+    execFileSync3("systemctl", ["--user", "daemon-reload"], { stdio: "pipe" });
+    execFileSync3("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT], { stdio: "pipe" });
+    return `it starts at every login (stop it with \`systemctl --user disable --now ${SYSTEMD_UNIT}\`)`;
+  }
+  throw new Error(`Automatic start isn't supported on ${process.platform}.`);
+}
+
 // src/commands/configure.ts
 function parseAiMode(value) {
   if (value === "claude-subscription" || value === "api-key") {
@@ -6550,13 +6841,13 @@ Device pairing failed: ${message}`));
 Device already paired as "${config.machineName ?? config.machineId}".`));
     }
     const defaultDir = isGitRepoDir(process.cwd()) ? process.cwd() : void 0;
-    console.log("\n" + chalk7.bold("Project directory for dispatched runs:"));
+    console.log("\n" + chalk7.bold("Project folder:"));
     console.log(
       chalk7.gray(
-        "  This is where dispatched @planner/@orchestrator runs read, edit, and commit \u2014 leave blank to skip."
+        "  The folder with your code (a git project) where the AI plans, edits and commits.\n  Leave blank to skip; add folders per project later with `compbox machines dirs add`."
       )
     );
-    const projectDirQuestion = "Which local repository should dispatched plan/orchestrate runs use?";
+    const projectDirQuestion = "Which project folder should the AI work in?";
     const MAX_PROJECT_DIR_ATTEMPTS = 5;
     let projectDirPersisted = false;
     let projectDirSkipped = false;
@@ -6673,8 +6964,8 @@ Device already paired as "${config.machineName ?? config.machineId}".`));
         "  Agent traffic would pass through it; if it is not running, calls fall back to a direct connection automatically."
       )
     );
-    updateConfig({ pxpipeEnabled: enablePxpipe === true });
-    if (enablePxpipe === true) {
+    updateConfig({ pxpipeEnabled: enablePxpipe });
+    if (enablePxpipe) {
       console.log(chalk7.green("\u2714 pxpipe routing enabled for this machine."));
       console.log(
         chalk7.yellow("  Note: which models are actually compressed is pxpipe's own setting, not CompBox's.")
@@ -6693,9 +6984,26 @@ Device already paired as "${config.machineName ?? config.machineId}".`));
         chalk7.gray("  Re-run `compbox configure` to change this later.")
       );
     }
-    const startServiceCmd = process.platform === "darwin" ? "brew services start compbox" : process.platform === "win32" ? "compbox service install" : "compbox run";
+    const scriptInstall = process.platform !== "win32" && isScriptInstall();
+    const startServiceCmd = process.platform === "win32" ? "compbox service install" : process.platform === "darwin" && !scriptInstall ? "brew services start compbox" : "compbox run";
     let daemonStarted = false;
-    if (process.platform === "darwin") {
+    if (scriptInstall) {
+      const startNow = await promptConfirm(
+        "Start the Agent Runner now and at every login? (lets CompBox send work to this computer)",
+        true
+      );
+      if (startNow) {
+        try {
+          const how = installAutostart();
+          daemonStarted = true;
+          console.log(chalk7.green(`\u2714 Agent Runner started \u2014 ${how}.`));
+        } catch (error) {
+          const message = (error instanceof Error ? error.message.split("\n")[0] : void 0) ?? "unknown error";
+          console.warn(chalk7.yellow(`\u26A0 Could not start the Agent Runner automatically: ${message}`));
+          console.warn(chalk7.gray("  Run `compbox run` in a terminal and keep it open instead."));
+        }
+      }
+    } else if (process.platform === "darwin") {
       const brew = findBrew();
       if (brew !== null) {
         const startNow = await promptConfirm(
@@ -6704,7 +7012,7 @@ Device already paired as "${config.machineName ?? config.machineId}".`));
         );
         if (startNow) {
           try {
-            execFileSync3(brew, ["services", "start", "compbox"], {
+            execFileSync4(brew, ["services", "start", "compbox"], {
               encoding: "utf-8",
               timeout: 3e4,
               stdio: ["ignore", "pipe", "pipe"]
@@ -6716,7 +7024,7 @@ Device already paired as "${config.machineName ?? config.machineId}".`));
               )
             );
           } catch (error) {
-            const message = error instanceof Error ? error.message.split("\n")[0] : "unknown error";
+            const message = (error instanceof Error ? error.message.split("\n")[0] : void 0) ?? "unknown error";
             console.warn(chalk7.yellow(`\u26A0 Could not start the service: ${message}`));
             console.warn(chalk7.gray(`  Start it manually with \`${startServiceCmd}\`.`));
           }
@@ -6743,22 +7051,22 @@ Configuration failed: ${error.message}`));
 });
 
 // src/commands/doctor.ts
-import { execFileSync as execFileSync5, spawn as spawn2 } from "child_process";
+import { execFileSync as execFileSync6, spawn as spawn2 } from "child_process";
 import { existsSync as existsSync8 } from "fs";
 import { Command as Command7 } from "commander";
 import chalk8 from "chalk";
 
 // src/utils/claude-runtime.ts
 import { spawn } from "node:child_process";
-import { execFileSync as execFileSync4 } from "node:child_process";
+import { execFileSync as execFileSync5 } from "node:child_process";
 import { accessSync, constants as fsConstants, statSync as statSync2 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { delimiter, join as join7 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { delimiter, join as join8 } from "node:path";
 var WELL_KNOWN_DIRS = buildWellKnownDirs();
 function buildWellKnownDirs() {
-  const home = homedir3();
+  const home = homedir4();
   const dirs = [
-    join7(home, ".local", "bin"),
+    join8(home, ".local", "bin"),
     // default Claude Code install location
     "/opt/homebrew/bin",
     // Homebrew on Apple Silicon
@@ -6766,14 +7074,14 @@ function buildWellKnownDirs() {
     // Homebrew on Intel / common Unix prefix
   ];
   if (process.env.npm_config_prefix) {
-    dirs.push(join7(process.env.npm_config_prefix, "bin"));
+    dirs.push(join8(process.env.npm_config_prefix, "bin"));
   }
-  dirs.push(join7(home, ".npm-global", "bin"));
+  dirs.push(join8(home, ".npm-global", "bin"));
   if (process.env.PNPM_HOME) {
     dirs.push(process.env.PNPM_HOME);
   }
-  dirs.push(join7(home, "Library", "pnpm"));
-  dirs.push(join7(home, ".local", "share", "pnpm"));
+  dirs.push(join8(home, "Library", "pnpm"));
+  dirs.push(join8(home, ".local", "share", "pnpm"));
   return dirs;
 }
 var LOGIN_SHELL_PATH_TIMEOUT_MS = 2e3;
@@ -6801,7 +7109,7 @@ function getLoginShellPath(exec = defaultExecFileSync) {
   return cachedLoginShellPath;
 }
 function defaultExecFileSync(file, args, options) {
-  return execFileSync4(file, args, {
+  return execFileSync5(file, args, {
     timeout: options.timeout,
     encoding: options.encoding,
     stdio: ["ignore", "pipe", "ignore"]
@@ -6839,7 +7147,7 @@ function resolveClaudeBinary(deps = {}) {
       continue;
     }
     seen.add(dir);
-    const candidate = join7(dir, "claude");
+    const candidate = join8(dir, "claude");
     if (isExec(candidate)) {
       return candidate;
     }
@@ -6878,7 +7186,7 @@ function probeAgentRuntime(deps = {}) {
       checkedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let settled = false;
     let child;
     let stdout2 = "";
@@ -6893,7 +7201,7 @@ function probeAgentRuntime(deps = {}) {
         child.kill("SIGKILL");
       } catch {
       }
-      resolve2({ ...result, checkedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      resolve3({ ...result, checkedAt: (/* @__PURE__ */ new Date()).toISOString() });
     };
     const timer = setTimeout(() => {
       settle({
@@ -6905,7 +7213,7 @@ function probeAgentRuntime(deps = {}) {
       child = spawnFn(abs, ["--version"], { stdio: ["ignore", "pipe", "pipe"] });
     } catch (error) {
       clearTimeout(timer);
-      resolve2({
+      resolve3({
         status: "error",
         detail: error instanceof Error ? error.message : "failed to spawn claude",
         checkedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -6997,7 +7305,7 @@ function countFailures(results) {
 }
 var LAUNCH_PROBE_TIMEOUT_MS = 5e3;
 function probeLaunchTarget(command, args, timeoutMs = LAUNCH_PROBE_TIMEOUT_MS) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let settled = false;
     const child = spawn2(command, args, {
       stdio: ["ignore", "pipe", "pipe"],
@@ -7019,7 +7327,7 @@ function probeLaunchTarget(command, args, timeoutMs = LAUNCH_PROBE_TIMEOUT_MS) {
         child.kill("SIGKILL");
       } catch {
       }
-      resolve2(result);
+      resolve3(result);
     };
     const timer = setTimeout(() => {
       settle({ status: "timeout" });
@@ -7108,7 +7416,7 @@ var BREW_SERVICE_LABEL = "homebrew.mxcl.compbox";
 function checkBrewService(deps = {}) {
   const name = "Homebrew service running (macOS)";
   const locateBrew = deps.findBrewFn ?? findBrew;
-  const exec = deps.execFn ?? ((file, args) => execFileSync5(file, args, {
+  const exec = deps.execFn ?? ((file, args) => execFileSync6(file, args, {
     encoding: "utf-8",
     timeout: 1e4,
     stdio: ["ignore", "pipe", "ignore"]
@@ -7126,7 +7434,7 @@ function checkBrewService(deps = {}) {
   try {
     output = exec(brew, ["services", "list"]);
   } catch (error) {
-    const cause = error instanceof Error ? error.message.split("\n")[0] : "unknown error";
+    const cause = (error instanceof Error ? error.message.split("\n")[0] : void 0) ?? "unknown error";
     try {
       exec("launchctl", ["list", BREW_SERVICE_LABEL]);
       return {
@@ -7416,13 +7724,68 @@ import chalk9 from "chalk";
 // src/utils/agent-invoker.ts
 import Anthropic from "@anthropic-ai/sdk";
 import { spawn as spawn3, spawnSync } from "node:child_process";
-import { mkdirSync as mkdirSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join8 } from "node:path";
+import { mkdirSync as mkdirSync5 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join9 } from "node:path";
+
+// src/utils/key-run.ts
+function keyRunEnv(env, keyRun) {
+  const next = { ...env, ANTHROPIC_API_KEY: keyRun.apiKey, ANTHROPIC_MODEL: keyRun.model };
+  delete next.ANTHROPIC_AUTH_TOKEN;
+  delete next.CLAUDE_CODE_OAUTH_TOKEN;
+  return next;
+}
+function keyRunArgs(args) {
+  return [...args, "--output-format", "json"];
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function parseClaudeJsonResult(stdout2, fallbackModel) {
+  let data;
+  try {
+    const start = stdout2.indexOf("{");
+    if (start === -1) return null;
+    data = JSON.parse(stdout2.slice(start));
+  } catch {
+    return null;
+  }
+  if (typeof data.result !== "string" && data.type !== "result") return null;
+  const usage = {
+    model: fallbackModel,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: typeof data.total_cost_usd === "number" ? data.total_cost_usd : null
+  };
+  const byModel = data.modelUsage;
+  if (typeof byModel === "object" && byModel !== null && Object.keys(byModel).length > 0) {
+    let topCost = -1;
+    for (const [model, raw] of Object.entries(byModel)) {
+      usage.inputTokens += num(raw.inputTokens);
+      usage.outputTokens += num(raw.outputTokens);
+      usage.cacheReadTokens += num(raw.cacheReadInputTokens);
+      usage.cacheWriteTokens += num(raw.cacheCreationInputTokens);
+      if (num(raw.costUSD) > topCost) {
+        topCost = num(raw.costUSD);
+        usage.model = model;
+      }
+    }
+  } else if (typeof data.usage === "object" && data.usage !== null) {
+    const u = data.usage;
+    usage.inputTokens = num(u.input_tokens);
+    usage.outputTokens = num(u.output_tokens);
+    usage.cacheReadTokens = num(u.cache_read_input_tokens);
+    usage.cacheWriteTokens = num(u.cache_creation_input_tokens);
+  }
+  return { text: typeof data.result === "string" ? data.result : "", usage };
+}
+
+// src/utils/agent-invoker.ts
 var ANTHROPIC_MODEL = "claude-fable-5";
 var MAX_INTERVIEW_TURNS = 18;
 var MAX_QUALITY_ROUNDS = 4;
-var TARGET_COMPLIANCE_TIER = "pass";
 var REPLY_POLL_INTERVAL_MS = 3e3;
 var REPLY_TIMEOUT_MS = 10 * 60 * 1e3;
 var CLAUDE_CLI_TURN_TIMEOUT_MS = 2 * 60 * 1e3;
@@ -7553,124 +7916,9 @@ async function submitAndScore(ctx, currentErId, draft) {
   const created = await createPersonalEpicRequest(ctx.apiBaseUrl, ctx.userApiToken, draft);
   return { erId: created.id, compliance: created.compliance };
 }
-function meetsComplianceTarget(compliance) {
-  return !compliance || compliance.tier === TARGET_COMPLIANCE_TIER;
-}
-function buildAuditFeedback(compliance) {
-  const ordered = [
-    ...compliance.issues.filter((i) => i.tier === "critical"),
-    ...compliance.issues.filter((i) => i.tier === "advisory")
-  ].slice(0, 8);
-  const list = ordered.length > 0 ? ordered.map((i) => `- ${i.message}`).join("\n") : "- (no specific issues returned; expand the required fields with more concrete detail)";
-  return `The epic request you just produced scored ${String(compliance.overall)}/100 (tier: ${compliance.tier}). It must reach 90/100 with ZERO critical issues before the interview can finish. Fix these:
-${list}
-
-If you can resolve these by EXPANDING what the employee already told you \u2014 a longer, more complete and concrete problemStatement / proposedSolution / impactAssessment / description that comfortably clear the length minimums \u2014 re-emit the completion JSON now with richer fields. Do NOT re-ask something you already have an answer for. Only if you genuinely need NEW information from the employee, ask ONE focused question to get it.`;
-}
-var OPTIONAL_DRAFT_KEYS = [
-  "successMetrics",
-  "targetAudience",
-  "alternatives",
-  "dependencies",
-  "estimatedEffort"
-];
-function isEpicRequestDraft(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  const nonEmpty = (x) => typeof x === "string" && x.trim().length > 0;
-  const requiredOk = nonEmpty(v.title) && nonEmpty(v.problemStatement) && nonEmpty(v.proposedSolution) && nonEmpty(v.impactAssessment) && nonEmpty(v.description);
-  if (!requiredOk) return false;
-  for (const key of OPTIONAL_DRAFT_KEYS) {
-    if (key in v && v[key] !== void 0 && typeof v[key] !== "string") return false;
-  }
-  return true;
-}
-function stripTrailingCommas(json) {
-  return json.replace(/,(\s*[}\]])/g, "$1");
-}
-function escapeRawControlCharsInStrings(json) {
-  let out = "";
-  let inString = false;
-  let escaped = false;
-  for (const ch of json) {
-    if (escaped) {
-      out += ch;
-      escaped = false;
-      continue;
-    }
-    if (ch === "\\") {
-      out += ch;
-      escaped = true;
-      continue;
-    }
-    if (ch === '"') {
-      inString = !inString;
-      out += ch;
-      continue;
-    }
-    if (inString && (ch === "\n" || ch === "\r" || ch === "	")) {
-      out += ch === "\n" ? "\\n" : ch === "\r" ? "\\r" : "\\t";
-      continue;
-    }
-    out += ch;
-  }
-  return out;
-}
-function completionJsonCandidates(text) {
-  const candidates = [];
-  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
-  if (fenced?.[1]) candidates.push(fenced[1]);
-  const trimmed = text.trim();
-  if (trimmed.startsWith("{")) candidates.push(trimmed);
-  const first = text.indexOf("{");
-  const last = text.lastIndexOf("}");
-  if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
-  return candidates;
-}
-function toDraft(parsed) {
-  const draft = {
-    title: parsed.title,
-    problemStatement: parsed.problemStatement,
-    proposedSolution: parsed.proposedSolution,
-    impactAssessment: parsed.impactAssessment,
-    description: parsed.description
-  };
-  for (const key of OPTIONAL_DRAFT_KEYS) {
-    const raw = parsed[key];
-    if (typeof raw === "string" && raw.trim().length > 0) {
-      draft[key] = raw;
-    }
-  }
-  return draft;
-}
-function extractCompletionJson(text) {
-  for (const candidate of completionJsonCandidates(text)) {
-    for (const variant of [
-      candidate,
-      stripTrailingCommas(candidate),
-      escapeRawControlCharsInStrings(candidate),
-      escapeRawControlCharsInStrings(stripTrailingCommas(candidate))
-    ]) {
-      try {
-        const parsed = JSON.parse(variant);
-        if (isEpicRequestDraft(parsed)) return toDraft(parsed);
-      } catch {
-      }
-    }
-  }
-  return null;
-}
-function looksLikeCompletionAttempt(text) {
-  const hasObject = /```(?:json)?\s*\{/i.test(text) || text.trim().startsWith("{");
-  if (!hasObject) return false;
-  return /"(?:done|title|problemStatement|proposedSolution|impactAssessment|description)"\s*:/i.test(
-    text
-  );
-}
-var COMPLETION_REPAIR_INSTRUCTION = 'Your last message looked like a completion but I could NOT parse it as a valid JSON object with all required fields. Re-emit ONLY a single valid JSON object inside a ```json code fence \u2014 no other text \u2014 with every string value properly escaped (escape any internal double-quotes as \\" and any line breaks as \\n), and make sure title, problemStatement, proposedSolution, impactAssessment, and description are all present and non-empty:\n```json\n{"done": true, "title": "...", "problemStatement": "...", "proposedSolution": "...", "impactAssessment": "...", "description": "..."}\n```';
 var MAX_JSON_REPAIRS = 3;
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function waitForUserReply(client, machineToken, jobId, turnsSoFar) {
   const deadline = Date.now() + REPLY_TIMEOUT_MS;
@@ -7781,15 +8029,15 @@ async function invokeEpicRequestViaApi(job, ctx) {
   };
 }
 function claudeCliSessionCwd() {
-  const dir = join8(homedir4(), ".compbox", "claude-sessions");
+  const dir = join9(homedir5(), ".compbox", "claude-sessions");
   try {
-    mkdirSync4(dir, { recursive: true });
+    mkdirSync5(dir, { recursive: true });
   } catch {
   }
   return dir;
 }
 function runClaudeCliTurn(prompt, opts) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const args = [
       "-p",
       prompt,
@@ -7864,7 +8112,7 @@ function runClaudeCliTurn(prompt, opts) {
         reject(new Error("claude CLI returned an unexpected JSON shape (missing result/session_id)."));
         return;
       }
-      resolve2({ text: shaped.result, sessionId: shaped.session_id });
+      resolve3({ text: shaped.result, sessionId: shaped.session_id });
     });
   });
 }
@@ -7958,6 +8206,17 @@ var PLANNER_RUN_TIMEOUT_MS = 30 * 60 * 1e3;
 var PLANNER_HEARTBEAT_INTERVAL_MS = 20 * 1e3;
 var PLANNER_FINAL_TURN_MAX_CHARS = 4e3;
 var ORCHESTRATOR_REVIEW_MARKER = "COMPBOX_NEEDS_HUMAN_REVIEW";
+function takeKeyRunResult(ctx, keyRun, stdout2) {
+  const parsed = parseClaudeJsonResult(stdout2, keyRun.model);
+  if (!parsed) return { text: stdout2, reported: Promise.resolve() };
+  const reported = ctx.mailboxClient.reportAiUsage(ctx.machineToken, ctx.jobId, parsed.usage).catch(() => void 0);
+  return { text: parsed.text, reported };
+}
+async function settleKeyRun(ctx, keyRun, stdout2) {
+  const { text, reported } = takeKeyRunResult(ctx, keyRun, stdout2);
+  await reported;
+  return text;
+}
 function buildPlannerArgs(epicRequestId) {
   return [
     "-p",
@@ -8078,13 +8337,14 @@ async function invokeStartExecutionPlan(ctx, deps = {}) {
   }
   const routing = await resolveRoutingImpl();
   const command = resolveClaudeBinary() ?? "claude";
-  const args = buildPlannerArgs(ctx.epicRequestId);
+  const args = ctx.keyRun ? keyRunArgs(buildPlannerArgs(ctx.epicRequestId)) : buildPlannerArgs(ctx.epicRequestId);
   const routedEnv = claudeSpawnEnv(process.env, routing);
-  const childEnv = {
+  const baseEnv = {
     ...routedEnv,
     COMPBOX_NONINTERACTIVE: "1",
     PATH: claudeChildEnvPath(routedEnv.PATH)
   };
+  const childEnv = ctx.keyRun ? keyRunEnv(baseEnv, ctx.keyRun) : baseEnv;
   try {
     await ctx.mailboxClient.postTurn(
       ctx.machineToken,
@@ -8093,7 +8353,7 @@ async function invokeStartExecutionPlan(ctx, deps = {}) {
     );
   } catch {
   }
-  const outcome = await new Promise((resolve2) => {
+  const outcome = await new Promise((resolve3) => {
     let stdout2 = "";
     let stderr = "";
     let settled = false;
@@ -8111,7 +8371,7 @@ async function invokeStartExecutionPlan(ctx, deps = {}) {
       settled = true;
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       clearTimeout(timer);
-      resolve2(result);
+      resolve3(result);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -8138,6 +8398,7 @@ async function invokeStartExecutionPlan(ctx, deps = {}) {
     });
     child.on("close", (code) => {
       void (async () => {
+        if (ctx.keyRun) stdout2 = await settleKeyRun(ctx, ctx.keyRun, stdout2);
         const combined = `${stdout2}
 ${stderr}`;
         const review = detectNeedsHumanReview(combined);
@@ -8248,6 +8509,13 @@ function defaultToolchainPresent(_dir) {
   }
   return false;
 }
+function describeRunBranch(finish) {
+  if (finish.prUrl) return `Pull request: ${finish.prUrl}`;
+  if (finish.compareUrl) return `Branch ${finish.branch} was pushed. Open the pull request here: ${finish.compareUrl}`;
+  if (finish.commits === 0) return "No code changes were made.";
+  if (finish.pushed) return `Branch ${finish.branch} was pushed.`;
+  return `The work is on branch ${finish.branch}${finish.keptWorktree ? ` (in ${finish.keptWorktree})` : ""}.`;
+}
 function markerString(marker, key) {
   const v = marker?.[key];
   return typeof v === "string" && v.length > 0 ? v : void 0;
@@ -8289,29 +8557,41 @@ async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
   if (!toolchainPresent(projectDir)) {
     return { status: "failed", result: { error: toolchainMissingMessage(projectDir) } };
   }
+  let workspace = null;
+  let workspaceNotes = [];
+  if (deps.workspace) {
+    const prepared = await deps.workspace.prepare(projectDir, ctx.epicId);
+    if (!prepared.ok) {
+      return { status: "failed", result: { error: prepared.error } };
+    }
+    workspace = prepared.workspace;
+    workspaceNotes = prepared.notes;
+  }
+  const runDir = workspace?.dir ?? projectDir;
   const routing = await resolveRoutingImpl();
   const command = resolveClaudeBinary() ?? "claude";
-  const args = buildOrchestratorArgs(ctx.epicId);
+  const args = ctx.keyRun ? keyRunArgs(buildOrchestratorArgs(ctx.epicId)) : buildOrchestratorArgs(ctx.epicId);
   const routedEnv = claudeSpawnEnv(process.env, routing);
-  const childEnv = {
+  const baseEnv = {
     ...routedEnv,
     COMPBOX_NONINTERACTIVE: "1",
     PATH: claudeChildEnvPath(routedEnv.PATH)
   };
+  const childEnv = ctx.keyRun ? keyRunEnv(baseEnv, ctx.keyRun) : baseEnv;
   try {
     await ctx.mailboxClient.postTurn(
       ctx.machineToken,
       ctx.jobId,
-      `Started the orchestrator for epic ${ctx.epicId} (headless, non-interactive). This executes the full epic \u2014 every phase and feature \u2014 and may take a long time.`
+      `Started the orchestrator for epic ${ctx.epicId} (headless, non-interactive). This executes the full epic \u2014 every phase and feature \u2014 and may take a long time.` + (workspace ? ` Working on a new branch, ${workspace.branch}, which will end as a pull request into ${workspace.baseBranch}.` : "") + (workspaceNotes.length > 0 ? ` Note: ${workspaceNotes.join(" ")}` : "")
     );
   } catch {
   }
-  const outcome = await new Promise((resolve2) => {
+  const outcome = await new Promise((resolve3) => {
     let stdout2 = "";
     let stderr = "";
     let settled = false;
     const child = spawnImpl(command, args, {
-      cwd: projectDir,
+      cwd: runDir,
       stdio: ["ignore", "pipe", "pipe"],
       env: childEnv
     });
@@ -8324,7 +8604,7 @@ async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
       settled = true;
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       clearTimeout(timer);
-      resolve2(result);
+      resolve3(result);
     };
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
@@ -8350,6 +8630,7 @@ async function invokeStartExecutionOrchestrate(ctx, deps = {}) {
       });
     });
     child.on("close", (code) => {
+      if (ctx.keyRun) stdout2 = takeKeyRunResult(ctx, ctx.keyRun, stdout2).text;
       const combined = `${stdout2}
 ${stderr}`;
       const review = detectNeedsHumanReview(combined);
@@ -8372,8 +8653,31 @@ ${stderr}`;
       finish({ status: "done", result: { epicId: ctx.epicId } });
     });
   });
+  let branchLine = "";
+  if (deps.workspace && workspace) {
+    const resultError = outcome.result;
+    const stopReason = typeof resultError.message === "string" ? resultError.message : typeof resultError.error === "string" ? resultError.error.split("\n")[0] : void 0;
+    const finished = await deps.workspace.finish({
+      workspace,
+      epicId: ctx.epicId,
+      jobId: ctx.jobId,
+      completed: outcome.status === "done",
+      ...stopReason ? { stopReason } : {}
+    });
+    branchLine = describeRunBranch(finished);
+    outcome.result = {
+      ...outcome.result,
+      branch: finished.branch,
+      commits: finished.commits,
+      pushed: finished.pushed,
+      ...finished.prUrl ? { prUrl: finished.prUrl } : {},
+      ...finished.compareUrl ? { compareUrl: finished.compareUrl } : {},
+      ...finished.notes.length > 0 ? { branchNotes: finished.notes } : {}
+    };
+  }
   try {
-    const summary = outcome.status === "done" ? `Execution complete \u2014 epic ${ctx.epicId} finished all phases.` : `Orchestrator run ended: ${JSON.stringify(outcome.result).slice(0, ORCHESTRATOR_FINAL_TURN_MAX_CHARS)}`;
+    const summary = (outcome.status === "done" ? `Execution complete \u2014 epic ${ctx.epicId} finished all phases.` : `Orchestrator run ended: ${JSON.stringify(outcome.result).slice(0, ORCHESTRATOR_FINAL_TURN_MAX_CHARS)}`) + (branchLine ? `
+${branchLine}` : "");
     await ctx.mailboxClient.postTurn(ctx.machineToken, ctx.jobId, summary);
   } catch {
   }
@@ -8462,6 +8766,377 @@ async function updatePersonalEpicRequest(apiBaseUrl, userApiToken, epicRequestId
   return parseComplianceFromData(data?.data);
 }
 
+// src/utils/run-workspace.ts
+import { spawn as spawn4 } from "node:child_process";
+import { copyFileSync, existsSync as existsSync9, mkdirSync as mkdirSync6 } from "node:fs";
+import { basename as basename2, dirname as dirname4, join as join10 } from "node:path";
+var RUN_PUSH_ENV = "COMPBOX_RUN_PUSH";
+var INSTALL_TIMEOUT_MS = 20 * 60 * 1e3;
+var GIT_TIMEOUT_MS = 5 * 60 * 1e3;
+var defaultCommandRunner = (command, args, cwd) => new Promise((resolve3) => {
+  let stdout2 = "";
+  let stderr = "";
+  let settled = false;
+  const done = (result) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    resolve3(result);
+  };
+  const child = spawn4(command, args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, PATH: claudeChildEnvPath(process.env.PATH), GIT_TERMINAL_PROMPT: "0" }
+  });
+  const timer = setTimeout(
+    () => {
+      child.kill("SIGKILL");
+      done({ status: 1, stdout: stdout2, stderr: `${command} timed out` });
+    },
+    command === "git" || command === "gh" ? GIT_TIMEOUT_MS : INSTALL_TIMEOUT_MS
+  );
+  child.stdout.on("data", (chunk) => {
+    stdout2 += chunk.toString("utf-8");
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf-8");
+  });
+  child.on("error", (error) => {
+    done({ status: 1, stdout: stdout2, stderr: error.message });
+  });
+  child.on("close", (code) => {
+    done({ status: code ?? 1, stdout: stdout2, stderr });
+  });
+});
+function isLocalConfigFile(path3) {
+  if (path3.split("/").includes("node_modules")) return false;
+  const name = basename2(path3);
+  return name === ".mcp.json" || name === "CLAUDE.local.md" || path3 === ".claude/settings.local.json" || name === ".env" || name.startsWith(".env.") && !name.endsWith(".example") && !name.endsWith(".sample");
+}
+function slugForBranch(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "run";
+}
+function stamp(now) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${String(now.getFullYear())}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+function firstLine(text) {
+  return text.trim().split("\n")[0] ?? "";
+}
+function installCommand2(dir, exists = existsSync9) {
+  if (exists(join10(dir, "pnpm-lock.yaml"))) return ["pnpm", ["install", "--frozen-lockfile", "--prefer-offline"]];
+  if (exists(join10(dir, "package-lock.json"))) return ["npm", ["ci", "--prefer-offline"]];
+  if (exists(join10(dir, "yarn.lock"))) return ["yarn", ["install", "--frozen-lockfile"]];
+  return null;
+}
+function githubCompareUrl(remoteUrl, baseBranch, branch) {
+  const m = /^https?:\/\/(?:[^@/]+@)?github\.com\/([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl.trim()) ?? /^(?:ssh:\/\/)?git@github\.com[:/]([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remoteUrl.trim());
+  if (!m) return null;
+  return `https://github.com/${m[1] ?? ""}/${m[2] ?? ""}/compare/${encodeURIComponent(baseBranch)}...${encodeURIComponent(branch)}?expand=1`;
+}
+var RunWorkspaceManager = class {
+  run;
+  now;
+  runsRoot;
+  exists;
+  copyFile;
+  env;
+  constructor(deps = {}) {
+    this.run = deps.run ?? defaultCommandRunner;
+    this.now = deps.now ?? (() => /* @__PURE__ */ new Date());
+    this.runsRoot = deps.runsRoot ?? join10(getConfigDir(), "runs");
+    this.exists = deps.exists ?? existsSync9;
+    this.copyFile = deps.copyFile ?? ((from, to) => {
+      mkdirSync6(dirname4(to), { recursive: true });
+      copyFileSync(from, to);
+    });
+    this.env = deps.env ?? process.env;
+  }
+  git(args, cwd) {
+    return this.run("git", args, cwd);
+  }
+  /** Creates the branch + worktree for a run. Never touches the person's checkout. */
+  async prepare(projectDir, epicId) {
+    const notes = [];
+    const remotes = (await this.git(["remote"], projectDir)).stdout.split("\n").map((r) => r.trim()).filter(Boolean);
+    const remote = remotes.includes("origin") ? "origin" : remotes[0] ?? null;
+    let baseBranch = "";
+    let baseRef = "HEAD";
+    if (remote) {
+      if ((await this.git(["fetch", remote, "--quiet"], projectDir)).status !== 0) {
+        notes.push(`Couldn't fetch from ${remote}, so the run starts from the last fetched copy.`);
+      }
+      const head = await this.git(["symbolic-ref", "--quiet", "--short", `refs/remotes/${remote}/HEAD`], projectDir);
+      if (head.status === 0 && head.stdout.trim().startsWith(`${remote}/`)) {
+        baseBranch = head.stdout.trim().slice(remote.length + 1);
+      } else {
+        for (const candidate of ["main", "master"]) {
+          if ((await this.git(["rev-parse", "--verify", "--quiet", `${remote}/${candidate}`], projectDir)).status === 0) {
+            baseBranch = candidate;
+            break;
+          }
+        }
+      }
+      if (baseBranch) baseRef = `${remote}/${baseBranch}`;
+    }
+    if (!baseBranch) {
+      baseBranch = (await this.git(["rev-parse", "--abbrev-ref", "HEAD"], projectDir)).stdout.trim() || "main";
+      baseRef = "HEAD";
+    }
+    const when = stamp(this.now());
+    const branch = `compbox/epic-${slugForBranch(epicId)}-${when}`;
+    const dir = join10(this.runsRoot, `${slugForBranch(basename2(projectDir))}-${slugForBranch(epicId)}-${when}`);
+    mkdirSync6(this.runsRoot, { recursive: true });
+    const add = await this.git(["worktree", "add", "-b", branch, dir, baseRef], projectDir);
+    if (add.status !== 0) {
+      return {
+        ok: false,
+        error: [
+          `Couldn't create a separate workspace for this run (git worktree add failed): ${firstLine(add.stderr) || "unknown error"}`,
+          "The run was not started, and your project folder was not changed."
+        ].join("\n")
+      };
+    }
+    const ignored = await this.git(["ls-files", "--others", "--ignored", "--exclude-standard", "--directory"], projectDir);
+    const untracked = await this.git(["ls-files", "--others", "--exclude-standard"], projectDir);
+    const candidates = new Set(
+      `${ignored.stdout}
+${untracked.stdout}`.split("\n").map((p) => p.trim()).filter((p) => p && !p.endsWith("/"))
+    );
+    for (const path3 of candidates) {
+      if (!isLocalConfigFile(path3)) continue;
+      try {
+        this.copyFile(join10(projectDir, path3), join10(dir, path3));
+      } catch {
+        notes.push(`Couldn't copy ${path3} into the run workspace.`);
+      }
+    }
+    const install = installCommand2(dir, this.exists);
+    if (install) {
+      const [command, args] = install;
+      const res = await this.run(command, args, dir);
+      if (res.status !== 0) {
+        await this.git(["worktree", "remove", "--force", dir], projectDir);
+        await this.git(["branch", "-D", branch], projectDir);
+        return {
+          ok: false,
+          error: [
+            `Installing the project's dependencies failed (${command} ${args.join(" ")}): ${firstLine(res.stderr) || firstLine(res.stdout) || "unknown error"}`,
+            "The run was not started. Check that the same command works in your project folder."
+          ].join("\n")
+        };
+      }
+    }
+    return { ok: true, workspace: { dir, projectDir, branch, baseRef, baseBranch, remote }, notes };
+  }
+  /** Commits, pushes and opens the pull request; then cleans up the worktree. */
+  async finish(input) {
+    const { workspace: ws } = input;
+    const notes = [];
+    if ((await this.git(["status", "--porcelain"], ws.dir)).stdout.trim()) {
+      await this.git(["add", "-A"], ws.dir);
+      const commit = await this.git(
+        ["commit", "-m", `chore(compbox): save work left uncommitted by the orchestrator (epic ${input.epicId})`],
+        ws.dir
+      );
+      if (commit.status !== 0) {
+        notes.push(`Couldn't commit the remaining changes: ${firstLine(commit.stderr) || firstLine(commit.stdout)}`);
+      }
+    }
+    const commits = Number.parseInt((await this.git(["rev-list", "--count", `${ws.baseRef}..HEAD`], ws.dir)).stdout.trim(), 10) || 0;
+    const base = { branch: ws.branch, commits, pushed: false, notes };
+    if (commits === 0) {
+      await this.git(["worktree", "remove", "--force", ws.dir], ws.projectDir);
+      await this.git(["branch", "-D", ws.branch], ws.projectDir);
+      notes.push("The run made no code changes, so there is nothing to review.");
+      return base;
+    }
+    if (!ws.remote || this.env[RUN_PUSH_ENV] === "0") {
+      await this.git(["worktree", "remove", "--force", ws.dir], ws.projectDir);
+      notes.push(
+        ws.remote ? `Pushing is turned off (${RUN_PUSH_ENV}=0). The work is on the local branch ${ws.branch}.` : `The repository has no remote, so the work is on the local branch ${ws.branch}.`
+      );
+      return base;
+    }
+    const push = await this.git(["push", "--set-upstream", ws.remote, ws.branch], ws.dir);
+    if (push.status !== 0) {
+      notes.push(
+        `Couldn't push the branch to ${ws.remote}: ${firstLine(push.stderr) || "unknown error"}. The work is safe in ${ws.dir} on branch ${ws.branch}.`
+      );
+      return { ...base, keptWorktree: ws.dir };
+    }
+    const title = `CompBox: epic ${input.epicId}${input.completed ? "" : " (stopped early, needs review)"}`;
+    const body = [
+      `Code written by the CompBox orchestrator for epic **${input.epicId}** (job \`${input.jobId}\`).`,
+      "",
+      input.completed ? "The orchestrator finished every phase. Review the changes, check that CI passes, then merge." : `The orchestrator stopped before finishing${input.stopReason ? `: ${input.stopReason}` : "."} This is a draft so the partial work can be reviewed.`,
+      "",
+      `${String(commits)} commit${commits === 1 ? "" : "s"} on \`${ws.branch}\`, based on \`${ws.baseBranch}\`.`
+    ].join("\n");
+    const prArgs = ["pr", "create", "--base", ws.baseBranch, "--head", ws.branch, "--title", title, "--body", body];
+    if (!input.completed) prArgs.push("--draft");
+    const pr = await this.run("gh", prArgs, ws.dir);
+    const prUrl = pr.status === 0 ? /https:\/\/\S+/.exec(pr.stdout)?.[0] : void 0;
+    let compareUrl;
+    if (!prUrl) {
+      const remoteUrl = (await this.git(["remote", "get-url", ws.remote], ws.dir)).stdout.trim();
+      compareUrl = githubCompareUrl(remoteUrl, ws.baseBranch, ws.branch) ?? void 0;
+      notes.push(
+        `The branch was pushed, but the pull request couldn't be opened automatically${firstLine(pr.stderr) ? ` (${firstLine(pr.stderr)})` : ""}.` + (compareUrl ? " Use the link to open it." : ` Open a pull request for ${ws.branch} on your git host.`)
+      );
+    }
+    await this.git(["worktree", "remove", "--force", ws.dir], ws.projectDir);
+    return { ...base, pushed: true, ...prUrl ? { prUrl } : {}, ...compareUrl ? { compareUrl } : {} };
+  }
+};
+
+// src/utils/repo-setup.ts
+import { spawn as spawn5 } from "node:child_process";
+import { existsSync as existsSync10, mkdirSync as mkdirSync7, readdirSync } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { dirname as dirname5, isAbsolute as isAbsolute2, join as join11, resolve as resolve2 } from "node:path";
+var CLONE_TIMEOUT_MS = 15 * 60 * 1e3;
+var defaultGitCloner = (url, target) => new Promise((done) => {
+  let stderr = "";
+  const child = spawn5("git", ["clone", "--quiet", url, target], {
+    stdio: ["ignore", "ignore", "pipe"],
+    // Never hang on a username/password prompt: fail and explain instead.
+    env: { ...process.env, PATH: claudeChildEnvPath(process.env.PATH), GIT_TERMINAL_PROMPT: "0" }
+  });
+  const timer = setTimeout(() => {
+    child.kill("SIGKILL");
+    stderr += "git clone timed out";
+  }, CLONE_TIMEOUT_MS);
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf-8");
+  });
+  child.on("error", (error) => {
+    clearTimeout(timer);
+    done({ status: 1, stderr: error.message });
+  });
+  child.on("close", (code) => {
+    clearTimeout(timer);
+    done({ status: code ?? 1, stderr });
+  });
+});
+function repoFolderName(remote) {
+  const last = remote.replace(/\/+$/, "").split("/").pop() ?? "";
+  return last.replace(/[^A-Za-z0-9._-]+/g, "-") || "project";
+}
+function resolveFolder(folder, home) {
+  const trimmed = folder.trim();
+  if (trimmed === "~") return home;
+  if (trimmed.startsWith("~/")) return join11(home, trimmed.slice(2));
+  return isAbsolute2(trimmed) ? resolve2(trimmed) : join11(home, trimmed);
+}
+function cloneUrls(remote) {
+  const urls = [`${remote}.git`];
+  const gh = /^https:\/\/github\.com\/([^/]+)\/([^/]+)$/.exec(remote);
+  if (gh) urls.push(`git@github.com:${gh[1] ?? ""}/${gh[2] ?? ""}.git`);
+  return urls;
+}
+function parsePayload(payload) {
+  if (typeof payload !== "object" || payload === null) return null;
+  const p = payload;
+  if (typeof p.teamId !== "string" || typeof p.projectRemote !== "string") return null;
+  if (!p.projectRemote.startsWith("https://")) return null;
+  return {
+    teamId: p.teamId,
+    projectRemote: p.projectRemote,
+    ...typeof p.folder === "string" ? { folder: p.folder } : {},
+    ...typeof p.projectName === "string" ? { projectName: p.projectName } : {}
+  };
+}
+function firstLine2(text) {
+  return text.trim().split("\n").filter(Boolean).pop() ?? "";
+}
+async function invokeConnectRepo(payload, deps = {}) {
+  const clone = deps.clone ?? defaultGitCloner;
+  const home = deps.home ?? homedir6();
+  const exists = deps.exists ?? existsSync10;
+  const isEmptyDir = deps.isEmptyDir ?? ((path3) => {
+    try {
+      return readdirSync(path3).length === 0;
+    } catch {
+      return false;
+    }
+  });
+  const isGitRepo = deps.isGitRepo ?? isGitRepoDir;
+  const readOrigin = deps.readOrigin ?? readOriginRemote;
+  const listDirs = deps.listDirs ?? listProjectDirs;
+  const addDir = deps.addDir ?? ((path3) => addProjectDir(path3));
+  const mkdir2 = deps.mkdir ?? ((path3) => void mkdirSync7(path3, { recursive: true }));
+  const p = parsePayload(payload);
+  if (!p) {
+    return { status: "failed", result: { error: "The job was missing the project repository. Try again from the project page." } };
+  }
+  const remote = normalizeGitRemote(p.projectRemote);
+  const name = p.projectName ?? repoFolderName(remote);
+  const existing = listDirs().find((entry) => entry.remote === remote && exists(entry.path));
+  if (existing) {
+    return {
+      status: "done",
+      result: { path: existing.path, remote, outcome: "already_set_up", message: `${name} is already set up on this computer at ${existing.path}.` }
+    };
+  }
+  const target = resolveFolder(p.folder ?? join11("CompBox", repoFolderName(remote)), home);
+  try {
+    if (exists(target) && !isEmptyDir(target)) {
+      let origin = "";
+      try {
+        origin = isGitRepo(target) ? normalizeGitRemote(readOrigin(target)) : "";
+      } catch {
+        origin = "";
+      }
+      if (origin !== remote) {
+        return {
+          status: "failed",
+          result: {
+            error: `The folder ${target} already exists and isn't a copy of ${remote}. Choose a different folder and try again.`
+          }
+        };
+      }
+      const entry2 = addDir(target);
+      return {
+        status: "done",
+        result: { path: entry2.path, remote, outcome: "adopted", message: `Found an existing copy of ${name} at ${entry2.path} and set it up.` }
+      };
+    }
+    mkdir2(dirname5(target));
+    const errors = [];
+    let cloned = false;
+    for (const url of cloneUrls(remote)) {
+      const res = await clone(url, target);
+      if (res.status === 0) {
+        cloned = true;
+        break;
+      }
+      errors.push(firstLine2(res.stderr));
+    }
+    if (!cloned) {
+      return {
+        status: "failed",
+        result: {
+          error: [
+            `This computer couldn't download ${remote}: ${errors.filter(Boolean).join(" / ") || "unknown error"}.`,
+            "Make sure this computer can access the repository, for example by signing in with `gh auth login` or adding an SSH key to your Git account, then try again."
+          ].join(" ")
+        }
+      };
+    }
+    const entry = addDir(target);
+    return {
+      status: "done",
+      result: { path: entry.path, remote, outcome: "cloned", message: `Downloaded ${name} to ${entry.path} and set it up.` }
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      result: { error: `Setting up ${name} failed: ${error instanceof Error ? error.message : String(error)}` }
+    };
+  }
+}
+
 // src/commands/run.ts
 var POLL_WAIT_MS = 0;
 var IDLE_POLL_INTERVAL_MS = 15e3;
@@ -8478,7 +9153,7 @@ function runtimeHeartbeatDue(nowMs, lastRuntimeSentMs, intervalMs = HEARTBEAT_IN
   return nowMs - lastRuntimeSentMs >= intervalMs;
 }
 function sleep2(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function backoffDelay(consecutiveErrors) {
   return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
@@ -8523,11 +9198,12 @@ function parseStartExecutionPayload(payload) {
   const p = parsed;
   if (!START_EXECUTION_KINDS.includes(p.kind)) return null;
   const projectRemote = typeof p.projectRemote === "string" && p.projectRemote.length > 0 ? p.projectRemote : void 0;
+  const useAiKey = p.useAiKey === true;
   if (p.kind === "plan" && typeof p.epicRequestId === "string" && p.epicRequestId.length > 0) {
-    return { kind: "plan", epicRequestId: p.epicRequestId, ...projectRemote && { projectRemote } };
+    return { kind: "plan", epicRequestId: p.epicRequestId, ...projectRemote && { projectRemote }, ...useAiKey && { useAiKey } };
   }
   if (p.kind === "orchestrate" && typeof p.epicId === "string" && p.epicId.length > 0) {
-    return { kind: "orchestrate", epicId: p.epicId, ...projectRemote && { projectRemote } };
+    return { kind: "orchestrate", epicId: p.epicId, ...projectRemote && { projectRemote }, ...useAiKey && { useAiKey } };
   }
   return null;
 }
@@ -8550,6 +9226,18 @@ async function handleStartExecution(ctx, job) {
     return;
   }
   const jobProjectDir = routed.status === "registered" || routed.status === "fallback" ? routed.path : void 0;
+  let keyRun;
+  if (payload.useAiKey) {
+    try {
+      const key = await ctx.client.getAiKey(ctx.machineToken, job.id);
+      keyRun = { apiKey: key.apiKey, model: key.model };
+      console.log(chalk9.gray(`  Running on your saved API key (${key.provider}, ${key.model}).`));
+    } catch (error) {
+      const message = error instanceof MailboxClientError ? error.message : "the key request failed";
+      await completeWithFailure(ctx, job, `Couldn't get your saved API key from CompBox (${message}). Check Settings \u2192 AI, or run with this computer's own sign-in.`);
+      return;
+    }
+  }
   if (payload.kind === "plan") {
     const userApiToken2 = ctx.userApiToken;
     if (!userApiToken2) {
@@ -8572,7 +9260,8 @@ async function handleStartExecution(ctx, job) {
           apiBaseUrl: ctx.apiBaseUrl,
           userApiToken: userApiToken2,
           epicRequestId: payload.epicRequestId,
-          projectDir: jobProjectDir
+          projectDir: jobProjectDir,
+          ...keyRun && { keyRun }
         },
         {
           // H4: keep this machine online during the long planner run — the poll
@@ -8602,12 +9291,15 @@ async function handleStartExecution(ctx, job) {
         machineToken: ctx.machineToken,
         jobId: job.id,
         epicId: payload.epicId,
-        projectDir: jobProjectDir
+        projectDir: jobProjectDir,
+        ...keyRun && { keyRun }
       },
       {
         // H4: keep this machine online during the long orchestrator run — the
         // poll loop (its own heartbeat) is blocked for the whole job.
-        heartbeat: () => ctx.client.heartbeat(ctx.machineToken).catch(() => void 0)
+        heartbeat: () => ctx.client.heartbeat(ctx.machineToken).catch(() => void 0),
+        // Own branch + worktree per run, finishing with a pull request.
+        workspace: new RunWorkspaceManager()
       }
     )
   );
@@ -8675,6 +9367,17 @@ async function handleJob(ctx, job) {
       return;
     }
   }
+  if (job.type === "connect_repo") {
+    console.log(chalk9.gray("  Setting up a project repository on this computer (connect_repo)..."));
+    await runInvokerAndComplete(ctx, job, async () => {
+      const outcome = await invokeConnectRepo(job.payload);
+      if (outcome.status === "done") {
+        await ctx.client.heartbeat(ctx.machineToken, void 0, gatherServicedRemotes()).catch(() => void 0);
+      }
+      return outcome;
+    });
+    return;
+  }
   if (job.type === "start_execution") {
     await handleStartExecution(ctx, job);
     return;
@@ -9090,7 +9793,7 @@ machinesCommand.command("rm <id>").description("Remove (revoke) a paired machine
 // src/index.ts
 function resolveCliVersion() {
   if (true) {
-    return "1.18.0";
+    return "1.19.0";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");