@algosuite/vo-mcp 0.2.0-beta.1 → 0.2.0-beta.2

package/dist/runner-cli.js

@@ -155,12 +155,65 @@ import fs from "node:fs";
 function repoRoot() {
   return process.env.VO_CODE_RUNNER_REPO || process.cwd();
 }
+function clonesRoot() {
+  return process.env.VO_CODE_RUNNER_CLONES_ROOT || "";
+}
+var VALID_REPO_SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+var TRACKED_WORKTREES = /* @__PURE__ */ new Map();
 function sanitize(value, fallback) {
   const cleaned = String(value || "").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return cleaned || fallback;
 }
+function cloneDirForSlug(repoSlug, clonesRootDir) {
+  if (!clonesRootDir || !repoSlug || !VALID_REPO_SLUG.test(String(repoSlug))) return null;
+  const [owner, name] = String(repoSlug).split("/");
+  if (owner === "." || owner === ".." || name === "." || name === "..") return null;
+  if (owner.startsWith("-") || name.startsWith("-")) return null;
+  return path.join(clonesRootDir, `${sanitize(owner, "owner")}__${sanitize(name, "repo")}`);
+}
+function resolveTaskRoot(repoSlug) {
+  const root = clonesRoot();
+  if (root && !path.isAbsolute(root)) {
+    throw new Error(
+      `[vo-mcp runner] VO_CODE_RUNNER_CLONES_ROOT must be an absolute path (got '${root}')`
+    );
+  }
+  const dir = cloneDirForSlug(repoSlug, root);
+  if (!dir) return { root: repoRoot(), multiRepo: false };
+  if (!fs.existsSync(path.join(dir, ".git"))) {
+    fs.mkdirSync(clonesRoot(), { recursive: true });
+    const [owner, name] = String(repoSlug).split("/");
+    const tmpDir = `${dir}.tmp-${process.pid}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
+    const cl = spawnSync(
+      "git",
+      ["clone", "--no-tags", `https://github.com/${owner}/${name}.git`, tmpDir],
+      { encoding: "utf8", timeout: 6e5 }
+    );
+    if (cl.status !== 0 || !fs.existsSync(path.join(tmpDir, ".git"))) {
+      try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+      }
+      throw new Error(
+        `[vo-mcp runner] clone failed for ${repoSlug}: ${String(cl.stderr || cl.error || "").slice(0, 200)}`
+      );
+    }
+    try {
+      fs.renameSync(tmpDir, dir);
+    } catch {
+      try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+      }
+      if (!fs.existsSync(path.join(dir, ".git"))) {
+        throw new Error(`[vo-mcp runner] clone race left no usable clone for ${repoSlug}`);
+      }
+    }
+  }
+  return { root: dir, multiRepo: true };
+}
 function createFixWorktree(kind, error = {}) {
-  const root = repoRoot();
+  const { root, multiRepo } = resolveTaskRoot(error.repo);
   const safeKind = sanitize(kind, "task");
   const safeTarget = sanitize(error.source || error.tester || "run", "run").slice(0, 24);
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
@@ -174,18 +227,23 @@ function createFixWorktree(kind, error = {}) {
     { cwd: root, encoding: "utf8", timeout: 12e4 }
   );
   if (add.status === 0 && fs.existsSync(worktreeDir)) {
+    TRACKED_WORKTREES.set(worktreeName, { worktreeDir, root });
     return { worktreeDir, worktreeName };
   }
-  console.error(
-    `[vo-mcp runner] worktree isolation unavailable: ${String(add.stderr || add.error || "").slice(0, 200)}`
-  );
+  const detail = String(add.stderr || add.error || "").slice(0, 200);
+  if (multiRepo) {
+    throw new Error(`[vo-mcp runner] worktree create failed for ${error.repo}: ${detail}`);
+  }
+  console.error(`[vo-mcp runner] worktree isolation unavailable: ${detail}`);
   return { worktreeDir: root, worktreeName: "" };
 }
 function cleanupFixWorktree(worktreeName) {
   if (!worktreeName) return;
-  const root = repoRoot();
-  const worktreeDir = path.join(root, ".agent-worktrees", worktreeName);
+  const tracked = TRACKED_WORKTREES.get(worktreeName);
+  const root = tracked ? tracked.root : repoRoot();
+  const worktreeDir = tracked ? tracked.worktreeDir : path.join(root, ".agent-worktrees", worktreeName);
   spawnSync("git", ["worktree", "remove", "--force", worktreeDir], { cwd: root, timeout: 12e4 });
+  TRACKED_WORKTREES.delete(worktreeName);
 }
 
 // src/runner/spend-cap-shim.mjs
