agent-board-runner 0.1.13 → 0.1.15

package/dist/cli.js

@@ -7,13 +7,14 @@ import { resolve as resolve4 } from "node:path";
 
 // src/auth.ts
 import { createClient } from "@supabase/supabase-js";
+import { createPrivateKey, randomInt, sign } from "node:crypto";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { createServer } from "node:http";
 import { join as join2 } from "node:path";
 import open from "open";
 
 // src/config.ts
-import { randomUUID } from "node:crypto";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { hostname, homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -27,8 +28,21 @@ function saveConfig(config) {
   if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
   writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
 }
+function generateRecoveryKeypair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" }
+  });
+  return { recoveryPublicKey: publicKey, recoveryPrivateKey: privateKey };
+}
 function createRunnerIdentity() {
-  return { runnerId: randomUUID(), authToken: randomUUID() };
+  return { runnerId: randomUUID(), authToken: randomUUID(), ...generateRecoveryKeypair() };
+}
+function ensureRecoveryKeypair(config) {
+  if (config.recoveryPublicKey && config.recoveryPrivateKey) return config;
+  Object.assign(config, generateRecoveryKeypair());
+  saveConfig(config);
+  return config;
 }
 function applyAllowedRoot(config, explicitPath) {
   const raw = explicitPath ?? process.env.AGENT_BOARD_ALLOWED_ROOT;
@@ -162,6 +176,110 @@ async function logout() {
   await supabase.auth.signOut();
   if (existsSync2(SESSION_FILE)) rmSync(SESSION_FILE);
 }
+function resolveWebUrl() {
+  const url = process.env.AGENT_BOARD_WEB_URL;
+  if (!url) {
+    throw new Error(
+      "AGENT_BOARD_WEB_URL is not set \u2014 point it at the deployed agent-board web app (e.g. https://board.example.com) to use `request-approval` on a machine with no browser."
+    );
+  }
+  return url.replace(/\/+$/, "");
+}
+var CONFIRMATION_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+function generateConfirmationCode() {
+  let code = "";
+  for (let i = 0; i < 6; i += 1) {
+    code += CONFIRMATION_CODE_ALPHABET[randomInt(CONFIRMATION_CODE_ALPHABET.length)];
+  }
+  return code;
+}
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(data.error ?? `Request to ${url} failed with status ${response.status}`);
+  return data;
+}
+var POLL_INTERVAL_MS = 4e3;
+var POLL_TIMEOUT_MS = 15 * 60 * 1e3;
+async function requestApproval(options) {
+  const webUrl = resolveWebUrl();
+  const confirmationCode = generateConfirmationCode();
+  const { requestId } = await postJson(`${webUrl}/api/public/runner-approval/request`, {
+    runnerName: options.runnerName,
+    hostname: options.hostname,
+    confirmationCode,
+    expectedEmail: options.expectedEmail
+  });
+  console.log("");
+  console.log("Este runner precisa ser aprovado pela web antes de continuar.");
+  console.log(`  C\xF3digo de confirma\xE7\xE3o: ${confirmationCode}`);
+  console.log(`  Runner: ${options.runnerName} (${options.hostname})`);
+  console.log(`  Abra ${webUrl}/perfil, encontre este runner em "Runners pendentes de aprova\xE7\xE3o" e digite o c\xF3digo acima.`);
+  console.log("Aguardando aprova\xE7\xE3o...");
+  console.log("");
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  let approved = false;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    const statusUrl = `${webUrl}/api/public/runner-approval/status?requestId=${encodeURIComponent(requestId)}`;
+    const statusResponse = await fetch(statusUrl);
+    const { status } = await statusResponse.json();
+    if (status === "approved") {
+      approved = true;
+      break;
+    }
+    if (status === "expired" || !statusResponse.ok) {
+      throw new Error("A solicita\xE7\xE3o de aprova\xE7\xE3o expirou antes de ser aprovada. Rode `request-approval` de novo.");
+    }
+  }
+  if (!approved) {
+    throw new Error("Tempo esgotado esperando aprova\xE7\xE3o. Rode `request-approval` de novo.");
+  }
+  const { accessToken, refreshToken, email } = await postJson(
+    `${webUrl}/api/public/runner-approval/claim`,
+    { requestId, confirmationCode }
+  );
+  const supabase = createAuthedSupabaseClient();
+  const { error } = await supabase.auth.setSession({ access_token: accessToken, refresh_token: refreshToken });
+  if (error) throw error;
+  return { email };
+}
+async function recoverSession(config) {
+  const webUrl = resolveWebUrl();
+  let nonce;
+  try {
+    ({ nonce } = await postJson(`${webUrl}/api/public/runner-recovery/challenge`, {
+      runnerId: config.runnerId
+    }));
+  } catch (error2) {
+    throw new Error(
+      `Recupera\xE7\xE3o autom\xE1tica indispon\xEDvel para este runner (${error2 instanceof Error ? error2.message : error2}). Rode "agent-board-runner request-approval --email <seu-email>" para configur\xE1-lo (uma \xFAnica vez).`
+    );
+  }
+  const signature = sign(null, Buffer.from(nonce, "utf8"), createPrivateKey(config.recoveryPrivateKey)).toString("base64");
+  const { accessToken, refreshToken, email } = await postJson(
+    `${webUrl}/api/public/runner-recovery/verify`,
+    { runnerId: config.runnerId, signature }
+  );
+  const supabase = createAuthedSupabaseClient();
+  const { error } = await supabase.auth.setSession({ access_token: accessToken, refresh_token: refreshToken });
+  if (error) throw error;
+  console.log(`Sess\xE3o recuperada automaticamente (${email}) \u2014 sem interven\xE7\xE3o manual.`);
+  return { email };
+}
+async function ensureSession(config) {
+  const probe = createAuthedSupabaseClient();
+  const existing = await getSession(probe);
+  if (existing) return { client: probe, session: existing };
+  await recoverSession(config);
+  const client = createAuthedSupabaseClient();
+  const session = await requireSession(client);
+  return { client, session };
+}
 
 // ../../packages/shared-types/dist/index.js
 var BOARD_COLUMNS = [
@@ -834,11 +952,26 @@ async function updateSession(supabase, sessionId, changes, activityContext) {
   }
 }
 async function getActiveSessionForCard(supabase, cardId) {
-  const { data, error } = await supabase.from("sessions").select("id, status, agent_state").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
+  const { data, error } = await supabase.from("sessions").select("id, status, agent_state, runner_id").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
   if (!data) return null;
   const row = data;
-  return { id: row.id, status: row.status, agentState: row.agent_state };
+  return { id: row.id, status: row.status, agentState: row.agent_state, runnerId: row.runner_id };
+}
+var STALE_RUNNER_HEARTBEAT_MS = 8 * 6e4;
+async function getRunnerHeartbeats(supabase, runnerIds) {
+  const uniqueIds = Array.from(new Set(runnerIds));
+  if (uniqueIds.length === 0) return /* @__PURE__ */ new Map();
+  const { data, error } = await supabase.from("runners").select("id, last_heartbeat_at").in("id", uniqueIds);
+  if (error) throw error;
+  return new Map(data.map((row) => [row.id, row.last_heartbeat_at]));
+}
+function isRunnerHeartbeatStale(lastHeartbeatAt) {
+  return lastHeartbeatAt === null || Date.now() - new Date(lastHeartbeatAt).getTime() > STALE_RUNNER_HEARTBEAT_MS;
+}
+async function claimReferenceRunner(supabase, projectId, runnerId) {
+  const { error } = await supabase.from("projects").update({ runner_id: runnerId }).eq("id", projectId);
+  if (error) throw error;
 }
 async function pauseRunningSession(supabase, sessionId, activityContext) {
   const { data, error } = await supabase.from("sessions").update({ status: "paused" }).eq("id", sessionId).eq("status", "running").select("id");
@@ -1487,7 +1620,7 @@ function ensureMcpServersTrusted(dirPath) {
 var SESSION_ID = "usage-monitor";
 var TICKET = randomUUID4();
 var SCRATCH_DIR = join8(tmpdir5(), "agent-board-usage-monitor");
-var POLL_INTERVAL_MS = Number(process.env.AGENT_BOARD_USAGE_POLL_INTERVAL_MS ?? 15 * 6e4);
+var POLL_INTERVAL_MS2 = Number(process.env.AGENT_BOARD_USAGE_POLL_INTERVAL_MS ?? 15 * 6e4);
 var IDLE_MS = 2e3;
 var HARD_TIMEOUT_MS = 6e4;
 function usageMonitorSessionId() {
@@ -1544,7 +1677,7 @@ function startUsageMonitor() {
   mkdirSync3(SCRATCH_DIR, { recursive: true });
   ensureDirTrusted(SCRATCH_DIR);
   pollUsageOnce();
-  setInterval(pollUsageOnce, POLL_INTERVAL_MS);
+  setInterval(pollUsageOnce, POLL_INTERVAL_MS2);
 }
 
 // src/filesServer.ts
@@ -2394,7 +2527,7 @@ async function ensureBranchWatchers(supabase, config) {
 // src/columnActions.ts
 import { exec } from "node:child_process";
 import { join as join12 } from "node:path";
-import { promisify as promisify4 } from "node:util";
+import { promisify as promisify5 } from "node:util";
 
 // src/orchestrator.ts
 import { randomUUID as randomUUID7 } from "node:crypto";
@@ -2600,10 +2733,164 @@ ${list}`;
 }
 
 // src/mcpContextNote.ts
-function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
-  return `${instructions}
+function buildInstructionsWithMcpContext(instructions, cardId, projectId, approvedCommands) {
+  const base = `${instructions}
 
 Agent Board MCP: this card's id is \`${cardId}\` and its project id is \`${projectId}\` \u2014 pass these directly to board tools (\`update_card\`, \`create_card\`, \`add_card_comment\`, etc.), no lookup needed. If this task turns out too large for one session, use \`create_card\` to split it into subtask cards (chain them with \`prerequisiteCardId\` when one depends on another) instead of trying to fit everything here. If part of the delivery needs a human to do something you can't do yourself (rotate a secret, approve something in a third-party dashboard, delete a resource manually, etc.), register each step with \`add_manual_actions\` instead of just mentioning it in your final message \u2014 that's the only place humans will reliably see it. Before finishing, post a short summary of what you did as a comment on this card via \`add_card_comment\` so the project's humans have visibility without opening this terminal.`;
+  if (approvedCommands.length === 0) return base;
+  const names = approvedCommands.map((command2) => command2.description ? `${command2.name} (${command2.description})` : command2.name).join(", ");
+  return `${base}
+
+This project already has approved custom command templates you can invoke instead of running the equivalent shell command yourself or proposing a near-duplicate: ${names}. Call \`list_project_commands\` first to see each one's declared arguments, then \`run_project_command\` to invoke it.`;
+}
+
+// src/projectCommands.ts
+import { execFile as execFile4 } from "node:child_process";
+import { promisify as promisify4 } from "node:util";
+
+// src/runnerRpcServer.ts
+import { parse as parse3 } from "node:url";
+import { WebSocketServer as WebSocketServer2 } from "ws";
+var handlers = /* @__PURE__ */ new Map();
+function registerRunnerRpcHandler(method, handler) {
+  handlers.set(method, handler);
+}
+function isRpcRequestMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.type === "request" && typeof candidate.id === "string" && typeof candidate.method === "string";
+}
+async function handleRequest2(socket, message) {
+  const handler = handlers.get(message.method);
+  let response;
+  if (!handler) {
+    response = { type: "response", id: message.id, ok: false, error: `Unknown runner RPC method: ${message.method}` };
+  } else {
+    try {
+      const result = await handler(message.payload);
+      response = { type: "response", id: message.id, ok: true, result };
+    } catch (err) {
+      response = { type: "response", id: message.id, ok: false, error: err instanceof Error ? err.message : "Internal runner error." };
+    }
+  }
+  if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(response));
+}
+function attachRunnerRpcServer() {
+  const wss = new WebSocketServer2({ noServer: true });
+  wss.on("connection", (socket, request) => {
+    const { query } = parse3(request.url ?? "", true);
+    const entry = authenticateAgent(query);
+    if (!entry) {
+      logger.runner.warn("RUNNER-RPC", "Runner RPC WS rejected: invalid or expired agent ticket.");
+      socket.close(4401, "Invalid or expired ticket");
+      return;
+    }
+    socket.on("message", (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!isRpcRequestMessage(parsed)) return;
+      void handleRequest2(socket, parsed);
+    });
+  });
+  logger.runner.info("RUNNER-RPC", "Runner RPC WebSocket handler attached.");
+  return wss;
+}
+
+// src/vaultSecrets.ts
+async function resolveProjectSecretsEnv(supabase, projectId, repoId) {
+  try {
+    const { data, error } = await supabase.rpc("resolve_project_secrets", { p_project_id: projectId, p_repo_id: repoId });
+    if (error) throw error;
+    const rows = data ?? [];
+    const env = {};
+    for (const row of rows) env[row.name] = row.value;
+    if (rows.length > 0) {
+      logger.runner.info(
+        "VAULT",
+        `Resolved ${rows.length} secret(s) for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}: ${rows.map((r) => r.name).join(", ")}.`
+      );
+    }
+    return env;
+  } catch (err) {
+    logger.runner.error("VAULT", `Failed to resolve secrets for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}:`, err);
+    return {};
+  }
+}
+
+// src/projectCommands.ts
+function registerProjectCommandRpcHandler(supabase, config) {
+  registerRunnerRpcHandler("run_project_command", (payload) => runProjectCommand(supabase, config, payload));
+}
+async function listApprovedProjectCommands(supabase, projectId) {
+  try {
+    const { data, error } = await supabase.rpc("resolve_project_commands", { p_project_id: projectId, p_repo_id: null });
+    if (error) throw error;
+    return (data ?? []).map((row) => ({ name: row.name, description: row.description }));
+  } catch (err) {
+    logger.runner.warn("PROJECT_COMMAND", `Failed to resolve approved commands for project ${projectId}:`, err);
+    return [];
+  }
+}
+var execFileAsync4 = promisify4(execFile4);
+var OUTPUT_TAIL_CHARS = 2e4;
+var COMMAND_TIMEOUT_MS = 5 * 60 * 1e3;
+var MAX_BUFFER = 10 * 1024 * 1024;
+var SECRET_PLACEHOLDER_RE = /\{\{secret:([A-Z][A-Z0-9_]*)\}\}/g;
+function isRunProjectCommandPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.projectId === "string" && Array.isArray(candidate.argv) && candidate.argv.length > 0 && candidate.argv.every((entry) => typeof entry === "string");
+}
+function tail(text) {
+  return text.length > OUTPUT_TAIL_CHARS ? text.slice(text.length - OUTPUT_TAIL_CHARS) : text;
+}
+async function runProjectCommand(supabase, config, payload) {
+  if (!isRunProjectCommandPayload(payload)) throw new Error("Malformed run_project_command payload.");
+  const { projectId, argv } = payload;
+  const registered = config.registeredProjects.find((project) => project.id === projectId);
+  if (!registered) throw new Error("This runner does not have that project registered.");
+  const secretsEnv = await resolveProjectSecretsEnv(supabase, projectId, null);
+  const referencedSecretNames = /* @__PURE__ */ new Set();
+  const resolvedArgv = argv.map(
+    (part) => part.replace(SECRET_PLACEHOLDER_RE, (_match, name) => {
+      const value = secretsEnv[name];
+      if (value === void 0) throw new Error(`Secret "${name}" referenced by this command is no longer configured for this project.`);
+      referencedSecretNames.add(name);
+      return value;
+    })
+  );
+  function redact(text) {
+    let redacted = text;
+    for (const name of referencedSecretNames) {
+      const value = secretsEnv[name];
+      if (value) redacted = redacted.split(value).join("***");
+    }
+    return redacted;
+  }
+  try {
+    const { stdout, stderr } = await execFileAsync4(resolvedArgv[0], resolvedArgv.slice(1), {
+      cwd: registered.repoPath,
+      env: process.env,
+      timeout: COMMAND_TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER
+    });
+    logger.runner.info("PROJECT_COMMAND", `Ran "${argv[0]}" for project ${projectId} (exit 0).`);
+    return { ok: true, exitCode: 0, stdout: tail(redact(stdout)), stderr: tail(redact(stderr)) };
+  } catch (err) {
+    const failure = err;
+    const exitCode = typeof failure.code === "number" ? failure.code : null;
+    logger.runner.warn("PROJECT_COMMAND", `"${argv[0]}" failed for project ${projectId} (exit ${exitCode ?? "?"}).`);
+    return {
+      ok: false,
+      exitCode,
+      stdout: tail(redact(failure.stdout ?? "")),
+      stderr: tail(redact(failure.stderr ?? failure.message))
+    };
+  }
 }
 
 // src/prototypeGateNote.ts
