agent-board-runner 0.1.13 → 0.1.14

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
@@ -2719,7 +2852,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);
@@ -3590,10 +3736,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;
@@ -3837,7 +3997,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 +4005,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 +4019,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 +4044,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) {
@@ -4064,7 +4227,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 +4244,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 +4290,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 +4303,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";
@@ -2336,10 +2418,10 @@ import { join as join12 } from "node:path";
 import { promisify as promisify4 } 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,
     [
@@ -2658,7 +2740,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 +2913,7 @@ async function spawnSessionPty(supabase, config, entry) {
     );
     return false;
   }
-  const ticket = randomUUID6();
+  const ticket = randomUUID7();
   let pty;
   let newClaudeSessionId = null;
   let resumeConversationMissing = false;
@@ -3529,10 +3624,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;
@@ -3776,7 +3885,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 +3893,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 +3907,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 +3932,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-board-runner",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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": {