@@ -324,6 +382,52 @@ function createControlPlaneClient({
       if (!res.ok) throw new Error(`weekly-tokens failed: HTTP ${res.status}`);
       return true;
     },
+    /**
+     * Send a liveness heartbeat (M2). The control-plane upserts it under the
+     * authenticated operator so the web shows a TRUE "runner online" signal.
+     * Best-effort caller; throws on 401/non-ok so the daemon can log + retry.
+     */
+    async postHeartbeat({ runnerId, uptimeSec, activeTasks, version }) {
+      const body = { runner_id: runnerId };
+      if (typeof uptimeSec === "number") body.uptime_sec = uptimeSec;
+      if (typeof activeTasks === "number") body.active_tasks = activeTasks;
+      if (version) body.version = version;
+      const res = await req("POST", "/api/v1/runner/heartbeat", body);
+      if (res.status === 401) {
+        cachedFirebaseToken = null;
+        throw new Error("heartbeat unauthorized (401)");
+      }
+      if (!res.ok) throw new Error(`heartbeat failed: HTTP ${res.status}`);
+      return true;
+    },
+    /**
+     * Mint a short-lived (~1h), repo-scoped GitHub App installation token for
+     * THIS runner's operator (M3). The control-plane keys the mint on the
+     * authenticated operator (ctx.operator_id), so the token covers only that
+     * operator's installation.
+     *
+     * Returns { token, expiresAt } on success, or `null` on ANY non-success —
+     * 503 (App not configured / dormant), 404 (operator has no installation),
+     * other non-2xx, or a network error. `null` is the signal to the caller to
+     * fall back to the runner's own ambient `gh` auth, so a dormant or
+     * unmapped App NEVER blocks a PR the runner could open itself. Never throws.
+     *
+     * The minted token is only usable for push + PR if the GitHub App grants
+     * BOTH `Contents: write` (git push) AND `Pull requests: write` (gh pr
+     * create) — see docs/vo/github-app-setup-2026-06-18.md. A token missing
+     * either scope fails at push (→ ambient fallback) or at `gh pr create`.
+     */
+    async getInstallationToken() {
+      try {
+        const res = await req("POST", "/api/v1/github/installation-token", {});
+        if (!res.ok) return null;
+        const json = await res.json();
+        if (!json || !json.token) return null;
+        return { token: json.token, expiresAt: json.expires_at || null };
+      } catch {
+        return null;
+      }
+    },
     /**
      * Read the operator's dispatch-mode config (Fast→Ultracode effort setting).
      * Returns the mode string ('fast'|'standard'|'deep'|'ultra'|'ultracode'),
@@ -345,6 +449,39 @@ function createControlPlaneClient({
 // ../../scripts/virtual-office/code-runner/claude-runner.mjs
 import { spawn } from "node:child_process";
 import { spawnSync as spawnSync2 } from "node:child_process";
+
+// ../../scripts/virtual-office/code-runner/anthropic-key-store.mjs
+import { createRequire as createRequire2 } from "node:module";
+var require2 = createRequire2(import.meta.url);
+var KEY_SERVICE = "algosuite-vo";
+var KEY_ACCOUNT = "anthropic-api-key";
+var _entryCtor;
+var _loadTried = false;
+function defaultEntryCtor() {
+  if (_loadTried) return _entryCtor;
+  _loadTried = true;
+  try {
+    _entryCtor = require2("@napi-rs/keyring").Entry;
+  } catch {
+    _entryCtor = null;
+  }
+  return _entryCtor;
+}
+function getAnthropicKey({ EntryCtor = defaultEntryCtor() } = {}) {
+  if (!EntryCtor) return null;
+  try {
+    return new EntryCtor(KEY_SERVICE, KEY_ACCOUNT).getPassword() || null;
+  } catch {
+    return null;
+  }
+}
+function withAnthropicKey(baseEnv = {}, { getKey = getAnthropicKey } = {}) {
+  if (baseEnv.ANTHROPIC_API_KEY) return { ...baseEnv };
+  const key = getKey();
+  return key ? { ...baseEnv, ANTHROPIC_API_KEY: key } : { ...baseEnv };
+}
+
+// ../../scripts/virtual-office/code-runner/claude-runner.mjs
 var DEFAULT_PERMISSION_MODE = "acceptEdits";
 function extractText(content) {
   if (typeof content === "string") return content.trim();
@@ -396,10 +533,11 @@ function buildClaudeArgs({ permissionMode = DEFAULT_PERMISSION_MODE, maxTurns, m
   }
   return args;
 }
-function runClaudeTask({
+function runAgentTask({
+  runner,
   prompt,
   cwd,
-  claudeBin = "claude",
+  bin = runner.binary,
   permissionMode,
   maxTurns,
   model,
@@ -412,16 +550,20 @@ function runClaudeTask({
   spawnImpl = spawn
 }) {
   return new Promise((resolve) => {
-    const args = buildClaudeArgs({ permissionMode, maxTurns, model });
-    const child = spawnImpl(claudeBin, args, {
+    const args = runner.buildArgs({ permissionMode, maxTurns, model, prompt });
+    const child = spawnImpl(bin, args, {
       cwd,
-      env: { ...env2 },
+      // BYO auth: each runner fills its provider's credential env var(s) from the
+      // OS keychain when not already set (Claude→ANTHROPIC_API_KEY via
+      // anthropic-key-store, Codex→OPENAI_API_KEY, …). Explicit env wins; no key
+      // stored → unchanged (the CLI's own login as before).
+      env: typeof runner.applyAuthEnv === "function" ? runner.applyAuthEnv(env2) : env2,
       stdio: ["pipe", "pipe", "pipe"],
-      // Windows: `claude` is a `.cmd` shim → spawn needs a shell to resolve it
-      // (without it: spawn ENOENT). Safe because the prompt goes via stdin
-      // below, never argv, so the shell never sees untrusted input.
-      shell: process.platform === "win32",
-      windowsHide: true
+      // getSpawnOptions carries the per-runner shell/windowsHide posture. On
+      // Windows the CLI is a `.cmd` shim → spawn needs shell:true to resolve it
+      // (without it: ENOENT). Safe because the prompt goes via stdin below,
+      // never argv, so the shell never sees untrusted input.
+      ...runner.getSpawnOptions()
     });
     try {
       child.stdin.write(String(prompt));
@@ -456,7 +598,7 @@ function runClaudeTask({
       while ((nl = buffer.indexOf("\n")) >= 0) {
         const line = buffer.slice(0, nl);
         buffer = buffer.slice(nl + 1);
-        const evt = parseStreamEvent(line);
+        const evt = runner.parseEvent(line);
         if (!evt) continue;
         if (evt.kind === "progress") {
           try {
@@ -509,7 +651,7 @@ function runClaudeTask({
         return;
       }
       if (!result.summary && code !== 0) {
-        result.summary = stderrTail.slice(-500) || `claude exited ${code}`;
+        result.summary = stderrTail.slice(-500) || `${bin} exited ${code}`;
       }
       resolve({ ...result, ok: result.ok && code === 0 });
     });
@@ -531,6 +673,14 @@ var ClaudeRunner = class {
       windowsHide: true
     };
   }
+  /**
+   * Fill ANTHROPIC_API_KEY from the OS keychain when not already set (M4 BYO),
+   * so a friend who ran `vo-mcp set-key` authenticates without an env var.
+   * Explicit env wins; no key stored → unchanged (Claude Code login as before).
+   */
+  applyAuthEnv(env2 = process.env) {
+    return withAnthropicKey(env2);
+  }
   /**
    * Best-effort auth check: is `claude` on PATH and can we verify login?
    * Never throws. If we can't cheaply detect auth, we return installed:true
@@ -574,6 +724,310 @@ var ClaudeRunner = class {
 };
 var claudeRunner = new ClaudeRunner();
 
+// ../../scripts/virtual-office/code-runner/codex-runner.mjs
+import { spawnSync as spawnSync3 } from "node:child_process";
+
+// ../../scripts/virtual-office/code-runner/agent-key-store.mjs
+import { createRequire as createRequire3 } from "node:module";
+var require3 = createRequire3(import.meta.url);
+var KEY_SERVICE2 = "algosuite-vo";
+var PROVIDER_ENV = {
+  anthropic: ["ANTHROPIC_API_KEY"],
+  openai: ["OPENAI_API_KEY", "CODEX_API_KEY"],
+  cursor: ["CURSOR_API_KEY"]
+};
+var PROVIDER_ALIAS = {
+  claude: "anthropic",
+  anthropic: "anthropic",
+  codex: "openai",
+  openai: "openai",
+  cursor: "cursor"
+};
+function resolveProvider(name) {
+  const key = String(name || "").trim().toLowerCase();
+  return PROVIDER_ALIAS[key] || null;
+}
+function accountFor(provider) {
+  return `${provider}-api-key`;
+}
+var _entryCtor2;
+var _loadTried2 = false;
+function defaultEntryCtor2() {
+  if (_loadTried2) return _entryCtor2;
+  _loadTried2 = true;
+  try {
+    _entryCtor2 = require3("@napi-rs/keyring").Entry;
+  } catch {
+    _entryCtor2 = null;
+  }
+  return _entryCtor2;
+}
+function getAgentKey(provider, { EntryCtor = defaultEntryCtor2() } = {}) {
+  const p = resolveProvider(provider);
+  if (!p || !EntryCtor) return null;
+  try {
+    return new EntryCtor(KEY_SERVICE2, accountFor(p)).getPassword() || null;
+  } catch {
+    return null;
+  }
+}
+function withAgentKey(provider, baseEnv = {}, { getKey = getAgentKey } = {}) {
+  const p = resolveProvider(provider);
+  const vars = p && PROVIDER_ENV[p] || [];
+  const out = { ...baseEnv };
+  if (!p || vars.length === 0) return out;
+  if (vars.some((v) => out[v])) return out;
+  const key = getKey(p);
+  if (!key) return out;
+  for (const v of vars) out[v] = key;
+  return out;
+}
+
+// ../../scripts/virtual-office/code-runner/codex-runner.mjs
+function buildCodexArgs({ model } = {}) {
+  const args = ["exec", "--json", "--full-auto"];
+  if (model) {
+    args.push("--model", String(model));
+  }
+  args.push("-");
+  return args;
+}
+function itemText(item) {
+  if (!item) return "";
+  if (typeof item.text === "string") return item.text;
+  if (typeof item.message === "string") return item.message;
+  if (Array.isArray(item.content)) {
+    return item.content.map((b) => typeof b === "string" ? b : typeof b?.text === "string" ? b.text : "").join("");
+  }
+  return "";
+}
+function parseCodexEvent(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed) return null;
+  let evt;
+  try {
+    evt = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!evt || typeof evt !== "object") return null;
+  const type = evt.type;
+  if (type === "item.completed" && evt.item) {
+    const it = evt.item.type;
+    if (it === "agent_message" || it === "assistant_message") {
+      const text = itemText(evt.item).trim();
+      return text ? { kind: "progress", text } : null;
+    }
+    return null;
+  }
+  if (type === "turn.completed") {
+    return { kind: "result", isError: false, costUsd: null, summary: "completed", numTurns: null };
+  }
+  if (type === "turn.failed" || type === "error") {
+    const msg = evt.error && (evt.error.message || evt.error) || evt.message || "codex run failed";
+    return { kind: "result", isError: true, costUsd: null, summary: String(msg), numTurns: null };
+  }
+  return null;
+}
+var CodexRunner = class {
+  get binary() {
+    return "codex";
+  }
+  buildArgs(opts = {}) {
+    return buildCodexArgs(opts);
+  }
+  parseEvent(line) {
+    return parseCodexEvent(line);
+  }
+  getSpawnOptions() {
+    return {
+      shell: process.platform === "win32",
+      windowsHide: true
+    };
+  }
+  /**
+   * Fill the OpenAI credential env var(s) (OPENAI_API_KEY / CODEX_API_KEY) from
+   * the OS keychain when not already set, so a BYO friend who ran
+   * `vo-mcp set-key --provider codex` authenticates without an env var. Explicit
+   * env wins; no key stored → unchanged (a prior `codex login` still works).
+   */
+  applyAuthEnv(env2 = process.env) {
+    return withAgentKey("openai", env2);
+  }
+  /** Best-effort: is `codex` on PATH? Never throws. */
+  async checkAuth() {
+    try {
+      const { status, error } = spawnSync3("codex", ["--version"], {
+        shell: process.platform === "win32",
+        windowsHide: true,
+        timeout: 3e3,
+        stdio: "ignore"
+      });
+      if (error) {
+        return { installed: false, authenticated: false, message: `codex not found on PATH: ${error.message}` };
+      }
+      if (status !== 0) {
+        return { installed: true, authenticated: false, message: "codex exists but --version failed (auth unclear)" };
+      }
+      return { installed: true, authenticated: true, message: "codex binary found (auth check is best-effort)" };
+    } catch (err) {
+      return { installed: false, authenticated: false, message: `checkAuth probe failed: ${err.message}` };
+    }
+  }
+};
+var codexRunner = new CodexRunner();
+
+// ../../scripts/virtual-office/code-runner/cursor-runner.mjs
+import { spawnSync as spawnSync4 } from "node:child_process";
+function buildCursorArgs({ model, prompt } = {}) {
+  const args = ["-p", "--output-format", "stream-json", "--force"];
+  if (model) {
+    args.push("--model", String(model));
+  }
+  const p = String(prompt ?? "");
+  if (p.length > 0) {
+    args.push(p);
+  }
+  return args;
+}
+function messageText(message) {
+  if (!message) return "";
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((b) => typeof b === "string" ? b : typeof b?.text === "string" ? b.text : "").join("");
+  }
+  return "";
+}
+function parseCursorEvent(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed) return null;
+  let evt;
+  try {
+    evt = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!evt || typeof evt !== "object") return null;
+  if (evt.type === "assistant") {
+    const text = messageText(evt.message).trim();
+    return text ? { kind: "progress", text } : null;
+  }
+  if (evt.type === "result") {
+    const isError = Boolean(evt.is_error) || evt.subtype === "error";
+    return {
+      kind: "result",
+      isError,
+      costUsd: null,
+      summary: typeof evt.result === "string" && evt.result.length > 0 ? evt.result : evt.subtype || (isError ? "error" : "completed"),
+      numTurns: null
+    };
+  }
+  return null;
+}
+var CursorRunner = class {
+  get binary() {
+    return "cursor-agent";
+  }
+  buildArgs(opts = {}) {
+    return buildCursorArgs(opts);
+  }
+  parseEvent(line) {
+    return parseCursorEvent(line);
+  }
+  getSpawnOptions() {
+    return {
+      shell: process.platform === "win32",
+      windowsHide: true
+    };
+  }
+  /**
+   * Fill CURSOR_API_KEY from the OS keychain when not already set, so a BYO
+   * friend who ran `vo-mcp set-key --provider cursor` authenticates without an
+   * env var. Explicit env wins; no key stored → a prior `cursor-agent login`.
+   */
+  applyAuthEnv(env2 = process.env) {
+    return withAgentKey("cursor", env2);
+  }
+  /** Best-effort: is `cursor-agent` on PATH? Never throws. */
+  async checkAuth() {
+    try {
+      const { status, error } = spawnSync4("cursor-agent", ["--version"], {
+        shell: process.platform === "win32",
+        windowsHide: true,
+        timeout: 3e3,
+        stdio: "ignore"
+      });
+      if (error) {
+        return { installed: false, authenticated: false, message: `cursor-agent not found on PATH: ${error.message}` };
+      }
+      if (status !== 0) {
+        return { installed: true, authenticated: false, message: "cursor-agent exists but --version failed (auth unclear)" };
+      }
+      return {
+        installed: true,
+        authenticated: true,
+        message: "cursor-agent found (EXPERIMENTAL: headless mode may need a TTY; auth check is best-effort)"
+      };
+    } catch (err) {
+      return { installed: false, authenticated: false, message: `checkAuth probe failed: ${err.message}` };
+    }
+  }
+};
+var cursorRunner = new CursorRunner();
+
+// ../../scripts/virtual-office/code-runner/agent-runner-interface.mjs
+function validateAgentRunner(runner) {
+  if (!runner || typeof runner !== "object") {
+    throw new TypeError("AgentRunner must be an object");
+  }
+  if (typeof runner.binary !== "string" || runner.binary.length === 0) {
+    throw new TypeError("AgentRunner.binary must be a non-empty string");
+  }
+  if (typeof runner.buildArgs !== "function") {
+    throw new TypeError("AgentRunner.buildArgs must be a function");
+  }
+  if (typeof runner.parseEvent !== "function") {
+    throw new TypeError("AgentRunner.parseEvent must be a function");
+  }
+  if (typeof runner.getSpawnOptions !== "function") {
+    throw new TypeError("AgentRunner.getSpawnOptions must be a function");
+  }
+  if (typeof runner.checkAuth !== "function") {
+    throw new TypeError("AgentRunner.checkAuth must be a function");
+  }
+}
+
+// ../../scripts/virtual-office/code-runner/resolve-runner.mjs
+var DEFAULT_AGENT = "claude";
+var RUNNERS = {
+  claude: claudeRunner,
+  codex: codexRunner,
+  cursor: cursorRunner
+};
+function listAgents() {
+  return Object.keys(RUNNERS);
+}
+function resolveRunner(env2 = process.env, { warn = () => {
+} } = {}) {
+  const raw = String(env2.VO_CODE_RUNNER_AGENT || env2.VO_AGENT || DEFAULT_AGENT).trim().toLowerCase();
+  let agent = raw;
+  let fellBack = false;
+  let runner = RUNNERS[agent];
+  if (!runner) {
+    try {
+      warn(`unknown VO_CODE_RUNNER_AGENT "${raw}"; falling back to "${DEFAULT_AGENT}" (known: ${listAgents().join(", ")})`);
+    } catch {
+    }
+    agent = DEFAULT_AGENT;
+    runner = RUNNERS[DEFAULT_AGENT];
+    fellBack = true;
+  }
+  validateAgentRunner(runner);
+  const runnerBin = env2.VO_CODE_RUNNER_BIN || (agent === "claude" ? env2.VO_CODE_RUNNER_CLAUDE_BIN : "") || runner.binary;
+  return { agent, runner, runnerBin, fellBack };
+}
+
 // ../../scripts/virtual-office/code-runner/rate-limit-resume.mjs
 import { appendFileSync, mkdirSync as mkdirSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
@@ -674,9 +1128,9 @@ function classifyFailureForResume({
 }
 
 // ../../scripts/virtual-office/code-runner/publish.mjs
-import { spawnSync as spawnSync3 } from "node:child_process";
-function run(cmd, args, cwd, { timeout = 18e4, raw = false } = {}) {
-  const r = spawnSync3(cmd, args, { cwd, encoding: "utf8", timeout });
+import { spawnSync as spawnSync5 } from "node:child_process";
+function run(cmd, args, cwd, { timeout = 18e4, raw = false, env: env2 } = {}) {
+  const r = spawnSync5(cmd, args, { cwd, encoding: "utf8", timeout, ...env2 ? { env: env2 } : {} });
   if (r.error) throw r.error;
   if (r.status !== 0) {
     throw new Error(`${cmd} ${args[0]} failed (exit ${r.status}): ${(r.stderr || "").slice(-300)}`);
@@ -735,6 +1189,44 @@ function listCommittedFiles(cwd, base = "origin/main") {
 function compactTitle(s, max = 100) {
   return String(s || "").replace(/\s+/g, " ").trim().slice(0, max) || "code-task";
 }
+function installationTokenEnv(githubToken, baseEnv = process.env) {
+  if (!githubToken) return void 0;
+  return { ...baseEnv, GH_TOKEN: githubToken, GITHUB_TOKEN: githubToken };
+}
+function pushArgs(branch, { withToken = false } = {}) {
+  if (withToken) {
+    return [
+      "-c",
+      "credential.helper=",
+      "-c",
+      "credential.helper=!gh auth git-credential",
+      "push",
+      "origin",
+      branch
+    ];
+  }
+  return ["push", "origin", branch];
+}
+function pushPlan(branch, githubToken) {
+  if (githubToken) {
+    return {
+      primary: { args: pushArgs(branch, { withToken: true }), env: installationTokenEnv(githubToken), tokenUsed: true },
+      fallback: { args: pushArgs(branch), env: void 0, tokenUsed: false }
+    };
+  }
+  return { primary: { args: pushArgs(branch), env: void 0, tokenUsed: false }, fallback: null };
+}
+function pushBranch(worktreeDir, branch, githubToken, runFn = run) {
+  const { primary, fallback } = pushPlan(branch, githubToken);
+  try {
+    runFn("git", primary.args, worktreeDir, { env: primary.env });
+    return primary.tokenUsed;
+  } catch (err) {
+    if (!fallback) throw err;
+    runFn("git", fallback.args, worktreeDir, { env: fallback.env });
+    return fallback.tokenUsed;
+  }
+}
 function openCodeTaskPr(worktreeDir, files, {
   title,
   body,
@@ -744,7 +1236,12 @@ function openCodeTaskPr(worktreeDir, files, {
   maxFiles = 200,
   // Safety net: the agent already COMMITTED its work to a branch (despite the
   // preamble). Skip add+commit; just push the existing branch and open the PR.
-  alreadyCommitted = false
+  alreadyCommitted = false,
+  // Optional GitHub App installation token (M3). When present, the push + PR
+  // authenticate as the App (the runner needs no repo write access of its own);
+  // a push failure transparently falls back to the runner's ambient gh auth.
+  // Absent → today's behavior (ambient gh) exactly.
+  githubToken = null
 } = {}) {
   if (!Array.isArray(files) || files.length === 0) {
     throw new Error("openCodeTaskPr: no files to commit");
@@ -761,13 +1258,14 @@ function openCodeTaskPr(worktreeDir, files, {
     branch = run("git", ["branch", "--show-current"], worktreeDir, { timeout: 3e4 });
   } catch {
   }
+  let tokenUsed;
   if (alreadyCommitted) {
     if (!branch || branch === "main" || branch === "HEAD") {
       const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
       branch = `${branchPrefix}-${stamp}`;
       run("git", ["checkout", "-b", branch], worktreeDir);
     }
-    run("git", ["push", "origin", branch], worktreeDir);
+    tokenUsed = pushBranch(worktreeDir, branch, githubToken);
   } else {
     if (!branch || branch === "main" || branch === "HEAD") {
       const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
@@ -780,7 +1278,7 @@ function openCodeTaskPr(worktreeDir, files, {
     }
     const commitMsg = compactTitle(title, 180);
     run("git", ["commit", "--no-verify", "-m", commitMsg], worktreeDir);
-    run("git", ["push", "origin", branch], worktreeDir);
+    tokenUsed = pushBranch(worktreeDir, branch, githubToken);
   }
   const out = run(
     "gh",
@@ -796,7 +1294,8 @@ function openCodeTaskPr(worktreeDir, files, {
       "--body",
       String(body || "")
     ],
-    worktreeDir
+    worktreeDir,
+    { env: tokenUsed ? installationTokenEnv(githubToken) : void 0 }
   );
   const m = out.match(/https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/(\d+)/);
   if (!m) throw new Error("gh pr create returned no parseable PR URL");
@@ -983,14 +1482,37 @@ async function forwardSessionSpool(deps) {
   return { forwarded, pruned };
 }
 
+// ../../scripts/virtual-office/code-runner/loop-ticks.mjs
+var HEARTBEAT_MS = 6e4;
+function makeLoopTicks({ client, cfg, env: env2, log: log2, getActive }) {
+  let lastSessionForward = 0;
+  let lastHeartbeat = 0;
+  return function tick() {
+    const now = Date.now();
+    if (cfg.sessionForwardSec > 0 && now - lastSessionForward >= cfg.sessionForwardSec * 1e3) {
+      lastSessionForward = now;
+      forwardSessionSpool({
+        baseUrl: String(env2.VO_CONTROL_PLANE_URL || "").replace(/\/$/, ""),
+        token: env2.VO_CONTROL_PLANE_ADMIN_TOKEN || "",
+        operatorSeed: cfg.operatorSeed
+      }).catch(() => {
+      });
+    }
+    if (now - lastHeartbeat >= HEARTBEAT_MS) {
+      lastHeartbeat = now;
+      client.postHeartbeat({ runnerId: cfg.runnerId, uptimeSec: Math.floor(process.uptime()), activeTasks: getActive() }).catch((e) => log2(`heartbeat failed: ${e.message}`));
+    }
+  };
+}
+
 // ../../scripts/virtual-office/code-runner/pr-watcher.mjs
 import { homedir as homedir4 } from "node:os";
 import { join as join4 } from "node:path";
 import { readFile as readFile2, writeFile as writeFile2, mkdir } from "node:fs/promises";
-import { spawnSync as spawnSync4 } from "node:child_process";
+import { spawnSync as spawnSync6 } from "node:child_process";
 var CI_FIX_MARKER = "[VO-CI-FIX]";
 function ghViewPr(prNumber, repo) {
-  const r = spawnSync4(
+  const r = spawnSync6(
     "gh",
     ["pr", "view", String(prNumber), "-R", repo, "--json", "state,statusCheckRollup,headRefName"],
     { encoding: "utf8", timeout: 3e4 }
@@ -1628,7 +2150,8 @@ var parseList = (s) => String(s || "").split(/[\s,]+/).map((x) => x.trim()).filt
 function loadConfig(env2 = process.env) {
   return {
     runnerId: env2.VO_CODE_RUNNER_ID || `vo-code-runner-${os.hostname()}`,
-    claudeBin: env2.VO_CODE_RUNNER_CLAUDE_BIN || "claude",
+    // BYO multi-agent: {agent, runner, runnerBin} — VO_CODE_RUNNER_AGENT (claude|codex).
+    ...resolveRunner(env2, { warn: (m) => log(`agent-select: ${m}`) }),
     permissionMode: env2.VO_CODE_RUNNER_PERMISSION_MODE || "acceptEdits",
     maxConcurrency: Math.max(1, Number(env2.VO_CODE_TASK_MAX_CONCURRENCY || 2) || 2),
     pollSec: Math.max(1, Number(env2.VO_CODE_RUNNER_POLL_SEC || 5) || 5),
@@ -1699,15 +2222,16 @@ async function processOneTask(client, task, cfg) {
   const id = task.code_task_id;
   let worktreeName = "";
   try {
-    const wt = createFixWorktree("code-task", { source: id.slice(0, 8) });
+    const wt = createFixWorktree("code-task", { source: id.slice(0, 8), repo: task.repo });
     worktreeName = wt.worktreeName;
     const { dispatchMode, tier, model, permissionMode: effectivePermissionMode, maxTurns: effectiveMaxTurns, prompt: effortPrompt } = await resolveEffortDispatch({ client, task, env: process.env, basePrompt: composeDispatchPrompt(task.prompt, { repo: task.repo }) });
-    await safeProgress(client, id, { message: `${cfg.runnerId} spawning ${model} (${tier}, effort ${dispatchMode})` });
+    await safeProgress(client, id, { message: `${cfg.runnerId} spawning ${cfg.agent}:${model} (${tier}, effort ${dispatchMode})` });
     const cap = typeof task.max_budget_usd === "number" ? task.max_budget_usd : resolveSpendCapUsd();
-    const run2 = await runClaudeTask({
+    const run2 = await runAgentTask({
+      runner: cfg.runner,
+      bin: cfg.runnerBin,
       prompt: effortPrompt,
       cwd: wt.worktreeDir,
-      claudeBin: cfg.claudeBin,
       permissionMode: effectivePermissionMode,
       maxTurns: effectiveMaxTurns,
       model,
@@ -1779,10 +2303,12 @@ async function processOneTask(client, task, cfg) {
       return;
     }
     await safeProgress(client, id, { message: `opening PR for ${files.length} changed file(s)` });
+    const githubToken = (await client.getInstallationToken())?.token ?? null;
     const pr = openCodeTaskPr(wt.worktreeDir, files, {
       title: `code-task: ${task.prompt}`,
       body: buildPrBody(task, run2, files),
-      alreadyCommitted
+      alreadyCommitted,
+      githubToken
     });
     await safeProgress(client, id, {
       status: "pr_opened",
@@ -1836,25 +2362,17 @@ async function main({ env: env2 = process.env, once: once2 = false } = {}) {
     log
   });
   log(
-    `up as ${cfg.runnerId} \u2192 ${env2.VO_CONTROL_PLANE_URL} (concurrency ${cfg.maxConcurrency}, poll ${cfg.pollSec}s, once=${once2})`
+    `up as ${cfg.runnerId} \u2192 ${env2.VO_CONTROL_PLANE_URL} (agent ${cfg.agent} [${cfg.runnerBin}], concurrency ${cfg.maxConcurrency}, poll ${cfg.pollSec}s, once=${once2})`
   );
   for (const line of describeClaimScoping(cfg, env2)) log(line);
   log(
     cfg.watchEnabled ? `PR watcher ON \u2014 auto-fix ${cfg.watchMaxFix}/PR on CI failure, never auto-merges, every ${cfg.watchIntervalSec}s (VO_CODE_RUNNER_WATCH=0 to disable)` : "PR watcher OFF (VO_CODE_RUNNER_WATCH=0)"
   );
-  let lastSessionForward = 0;
   let lastWatchCycle = 0;
   const runWatch = makeWatchRunner({ client, log, maxFixAttempts: cfg.watchMaxFix });
+  const loopTick = makeLoopTicks({ client, cfg, env: env2, log, getActive: () => active });
   while (!stopping) {
-    if (cfg.sessionForwardSec > 0 && Date.now() - lastSessionForward >= cfg.sessionForwardSec * 1e3) {
-      lastSessionForward = Date.now();
-      forwardSessionSpool({
-        baseUrl: String(env2.VO_CONTROL_PLANE_URL || "").replace(/\/$/, ""),
-        token: env2.VO_CONTROL_PLANE_ADMIN_TOKEN || "",
-        operatorSeed: cfg.operatorSeed
-      }).catch(() => {
-      });
-    }
+    loopTick();
     if (cfg.watchEnabled && Date.now() - lastWatchCycle >= cfg.watchIntervalSec * 1e3) {
       lastWatchCycle = Date.now();
       runWatch().then((r) => {