@@ -2719,7 +3006,20 @@ async function enqueueCard(supabase, config, card) {
   inFlightCardIds.add(card.id);
   try {
     const active = await getActiveSessionForCard(supabase, card.id);
-    if (active) return;
+    if (active) {
+      if (active.runnerId !== config.runnerId) {
+        const holderHeartbeat = active.runnerId === null ? null : (await getRunnerHeartbeats(supabase, [active.runnerId])).get(active.runnerId) ?? null;
+        if (active.runnerId !== null && !isRunnerHeartbeatStale(holderHeartbeat)) return;
+        logger.card.warn(
+          card.id,
+          `Active session ${active.id} belongs to runner ${active.runnerId ?? "(none)"}, which looks offline \u2014 reclaiming for ${config.runnerId}.`
+        );
+        await updateSession(supabase, active.id, { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() });
+        activeSessionByCard.delete(card.id);
+      } else {
+        return;
+      }
+    }
     await createQueuedSession(supabase, config, card);
   } finally {
     inFlightCardIds.delete(card.id);
@@ -2891,6 +3191,7 @@ async function spawnSessionPty(supabase, config, entry) {
       });
     } else {
       const attachmentPaths = await downloadCardAttachments(supabase, cardId);
+      const approvedCommands = await listApprovedProjectCommands(supabase, card.project_id);
       const instructions = buildInstructionsWithMcpContext(
         buildInstructionsWithPrototypeGate(
           buildInstructionsWithFileReferences(
@@ -2900,7 +3201,8 @@ async function spawnSessionPty(supabase, config, entry) {
           card.prototype_first
         ),
         cardId,
-        card.project_id
+        card.project_id,
+        approvedCommands
       );
       const spawned = spawnAgentPty(registered.repoPath, cardId, card.title, instructions, sessionId, ticket, card.plan_first);
       pty = spawned.pty;
@@ -3099,32 +3401,11 @@ async function restartCardSession(supabase, config, card) {
   await enqueueCard(supabase, config, card);
 }
 
-// src/vaultSecrets.ts
-async function resolveProjectSecretsEnv(supabase, projectId, repoId) {
-  try {
-    const { data, error } = await supabase.rpc("resolve_project_secrets", { p_project_id: projectId, p_repo_id: repoId });
-    if (error) throw error;
-    const rows = data ?? [];
-    const env = {};
-    for (const row of rows) env[row.name] = row.value;
-    if (rows.length > 0) {
-      logger.runner.info(
-        "VAULT",
-        `Resolved ${rows.length} secret(s) for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}: ${rows.map((r) => r.name).join(", ")}.`
-      );
-    }
-    return env;
-  } catch (err) {
-    logger.runner.error("VAULT", `Failed to resolve secrets for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}:`, err);
-    return {};
-  }
-}
-
 // src/columnActions.ts
-var execAsync = promisify4(exec);
-var OUTPUT_TAIL_CHARS = 4e3;
-function tail(text) {
-  return text.length > OUTPUT_TAIL_CHARS ? text.slice(text.length - OUTPUT_TAIL_CHARS) : text;
+var execAsync = promisify5(exec);
+var OUTPUT_TAIL_CHARS2 = 4e3;
+function tail2(text) {
+  return text.length > OUTPUT_TAIL_CHARS2 ? text.slice(text.length - OUTPUT_TAIL_CHARS2) : text;
 }
 function resolveTargets(project, children, repoRoot, column, timing) {
   if (children.length > 0) {
@@ -3138,11 +3419,11 @@ var EXEC_OPTIONS = { maxBuffer: 10 * 1024 * 1024 };
 async function runCommand(target, extraEnv) {
   try {
     const { stdout, stderr } = await execAsync(target.command, { ...EXEC_OPTIONS, cwd: target.cwd, env: { ...process.env, ...extraEnv } });
-    return { ok: true, output: tail(`${stdout}${stderr}`) };
+    return { ok: true, output: tail2(`${stdout}${stderr}`) };
   } catch (err) {
     const { stdout, stderr } = err;
     const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, output: tail(`${stdout ?? ""}${stderr ?? ""}` || message) };
+    return { ok: false, output: tail2(`${stdout ?? ""}${stderr ?? ""}` || message) };
   }
 }
 var inFlightColumns = /* @__PURE__ */ new Set();
@@ -3473,12 +3754,12 @@ function stopAll() {
 }
 
 // src/git.ts
-import { execFile as execFile4 } from "node:child_process";
-import { promisify as promisify5 } from "node:util";
-var execFileAsync4 = promisify5(execFile4);
+import { execFile as execFile5 } from "node:child_process";
+import { promisify as promisify6 } from "node:util";
+var execFileAsync5 = promisify6(execFile5);
 async function pushBranchToMain(repoPath) {
   try {
-    await execFileAsync4("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
+    await execFileAsync5("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
     return { ok: true };
   } catch (err) {
     const stderr = err.stderr;
@@ -3590,10 +3871,24 @@ async function syncRegisteredProjects(supabase, config, registeredPaths) {
   const localById = new Map(config.registeredProjects.map((project) => [project.id, project]));
   const linkedRunnerIds = await listProjectRunnerIds(supabase, config.runnerId);
   let changed = false;
+  const otherReferenceRunnerIds = remoteProjects.filter((remote) => localById.has(remote.id) && remote.runner_id !== config.runnerId).map((remote) => remote.runner_id);
+  const referenceHeartbeats = await getRunnerHeartbeats(supabase, otherReferenceRunnerIds);
   for (const remote of remoteProjects) {
     const local = localById.get(remote.id);
     if (local) {
-      const isReferenceRunner = remote.runner_id === config.runnerId;
+      let isReferenceRunner = remote.runner_id === config.runnerId;
+      if (!isReferenceRunner && isRunnerHeartbeatStale(referenceHeartbeats.get(remote.runner_id) ?? null)) {
+        try {
+          await claimReferenceRunner(supabase, remote.id, config.runnerId);
+          isReferenceRunner = true;
+          logger.runner.info(
+            "PROJECT_SYNC",
+            `Claimed reference runner for project ${remote.id} \u2014 previous one (${remote.runner_id}) looks offline.`
+          );
+        } catch (err) {
+          logger.runner.error("PROJECT_SYNC", `Failed to claim reference runner for project ${remote.id}:`, err);
+        }
+      }
       if (local.isReferenceRunner !== isReferenceRunner) {
         local.isReferenceRunner = isReferenceRunner;
         changed = true;
@@ -3724,14 +4019,14 @@ async function checkPendingDevServerRestarts(supabase, config) {
 }
 
 // src/terminalServer.ts
-import { parse as parse3 } from "node:url";
-import { WebSocketServer as WebSocketServer2 } from "ws";
+import { parse as parse4 } from "node:url";
+import { WebSocketServer as WebSocketServer3 } from "ws";
 var FRAME_TYPE_RESIZE = 0;
 var FRAME_TYPE_IMAGE = 1;
 function attachTerminalServer() {
-  const wss = new WebSocketServer2({ noServer: true });
+  const wss = new WebSocketServer3({ noServer: true });
   wss.on("connection", (socket, request) => {
-    const { query } = parse3(request.url ?? "", true);
+    const { query } = parse4(request.url ?? "", true);
     const sessionId = typeof query.sessionId === "string" ? query.sessionId : null;
     const ticket = typeof query.ticket === "string" ? query.ticket : null;
     if (!sessionId || !ticket) {
@@ -3837,7 +4132,7 @@ async function startRunner() {
     logger.runner.error("BOOT", 'No runner set up yet. Run "agent-board-runner start --path <repos-root>" first.');
     process.exit(1);
   }
-  const config = applyRunnerName(applyAllowedRoot(loadedConfig));
+  const config = ensureRecoveryKeypair(applyRunnerName(applyAllowedRoot(loadedConfig)));
   if (!config.allowedRootPath) {
     logger.runner.error(
       "BOOT",
@@ -3845,10 +4140,9 @@ async function startRunner() {
     );
     process.exit(1);
   }
-  const supabase = createAuthedSupabaseClient();
-  let session;
+  let supabase, session;
   try {
-    session = await requireSession(supabase);
+    ({ client: supabase, session } = await ensureSession(config));
   } catch (error) {
     logger.runner.error("BOOT", error instanceof Error ? error.message : String(error));
     process.exit(1);
@@ -3860,7 +4154,7 @@ async function startRunner() {
     if (event === "SIGNED_OUT") {
       logger.runner.error(
         "AUTH",
-        'Supabase session was lost (refresh failed or was revoked) \u2014 every write from now on will fail row-level security checks. Run "agent-board-runner login" again and restart the runner.'
+        "Supabase session was lost (refresh failed or was revoked) \u2014 exiting so the process manager restarts this runner; the next boot recovers automatically."
       );
       process.exit(1);
     }
@@ -3885,6 +4179,10 @@ async function startRunner() {
     user_id: config.ownerUserId,
     name: config.runnerName,
     auth_token_hash: config.authToken,
+    // Re-sent on every boot with a real session — idempotent (same local key every time) and
+    // what makes automatic recovery possible the next time this runner loses its session, see
+    // ensureSession()/recoverSession() in auth.ts.
+    recovery_public_key: config.recoveryPublicKey,
     version: RUNNER_VERSION
   });
   if (runnerError) {
@@ -3909,6 +4207,8 @@ async function startRunner() {
   const httpServer = createServer2();
   const terminalWss = attachTerminalServer();
   const agentEventsWss = attachAgentEventsServer();
+  const runnerRpcWss = attachRunnerRpcServer();
+  registerProjectCommandRpcHandler(supabase, config);
   attachFilesServer(httpServer, supabase, config);
   httpServer.on("upgrade", (request, socket, head) => {
     const pathname = (request.url ?? "").split("?")[0];
@@ -3916,6 +4216,8 @@ async function startRunner() {
       terminalWss.handleUpgrade(request, socket, head, (ws) => terminalWss.emit("connection", ws, request));
     } else if (pathname === "/agent-events") {
       agentEventsWss.handleUpgrade(request, socket, head, (ws) => agentEventsWss.emit("connection", ws, request));
+    } else if (pathname === "/runner-rpc") {
+      runnerRpcWss.handleUpgrade(request, socket, head, (ws) => runnerRpcWss.emit("connection", ws, request));
     } else {
       socket.destroy();
     }
@@ -4064,7 +4366,7 @@ function parseArgs(argv) {
 }
 function bootstrapConfig() {
   const existing = loadConfig();
-  if (existing) return existing;
+  if (existing) return ensureRecoveryKeypair(existing);
   const identity = createRunnerIdentity();
   const config = {
     ...identity,
@@ -4081,6 +4383,22 @@ async function cmdLogin() {
   const { email } = await login();
   console.log(`Signed in as ${email}.`);
 }
+async function cmdRequestApproval(args2) {
+  if (!args2.email) {
+    console.error(
+      "Use: agent-board-runner request-approval --email <seu-email-no-agent-board> [--name <nome-do-runner>]\nSem --email, ningu\xE9m saberia de quem \xE9 esta solicita\xE7\xE3o na tela de aprova\xE7\xE3o."
+    );
+    process.exit(1);
+  }
+  const config = bootstrapConfig();
+  const { email } = await requestApproval({
+    runnerName: args2.name ?? config.runnerName,
+    hostname: hostname2(),
+    expectedEmail: args2.email
+  });
+  console.log(`Aprovado! Sess\xE3o criada para ${email}.`);
+  console.log("A partir de agora, se este runner perder a sess\xE3o, ele se recupera sozinho (sem precisar rodar isto de novo).");
+}
 async function cmdLogout() {
   await logout();
   console.log("Signed out.");
@@ -4111,6 +4429,9 @@ switch (command) {
   case "login":
     cmdLogin().catch(fail);
     break;
+  case "request-approval":
+    cmdRequestApproval(args).catch(fail);
+    break;
   case "logout":
     cmdLogout().catch(fail);
     break;
@@ -4121,8 +4442,11 @@ switch (command) {
     cmdStart(args).catch(fail);
     break;
   default:
-    console.log("Usage: agent-board-runner <login|logout|whoami|start>");
+    console.log("Usage: agent-board-runner <login|request-approval|logout|whoami|start>");
     console.log("  login                sign in with Google");
+    console.log("  request-approval --email <email> [--name <nome>]");
+    console.log("                       login sem navegador: aprove pela web (AGENT_BOARD_WEB_URL precisa estar configurada)");
+    console.log("                       s\xF3 precisa ser rodado uma vez \u2014 depois disso, `start` recupera a sess\xE3o sozinho se ela cair");
     console.log("  logout               sign out and clear the local session");
     console.log("  whoami               show the signed-in account");
     console.log("  start [--path <repos-root>]   run the runner (repos root can also come from AGENT_BOARD_ALLOWED_ROOT)");

package/dist/index.js

@@ -672,11 +672,26 @@ async function updateSession(supabase, sessionId, changes, activityContext) {
   }
 }
 async function getActiveSessionForCard(supabase, cardId) {
-  const { data, error } = await supabase.from("sessions").select("id, status, agent_state").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
+  const { data, error } = await supabase.from("sessions").select("id, status, agent_state, runner_id").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
   if (!data) return null;
   const row = data;
-  return { id: row.id, status: row.status, agentState: row.agent_state };
+  return { id: row.id, status: row.status, agentState: row.agent_state, runnerId: row.runner_id };
+}
+var STALE_RUNNER_HEARTBEAT_MS = 8 * 6e4;
+async function getRunnerHeartbeats(supabase, runnerIds) {
+  const uniqueIds = Array.from(new Set(runnerIds));
+  if (uniqueIds.length === 0) return /* @__PURE__ */ new Map();
+  const { data, error } = await supabase.from("runners").select("id, last_heartbeat_at").in("id", uniqueIds);
+  if (error) throw error;
+  return new Map(data.map((row) => [row.id, row.last_heartbeat_at]));
+}
+function isRunnerHeartbeatStale(lastHeartbeatAt) {
+  return lastHeartbeatAt === null || Date.now() - new Date(lastHeartbeatAt).getTime() > STALE_RUNNER_HEARTBEAT_MS;
+}
+async function claimReferenceRunner(supabase, projectId, runnerId) {
+  const { error } = await supabase.from("projects").update({ runner_id: runnerId }).eq("id", projectId);
+  if (error) throw error;
 }
 async function pauseRunningSession(supabase, sessionId, activityContext) {
   const { data, error } = await supabase.from("sessions").update({ status: "paused" }).eq("id", sessionId).eq("status", "running").select("id");
@@ -2165,11 +2180,13 @@ function attachAgentEventsServer() {
 
 // src/auth.ts
 import { createClient } from "@supabase/supabase-js";
+import { createPrivateKey, randomInt, sign } from "node:crypto";
 import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync4, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join9 } from "node:path";
 import open from "open";
 
 // src/config.ts
+import { generateKeyPairSync, randomUUID as randomUUID5 } from "node:crypto";
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync6 } from "node:fs";
 import { hostname, homedir as homedir4 } from "node:os";
 import { join as join8, resolve as resolve2 } from "node:path";
@@ -2183,6 +2200,19 @@ function saveConfig(config) {
   if (!existsSync3(CONFIG_DIR)) mkdirSync3(CONFIG_DIR, { recursive: true });
   writeFileSync6(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
 }
+function generateRecoveryKeypair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" }
+  });
+  return { recoveryPublicKey: publicKey, recoveryPrivateKey: privateKey };
+}
+function ensureRecoveryKeypair(config) {
+  if (config.recoveryPublicKey && config.recoveryPrivateKey) return config;
+  Object.assign(config, generateRecoveryKeypair());
+  saveConfig(config);
+  return config;
+}
 function applyAllowedRoot(config, explicitPath) {
   const raw = explicitPath ?? process.env.AGENT_BOARD_ALLOWED_ROOT;
   if (!raw) return config;
@@ -2263,6 +2293,58 @@ async function requireSession(supabase) {
   }
   return session;
 }
+function resolveWebUrl() {
+  const url = process.env.AGENT_BOARD_WEB_URL;
+  if (!url) {
+    throw new Error(
+      "AGENT_BOARD_WEB_URL is not set \u2014 point it at the deployed agent-board web app (e.g. https://board.example.com) to use `request-approval` on a machine with no browser."
+    );
+  }
+  return url.replace(/\/+$/, "");
+}
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const data = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(data.error ?? `Request to ${url} failed with status ${response.status}`);
+  return data;
+}
+var POLL_TIMEOUT_MS = 15 * 60 * 1e3;
+async function recoverSession(config) {
+  const webUrl = resolveWebUrl();
+  let nonce;
+  try {
+    ({ nonce } = await postJson(`${webUrl}/api/public/runner-recovery/challenge`, {
+      runnerId: config.runnerId
+    }));
+  } catch (error2) {
+    throw new Error(
+      `Recupera\xE7\xE3o autom\xE1tica indispon\xEDvel para este runner (${error2 instanceof Error ? error2.message : error2}). Rode "agent-board-runner request-approval --email <seu-email>" para configur\xE1-lo (uma \xFAnica vez).`
+    );
+  }
+  const signature = sign(null, Buffer.from(nonce, "utf8"), createPrivateKey(config.recoveryPrivateKey)).toString("base64");
+  const { accessToken, refreshToken, email } = await postJson(
+    `${webUrl}/api/public/runner-recovery/verify`,
+    { runnerId: config.runnerId, signature }
+  );
+  const supabase = createAuthedSupabaseClient();
+  const { error } = await supabase.auth.setSession({ access_token: accessToken, refresh_token: refreshToken });
+  if (error) throw error;
+  console.log(`Sess\xE3o recuperada automaticamente (${email}) \u2014 sem interven\xE7\xE3o manual.`);
+  return { email };
+}
+async function ensureSession(config) {
+  const probe = createAuthedSupabaseClient();
+  const existing = await getSession(probe);
+  if (existing) return { client: probe, session: existing };
+  await recoverSession(config);
+  const client = createAuthedSupabaseClient();
+  const session = await requireSession(client);
+  return { client, session };
+}
 
 // src/branchWatcher.ts
 import { execFile as execFile3 } from "node:child_process";
@@ -2333,13 +2415,13 @@ async function ensureBranchWatchers(supabase, config) {
 // src/columnActions.ts
 import { exec } from "node:child_process";
 import { join as join12 } from "node:path";
-import { promisify as promisify4 } from "node:util";
+import { promisify as promisify5 } from "node:util";
 
 // src/orchestrator.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomUUID as randomUUID7 } from "node:crypto";
 
 // src/agentSession.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
+import { randomUUID as randomUUID6 } from "node:crypto";
 import { spawn as spawn3 } from "node-pty";
 
 // src/sessionName.ts
@@ -2367,7 +2449,7 @@ var PLAN_MODE_INDICATOR = /plan mode on/i;
 function spawnAgentPty(repoPath, cardId, cardTitle, instructions, sessionId, ticket, planFirst) {
   ensureDirTrusted(repoPath);
   ensureMcpServersTrusted(repoPath);
-  const claudeSessionId = randomUUID5();
+  const claudeSessionId = randomUUID6();
   const pty = spawn3(
     CLAUDE_BINARY,
     [
@@ -2539,10 +2621,164 @@ ${list}`;
 }
 
 // src/mcpContextNote.ts
-function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
-  return `${instructions}
+function buildInstructionsWithMcpContext(instructions, cardId, projectId, approvedCommands) {
+  const base = `${instructions}
 
 Agent Board MCP: this card's id is \`${cardId}\` and its project id is \`${projectId}\` \u2014 pass these directly to board tools (\`update_card\`, \`create_card\`, \`add_card_comment\`, etc.), no lookup needed. If this task turns out too large for one session, use \`create_card\` to split it into subtask cards (chain them with \`prerequisiteCardId\` when one depends on another) instead of trying to fit everything here. If part of the delivery needs a human to do something you can't do yourself (rotate a secret, approve something in a third-party dashboard, delete a resource manually, etc.), register each step with \`add_manual_actions\` instead of just mentioning it in your final message \u2014 that's the only place humans will reliably see it. Before finishing, post a short summary of what you did as a comment on this card via \`add_card_comment\` so the project's humans have visibility without opening this terminal.`;
+  if (approvedCommands.length === 0) return base;
+  const names = approvedCommands.map((command) => command.description ? `${command.name} (${command.description})` : command.name).join(", ");
+  return `${base}
+
+This project already has approved custom command templates you can invoke instead of running the equivalent shell command yourself or proposing a near-duplicate: ${names}. Call \`list_project_commands\` first to see each one's declared arguments, then \`run_project_command\` to invoke it.`;
+}
+
+// src/projectCommands.ts
+import { execFile as execFile4 } from "node:child_process";
+import { promisify as promisify4 } from "node:util";
+
+// src/runnerRpcServer.ts
+import { parse as parse3 } from "node:url";
+import { WebSocketServer as WebSocketServer2 } from "ws";
+var handlers = /* @__PURE__ */ new Map();
+function registerRunnerRpcHandler(method, handler) {
+  handlers.set(method, handler);
+}
+function isRpcRequestMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.type === "request" && typeof candidate.id === "string" && typeof candidate.method === "string";
+}
+async function handleRequest2(socket, message) {
+  const handler = handlers.get(message.method);
+  let response;
+  if (!handler) {
+    response = { type: "response", id: message.id, ok: false, error: `Unknown runner RPC method: ${message.method}` };
+  } else {
+    try {
+      const result = await handler(message.payload);
+      response = { type: "response", id: message.id, ok: true, result };
+    } catch (err) {
+      response = { type: "response", id: message.id, ok: false, error: err instanceof Error ? err.message : "Internal runner error." };
+    }
+  }
+  if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(response));
+}
+function attachRunnerRpcServer() {
+  const wss = new WebSocketServer2({ noServer: true });
+  wss.on("connection", (socket, request) => {
+    const { query } = parse3(request.url ?? "", true);
+    const entry = authenticateAgent(query);
+    if (!entry) {
+      logger.runner.warn("RUNNER-RPC", "Runner RPC WS rejected: invalid or expired agent ticket.");
+      socket.close(4401, "Invalid or expired ticket");
+      return;
+    }
+    socket.on("message", (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!isRpcRequestMessage(parsed)) return;
+      void handleRequest2(socket, parsed);
+    });
+  });
+  logger.runner.info("RUNNER-RPC", "Runner RPC WebSocket handler attached.");
+  return wss;
+}
+
+// src/vaultSecrets.ts
+async function resolveProjectSecretsEnv(supabase, projectId, repoId) {
+  try {
+    const { data, error } = await supabase.rpc("resolve_project_secrets", { p_project_id: projectId, p_repo_id: repoId });
+    if (error) throw error;
+    const rows = data ?? [];
+    const env = {};
+    for (const row of rows) env[row.name] = row.value;
+    if (rows.length > 0) {
+      logger.runner.info(
+        "VAULT",
+        `Resolved ${rows.length} secret(s) for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}: ${rows.map((r) => r.name).join(", ")}.`
+      );
+    }
+    return env;
+  } catch (err) {
+    logger.runner.error("VAULT", `Failed to resolve secrets for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}:`, err);
+    return {};
+  }
+}
+
+// src/projectCommands.ts
+function registerProjectCommandRpcHandler(supabase, config) {
+  registerRunnerRpcHandler("run_project_command", (payload) => runProjectCommand(supabase, config, payload));
+}
+async function listApprovedProjectCommands(supabase, projectId) {
+  try {
+    const { data, error } = await supabase.rpc("resolve_project_commands", { p_project_id: projectId, p_repo_id: null });
+    if (error) throw error;
+    return (data ?? []).map((row) => ({ name: row.name, description: row.description }));
+  } catch (err) {
+    logger.runner.warn("PROJECT_COMMAND", `Failed to resolve approved commands for project ${projectId}:`, err);
+    return [];
+  }
+}
+var execFileAsync4 = promisify4(execFile4);
+var OUTPUT_TAIL_CHARS = 2e4;
+var COMMAND_TIMEOUT_MS = 5 * 60 * 1e3;
+var MAX_BUFFER = 10 * 1024 * 1024;
+var SECRET_PLACEHOLDER_RE = /\{\{secret:([A-Z][A-Z0-9_]*)\}\}/g;
+function isRunProjectCommandPayload(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.projectId === "string" && Array.isArray(candidate.argv) && candidate.argv.length > 0 && candidate.argv.every((entry) => typeof entry === "string");
+}
+function tail(text) {
+  return text.length > OUTPUT_TAIL_CHARS ? text.slice(text.length - OUTPUT_TAIL_CHARS) : text;
+}
+async function runProjectCommand(supabase, config, payload) {
+  if (!isRunProjectCommandPayload(payload)) throw new Error("Malformed run_project_command payload.");
+  const { projectId, argv } = payload;
+  const registered = config.registeredProjects.find((project) => project.id === projectId);
+  if (!registered) throw new Error("This runner does not have that project registered.");
+  const secretsEnv = await resolveProjectSecretsEnv(supabase, projectId, null);
+  const referencedSecretNames = /* @__PURE__ */ new Set();
+  const resolvedArgv = argv.map(
+    (part) => part.replace(SECRET_PLACEHOLDER_RE, (_match, name) => {
+      const value = secretsEnv[name];
+      if (value === void 0) throw new Error(`Secret "${name}" referenced by this command is no longer configured for this project.`);
+      referencedSecretNames.add(name);
+      return value;
+    })
+  );
+  function redact(text) {
+    let redacted = text;
+    for (const name of referencedSecretNames) {
+      const value = secretsEnv[name];
+      if (value) redacted = redacted.split(value).join("***");
+    }
+    return redacted;
+  }
+  try {
+    const { stdout, stderr } = await execFileAsync4(resolvedArgv[0], resolvedArgv.slice(1), {
+      cwd: registered.repoPath,
+      env: process.env,
+      timeout: COMMAND_TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER
+    });
+    logger.runner.info("PROJECT_COMMAND", `Ran "${argv[0]}" for project ${projectId} (exit 0).`);
+    return { ok: true, exitCode: 0, stdout: tail(redact(stdout)), stderr: tail(redact(stderr)) };
+  } catch (err) {
+    const failure = err;
+    const exitCode = typeof failure.code === "number" ? failure.code : null;
+    logger.runner.warn("PROJECT_COMMAND", `"${argv[0]}" failed for project ${projectId} (exit ${exitCode ?? "?"}).`);
+    return {
+      ok: false,
+      exitCode,
+      stdout: tail(redact(failure.stdout ?? "")),
+      stderr: tail(redact(failure.stderr ?? failure.message))
+    };
+  }
 }
 
 // src/prototypeGateNote.ts
@@ -2658,7 +2894,20 @@ async function enqueueCard(supabase, config, card) {
   inFlightCardIds.add(card.id);
   try {
     const active = await getActiveSessionForCard(supabase, card.id);
-    if (active) return;
+    if (active) {
+      if (active.runnerId !== config.runnerId) {
+        const holderHeartbeat = active.runnerId === null ? null : (await getRunnerHeartbeats(supabase, [active.runnerId])).get(active.runnerId) ?? null;
+        if (active.runnerId !== null && !isRunnerHeartbeatStale(holderHeartbeat)) return;
+        logger.card.warn(
+          card.id,
+          `Active session ${active.id} belongs to runner ${active.runnerId ?? "(none)"}, which looks offline \u2014 reclaiming for ${config.runnerId}.`
+        );
+        await updateSession(supabase, active.id, { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() });
+        activeSessionByCard.delete(card.id);
+      } else {
+        return;
+      }
+    }
     await createQueuedSession(supabase, config, card);
   } finally {
     inFlightCardIds.delete(card.id);
@@ -2818,7 +3067,7 @@ async function spawnSessionPty(supabase, config, entry) {
     );
     return false;
   }
-  const ticket = randomUUID6();
+  const ticket = randomUUID7();
   let pty;
   let newClaudeSessionId = null;
   let resumeConversationMissing = false;
@@ -2830,6 +3079,7 @@ async function spawnSessionPty(supabase, config, entry) {
       });
     } else {
       const attachmentPaths = await downloadCardAttachments(supabase, cardId);
+      const approvedCommands = await listApprovedProjectCommands(supabase, card.project_id);
       const instructions = buildInstructionsWithMcpContext(
         buildInstructionsWithPrototypeGate(
           buildInstructionsWithFileReferences(
@@ -2839,7 +3089,8 @@ async function spawnSessionPty(supabase, config, entry) {
           card.prototype_first
         ),
         cardId,
-        card.project_id
+        card.project_id,
+        approvedCommands
       );
       const spawned = spawnAgentPty(registered.repoPath, cardId, card.title, instructions, sessionId, ticket, card.plan_first);
       pty = spawned.pty;
@@ -3038,32 +3289,11 @@ async function restartCardSession(supabase, config, card) {
   await enqueueCard(supabase, config, card);
 }
 
-// src/vaultSecrets.ts
-async function resolveProjectSecretsEnv(supabase, projectId, repoId) {
-  try {
-    const { data, error } = await supabase.rpc("resolve_project_secrets", { p_project_id: projectId, p_repo_id: repoId });
-    if (error) throw error;
-    const rows = data ?? [];
-    const env = {};
-    for (const row of rows) env[row.name] = row.value;
-    if (rows.length > 0) {
-      logger.runner.info(
-        "VAULT",
-        `Resolved ${rows.length} secret(s) for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}: ${rows.map((r) => r.name).join(", ")}.`
-      );
-    }
-    return env;
-  } catch (err) {
-    logger.runner.error("VAULT", `Failed to resolve secrets for project ${projectId}${repoId ? ` (repo ${repoId})` : ""}:`, err);
-    return {};
-  }
-}
-
 // src/columnActions.ts
-var execAsync = promisify4(exec);
-var OUTPUT_TAIL_CHARS = 4e3;
-function tail(text) {
-  return text.length > OUTPUT_TAIL_CHARS ? text.slice(text.length - OUTPUT_TAIL_CHARS) : text;
+var execAsync = promisify5(exec);
+var OUTPUT_TAIL_CHARS2 = 4e3;
+function tail2(text) {
+  return text.length > OUTPUT_TAIL_CHARS2 ? text.slice(text.length - OUTPUT_TAIL_CHARS2) : text;
 }
 function resolveTargets(project, children, repoRoot, column, timing) {
   if (children.length > 0) {
@@ -3077,11 +3307,11 @@ var EXEC_OPTIONS = { maxBuffer: 10 * 1024 * 1024 };
 async function runCommand(target, extraEnv) {
   try {
     const { stdout, stderr } = await execAsync(target.command, { ...EXEC_OPTIONS, cwd: target.cwd, env: { ...process.env, ...extraEnv } });
-    return { ok: true, output: tail(`${stdout}${stderr}`) };
+    return { ok: true, output: tail2(`${stdout}${stderr}`) };
   } catch (err) {
     const { stdout, stderr } = err;
     const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, output: tail(`${stdout ?? ""}${stderr ?? ""}` || message) };
+    return { ok: false, output: tail2(`${stdout ?? ""}${stderr ?? ""}` || message) };
   }
 }
 var inFlightColumns = /* @__PURE__ */ new Set();
@@ -3412,12 +3642,12 @@ function stopAll() {
 }
 
 // src/git.ts
-import { execFile as execFile4 } from "node:child_process";
-import { promisify as promisify5 } from "node:util";
-var execFileAsync4 = promisify5(execFile4);
+import { execFile as execFile5 } from "node:child_process";
+import { promisify as promisify6 } from "node:util";
+var execFileAsync5 = promisify6(execFile5);
 async function pushBranchToMain(repoPath) {
   try {
-    await execFileAsync4("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
+    await execFileAsync5("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
     return { ok: true };
   } catch (err) {
     const stderr = err.stderr;
@@ -3529,10 +3759,24 @@ async function syncRegisteredProjects(supabase, config, registeredPaths) {
   const localById = new Map(config.registeredProjects.map((project) => [project.id, project]));
   const linkedRunnerIds = await listProjectRunnerIds(supabase, config.runnerId);
   let changed = false;
+  const otherReferenceRunnerIds = remoteProjects.filter((remote) => localById.has(remote.id) && remote.runner_id !== config.runnerId).map((remote) => remote.runner_id);
+  const referenceHeartbeats = await getRunnerHeartbeats(supabase, otherReferenceRunnerIds);
   for (const remote of remoteProjects) {
     const local = localById.get(remote.id);
     if (local) {
-      const isReferenceRunner = remote.runner_id === config.runnerId;
+      let isReferenceRunner = remote.runner_id === config.runnerId;
+      if (!isReferenceRunner && isRunnerHeartbeatStale(referenceHeartbeats.get(remote.runner_id) ?? null)) {
+        try {
+          await claimReferenceRunner(supabase, remote.id, config.runnerId);
+          isReferenceRunner = true;
+          logger.runner.info(
+            "PROJECT_SYNC",
+            `Claimed reference runner for project ${remote.id} \u2014 previous one (${remote.runner_id}) looks offline.`
+          );
+        } catch (err) {
+          logger.runner.error("PROJECT_SYNC", `Failed to claim reference runner for project ${remote.id}:`, err);
+        }
+      }
       if (local.isReferenceRunner !== isReferenceRunner) {
         local.isReferenceRunner = isReferenceRunner;
         changed = true;
@@ -3663,14 +3907,14 @@ async function checkPendingDevServerRestarts(supabase, config) {
 }
 
 // src/terminalServer.ts
-import { parse as parse3 } from "node:url";
-import { WebSocketServer as WebSocketServer2 } from "ws";
+import { parse as parse4 } from "node:url";
+import { WebSocketServer as WebSocketServer3 } from "ws";
 var FRAME_TYPE_RESIZE = 0;
 var FRAME_TYPE_IMAGE = 1;
 function attachTerminalServer() {
-  const wss = new WebSocketServer2({ noServer: true });
+  const wss = new WebSocketServer3({ noServer: true });
   wss.on("connection", (socket, request) => {
-    const { query } = parse3(request.url ?? "", true);
+    const { query } = parse4(request.url ?? "", true);
     const sessionId = typeof query.sessionId === "string" ? query.sessionId : null;
     const ticket = typeof query.ticket === "string" ? query.ticket : null;
     if (!sessionId || !ticket) {
@@ -3776,7 +4020,7 @@ async function startRunner() {
     logger.runner.error("BOOT", 'No runner set up yet. Run "agent-board-runner start --path <repos-root>" first.');
     process.exit(1);
   }
-  const config = applyRunnerName(applyAllowedRoot(loadedConfig));
+  const config = ensureRecoveryKeypair(applyRunnerName(applyAllowedRoot(loadedConfig)));
   if (!config.allowedRootPath) {
     logger.runner.error(
       "BOOT",
@@ -3784,10 +4028,9 @@ async function startRunner() {
     );
     process.exit(1);
   }
-  const supabase = createAuthedSupabaseClient();
-  let session;
+  let supabase, session;
   try {
-    session = await requireSession(supabase);
+    ({ client: supabase, session } = await ensureSession(config));
   } catch (error) {
     logger.runner.error("BOOT", error instanceof Error ? error.message : String(error));
     process.exit(1);
@@ -3799,7 +4042,7 @@ async function startRunner() {
     if (event === "SIGNED_OUT") {
       logger.runner.error(
         "AUTH",
-        'Supabase session was lost (refresh failed or was revoked) \u2014 every write from now on will fail row-level security checks. Run "agent-board-runner login" again and restart the runner.'
+        "Supabase session was lost (refresh failed or was revoked) \u2014 exiting so the process manager restarts this runner; the next boot recovers automatically."
       );
       process.exit(1);
     }
@@ -3824,6 +4067,10 @@ async function startRunner() {
     user_id: config.ownerUserId,
     name: config.runnerName,
     auth_token_hash: config.authToken,
+    // Re-sent on every boot with a real session — idempotent (same local key every time) and
+    // what makes automatic recovery possible the next time this runner loses its session, see
+    // ensureSession()/recoverSession() in auth.ts.
+    recovery_public_key: config.recoveryPublicKey,
     version: RUNNER_VERSION
   });
   if (runnerError) {
@@ -3848,6 +4095,8 @@ async function startRunner() {
   const httpServer = createServer();
   const terminalWss = attachTerminalServer();
   const agentEventsWss = attachAgentEventsServer();
+  const runnerRpcWss = attachRunnerRpcServer();
+  registerProjectCommandRpcHandler(supabase, config);
   attachFilesServer(httpServer, supabase, config);
   httpServer.on("upgrade", (request, socket, head) => {
     const pathname = (request.url ?? "").split("?")[0];
@@ -3855,6 +4104,8 @@ async function startRunner() {
       terminalWss.handleUpgrade(request, socket, head, (ws) => terminalWss.emit("connection", ws, request));
     } else if (pathname === "/agent-events") {
       agentEventsWss.handleUpgrade(request, socket, head, (ws) => agentEventsWss.emit("connection", ws, request));
+    } else if (pathname === "/runner-rpc") {
+      runnerRpcWss.handleUpgrade(request, socket, head, (ws) => runnerRpcWss.emit("connection", ws, request));
     } else {
       socket.destroy();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-board-runner",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Local runner for Agent Board — signs in with your own Supabase account (no shared secrets) and drives Claude Code against repos under your local repos root.",
   "type": "module",
   "bin": {