agent-board-runner 0.1.12 → 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 = [
@@ -772,32 +890,33 @@ async function logActivity(supabase, params) {
 }
 
 // src/sessions.ts
-async function getRunningSessionForProject(supabase, projectId, ownerUserId) {
-  const { data, error } = await supabase.from("sessions").select("id, card_id, agent_state, cards!card_id!inner(project_id, assigned_user_id)").eq("cards.project_id", projectId).eq("cards.assigned_user_id", ownerUserId).eq("status", "running").limit(1).maybeSingle();
+async function getRunningSessionForProject(supabase, projectId, runnerId) {
+  const { data, error } = await supabase.from("sessions").select("id, card_id, agent_state, cards!card_id!inner(project_id)").eq("cards.project_id", projectId).eq("runner_id", runnerId).eq("status", "running").limit(1).maybeSingle();
   if (error) throw error;
   if (!data) return null;
   const row = data;
   return { id: row.id, cardId: row.card_id, agentState: row.agent_state };
 }
-async function listQueuedSessionsForRunner(supabase, ownerUserId) {
+async function listQueuedSessionsForRunner(supabase, runnerId) {
   const { data, error } = await supabase.from("sessions").select(
-    "id, card_id, claude_session_id, agent_state, created_at, cards!card_id!inner(project_id, assigned_user_id, title, instructions, file_references, plan_first, prerequisite_card_id, prototype_first, prototype_url, prototype_approved)"
-  ).eq("cards.assigned_user_id", ownerUserId).eq("status", "queued").order("created_at", { ascending: true });
+    "id, card_id, claude_session_id, agent_state, created_at, cards!card_id!inner(project_id, title, instructions, file_references, plan_first, prerequisite_card_id, prototype_first, prototype_url, prototype_approved)"
+  ).eq("runner_id", runnerId).eq("status", "queued").order("created_at", { ascending: true });
   if (error) throw error;
   return data;
 }
-async function listPausedSessionsForRunner(supabase, ownerUserId) {
-  const { data, error } = await supabase.from("sessions").select("card_id, cards!card_id!inner(project_id, assigned_user_id)").eq("cards.assigned_user_id", ownerUserId).eq("status", "paused");
+async function listPausedSessionsForRunner(supabase, runnerId) {
+  const { data, error } = await supabase.from("sessions").select("card_id, cards!card_id!inner(project_id)").eq("runner_id", runnerId).eq("status", "paused");
   if (error) throw error;
   return data.map((row) => ({
     card_id: row.card_id,
     project_id: row.cards.project_id
   }));
 }
-async function createSession(supabase, userId, cardId, resumeClaudeSessionId) {
+async function createSession(supabase, userId, cardId, runnerId, resumeClaudeSessionId) {
   const { data, error } = await supabase.from("sessions").insert({
     card_id: cardId,
     user_id: userId,
+    runner_id: runnerId,
     status: "queued",
     // Pre-set so spawnSessionPty takes the resume path (see its doc comment) instead of
     // starting a blank conversation and resending the card's instructions.
@@ -806,6 +925,11 @@ async function createSession(supabase, userId, cardId, resumeClaudeSessionId) {
   if (error) throw error;
   return data.id;
 }
+async function getDefaultRunnerIdForUser(supabase, ownerUserId) {
+  const { data, error } = await supabase.from("runners").select("id").eq("user_id", ownerUserId).eq("is_default", true).maybeSingle();
+  if (error) throw error;
+  return data?.id ?? null;
+}
 async function updateSession(supabase, sessionId, changes, activityContext) {
   const { error } = await supabase.from("sessions").update({
     ...changes.status !== void 0 ? { status: changes.status } : {},
@@ -828,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");
@@ -887,7 +1026,7 @@ async function getProjectRepos(supabase, projectId) {
 }
 async function listCardsInColumn(supabase, projectId, column) {
   const { data, error } = await supabase.from("cards").select(
-    "id, project_id, title, instructions, column_name, assigned_user_id, deploy_error, file_references, preview_urls, custom_action_status, requeue_requested_at, restart_requested_at"
+    "id, project_id, title, instructions, column_name, assigned_user_id, runner_id, deploy_error, file_references, preview_urls, custom_action_status, requeue_requested_at, restart_requested_at"
   ).eq("project_id", projectId).eq("column_name", column);
   if (error) throw error;
   return data;
@@ -1481,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() {
@@ -1538,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
@@ -2387,1086 +2526,1111 @@ async function ensureBranchWatchers(supabase, config) {
 
 // src/columnActions.ts
 import { exec } from "node:child_process";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 import { promisify as promisify4 } from "node:util";
 
-// 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/orchestrator.ts
+import { randomUUID as randomUUID7 } from "node:crypto";
 
-// 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;
+// src/agentSession.ts
+import { randomUUID as randomUUID6 } from "node:crypto";
+import { spawn as spawn3 } from "node-pty";
+
+// src/sessionName.ts
+var MAX_LENGTH = 60;
+var FALLBACK_NAME = "card";
+function toSessionName(title) {
+  const slug = title.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug.length === 0) return FALLBACK_NAME;
+  if (slug.length <= MAX_LENGTH) return slug;
+  const truncated = slug.slice(0, MAX_LENGTH);
+  const lastHyphen = truncated.lastIndexOf("-");
+  return (lastHyphen > 0 ? truncated.slice(0, lastHyphen) : truncated).replace(/-+$/, "");
 }
-function resolveTargets(project, children, repoRoot, column, timing) {
-  if (children.length > 0) {
-    return children.flatMap(
-      (child2) => (child2.column_actions[column] ?? []).filter((action) => action.timing === timing).map((action) => ({ label: child2.subpath, cwd: join11(repoRoot, child2.subpath), command: action.command, repoId: child2.id }))
-    );
-  }
-  return (project.column_actions[column] ?? []).filter((action) => action.timing === timing).map((action) => ({ label: null, cwd: repoRoot, command: action.command, repoId: null }));
+
+// src/agentSession.ts
+var TUI_IDLE_MS = 1500;
+var TUI_READY_TIMEOUT_MS = 6e4;
+var SUBMIT_DELAY_MS = 150;
+var PASTE_START = "\x1B[200~";
+var PASTE_END = "\x1B[201~";
+var SHIFT_TAB = "\x1B[Z";
+var SHIFT_TAB_PRESSES_TO_PLAN_MODE = 4;
+var SHIFT_TAB_DELAY_MS = 400;
+var PLAN_MODE_INDICATOR = /plan mode on/i;
+function spawnAgentPty(repoPath, cardId, cardTitle, instructions, sessionId, ticket, planFirst) {
+  ensureDirTrusted(repoPath);
+  ensureMcpServersTrusted(repoPath);
+  const claudeSessionId = randomUUID6();
+  const pty = spawn3(
+    CLAUDE_BINARY,
+    [
+      "--dangerously-skip-permissions",
+      "--model",
+      "claude-sonnet-5",
+      "--session-id",
+      claudeSessionId,
+      ...claudeCliSettingsArgs(),
+      `/rename ${toSessionName(cardTitle)}`
+    ],
+    {
+      name: "xterm-color",
+      cols: 120,
+      rows: 32,
+      cwd: repoPath,
+      env: statuslineEnv(sessionId, ticket)
+    }
+  );
+  sendMessageWhenIdle(pty, cardId, instructions, planFirst);
+  return { pty, claudeSessionId };
 }
-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}`) };
-  } catch (err) {
-    const { stdout, stderr } = err;
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, output: tail(`${stdout ?? ""}${stderr ?? ""}` || message) };
-  }
+function sendMessageWhenIdle(pty, cardId, message, planFirst) {
+  let idleTimer;
+  let deadlineTimer;
+  let dataSubscription;
+  let settled = false;
+  const stopWaiting = () => {
+    if (settled) return false;
+    settled = true;
+    clearTimeout(idleTimer);
+    clearTimeout(deadlineTimer);
+    dataSubscription?.dispose();
+    return true;
+  };
+  const send = async () => {
+    if (!stopWaiting()) return;
+    if (planFirst) await enterPlanMode(pty, cardId);
+    try {
+      pty.write(`${PASTE_START}${message}${PASTE_END}`);
+      setTimeout(() => {
+        try {
+          pty.write("\r");
+        } catch (err) {
+          logger.card.error(cardId, "Failed to submit the card instructions to the agent:", err);
+        }
+      }, SUBMIT_DELAY_MS);
+    } catch (err) {
+      logger.card.error(cardId, "Failed to send the card instructions to the agent:", err);
+    }
+  };
+  deadlineTimer = setTimeout(send, TUI_READY_TIMEOUT_MS);
+  dataSubscription = pty.onData(() => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(send, TUI_IDLE_MS);
+  });
+  pty.onExit(() => stopWaiting());
 }
-var inFlightColumns = /* @__PURE__ */ new Set();
-async function handleColumnEntered(supabase, config, card) {
-  const key = `${card.project_id}:${card.column_name}`;
-  if (inFlightColumns.has(key)) return;
-  inFlightColumns.add(key);
+async function enterPlanMode(pty, cardId) {
+  let recentOutput = "";
+  const subscription = pty.onData((chunk) => {
+    recentOutput += normalizeTerminalOutput(chunk);
+  });
   try {
-    const project = await getProject(supabase, card.project_id);
-    const children = await getProjectRepos(supabase, project.id);
-    const repoRoot = resolveRepoPath(config, project.repo_path);
-    const targets = resolveTargets(project, children, repoRoot, card.column_name, "before");
-    if (targets.length === 0) return;
-    const allCards = await listCardsInColumn(supabase, project.id, card.column_name);
-    const cards = allCards.filter((candidate) => candidate.assigned_user_id === config.ownerUserId);
-    if (cards.length === 0) return;
-    await Promise.all(
-      cards.map((candidate) => updateCard(supabase, candidate.id, { customActionStatus: "running", customActionOutput: null }))
-    );
-    let failure = null;
-    for (const target of targets) {
-      const secretsEnv = await resolveProjectSecretsEnv(supabase, project.id, target.repoId);
-      const result = await runCommand(target, secretsEnv);
-      if (!result.ok) {
-        failure = { label: target.label, output: result.output };
-        break;
-      }
+    for (let attempt = 1; attempt <= SHIFT_TAB_PRESSES_TO_PLAN_MODE; attempt++) {
+      pty.write(SHIFT_TAB);
+      await new Promise((resolve5) => setTimeout(resolve5, SHIFT_TAB_DELAY_MS));
     }
-    if (failure) {
-      const message = failure.label ? `[${failure.label}] ${failure.output}` : failure.output;
-      logger.runner.warn("COLUMN_ACTION", `Command failed for project ${project.id} in "${card.column_name}": ${message}`);
-      await Promise.all(
-        cards.map(
-          (candidate) => updateCard(supabase, candidate.id, { customActionStatus: "failed", customActionOutput: message })
-        )
-      );
-    } else {
-      logger.runner.info("COLUMN_ACTION", `Command passed for project ${project.id} in "${card.column_name}".`);
-      await Promise.all(
-        cards.map(
-          (candidate) => updateCard(supabase, candidate.id, { customActionStatus: "passed", customActionOutput: null })
-        )
+    if (!PLAN_MODE_INDICATOR.test(recentOutput)) {
+      logger.card.warn(
+        cardId,
+        `Sent ${SHIFT_TAB_PRESSES_TO_PLAN_MODE} Shift+Tab presses but never saw the plan-mode indicator \u2014 the session may not actually be in Plan Mode.`
       );
     }
+  } catch (err) {
+    logger.card.error(cardId, "Failed to switch the session into Plan Mode:", err);
   } finally {
-    inFlightColumns.delete(key);
-  }
-}
-async function clearColumnActionStatus(supabase, card) {
-  if (card.custom_action_status === null) return;
-  await updateCard(supabase, card.id, { customActionStatus: null, customActionOutput: null });
-}
-async function runAfterColumnActions(supabase, project, children, repoRoot, column) {
-  const targets = resolveTargets(project, children, repoRoot, column, "after");
-  for (const target of targets) {
-    const secretsEnv = await resolveProjectSecretsEnv(supabase, project.id, target.repoId);
-    const result = await runCommand(target, secretsEnv);
-    if (!result.ok) {
-      return { ok: false, error: target.label ? `${target.label}: ${result.output}` : result.output };
-    }
+    subscription.dispose();
   }
-  return { ok: true };
 }
-async function checkPendingColumnActions(supabase, config) {
-  for (const registered of config.registeredProjects) {
-    for (const column of BOARD_COLUMNS) {
-      const cards = await listCardsInColumn(supabase, registered.id, column);
-      const pending2 = cards.find(
-        (card) => card.assigned_user_id === config.ownerUserId && card.custom_action_status === null
-      );
-      if (pending2) await handleColumnEntered(supabase, config, pending2);
-    }
+function sendMessageToIdleSession(pty, cardId, message) {
+  try {
+    pty.write(`${PASTE_START}${message}${PASTE_END}`);
+    setTimeout(() => {
+      try {
+        pty.write("\r");
+      } catch (err) {
+        logger.card.error(cardId, "Failed to submit a message to the idle session:", err);
+      }
+    }, SUBMIT_DELAY_MS);
+  } catch (err) {
+    logger.card.error(cardId, "Failed to send a message to the idle session:", err);
   }
 }
-async function handleDeployActionRerunRequested(supabase, config, project) {
-  const allCards = await listCardsInColumn(supabase, project.id, "deploy");
-  const cards = allCards.filter((card) => card.assigned_user_id === config.ownerUserId);
-  if (cards.length === 0) {
-    logger.runner.info("COLUMN_ACTION", `Rerun requested for project ${project.id}'s "deploy" column but no card assigned to this runner's user is waiting there.`);
-  } else {
-    await handleColumnEntered(supabase, config, cards[0]);
-  }
-  await clearDeployActionRerunRequest(supabase, project.id);
+function resumeAgentPty(repoPath, claudeSessionId, sessionId, ticket) {
+  ensureDirTrusted(repoPath);
+  ensureMcpServersTrusted(repoPath);
+  return spawn3(
+    CLAUDE_BINARY,
+    [
+      "--dangerously-skip-permissions",
+      "--model",
+      "claude-sonnet-5",
+      "--resume",
+      claudeSessionId,
+      ...claudeCliSettingsArgs()
+    ],
+    {
+      name: "xterm-color",
+      cols: 120,
+      rows: 32,
+      cwd: repoPath,
+      env: statuslineEnv(sessionId, ticket)
+    }
+  );
 }
-async function checkPendingDeployActionReruns(supabase, config) {
-  for (const registered of config.registeredProjects) {
-    const project = await getProject(supabase, registered.id);
-    if (project.deploy_action_rerun_requested_at) {
-      await handleDeployActionRerunRequested(supabase, config, project);
+
+// src/cardAttachments.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { tmpdir as tmpdir6 } from "node:os";
+import { extname, join as join11 } from "node:path";
+var ATTACHMENTS_ROOT = join11(tmpdir6(), "agent-board", "card-attachments");
+function sanitizeFileName(fileName) {
+  return fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+async function downloadCardAttachments(supabase, cardId) {
+  const { data, error } = await supabase.from("card_attachments").select("id, storage_path, file_name").eq("card_id", cardId).order("created_at", { ascending: true });
+  if (error) {
+    logger.card.error(cardId, "Failed to list attachments:", error.message);
+    return [];
+  }
+  const rows = data ?? [];
+  if (rows.length === 0) return [];
+  const targetDir = join11(ATTACHMENTS_ROOT, cardId);
+  await mkdir2(targetDir, { recursive: true });
+  const paths = [];
+  for (const row of rows) {
+    const baseName = sanitizeFileName(row.file_name);
+    const fileName = extname(baseName) ? baseName : `${baseName}${extname(row.storage_path)}`;
+    const localPath = join11(targetDir, `${row.id}-${fileName}`);
+    try {
+      const { data: blob, error: downloadError } = await supabase.storage.from(CARD_ATTACHMENTS_BUCKET).download(row.storage_path);
+      if (downloadError) throw downloadError;
+      await writeFile2(localPath, Buffer.from(await blob.arrayBuffer()));
+      paths.push(localPath);
+    } catch (err) {
+      logger.card.error(cardId, `Failed to download attachment ${row.storage_path}:`, err);
     }
   }
+  return paths;
 }
+function buildInstructionsWithAttachments(instructions, attachmentPaths) {
+  if (attachmentPaths.length === 0) return instructions;
+  const list = attachmentPaths.map((path) => `- ${path}`).join("\n");
+  return `${instructions}
 
-// src/deploy.ts
-import { join as join14 } from "node:path";
+Files attached to this card (use each one as part of the task):
+${list}`;
+}
 
-// src/devServer.ts
-import { spawn as spawn4 } from "node:child_process";
+// src/fileReferences.ts
+function buildInstructionsWithFileReferences(instructions, fileReferences) {
+  if (fileReferences.length === 0) return instructions;
+  const list = fileReferences.map((path) => `- ${path}`).join("\n");
+  return `${instructions}
 
-// src/cloudflared.ts
-import { spawn as spawn3 } from "node:child_process";
-import { accessSync, constants } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { delimiter, join as join12 } from "node:path";
-import { bin as bundledBinaryPath, install as downloadCloudflared } from "cloudflared";
-var TRYCLOUDFLARE_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
-var STARTUP_TIMEOUT_MS = 2e4;
-var IS_WINDOWS2 = process.platform === "win32";
-var BINARY_NAME = IS_WINDOWS2 ? "cloudflared.exe" : "cloudflared";
-var CLOUDFLARED_INSTALL_DOCS_URL = "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/";
-function wellKnownDirectories() {
-  const home = homedir5();
-  if (IS_WINDOWS2) {
-    const candidates = [
-      process.env.ProgramFiles && join12(process.env.ProgramFiles, "cloudflared"),
-      process.env["ProgramFiles(x86)"] && join12(process.env["ProgramFiles(x86)"], "cloudflared"),
-      process.env.LOCALAPPDATA && join12(process.env.LOCALAPPDATA, "Microsoft", "WinGet", "Links"),
-      join12(home, "scoop", "shims"),
-      process.env.ChocolateyInstall && join12(process.env.ChocolateyInstall, "bin")
-    ];
-    return candidates.filter((dir) => Boolean(dir));
-  }
-  return ["/usr/local/bin", "/usr/bin", "/opt/homebrew/bin", join12(home, ".local", "bin")];
+Files/folders referenced on this card (read them before starting \u2014 they are part of the task):
+${list}`;
 }
-function pathDirectories() {
-  return (process.env.PATH ?? "").split(delimiter).map((dir) => dir.trim().replace(/^"|"$/g, "")).filter(Boolean);
+
+// src/mcpContextNote.ts
+function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
+  return `${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.`;
 }
-function isExecutableFile(path) {
-  try {
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
+
+// src/prototypeGateNote.ts
+function buildInstructionsWithPrototypeGate(instructions, prototypeFirst) {
+  if (!prototypeFirst) return instructions;
+  return `${instructions}
+
+Prototipagem visual obrigat\xF3ria antes de implementar (prototypeFirst est\xE1 ligado neste card):
+
+1. Antes de qualquer altera\xE7\xE3o de c\xF3digo real, publique SOMENTE um prot\xF3tipo visual (um Claude
+   Artifact \u2014 HTML est\xE1tico, sem l\xF3gica/integra\xE7\xE3o de verdade) do que voc\xEA vai construir.
+   Reaproveite ao m\xE1ximo o design system REAL deste reposit\xF3rio (n\xE3o o do agent-board): leia o
+   tailwind config, as CSS vars/tema e os componentes j\xE1 existentes neste \`cwd\` antes de
+   desenhar qualquer coisa. Use as skills \`frontend-design\`/\`artifact-design\` j\xE1 dispon\xEDveis
+   antes de publicar.
+2. Se os anexos/instru\xE7\xF5es deste card inclu\xEDrem um print de uma tela j\xE1 existente pedindo
+   ajustes, o prot\xF3tipo \xE9 diferente: publique uma p\xE1gina INTERATIVA que mostra o print e deixa
+   quem est\xE1 revisando clicar nele para soltar um pino numerado com um campo de texto por pino \u2014
+   persista cada pino usando a capability \`db\` do pr\xF3prio Artifact (carregue a skill
+   \`artifact-capabilities\` antes de declarar a capability). Nesse caso, a nota que voc\xEA passar
+   para \`publish_prototype\` deve pedir para marcarem os pontos de ajuste nele, n\xE3o para
+   aprovarem um resultado ainda.
+3. Chame a tool MCP \`publish_prototype\` com o link do Artifact e uma nota curta do que fez/pede.
+   Essa chamada j\xE1 zera a aprova\xE7\xE3o e avisa os humanos do projeto \u2014 n\xE3o poste o link via
+   add_card_comment manualmente tamb\xE9m, seria duplicado.
+4. Depois de chamar \`publish_prototype\`, PARE o turno \u2014 n\xE3o fique num loop verificando
+   aprova\xE7\xE3o nem monitorando o artifact sozinho. A sess\xE3o ser\xE1 retomada automaticamente quando
+   houver uma revis\xE3o nova (aprova\xE7\xE3o ou pedido de ajuste); tentar continuar por conta pr\xF3pria
+   antes disso \xE9 desperd\xEDcio.
+5. Quando a sess\xE3o for retomada, a mensagem vai dizer se o prot\xF3tipo foi aprovado:
+   - **Aprovado**: prossiga para a implementa\xE7\xE3o real agora, usando o prot\xF3tipo (e, se for o
+     caso de ajuste em tela existente, os pontos marcados nele \u2014 leia-os de volta via leitura do
+     banco do artifact) como refer\xEAncia. Se os pontos marcados forem grandes/numerosos o
+     suficiente para valer separar, quebre em cards novos (\`create_card\` +
+     \`prerequisiteCardId\`, encadeando os que dependem um do outro) e aplique o mesmo fluxo de
+     prot\xF3tipo em cada um antes de implementar; resolva no pr\xF3prio card quando o ajuste for
+     pequeno.
+   - **N\xE3o aprovado**: confira os coment\xE1rios deixados no Artifact (e, se for a p\xE1gina de
+     anota\xE7\xE3o, os pontos salvos), ajuste o prot\xF3tipo e publique a nova vers\xE3o de novo via
+     \`publish_prototype\` na MESMA url \u2014 depois pare o turno de novo, voltando ao passo 4.`;
 }
-function findInstalledBinary() {
-  const override = process.env.AGENT_BOARD_CLOUDFLARED_PATH;
-  const directories = [...pathDirectories(), ...wellKnownDirectories()];
-  const candidates = [...override ? [override] : [], ...directories.map((dir) => join12(dir, BINARY_NAME))];
-  return candidates.find(isExecutableFile) ?? null;
+
+// src/usageResume.ts
+var RESET_BUFFER_MS = 3e4;
+var UNKNOWN_RESET_RETRY_MS = 5 * 6e4;
+var pending = /* @__PURE__ */ new Map();
+function scheduleUsageResume(supabase, config, cardId, sessionId, pty) {
+  if (pending.has(sessionId)) return;
+  void (async () => {
+    const usage = await getClaudeUsage(supabase, config.ownerUserId).catch((err) => {
+      logger.card.error(cardId, "Failed to read claude_usage for usage-limit resume:", err);
+      return null;
+    });
+    const now = Date.now();
+    const candidates = [usage?.sessionResetsAt, usage?.weekResetsAt].map((iso) => iso ? new Date(iso).getTime() : null).filter((ms) => ms !== null && ms > now);
+    const resetAt = candidates.length > 0 ? Math.min(...candidates) : null;
+    const delay = resetAt !== null ? resetAt - now + RESET_BUFFER_MS : UNKNOWN_RESET_RETRY_MS;
+    logger.card.info(
+      cardId,
+      resetAt !== null ? `Usage limit hit \u2014 will send "continue" automatically at ${new Date(resetAt).toISOString()}.` : `Usage limit hit but no reset time known yet \u2014 will retry in ${Math.round(delay / 6e4)}min.`
+    );
+    const timer = setTimeout(() => {
+      pending.delete(sessionId);
+      sendMessageToIdleSession(pty, cardId, "continue");
+    }, delay);
+    timer.unref();
+    pending.set(sessionId, timer);
+  })();
 }
-async function locateCloudflared() {
-  const installed = findInstalledBinary();
-  if (installed) return installed;
-  if (isExecutableFile(bundledBinaryPath)) return bundledBinaryPath;
+function cancelUsageResume(sessionId) {
+  const timer = pending.get(sessionId);
+  if (!timer) return;
+  clearTimeout(timer);
+  pending.delete(sessionId);
+}
+
+// src/orchestrator.ts
+var TERMINAL_TICKET_TTL_MS = 60 * 60 * 1e3;
+var RESUME_CONVERSATION_MISSING_PATTERN = /no conversation found with session id/i;
+var inFlightCardIds = /* @__PURE__ */ new Set();
+var activeSessionByCard = /* @__PURE__ */ new Map();
+var intentionallyStoppedSessionIds = /* @__PURE__ */ new Set();
+var dispatchingRunner = false;
+async function isEffectiveOwner(supabase, card, config) {
+  if (card.assigned_user_id !== config.ownerUserId) return false;
+  if (card.runner_id) return card.runner_id === config.runnerId;
+  const defaultRunnerId = await getDefaultRunnerIdForUser(supabase, config.ownerUserId);
+  if (defaultRunnerId) return defaultRunnerId === config.runnerId;
+  return true;
+}
+async function scanForWork(supabase, config) {
+  for (const project of config.registeredProjects) {
+    await reconcileStaleSessions(supabase, config, project.id);
+    const { data: cards, error } = await supabase.from("cards").select("*").eq("project_id", project.id).eq("column_name", "desenvolvimento").eq("assigned_user_id", config.ownerUserId);
+    if (error) {
+      logger.runner.error("ORCHESTRATOR", `Failed to scan cards for project ${project.id}:`, error.message);
+      continue;
+    }
+    for (const card of cards ?? []) {
+      void enqueueCard(supabase, config, card);
+    }
+  }
+  void dispatchRunnerQueue(supabase, config);
+}
+async function enqueueCard(supabase, config, card) {
+  if (inFlightCardIds.has(card.id)) return;
+  const registered = config.registeredProjects.find((project) => project.id === card.project_id);
+  if (!registered) {
+    logger.card.warn(card.id, `Ignoring card: project ${card.project_id} is not registered on this runner.`);
+    return;
+  }
+  if (!await isEffectiveOwner(supabase, card, config)) return;
+  inFlightCardIds.add(card.id);
   try {
-    logger.runner.info("CLOUDFLARE", "Downloading the cloudflared binary (first run only)...");
-    return await downloadCloudflared(bundledBinaryPath);
-  } catch (err) {
-    logger.runner.error("CLOUDFLARE", `Failed to download cloudflared. Install it manually: ${CLOUDFLARED_INSTALL_DOCS_URL}`, err);
-    return null;
+    const active = await getActiveSessionForCard(supabase, card.id);
+    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);
   }
+  await dispatchRunnerQueue(supabase, config);
 }
-var lookup = null;
-function resolveCloudflaredPath() {
-  lookup ??= locateCloudflared().then((path) => {
-    if (!path) lookup = null;
-    return path;
-  });
-  return lookup;
+async function createQueuedSession(supabase, config, card) {
+  const resumeClaudeSessionId = await getLastClaudeSessionIdForCard(supabase, card.id);
+  const sessionId = await createSession(supabase, config.ownerUserId, card.id, config.runnerId, resumeClaudeSessionId);
+  logger.card.info(
+    card.id,
+    resumeClaudeSessionId ? `"${card.title}" queued (session ${sessionId}, will resume prior conversation ${resumeClaudeSessionId}).` : `"${card.title}" queued (session ${sessionId}).`
+  );
 }
-async function startQuickTunnel(label, port) {
-  const executable = await resolveCloudflaredPath();
-  if (!executable) {
-    logger.runner.error("CLOUDFLARE", `No cloudflared binary available, so ${label} cannot be exposed.`);
-    return null;
+async function reconcileStaleSessions(supabase, config, projectId) {
+  const { data, error } = await supabase.from("sessions").select("id, card_id, cards!card_id!inner(project_id, column_name)").eq("cards.project_id", projectId).eq("runner_id", config.runnerId).in("status", ["queued", "running", "waiting_input", "paused"]).neq("cards.column_name", "desenvolvimento");
+  if (error) {
+    logger.runner.error("ORCHESTRATOR", `Failed to scan stale sessions for project ${projectId}:`, error.message);
+    return;
   }
-  return new Promise((resolve5) => {
-    let child2;
-    try {
-      child2 = spawn3(executable, [
-        "tunnel",
-        "--url",
-        `http://localhost:${port}`,
-        "--http-host-header",
-        `localhost:${port}`
-      ]);
-    } catch (err) {
-      logger.runner.error("CLOUDFLARE", `Failed to spawn cloudflared for ${label}:`, err);
-      resolve5(null);
-      return;
-    }
-    let settled = false;
-    const settle = (value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve5(value);
-    };
-    const timer = setTimeout(() => {
-      logger.runner.warn("CLOUDFLARE", `cloudflared for ${label} did not print a trycloudflare.com URL within ${STARTUP_TIMEOUT_MS}ms.`);
-      settle(null);
-    }, STARTUP_TIMEOUT_MS);
-    const onOutput = (chunk) => {
-      if (settled) return;
-      const match = chunk.toString("utf-8").match(TRYCLOUDFLARE_URL_RE);
-      if (match) settle({ url: match[0], child: child2 });
-    };
-    child2.stdout?.on("data", onOutput);
-    child2.stderr?.on("data", onOutput);
-    child2.on("error", (err) => {
-      logger.runner.error("CLOUDFLARE", `cloudflared process error for ${label} (${executable}):`, err);
-      settle(null);
-    });
-    child2.on("exit", (code) => {
-      logger.runner.info("CLOUDFLARE", `cloudflared tunnel for ${label} exited (code ${code}).`);
-      settle(null);
-    });
-  });
-}
-function toTunnelHostname(url) {
-  return new URL(url).host;
-}
-
-// src/devServer.ts
-var STARTUP_TIMEOUT_MS2 = 45e3;
-var IS_WINDOWS3 = process.platform === "win32";
-var LOCAL_URL_PORT_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0):(\d{2,5})/i;
-var GENERIC_PORT_RE = /(?:listening|running|server).{0,40}?:?\s*(\d{4,5})\b/i;
-var ANSI_ESCAPE_RE2 = /\x1b\[[0-9;]*m/g;
-function detectPortFromOutput(chunk) {
-  const clean = chunk.replace(ANSI_ESCAPE_RE2, "");
-  const match = LOCAL_URL_PORT_RE.exec(clean) ?? GENERIC_PORT_RE.exec(clean);
-  return match ? Number(match[1]) : null;
-}
-function killProcessTree(child2) {
-  if (child2.pid == null) return;
-  if (IS_WINDOWS3) {
-    spawn4("taskkill", ["/pid", String(child2.pid), "/t", "/f"], { stdio: "ignore" });
-  } else {
-    child2.kill();
+  const stale = data ?? [];
+  if (stale.length === 0) return;
+  for (const { id: sessionId, card_id: cardId, cards } of stale) {
+    intentionallyStoppedSessionIds.add(sessionId);
+    stopPtySession(sessionId);
+    cancelUsageResume(sessionId);
+    activeSessionByCard.delete(cardId);
+    await updateSession(
+      supabase,
+      sessionId,
+      {
+        status: "done",
+        endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        // See stopCardSession's doc comment: "fim" is the authoritative completion signal for
+        // dispatchRunnerQueue's prerequisite gate, which only ever reads agent_state.
+        ...cards.column_name === "fim" ? { agentState: "done" } : {}
+      },
+      { projectId, cardId, userId: config.ownerUserId }
+    );
+    logger.card.info(cardId, `Ended stale session ${sessionId} (its card left "desenvolvimento" while this runner missed the event).`);
   }
+  await dispatchRunnerQueue(supabase, config);
 }
-var previews = /* @__PURE__ */ new Map();
-function ensurePreview(key, label, cwd, command2, cardId, extraEnv = {}) {
-  const existing = previews.get(key);
-  if (existing) {
-    existing.cardIds.add(cardId);
-    return existing.result;
-  }
-  let child2;
+async function dispatchRunnerQueue(supabase, config) {
+  if (dispatchingRunner) return;
+  dispatchingRunner = true;
+  let queued = [];
+  const promotedCardIds = /* @__PURE__ */ new Set();
   try {
-    child2 = spawn4(command2, { cwd, shell: true, windowsHide: true, env: { ...process.env, ...extraEnv } });
-  } catch (err) {
-    logger.runner.error("DEV_SERVER", `Failed to spawn "${command2}" in ${cwd}:`, err);
-    return Promise.resolve(null);
-  }
-  const entry = { child: child2, tunnelChild: null, cardIds: /* @__PURE__ */ new Set([cardId]), result: null };
-  entry.result = new Promise((resolve5) => {
-    let settled = false;
-    const settle = (value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (!value) {
-        killProcessTree(child2);
-        previews.delete(key);
+    queued = await listQueuedSessionsForRunner(supabase, config.runnerId);
+    if (queued.length === 0) return;
+    const queuedProjectIds = new Set(queued.map((entry) => entry.cards.project_id));
+    const maxConcurrentProjects = await getRunnerMaxConcurrentProjects(supabase, config.runnerId);
+    const runningProjectIds = /* @__PURE__ */ new Set();
+    for (const project of config.registeredProjects) {
+      const running = await getRunningSessionForProject(supabase, project.id, config.runnerId);
+      if (!running) continue;
+      if ((running.agentState === "done" || running.agentState === "waiting_prototype_review") && queuedProjectIds.has(project.id)) {
+        await pauseFinishedSession(supabase, config, project.id, running.cardId, running.id);
+        continue;
       }
-      resolve5(value);
-    };
-    const timer = setTimeout(() => {
-      logger.runner.warn("DEV_SERVER", `"${command2}" in ${cwd} did not reveal a port within ${STARTUP_TIMEOUT_MS2}ms.`);
-      settle(null);
-    }, STARTUP_TIMEOUT_MS2);
-    const onOutput = async (chunk) => {
-      if (settled) return;
-      const port = detectPortFromOutput(chunk.toString("utf-8"));
-      if (port == null) return;
-      settled = true;
-      clearTimeout(timer);
-      const tunnel = await startQuickTunnel(`dev server ${key}`, port);
-      if (!tunnel) {
-        logger.runner.warn("DEV_SERVER", `Detected port ${port} for ${key} but cloudflared could not tunnel it.`);
-        killProcessTree(child2);
-        previews.delete(key);
-        resolve5(null);
-        return;
+      runningProjectIds.add(project.id);
+    }
+    let freeProjectSlots = maxConcurrentProjects - runningProjectIds.size;
+    if (freeProjectSlots <= 0) return;
+    const promotedThisPass = /* @__PURE__ */ new Set();
+    for (const entry of queued) {
+      const projectId = entry.cards.project_id;
+      if (runningProjectIds.has(projectId) || promotedThisPass.has(projectId)) continue;
+      if (freeProjectSlots <= 0) break;
+      const prerequisiteCardId = entry.cards.prerequisite_card_id;
+      if (prerequisiteCardId) {
+        const prerequisiteAgentState = await getLatestAgentStateForCard(supabase, prerequisiteCardId);
+        if (prerequisiteAgentState !== "done") {
+          logger.card.info(
+            entry.card_id,
+            `Waiting on prerequisite card ${prerequisiteCardId} to reach agent state "done" (currently "${prerequisiteAgentState ?? "none"}") before starting \u2014 leaving queued.`
+          );
+          continue;
+        }
       }
-      entry.tunnelChild = tunnel.child;
-      logger.runner.info("DEV_SERVER", `${key} is up on port ${port}, tunneled at ${tunnel.url}.`);
-      resolve5({ label, url: tunnel.url });
-    };
-    child2.stdout?.on("data", onOutput);
-    child2.stderr?.on("data", onOutput);
-    child2.on("error", (err) => {
-      logger.runner.error("DEV_SERVER", `Dev server process error for ${key} (${command2} in ${cwd}):`, err);
-      settle(null);
-    });
-    child2.on("exit", (code) => {
-      logger.runner.info("DEV_SERVER", `Dev server for ${key} exited (code ${code}) before/without a usable preview.`);
-      settle(null);
-    });
-  });
-  previews.set(key, entry);
-  return entry.result;
-}
-function releaseCard(cardId) {
-  for (const [key, entry] of previews) {
-    if (!entry.cardIds.delete(cardId)) continue;
-    if (entry.cardIds.size > 0) continue;
-    killProcessTree(entry.child);
-    entry.tunnelChild?.kill();
-    previews.delete(key);
+      try {
+        await promoteQueuedSession(supabase, config, entry);
+        promotedThisPass.add(projectId);
+        promotedCardIds.add(entry.card_id);
+        freeProjectSlots -= 1;
+      } catch (err) {
+        logger.card.error(entry.card_id, `Failed to promote queued session ${entry.id}:`, err);
+      }
+    }
+  } finally {
+    await publishQueueSnapshots(supabase, config, queued, promotedCardIds).catch(
+      (err) => logger.runner.error("ORCHESTRATOR", "Failed to publish queue snapshots:", err)
+    );
+    dispatchingRunner = false;
   }
 }
-function stopProjectPreviews(projectId) {
-  const prefix = `${projectId}:`;
-  for (const [key, entry] of previews) {
-    if (!key.startsWith(prefix)) continue;
-    killProcessTree(entry.child);
-    entry.tunnelChild?.kill();
-    previews.delete(key);
+async function publishQueueSnapshots(supabase, config, queued, promotedCardIds) {
+  const paused = await listPausedSessionsForRunner(supabase, config.runnerId);
+  const queuedByProject = /* @__PURE__ */ new Map();
+  for (const entry of queued) {
+    if (promotedCardIds.has(entry.card_id)) continue;
+    const list = queuedByProject.get(entry.cards.project_id) ?? [];
+    list.push(entry.card_id);
+    queuedByProject.set(entry.cards.project_id, list);
   }
-}
-function stopAll() {
-  for (const key of [...previews.keys()]) {
-    const entry = previews.get(key);
-    if (!entry) continue;
-    killProcessTree(entry.child);
-    entry.tunnelChild?.kill();
-    previews.delete(key);
+  const pausedByProject = /* @__PURE__ */ new Map();
+  for (const { card_id: cardId, project_id: projectId } of paused) {
+    const list = pausedByProject.get(projectId) ?? [];
+    list.push(cardId);
+    pausedByProject.set(projectId, list);
   }
-}
-
-// src/git.ts
-import { execFile as execFile4 } from "node:child_process";
-import { promisify as promisify5 } from "node:util";
-var execFileAsync4 = promisify5(execFile4);
-async function pushBranchToMain(repoPath) {
-  try {
-    await execFileAsync4("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
-    return { ok: true };
-  } catch (err) {
-    const stderr = err.stderr;
-    const error = stderr?.trim() || (err instanceof Error ? err.message : String(err));
-    return { ok: false, error };
+  for (const project of config.registeredProjects) {
+    publishQueueEvent(project.id, {
+      queuedCardIds: queuedByProject.get(project.id) ?? [],
+      pausedCardIds: pausedByProject.get(project.id) ?? []
+    });
   }
 }
-
-// src/orchestrator.ts
-import { randomUUID as randomUUID7 } from "node:crypto";
-
-// src/agentSession.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
-import { spawn as spawn5 } from "node-pty";
-
-// src/sessionName.ts
-var MAX_LENGTH = 60;
-var FALLBACK_NAME = "card";
-function toSessionName(title) {
-  const slug = title.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  if (slug.length === 0) return FALLBACK_NAME;
-  if (slug.length <= MAX_LENGTH) return slug;
-  const truncated = slug.slice(0, MAX_LENGTH);
-  const lastHyphen = truncated.lastIndexOf("-");
-  return (lastHyphen > 0 ? truncated.slice(0, lastHyphen) : truncated).replace(/-+$/, "");
-}
-
-// src/agentSession.ts
-var TUI_IDLE_MS = 1500;
-var TUI_READY_TIMEOUT_MS = 6e4;
-var SUBMIT_DELAY_MS = 150;
-var PASTE_START = "\x1B[200~";
-var PASTE_END = "\x1B[201~";
-var SHIFT_TAB = "\x1B[Z";
-var SHIFT_TAB_PRESSES_TO_PLAN_MODE = 4;
-var SHIFT_TAB_DELAY_MS = 400;
-var PLAN_MODE_INDICATOR = /plan mode on/i;
-function spawnAgentPty(repoPath, cardId, cardTitle, instructions, sessionId, ticket, planFirst) {
-  ensureDirTrusted(repoPath);
-  ensureMcpServersTrusted(repoPath);
-  const claudeSessionId = randomUUID6();
-  const pty = spawn5(
-    CLAUDE_BINARY,
-    [
-      "--dangerously-skip-permissions",
-      "--model",
-      "claude-sonnet-5",
-      "--session-id",
-      claudeSessionId,
-      ...claudeCliSettingsArgs(),
-      `/rename ${toSessionName(cardTitle)}`
-    ],
-    {
-      name: "xterm-color",
-      cols: 120,
-      rows: 32,
-      cwd: repoPath,
-      env: statuslineEnv(sessionId, ticket)
-    }
-  );
-  sendMessageWhenIdle(pty, cardId, instructions, planFirst);
-  return { pty, claudeSessionId };
+function buildPrototypeReviewFollowUp(prototypeApproved, prototypeUrl) {
+  return prototypeApproved ? "O prot\xF3tipo foi revisado e aprovado \u2014 prossiga para a implementa\xE7\xE3o real, usando-o como refer\xEAncia." : `O prot\xF3tipo ainda n\xE3o foi aprovado${prototypeUrl ? ` (${prototypeUrl})` : ""} \u2014 confira os coment\xE1rios deixados nele (e, se for um prot\xF3tipo de marca\xE7\xE3o de pontos, os pontos salvos) e ajuste, publicando a nova vers\xE3o com publish_prototype. Depois, pare o turno de novo: a sess\xE3o ser\xE1 retomada quando houver outra revis\xE3o.`;
 }
-function sendMessageWhenIdle(pty, cardId, message, planFirst) {
-  let idleTimer;
-  let deadlineTimer;
-  let dataSubscription;
-  let settled = false;
-  const stopWaiting = () => {
-    if (settled) return false;
-    settled = true;
-    clearTimeout(idleTimer);
-    clearTimeout(deadlineTimer);
-    dataSubscription?.dispose();
-    return true;
-  };
-  const send = async () => {
-    if (!stopWaiting()) return;
-    if (planFirst) await enterPlanMode(pty, cardId);
-    try {
-      pty.write(`${PASTE_START}${message}${PASTE_END}`);
-      setTimeout(() => {
-        try {
-          pty.write("\r");
-        } catch (err) {
-          logger.card.error(cardId, "Failed to submit the card instructions to the agent:", err);
-        }
-      }, SUBMIT_DELAY_MS);
-    } catch (err) {
-      logger.card.error(cardId, "Failed to send the card instructions to the agent:", err);
+async function promoteQueuedSession(supabase, config, entry) {
+  const existingHandle = getPtySession(entry.id);
+  if (existingHandle) {
+    setPtySessionReadOnly(entry.id, false);
+    await updateSession(
+      supabase,
+      entry.id,
+      { status: "running" },
+      { projectId: entry.cards.project_id, cardId: entry.card_id, userId: config.ownerUserId }
+    );
+    activeSessionByCard.set(entry.card_id, entry.id);
+    logger.card.info(entry.card_id, "Resumed paused session from the front of the queue.");
+    if (entry.agent_state === "waiting_prototype_review" && !existingHandle.exited) {
+      sendMessageToIdleSession(
+        existingHandle.pty,
+        entry.card_id,
+        buildPrototypeReviewFollowUp(entry.cards.prototype_approved, entry.cards.prototype_url)
+      );
     }
-  };
-  deadlineTimer = setTimeout(send, TUI_READY_TIMEOUT_MS);
-  dataSubscription = pty.onData(() => {
-    clearTimeout(idleTimer);
-    idleTimer = setTimeout(send, TUI_IDLE_MS);
-  });
-  pty.onExit(() => stopWaiting());
+    return;
+  }
+  const spawned = await spawnSessionPty(supabase, config, entry);
+  if (spawned) logger.card.info(entry.card_id, "Promoted from queue.");
 }
-async function enterPlanMode(pty, cardId) {
-  let recentOutput = "";
-  const subscription = pty.onData((chunk) => {
-    recentOutput += normalizeTerminalOutput(chunk);
-  });
+async function spawnSessionPty(supabase, config, entry) {
+  const { id: sessionId, card_id: cardId, cards: card, claude_session_id: claudeSessionId } = entry;
+  const registered = config.registeredProjects.find((project) => project.id === card.project_id);
+  if (!registered) {
+    logger.card.error(cardId, `Session ${sessionId}: project ${card.project_id} is not registered \u2014 skipping.`);
+    await updateSession(
+      supabase,
+      sessionId,
+      { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+      { projectId: card.project_id, cardId, userId: config.ownerUserId }
+    );
+    return false;
+  }
+  const ticket = randomUUID7();
+  let pty;
+  let newClaudeSessionId = null;
+  let resumeConversationMissing = false;
   try {
-    for (let attempt = 1; attempt <= SHIFT_TAB_PRESSES_TO_PLAN_MODE; attempt++) {
-      pty.write(SHIFT_TAB);
-      await new Promise((resolve5) => setTimeout(resolve5, SHIFT_TAB_DELAY_MS));
-    }
-    if (!PLAN_MODE_INDICATOR.test(recentOutput)) {
-      logger.card.warn(
+    if (claudeSessionId) {
+      pty = resumeAgentPty(registered.repoPath, claudeSessionId, sessionId, ticket);
+      pty.onData((chunk) => {
+        if (RESUME_CONVERSATION_MISSING_PATTERN.test(normalizeTerminalOutput(chunk))) resumeConversationMissing = true;
+      });
+    } else {
+      const attachmentPaths = await downloadCardAttachments(supabase, cardId);
+      const instructions = buildInstructionsWithMcpContext(
+        buildInstructionsWithPrototypeGate(
+          buildInstructionsWithFileReferences(
+            buildInstructionsWithAttachments(card.instructions, attachmentPaths),
+            card.file_references
+          ),
+          card.prototype_first
+        ),
         cardId,
-        `Sent ${SHIFT_TAB_PRESSES_TO_PLAN_MODE} Shift+Tab presses but never saw the plan-mode indicator \u2014 the session may not actually be in Plan Mode.`
+        card.project_id
       );
+      const spawned = spawnAgentPty(registered.repoPath, cardId, card.title, instructions, sessionId, ticket, card.plan_first);
+      pty = spawned.pty;
+      newClaudeSessionId = spawned.claudeSessionId;
     }
   } catch (err) {
-    logger.card.error(cardId, "Failed to switch the session into Plan Mode:", err);
-  } finally {
-    subscription.dispose();
-  }
-}
-function sendMessageToIdleSession(pty, cardId, message) {
-  try {
-    pty.write(`${PASTE_START}${message}${PASTE_END}`);
-    setTimeout(() => {
-      try {
-        pty.write("\r");
-      } catch (err) {
-        logger.card.error(cardId, "Failed to submit a message to the idle session:", err);
-      }
-    }, SUBMIT_DELAY_MS);
-  } catch (err) {
-    logger.card.error(cardId, "Failed to send a message to the idle session:", err);
+    logger.card.error(cardId, `Failed to spawn pty for session ${sessionId}:`, err);
+    await updateSession(
+      supabase,
+      sessionId,
+      { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+      { projectId: card.project_id, cardId, userId: config.ownerUserId }
+    );
+    return false;
   }
-}
-function resumeAgentPty(repoPath, claudeSessionId, sessionId, ticket) {
-  ensureDirTrusted(repoPath);
-  ensureMcpServersTrusted(repoPath);
-  return spawn5(
-    CLAUDE_BINARY,
-    [
-      "--dangerously-skip-permissions",
-      "--model",
-      "claude-sonnet-5",
-      "--resume",
-      claudeSessionId,
-      ...claudeCliSettingsArgs()
-    ],
+  registerPtySession(sessionId, pty, ticket);
+  activeSessionByCard.set(cardId, sessionId);
+  publishAgentStateEvent(card.project_id, cardId, sessionId, newClaudeSessionId ? "starting" : entry.agent_state ?? "starting");
+  const activityWatcher = watchAgentActivity(supabase, config, card.project_id, cardId, sessionId, pty);
+  await updateSession(
+    supabase,
+    sessionId,
     {
-      name: "xterm-color",
-      cols: 120,
-      rows: 32,
-      cwd: repoPath,
-      env: statuslineEnv(sessionId, ticket)
-    }
+      status: "running",
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      terminalTicket: ticket,
+      terminalTicketExpiresAt: new Date(Date.now() + TERMINAL_TICKET_TTL_MS).toISOString(),
+      // Only stamp a fresh spawn as "starting" — a resumed session (claudeSessionId was
+      // already set) keeps whatever agent_state it had before the restart (e.g.
+      // "usage_limited"), so reconcileUsageLimitedSessions can find it afterwards. The
+      // freshly (re)constructed AgentActivityWatcher below will correct it the moment real
+      // output gives it something conclusive to classify.
+      ...newClaudeSessionId ? { agentState: "starting", claudeSessionId: newClaudeSessionId } : {}
+    },
+    { projectId: card.project_id, cardId, userId: config.ownerUserId }
   );
-}
-
-// src/cardAttachments.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
-import { tmpdir as tmpdir6 } from "node:os";
-import { extname, join as join13 } from "node:path";
-var ATTACHMENTS_ROOT = join13(tmpdir6(), "agent-board", "card-attachments");
-function sanitizeFileName(fileName) {
-  return fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-async function downloadCardAttachments(supabase, cardId) {
-  const { data, error } = await supabase.from("card_attachments").select("id, storage_path, file_name").eq("card_id", cardId).order("created_at", { ascending: true });
-  if (error) {
-    logger.card.error(cardId, "Failed to list attachments:", error.message);
-    return [];
-  }
-  const rows = data ?? [];
-  if (rows.length === 0) return [];
-  const targetDir = join13(ATTACHMENTS_ROOT, cardId);
-  await mkdir2(targetDir, { recursive: true });
-  const paths = [];
-  for (const row of rows) {
-    const baseName = sanitizeFileName(row.file_name);
-    const fileName = extname(baseName) ? baseName : `${baseName}${extname(row.storage_path)}`;
-    const localPath = join13(targetDir, `${row.id}-${fileName}`);
-    try {
-      const { data: blob, error: downloadError } = await supabase.storage.from(CARD_ATTACHMENTS_BUCKET).download(row.storage_path);
-      if (downloadError) throw downloadError;
-      await writeFile2(localPath, Buffer.from(await blob.arrayBuffer()));
-      paths.push(localPath);
-    } catch (err) {
-      logger.card.error(cardId, `Failed to download attachment ${row.storage_path}:`, err);
+  pty.onExit(({ exitCode }) => {
+    const wasIntentional = intentionallyStoppedSessionIds.delete(sessionId);
+    activityWatcher.stop();
+    unregisterAgentActivityWatcher(sessionId);
+    cancelUsageResume(sessionId);
+    activeSessionByCard.delete(cardId);
+    if (resumeConversationMissing) {
+      logger.card.warn(
+        cardId,
+        `Session ${sessionId}: --resume ${claudeSessionId} found no such conversation \u2014 clearing it so the next attempt starts a fresh one instead of repeating the same failure.`
+      );
+      void updateSession(
+        supabase,
+        sessionId,
+        { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString(), claudeSessionId: null },
+        { projectId: card.project_id, cardId, userId: config.ownerUserId }
+      );
+      return;
     }
-  }
-  return paths;
-}
-function buildInstructionsWithAttachments(instructions, attachmentPaths) {
-  if (attachmentPaths.length === 0) return instructions;
-  const list = attachmentPaths.map((path) => `- ${path}`).join("\n");
-  return `${instructions}
-
-Files attached to this card (use each one as part of the task):
-${list}`;
+    logger.card.warn(cardId, `Session exited (code ${exitCode}) \u2014 this only happens if the process crashed or was killed, the card doesn't auto-advance.`);
+    if (!wasIntentional && exitCode !== 0) {
+      publishAgentState(supabase, card.project_id, cardId, sessionId, "error");
+    }
+  });
+  return true;
 }
-
-// src/fileReferences.ts
-function buildInstructionsWithFileReferences(instructions, fileReferences) {
-  if (fileReferences.length === 0) return instructions;
-  const list = fileReferences.map((path) => `- ${path}`).join("\n");
-  return `${instructions}
-
-Files/folders referenced on this card (read them before starting \u2014 they are part of the task):
-${list}`;
+function publishAgentState(supabase, projectId, cardId, sessionId, state) {
+  publishAgentStateEvent(projectId, cardId, sessionId, state);
+  updateSession(supabase, sessionId, { agentState: state }).catch(
+    (err) => logger.card.error(cardId, `Failed to persist agent state "${state}" for session ${sessionId}:`, err)
+  );
 }
-
-// src/mcpContextNote.ts
-function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
-  return `${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.`;
+function watchAgentActivity(supabase, config, projectId, cardId, sessionId, pty) {
+  const watcher = new AgentActivityWatcher((state) => {
+    publishAgentState(supabase, projectId, cardId, sessionId, state);
+    if (state === "usage_limited") {
+      scheduleUsageResume(supabase, config, cardId, sessionId, pty);
+    } else {
+      cancelUsageResume(sessionId);
+    }
+    if (state === "done" || state === "waiting_prototype_review") void dispatchRunnerQueue(supabase, config);
+  });
+  pty.onData((chunk) => watcher.push(chunk));
+  registerAgentActivityWatcher(sessionId, watcher);
+  return watcher;
 }
-
-// src/prototypeGateNote.ts
-function buildInstructionsWithPrototypeGate(instructions, prototypeFirst) {
-  if (!prototypeFirst) return instructions;
-  return `${instructions}
-
-Prototipagem visual obrigat\xF3ria antes de implementar (prototypeFirst est\xE1 ligado neste card):
-
-1. Antes de qualquer altera\xE7\xE3o de c\xF3digo real, publique SOMENTE um prot\xF3tipo visual (um Claude
-   Artifact \u2014 HTML est\xE1tico, sem l\xF3gica/integra\xE7\xE3o de verdade) do que voc\xEA vai construir.
-   Reaproveite ao m\xE1ximo o design system REAL deste reposit\xF3rio (n\xE3o o do agent-board): leia o
-   tailwind config, as CSS vars/tema e os componentes j\xE1 existentes neste \`cwd\` antes de
-   desenhar qualquer coisa. Use as skills \`frontend-design\`/\`artifact-design\` j\xE1 dispon\xEDveis
-   antes de publicar.
-2. Se os anexos/instru\xE7\xF5es deste card inclu\xEDrem um print de uma tela j\xE1 existente pedindo
-   ajustes, o prot\xF3tipo \xE9 diferente: publique uma p\xE1gina INTERATIVA que mostra o print e deixa
-   quem est\xE1 revisando clicar nele para soltar um pino numerado com um campo de texto por pino \u2014
-   persista cada pino usando a capability \`db\` do pr\xF3prio Artifact (carregue a skill
-   \`artifact-capabilities\` antes de declarar a capability). Nesse caso, a nota que voc\xEA passar
-   para \`publish_prototype\` deve pedir para marcarem os pontos de ajuste nele, n\xE3o para
-   aprovarem um resultado ainda.
-3. Chame a tool MCP \`publish_prototype\` com o link do Artifact e uma nota curta do que fez/pede.
-   Essa chamada j\xE1 zera a aprova\xE7\xE3o e avisa os humanos do projeto \u2014 n\xE3o poste o link via
-   add_card_comment manualmente tamb\xE9m, seria duplicado.
-4. Depois de chamar \`publish_prototype\`, PARE o turno \u2014 n\xE3o fique num loop verificando
-   aprova\xE7\xE3o nem monitorando o artifact sozinho. A sess\xE3o ser\xE1 retomada automaticamente quando
-   houver uma revis\xE3o nova (aprova\xE7\xE3o ou pedido de ajuste); tentar continuar por conta pr\xF3pria
-   antes disso \xE9 desperd\xEDcio.
-5. Quando a sess\xE3o for retomada, a mensagem vai dizer se o prot\xF3tipo foi aprovado:
-   - **Aprovado**: prossiga para a implementa\xE7\xE3o real agora, usando o prot\xF3tipo (e, se for o
-     caso de ajuste em tela existente, os pontos marcados nele \u2014 leia-os de volta via leitura do
-     banco do artifact) como refer\xEAncia. Se os pontos marcados forem grandes/numerosos o
-     suficiente para valer separar, quebre em cards novos (\`create_card\` +
-     \`prerequisiteCardId\`, encadeando os que dependem um do outro) e aplique o mesmo fluxo de
-     prot\xF3tipo em cada um antes de implementar; resolva no pr\xF3prio card quando o ajuste for
-     pequeno.
-   - **N\xE3o aprovado**: confira os coment\xE1rios deixados no Artifact (e, se for a p\xE1gina de
-     anota\xE7\xE3o, os pontos salvos), ajuste o prot\xF3tipo e publique a nova vers\xE3o de novo via
-     \`publish_prototype\` na MESMA url \u2014 depois pare o turno de novo, voltando ao passo 4.`;
+async function pauseFinishedSession(supabase, config, projectId, cardId, sessionId) {
+  const paused = await pauseRunningSession(supabase, sessionId, { projectId, cardId, userId: config.ownerUserId });
+  if (!paused) return;
+  setPtySessionReadOnly(sessionId, true);
+  logger.card.info(cardId, `Session ${sessionId} paused (agent reached "done", another session needs this project's WIP slot).`);
 }
-
-// src/usageResume.ts
-var RESET_BUFFER_MS = 3e4;
-var UNKNOWN_RESET_RETRY_MS = 5 * 6e4;
-var pending = /* @__PURE__ */ new Map();
-function scheduleUsageResume(supabase, config, cardId, sessionId, pty) {
-  if (pending.has(sessionId)) return;
-  void (async () => {
-    const usage = await getClaudeUsage(supabase, config.ownerUserId).catch((err) => {
-      logger.card.error(cardId, "Failed to read claude_usage for usage-limit resume:", err);
-      return null;
-    });
-    const now = Date.now();
-    const candidates = [usage?.sessionResetsAt, usage?.weekResetsAt].map((iso) => iso ? new Date(iso).getTime() : null).filter((ms) => ms !== null && ms > now);
-    const resetAt = candidates.length > 0 ? Math.min(...candidates) : null;
-    const delay = resetAt !== null ? resetAt - now + RESET_BUFFER_MS : UNKNOWN_RESET_RETRY_MS;
-    logger.card.info(
-      cardId,
-      resetAt !== null ? `Usage limit hit \u2014 will send "continue" automatically at ${new Date(resetAt).toISOString()}.` : `Usage limit hit but no reset time known yet \u2014 will retry in ${Math.round(delay / 6e4)}min.`
+async function requeuePausedCard(supabase, config, card) {
+  const active = await getActiveSessionForCard(supabase, card.id);
+  if (!active) return;
+  if (active.status === "paused") {
+    await updateSession(
+      supabase,
+      active.id,
+      { status: "queued" },
+      { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
     );
-    const timer = setTimeout(() => {
-      pending.delete(sessionId);
-      sendMessageToIdleSession(pty, cardId, "continue");
-    }, delay);
-    timer.unref();
-    pending.set(sessionId, timer);
-  })();
-}
-function cancelUsageResume(sessionId) {
-  const timer = pending.get(sessionId);
-  if (!timer) return;
-  clearTimeout(timer);
-  pending.delete(sessionId);
+    await updateCard(supabase, card.id, { requeueRequestedAt: null });
+    logger.card.info(card.id, `Session ${active.id} requeued at the front of the line (was paused).`);
+    await dispatchRunnerQueue(supabase, config);
+    return;
+  }
+  if (active.status === "running" && active.agentState === "waiting_prototype_review") {
+    const handle = getPtySession(active.id);
+    await updateCard(supabase, card.id, { requeueRequestedAt: null });
+    if (handle && !handle.exited) {
+      sendMessageToIdleSession(handle.pty, card.id, buildPrototypeReviewFollowUp(card.prototype_approved, card.prototype_url));
+      logger.card.info(card.id, `Session ${active.id} was never paused (alone in its project) \u2014 sent the prototype review follow-up directly.`);
+    }
+  }
 }
-
-// src/orchestrator.ts
-var TERMINAL_TICKET_TTL_MS = 60 * 60 * 1e3;
-var RESUME_CONVERSATION_MISSING_PATTERN = /no conversation found with session id/i;
-var inFlightCardIds = /* @__PURE__ */ new Set();
-var activeSessionByCard = /* @__PURE__ */ new Map();
-var intentionallyStoppedSessionIds = /* @__PURE__ */ new Set();
-var dispatchingRunner = false;
-async function scanForWork(supabase, config) {
+async function reconcileOrphanedSessions(supabase, config) {
   for (const project of config.registeredProjects) {
-    await reconcileStaleSessions(supabase, config, project.id);
-    const { data: cards, error } = await supabase.from("cards").select("*").eq("project_id", project.id).eq("column_name", "desenvolvimento").eq("assigned_user_id", config.ownerUserId);
+    const { data, error } = await supabase.from("sessions").select(
+      "id, card_id, claude_session_id, agent_state, created_at, status, cards!card_id!inner(project_id, title, instructions, file_references, plan_first)"
+    ).eq("cards.project_id", project.id).eq("runner_id", config.runnerId).in("status", ["running", "paused"]);
     if (error) {
-      logger.runner.error("ORCHESTRATOR", `Failed to scan cards for project ${project.id}:`, error.message);
+      logger.runner.error("ORCHESTRATOR", `Failed to scan orphaned sessions for project ${project.id}:`, error.message);
       continue;
     }
-    for (const card of cards ?? []) {
-      void enqueueCard(supabase, config, card);
+    for (const entry of data ?? []) {
+      let spawned;
+      try {
+        spawned = await spawnSessionPty(supabase, config, entry);
+      } catch (err) {
+        logger.card.error(entry.card_id, `Failed to re-spawn orphaned session ${entry.id}:`, err);
+        continue;
+      }
+      if (!spawned) continue;
+      if (entry.status === "paused") {
+        await updateSession(
+          supabase,
+          entry.id,
+          { status: "paused" },
+          { projectId: project.id, cardId: entry.card_id, userId: config.ownerUserId }
+        );
+        setPtySessionReadOnly(entry.id, true);
+        logger.card.info(entry.card_id, "Re-spawned paused session (runner restarted) \u2014 still read-only until requeued.");
+      } else {
+        logger.card.info(entry.card_id, "Re-spawned orphaned session (runner restarted since it was last running).");
+      }
     }
   }
-  void dispatchRunnerQueue(supabase, config);
 }
-async function enqueueCard(supabase, config, card) {
-  if (inFlightCardIds.has(card.id)) return;
-  const registered = config.registeredProjects.find((project) => project.id === card.project_id);
-  if (!registered) {
-    logger.card.warn(card.id, `Ignoring card: project ${card.project_id} is not registered on this runner.`);
-    return;
-  }
-  if (card.assigned_user_id !== config.ownerUserId) return;
-  inFlightCardIds.add(card.id);
-  try {
-    const active = await getActiveSessionForCard(supabase, card.id);
-    if (active) return;
-    await createQueuedSession(supabase, config, card);
-  } finally {
-    inFlightCardIds.delete(card.id);
+async function reconcileUsageLimitedSessions(supabase, config) {
+  for (const project of config.registeredProjects) {
+    const { data, error } = await supabase.from("sessions").select("id, card_id, cards!card_id!inner(project_id)").eq("cards.project_id", project.id).eq("runner_id", config.runnerId).eq("status", "running").eq("agent_state", "usage_limited");
+    if (error) {
+      logger.runner.error("ORCHESTRATOR", `Failed to scan usage-limited sessions for project ${project.id}:`, error.message);
+      continue;
+    }
+    for (const { id: sessionId, card_id: cardId } of data ?? []) {
+      const handle = getPtySession(sessionId);
+      if (!handle) continue;
+      scheduleUsageResume(supabase, config, cardId, sessionId, handle.pty);
+    }
   }
-  await dispatchRunnerQueue(supabase, config);
 }
-async function createQueuedSession(supabase, config, card) {
-  const resumeClaudeSessionId = await getLastClaudeSessionIdForCard(supabase, card.id);
-  const sessionId = await createSession(supabase, config.ownerUserId, card.id, resumeClaudeSessionId);
-  logger.card.info(
-    card.id,
-    resumeClaudeSessionId ? `"${card.title}" queued (session ${sessionId}, will resume prior conversation ${resumeClaudeSessionId}).` : `"${card.title}" queued (session ${sessionId}).`
+async function stopCardSession(supabase, config, card) {
+  const sessionId = activeSessionByCard.get(card.id) ?? (await getActiveSessionForCard(supabase, card.id))?.id;
+  if (!sessionId) return;
+  intentionallyStoppedSessionIds.add(sessionId);
+  stopPtySession(sessionId);
+  cancelUsageResume(sessionId);
+  activeSessionByCard.delete(card.id);
+  await updateSession(
+    supabase,
+    sessionId,
+    {
+      status: "done",
+      endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...card.column_name === "fim" ? { agentState: "done" } : {}
+    },
+    { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
   );
+  logger.card.info(card.id, `Session ${sessionId} stopped.`);
+  await dispatchRunnerQueue(supabase, config);
 }
-async function reconcileStaleSessions(supabase, config, projectId) {
-  const { data, error } = await supabase.from("sessions").select("id, card_id, cards!card_id!inner(project_id, column_name, assigned_user_id)").eq("cards.project_id", projectId).eq("cards.assigned_user_id", config.ownerUserId).in("status", ["queued", "running", "waiting_input", "paused"]).neq("cards.column_name", "desenvolvimento");
-  if (error) {
-    logger.runner.error("ORCHESTRATOR", `Failed to scan stale sessions for project ${projectId}:`, error.message);
-    return;
-  }
-  const stale = data ?? [];
-  if (stale.length === 0) return;
-  for (const { id: sessionId, card_id: cardId, cards } of stale) {
+async function restartCardSession(supabase, config, card) {
+  const sessionId = activeSessionByCard.get(card.id) ?? (await getActiveSessionForCard(supabase, card.id))?.id;
+  if (sessionId) {
     intentionallyStoppedSessionIds.add(sessionId);
     stopPtySession(sessionId);
     cancelUsageResume(sessionId);
-    activeSessionByCard.delete(cardId);
+    activeSessionByCard.delete(card.id);
     await updateSession(
       supabase,
       sessionId,
-      {
-        status: "done",
-        endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        // See stopCardSession's doc comment: "fim" is the authoritative completion signal for
-        // dispatchRunnerQueue's prerequisite gate, which only ever reads agent_state.
-        ...cards.column_name === "fim" ? { agentState: "done" } : {}
-      },
-      { projectId, cardId, userId: config.ownerUserId }
+      { status: "failed", claudeSessionId: null, endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+      { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
     );
-    logger.card.info(cardId, `Ended stale session ${sessionId} (its card left "desenvolvimento" while this runner missed the event).`);
+    logger.card.info(card.id, `Session ${sessionId} abandoned by "Reiniciar sess\xE3o"; starting a fresh one.`);
   }
-  await dispatchRunnerQueue(supabase, config);
+  await updateCard(supabase, card.id, { restartRequestedAt: null });
+  await enqueueCard(supabase, config, card);
 }
-async function dispatchRunnerQueue(supabase, config) {
-  if (dispatchingRunner) return;
-  dispatchingRunner = true;
-  let queued = [];
-  const promotedCardIds = /* @__PURE__ */ new Set();
+
+// src/vaultSecrets.ts
+async function resolveProjectSecretsEnv(supabase, projectId, repoId) {
   try {
-    queued = await listQueuedSessionsForRunner(supabase, config.ownerUserId);
-    if (queued.length === 0) return;
-    const queuedProjectIds = new Set(queued.map((entry) => entry.cards.project_id));
-    const maxConcurrentProjects = await getRunnerMaxConcurrentProjects(supabase, config.runnerId);
-    const runningProjectIds = /* @__PURE__ */ new Set();
-    for (const project of config.registeredProjects) {
-      const running = await getRunningSessionForProject(supabase, project.id, config.ownerUserId);
-      if (!running) continue;
-      if ((running.agentState === "done" || running.agentState === "waiting_prototype_review") && queuedProjectIds.has(project.id)) {
-        await pauseFinishedSession(supabase, config, project.id, running.cardId, running.id);
-        continue;
+    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;
+}
+function resolveTargets(project, children, repoRoot, column, timing) {
+  if (children.length > 0) {
+    return children.flatMap(
+      (child2) => (child2.column_actions[column] ?? []).filter((action) => action.timing === timing).map((action) => ({ label: child2.subpath, cwd: join12(repoRoot, child2.subpath), command: action.command, repoId: child2.id }))
+    );
+  }
+  return (project.column_actions[column] ?? []).filter((action) => action.timing === timing).map((action) => ({ label: null, cwd: repoRoot, command: action.command, repoId: null }));
+}
+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}`) };
+  } catch (err) {
+    const { stdout, stderr } = err;
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, output: tail(`${stdout ?? ""}${stderr ?? ""}` || message) };
+  }
+}
+var inFlightColumns = /* @__PURE__ */ new Set();
+async function handleColumnEntered(supabase, config, card) {
+  const key = `${card.project_id}:${card.column_name}`;
+  if (inFlightColumns.has(key)) return;
+  inFlightColumns.add(key);
+  try {
+    const project = await getProject(supabase, card.project_id);
+    const children = await getProjectRepos(supabase, project.id);
+    const repoRoot = resolveRepoPath(config, project.repo_path);
+    const targets = resolveTargets(project, children, repoRoot, card.column_name, "before");
+    if (targets.length === 0) return;
+    const allCards = await listCardsInColumn(supabase, project.id, card.column_name);
+    const cards = (await Promise.all(allCards.map(async (candidate) => await isEffectiveOwner(supabase, candidate, config) ? candidate : null))).filter((candidate) => candidate !== null);
+    if (cards.length === 0) return;
+    await Promise.all(
+      cards.map((candidate) => updateCard(supabase, candidate.id, { customActionStatus: "running", customActionOutput: null }))
+    );
+    let failure = null;
+    for (const target of targets) {
+      const secretsEnv = await resolveProjectSecretsEnv(supabase, project.id, target.repoId);
+      const result = await runCommand(target, secretsEnv);
+      if (!result.ok) {
+        failure = { label: target.label, output: result.output };
+        break;
       }
-      runningProjectIds.add(project.id);
     }
-    let freeProjectSlots = maxConcurrentProjects - runningProjectIds.size;
-    if (freeProjectSlots <= 0) return;
-    const promotedThisPass = /* @__PURE__ */ new Set();
-    for (const entry of queued) {
-      const projectId = entry.cards.project_id;
-      if (runningProjectIds.has(projectId) || promotedThisPass.has(projectId)) continue;
-      if (freeProjectSlots <= 0) break;
-      const prerequisiteCardId = entry.cards.prerequisite_card_id;
-      if (prerequisiteCardId) {
-        const prerequisiteAgentState = await getLatestAgentStateForCard(supabase, prerequisiteCardId);
-        if (prerequisiteAgentState !== "done") {
-          logger.card.info(
-            entry.card_id,
-            `Waiting on prerequisite card ${prerequisiteCardId} to reach agent state "done" (currently "${prerequisiteAgentState ?? "none"}") before starting \u2014 leaving queued.`
-          );
-          continue;
+    if (failure) {
+      const message = failure.label ? `[${failure.label}] ${failure.output}` : failure.output;
+      logger.runner.warn("COLUMN_ACTION", `Command failed for project ${project.id} in "${card.column_name}": ${message}`);
+      await Promise.all(
+        cards.map(
+          (candidate) => updateCard(supabase, candidate.id, { customActionStatus: "failed", customActionOutput: message })
+        )
+      );
+    } else {
+      logger.runner.info("COLUMN_ACTION", `Command passed for project ${project.id} in "${card.column_name}".`);
+      await Promise.all(
+        cards.map(
+          (candidate) => updateCard(supabase, candidate.id, { customActionStatus: "passed", customActionOutput: null })
+        )
+      );
+    }
+  } finally {
+    inFlightColumns.delete(key);
+  }
+}
+async function clearColumnActionStatus(supabase, card) {
+  if (card.custom_action_status === null) return;
+  await updateCard(supabase, card.id, { customActionStatus: null, customActionOutput: null });
+}
+async function runAfterColumnActions(supabase, project, children, repoRoot, column) {
+  const targets = resolveTargets(project, children, repoRoot, column, "after");
+  for (const target of targets) {
+    const secretsEnv = await resolveProjectSecretsEnv(supabase, project.id, target.repoId);
+    const result = await runCommand(target, secretsEnv);
+    if (!result.ok) {
+      return { ok: false, error: target.label ? `${target.label}: ${result.output}` : result.output };
+    }
+  }
+  return { ok: true };
+}
+async function checkPendingColumnActions(supabase, config) {
+  for (const registered of config.registeredProjects) {
+    for (const column of BOARD_COLUMNS) {
+      const cards = await listCardsInColumn(supabase, registered.id, column);
+      let pending2;
+      for (const card of cards) {
+        if (card.custom_action_status !== null) continue;
+        if (await isEffectiveOwner(supabase, card, config)) {
+          pending2 = card;
+          break;
         }
       }
-      try {
-        await promoteQueuedSession(supabase, config, entry);
-        promotedThisPass.add(projectId);
-        promotedCardIds.add(entry.card_id);
-        freeProjectSlots -= 1;
-      } catch (err) {
-        logger.card.error(entry.card_id, `Failed to promote queued session ${entry.id}:`, err);
-      }
+      if (pending2) await handleColumnEntered(supabase, config, pending2);
     }
-  } finally {
-    await publishQueueSnapshots(supabase, config, queued, promotedCardIds).catch(
-      (err) => logger.runner.error("ORCHESTRATOR", "Failed to publish queue snapshots:", err)
-    );
-    dispatchingRunner = false;
   }
 }
-async function publishQueueSnapshots(supabase, config, queued, promotedCardIds) {
-  const paused = await listPausedSessionsForRunner(supabase, config.ownerUserId);
-  const queuedByProject = /* @__PURE__ */ new Map();
-  for (const entry of queued) {
-    if (promotedCardIds.has(entry.card_id)) continue;
-    const list = queuedByProject.get(entry.cards.project_id) ?? [];
-    list.push(entry.card_id);
-    queuedByProject.set(entry.cards.project_id, list);
-  }
-  const pausedByProject = /* @__PURE__ */ new Map();
-  for (const { card_id: cardId, project_id: projectId } of paused) {
-    const list = pausedByProject.get(projectId) ?? [];
-    list.push(cardId);
-    pausedByProject.set(projectId, list);
-  }
-  for (const project of config.registeredProjects) {
-    publishQueueEvent(project.id, {
-      queuedCardIds: queuedByProject.get(project.id) ?? [],
-      pausedCardIds: pausedByProject.get(project.id) ?? []
-    });
+async function handleDeployActionRerunRequested(supabase, config, project) {
+  const allCards = await listCardsInColumn(supabase, project.id, "deploy");
+  const cards = (await Promise.all(allCards.map(async (card) => await isEffectiveOwner(supabase, card, config) ? card : null))).filter((card) => card !== null);
+  if (cards.length === 0) {
+    logger.runner.info("COLUMN_ACTION", `Rerun requested for project ${project.id}'s "deploy" column but no card assigned to this runner's user is waiting there.`);
+  } else {
+    await handleColumnEntered(supabase, config, cards[0]);
   }
+  await clearDeployActionRerunRequest(supabase, project.id);
 }
-function buildPrototypeReviewFollowUp(prototypeApproved, prototypeUrl) {
-  return prototypeApproved ? "O prot\xF3tipo foi revisado e aprovado \u2014 prossiga para a implementa\xE7\xE3o real, usando-o como refer\xEAncia." : `O prot\xF3tipo ainda n\xE3o foi aprovado${prototypeUrl ? ` (${prototypeUrl})` : ""} \u2014 confira os coment\xE1rios deixados nele (e, se for um prot\xF3tipo de marca\xE7\xE3o de pontos, os pontos salvos) e ajuste, publicando a nova vers\xE3o com publish_prototype. Depois, pare o turno de novo: a sess\xE3o ser\xE1 retomada quando houver outra revis\xE3o.`;
-}
-async function promoteQueuedSession(supabase, config, entry) {
-  const existingHandle = getPtySession(entry.id);
-  if (existingHandle) {
-    setPtySessionReadOnly(entry.id, false);
-    await updateSession(
-      supabase,
-      entry.id,
-      { status: "running" },
-      { projectId: entry.cards.project_id, cardId: entry.card_id, userId: config.ownerUserId }
-    );
-    activeSessionByCard.set(entry.card_id, entry.id);
-    logger.card.info(entry.card_id, "Resumed paused session from the front of the queue.");
-    if (entry.agent_state === "waiting_prototype_review" && !existingHandle.exited) {
-      sendMessageToIdleSession(
-        existingHandle.pty,
-        entry.card_id,
-        buildPrototypeReviewFollowUp(entry.cards.prototype_approved, entry.cards.prototype_url)
-      );
+async function checkPendingDeployActionReruns(supabase, config) {
+  for (const registered of config.registeredProjects) {
+    const project = await getProject(supabase, registered.id);
+    if (project.deploy_action_rerun_requested_at) {
+      await handleDeployActionRerunRequested(supabase, config, project);
     }
-    return;
   }
-  const spawned = await spawnSessionPty(supabase, config, entry);
-  if (spawned) logger.card.info(entry.card_id, "Promoted from queue.");
 }
-async function spawnSessionPty(supabase, config, entry) {
-  const { id: sessionId, card_id: cardId, cards: card, claude_session_id: claudeSessionId } = entry;
-  const registered = config.registeredProjects.find((project) => project.id === card.project_id);
-  if (!registered) {
-    logger.card.error(cardId, `Session ${sessionId}: project ${card.project_id} is not registered \u2014 skipping.`);
-    await updateSession(
-      supabase,
-      sessionId,
-      { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
-      { projectId: card.project_id, cardId, userId: config.ownerUserId }
-    );
+
+// src/deploy.ts
+import { join as join14 } from "node:path";
+
+// src/devServer.ts
+import { spawn as spawn5 } from "node:child_process";
+
+// src/cloudflared.ts
+import { spawn as spawn4 } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { delimiter, join as join13 } from "node:path";
+import { bin as bundledBinaryPath, install as downloadCloudflared } from "cloudflared";
+var TRYCLOUDFLARE_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+var STARTUP_TIMEOUT_MS = 2e4;
+var IS_WINDOWS2 = process.platform === "win32";
+var BINARY_NAME = IS_WINDOWS2 ? "cloudflared.exe" : "cloudflared";
+var CLOUDFLARED_INSTALL_DOCS_URL = "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/";
+function wellKnownDirectories() {
+  const home = homedir5();
+  if (IS_WINDOWS2) {
+    const candidates = [
+      process.env.ProgramFiles && join13(process.env.ProgramFiles, "cloudflared"),
+      process.env["ProgramFiles(x86)"] && join13(process.env["ProgramFiles(x86)"], "cloudflared"),
+      process.env.LOCALAPPDATA && join13(process.env.LOCALAPPDATA, "Microsoft", "WinGet", "Links"),
+      join13(home, "scoop", "shims"),
+      process.env.ChocolateyInstall && join13(process.env.ChocolateyInstall, "bin")
+    ];
+    return candidates.filter((dir) => Boolean(dir));
+  }
+  return ["/usr/local/bin", "/usr/bin", "/opt/homebrew/bin", join13(home, ".local", "bin")];
+}
+function pathDirectories() {
+  return (process.env.PATH ?? "").split(delimiter).map((dir) => dir.trim().replace(/^"|"$/g, "")).filter(Boolean);
+}
+function isExecutableFile(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
     return false;
   }
-  const ticket = randomUUID7();
-  let pty;
-  let newClaudeSessionId = null;
-  let resumeConversationMissing = false;
+}
+function findInstalledBinary() {
+  const override = process.env.AGENT_BOARD_CLOUDFLARED_PATH;
+  const directories = [...pathDirectories(), ...wellKnownDirectories()];
+  const candidates = [...override ? [override] : [], ...directories.map((dir) => join13(dir, BINARY_NAME))];
+  return candidates.find(isExecutableFile) ?? null;
+}
+async function locateCloudflared() {
+  const installed = findInstalledBinary();
+  if (installed) return installed;
+  if (isExecutableFile(bundledBinaryPath)) return bundledBinaryPath;
   try {
-    if (claudeSessionId) {
-      pty = resumeAgentPty(registered.repoPath, claudeSessionId, sessionId, ticket);
-      pty.onData((chunk) => {
-        if (RESUME_CONVERSATION_MISSING_PATTERN.test(normalizeTerminalOutput(chunk))) resumeConversationMissing = true;
-      });
-    } else {
-      const attachmentPaths = await downloadCardAttachments(supabase, cardId);
-      const instructions = buildInstructionsWithMcpContext(
-        buildInstructionsWithPrototypeGate(
-          buildInstructionsWithFileReferences(
-            buildInstructionsWithAttachments(card.instructions, attachmentPaths),
-            card.file_references
-          ),
-          card.prototype_first
-        ),
-        cardId,
-        card.project_id
-      );
-      const spawned = spawnAgentPty(registered.repoPath, cardId, card.title, instructions, sessionId, ticket, card.plan_first);
-      pty = spawned.pty;
-      newClaudeSessionId = spawned.claudeSessionId;
-    }
+    logger.runner.info("CLOUDFLARE", "Downloading the cloudflared binary (first run only)...");
+    return await downloadCloudflared(bundledBinaryPath);
   } catch (err) {
-    logger.card.error(cardId, `Failed to spawn pty for session ${sessionId}:`, err);
-    await updateSession(
-      supabase,
-      sessionId,
-      { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
-      { projectId: card.project_id, cardId, userId: config.ownerUserId }
-    );
-    return false;
+    logger.runner.error("CLOUDFLARE", `Failed to download cloudflared. Install it manually: ${CLOUDFLARED_INSTALL_DOCS_URL}`, err);
+    return null;
   }
-  registerPtySession(sessionId, pty, ticket);
-  activeSessionByCard.set(cardId, sessionId);
-  publishAgentStateEvent(card.project_id, cardId, sessionId, newClaudeSessionId ? "starting" : entry.agent_state ?? "starting");
-  const activityWatcher = watchAgentActivity(supabase, config, card.project_id, cardId, sessionId, pty);
-  await updateSession(
-    supabase,
-    sessionId,
-    {
-      status: "running",
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      terminalTicket: ticket,
-      terminalTicketExpiresAt: new Date(Date.now() + TERMINAL_TICKET_TTL_MS).toISOString(),
-      // Only stamp a fresh spawn as "starting" — a resumed session (claudeSessionId was
-      // already set) keeps whatever agent_state it had before the restart (e.g.
-      // "usage_limited"), so reconcileUsageLimitedSessions can find it afterwards. The
-      // freshly (re)constructed AgentActivityWatcher below will correct it the moment real
-      // output gives it something conclusive to classify.
-      ...newClaudeSessionId ? { agentState: "starting", claudeSessionId: newClaudeSessionId } : {}
-    },
-    { projectId: card.project_id, cardId, userId: config.ownerUserId }
-  );
-  pty.onExit(({ exitCode }) => {
-    const wasIntentional = intentionallyStoppedSessionIds.delete(sessionId);
-    activityWatcher.stop();
-    unregisterAgentActivityWatcher(sessionId);
-    cancelUsageResume(sessionId);
-    activeSessionByCard.delete(cardId);
-    if (resumeConversationMissing) {
-      logger.card.warn(
-        cardId,
-        `Session ${sessionId}: --resume ${claudeSessionId} found no such conversation \u2014 clearing it so the next attempt starts a fresh one instead of repeating the same failure.`
-      );
-      void updateSession(
-        supabase,
-        sessionId,
-        { status: "failed", endedAt: (/* @__PURE__ */ new Date()).toISOString(), claudeSessionId: null },
-        { projectId: card.project_id, cardId, userId: config.ownerUserId }
-      );
+}
+var lookup = null;
+function resolveCloudflaredPath() {
+  lookup ??= locateCloudflared().then((path) => {
+    if (!path) lookup = null;
+    return path;
+  });
+  return lookup;
+}
+async function startQuickTunnel(label, port) {
+  const executable = await resolveCloudflaredPath();
+  if (!executable) {
+    logger.runner.error("CLOUDFLARE", `No cloudflared binary available, so ${label} cannot be exposed.`);
+    return null;
+  }
+  return new Promise((resolve5) => {
+    let child2;
+    try {
+      child2 = spawn4(executable, [
+        "tunnel",
+        "--url",
+        `http://localhost:${port}`,
+        "--http-host-header",
+        `localhost:${port}`
+      ]);
+    } catch (err) {
+      logger.runner.error("CLOUDFLARE", `Failed to spawn cloudflared for ${label}:`, err);
+      resolve5(null);
       return;
     }
-    logger.card.warn(cardId, `Session exited (code ${exitCode}) \u2014 this only happens if the process crashed or was killed, the card doesn't auto-advance.`);
-    if (!wasIntentional && exitCode !== 0) {
-      publishAgentState(supabase, card.project_id, cardId, sessionId, "error");
-    }
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve5(value);
+    };
+    const timer = setTimeout(() => {
+      logger.runner.warn("CLOUDFLARE", `cloudflared for ${label} did not print a trycloudflare.com URL within ${STARTUP_TIMEOUT_MS}ms.`);
+      settle(null);
+    }, STARTUP_TIMEOUT_MS);
+    const onOutput = (chunk) => {
+      if (settled) return;
+      const match = chunk.toString("utf-8").match(TRYCLOUDFLARE_URL_RE);
+      if (match) settle({ url: match[0], child: child2 });
+    };
+    child2.stdout?.on("data", onOutput);
+    child2.stderr?.on("data", onOutput);
+    child2.on("error", (err) => {
+      logger.runner.error("CLOUDFLARE", `cloudflared process error for ${label} (${executable}):`, err);
+      settle(null);
+    });
+    child2.on("exit", (code) => {
+      logger.runner.info("CLOUDFLARE", `cloudflared tunnel for ${label} exited (code ${code}).`);
+      settle(null);
+    });
   });
-  return true;
 }
-function publishAgentState(supabase, projectId, cardId, sessionId, state) {
-  publishAgentStateEvent(projectId, cardId, sessionId, state);
-  updateSession(supabase, sessionId, { agentState: state }).catch(
-    (err) => logger.card.error(cardId, `Failed to persist agent state "${state}" for session ${sessionId}:`, err)
-  );
+function toTunnelHostname(url) {
+  return new URL(url).host;
 }
-function watchAgentActivity(supabase, config, projectId, cardId, sessionId, pty) {
-  const watcher = new AgentActivityWatcher((state) => {
-    publishAgentState(supabase, projectId, cardId, sessionId, state);
-    if (state === "usage_limited") {
-      scheduleUsageResume(supabase, config, cardId, sessionId, pty);
-    } else {
-      cancelUsageResume(sessionId);
-    }
-    if (state === "done" || state === "waiting_prototype_review") void dispatchRunnerQueue(supabase, config);
-  });
-  pty.onData((chunk) => watcher.push(chunk));
-  registerAgentActivityWatcher(sessionId, watcher);
-  return watcher;
+
+// src/devServer.ts
+var STARTUP_TIMEOUT_MS2 = 45e3;
+var IS_WINDOWS3 = process.platform === "win32";
+var LOCAL_URL_PORT_RE = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0):(\d{2,5})/i;
+var GENERIC_PORT_RE = /(?:listening|running|server).{0,40}?:?\s*(\d{4,5})\b/i;
+var ANSI_ESCAPE_RE2 = /\x1b\[[0-9;]*m/g;
+function detectPortFromOutput(chunk) {
+  const clean = chunk.replace(ANSI_ESCAPE_RE2, "");
+  const match = LOCAL_URL_PORT_RE.exec(clean) ?? GENERIC_PORT_RE.exec(clean);
+  return match ? Number(match[1]) : null;
 }
-async function pauseFinishedSession(supabase, config, projectId, cardId, sessionId) {
-  const paused = await pauseRunningSession(supabase, sessionId, { projectId, cardId, userId: config.ownerUserId });
-  if (!paused) return;
-  setPtySessionReadOnly(sessionId, true);
-  logger.card.info(cardId, `Session ${sessionId} paused (agent reached "done", another session needs this project's WIP slot).`);
+function killProcessTree(child2) {
+  if (child2.pid == null) return;
+  if (IS_WINDOWS3) {
+    spawn5("taskkill", ["/pid", String(child2.pid), "/t", "/f"], { stdio: "ignore" });
+  } else {
+    child2.kill();
+  }
 }
-async function requeuePausedCard(supabase, config, card) {
-  const active = await getActiveSessionForCard(supabase, card.id);
-  if (!active) return;
-  if (active.status === "paused") {
-    await updateSession(
-      supabase,
-      active.id,
-      { status: "queued" },
-      { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
-    );
-    await updateCard(supabase, card.id, { requeueRequestedAt: null });
-    logger.card.info(card.id, `Session ${active.id} requeued at the front of the line (was paused).`);
-    await dispatchRunnerQueue(supabase, config);
-    return;
+var previews = /* @__PURE__ */ new Map();
+function ensurePreview(key, label, cwd, command2, cardId, extraEnv = {}) {
+  const existing = previews.get(key);
+  if (existing) {
+    existing.cardIds.add(cardId);
+    return existing.result;
   }
-  if (active.status === "running" && active.agentState === "waiting_prototype_review") {
-    const handle = getPtySession(active.id);
-    await updateCard(supabase, card.id, { requeueRequestedAt: null });
-    if (handle && !handle.exited) {
-      sendMessageToIdleSession(handle.pty, card.id, buildPrototypeReviewFollowUp(card.prototype_approved, card.prototype_url));
-      logger.card.info(card.id, `Session ${active.id} was never paused (alone in its project) \u2014 sent the prototype review follow-up directly.`);
-    }
+  let child2;
+  try {
+    child2 = spawn5(command2, { cwd, shell: true, windowsHide: true, env: { ...process.env, ...extraEnv } });
+  } catch (err) {
+    logger.runner.error("DEV_SERVER", `Failed to spawn "${command2}" in ${cwd}:`, err);
+    return Promise.resolve(null);
   }
-}
-async function reconcileOrphanedSessions(supabase, config) {
-  for (const project of config.registeredProjects) {
-    const { data, error } = await supabase.from("sessions").select(
-      "id, card_id, claude_session_id, agent_state, created_at, status, cards!card_id!inner(project_id, assigned_user_id, title, instructions, file_references, plan_first)"
-    ).eq("cards.project_id", project.id).eq("cards.assigned_user_id", config.ownerUserId).in("status", ["running", "paused"]);
-    if (error) {
-      logger.runner.error("ORCHESTRATOR", `Failed to scan orphaned sessions for project ${project.id}:`, error.message);
-      continue;
-    }
-    for (const entry of data ?? []) {
-      let spawned;
-      try {
-        spawned = await spawnSessionPty(supabase, config, entry);
-      } catch (err) {
-        logger.card.error(entry.card_id, `Failed to re-spawn orphaned session ${entry.id}:`, err);
-        continue;
+  const entry = { child: child2, tunnelChild: null, cardIds: /* @__PURE__ */ new Set([cardId]), result: null };
+  entry.result = new Promise((resolve5) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (!value) {
+        killProcessTree(child2);
+        previews.delete(key);
       }
-      if (!spawned) continue;
-      if (entry.status === "paused") {
-        await updateSession(
-          supabase,
-          entry.id,
-          { status: "paused" },
-          { projectId: project.id, cardId: entry.card_id, userId: config.ownerUserId }
-        );
-        setPtySessionReadOnly(entry.id, true);
-        logger.card.info(entry.card_id, "Re-spawned paused session (runner restarted) \u2014 still read-only until requeued.");
-      } else {
-        logger.card.info(entry.card_id, "Re-spawned orphaned session (runner restarted since it was last running).");
+      resolve5(value);
+    };
+    const timer = setTimeout(() => {
+      logger.runner.warn("DEV_SERVER", `"${command2}" in ${cwd} did not reveal a port within ${STARTUP_TIMEOUT_MS2}ms.`);
+      settle(null);
+    }, STARTUP_TIMEOUT_MS2);
+    const onOutput = async (chunk) => {
+      if (settled) return;
+      const port = detectPortFromOutput(chunk.toString("utf-8"));
+      if (port == null) return;
+      settled = true;
+      clearTimeout(timer);
+      const tunnel = await startQuickTunnel(`dev server ${key}`, port);
+      if (!tunnel) {
+        logger.runner.warn("DEV_SERVER", `Detected port ${port} for ${key} but cloudflared could not tunnel it.`);
+        killProcessTree(child2);
+        previews.delete(key);
+        resolve5(null);
+        return;
       }
-    }
+      entry.tunnelChild = tunnel.child;
+      logger.runner.info("DEV_SERVER", `${key} is up on port ${port}, tunneled at ${tunnel.url}.`);
+      resolve5({ label, url: tunnel.url });
+    };
+    child2.stdout?.on("data", onOutput);
+    child2.stderr?.on("data", onOutput);
+    child2.on("error", (err) => {
+      logger.runner.error("DEV_SERVER", `Dev server process error for ${key} (${command2} in ${cwd}):`, err);
+      settle(null);
+    });
+    child2.on("exit", (code) => {
+      logger.runner.info("DEV_SERVER", `Dev server for ${key} exited (code ${code}) before/without a usable preview.`);
+      settle(null);
+    });
+  });
+  previews.set(key, entry);
+  return entry.result;
+}
+function releaseCard(cardId) {
+  for (const [key, entry] of previews) {
+    if (!entry.cardIds.delete(cardId)) continue;
+    if (entry.cardIds.size > 0) continue;
+    killProcessTree(entry.child);
+    entry.tunnelChild?.kill();
+    previews.delete(key);
   }
 }
-async function reconcileUsageLimitedSessions(supabase, config) {
-  for (const project of config.registeredProjects) {
-    const { data, error } = await supabase.from("sessions").select("id, card_id, cards!card_id!inner(project_id, assigned_user_id)").eq("cards.project_id", project.id).eq("cards.assigned_user_id", config.ownerUserId).eq("status", "running").eq("agent_state", "usage_limited");
-    if (error) {
-      logger.runner.error("ORCHESTRATOR", `Failed to scan usage-limited sessions for project ${project.id}:`, error.message);
-      continue;
-    }
-    for (const { id: sessionId, card_id: cardId } of data ?? []) {
-      const handle = getPtySession(sessionId);
-      if (!handle) continue;
-      scheduleUsageResume(supabase, config, cardId, sessionId, handle.pty);
-    }
+function stopProjectPreviews(projectId) {
+  const prefix = `${projectId}:`;
+  for (const [key, entry] of previews) {
+    if (!key.startsWith(prefix)) continue;
+    killProcessTree(entry.child);
+    entry.tunnelChild?.kill();
+    previews.delete(key);
   }
 }
-async function stopCardSession(supabase, config, card) {
-  const sessionId = activeSessionByCard.get(card.id) ?? (await getActiveSessionForCard(supabase, card.id))?.id;
-  if (!sessionId) return;
-  intentionallyStoppedSessionIds.add(sessionId);
-  stopPtySession(sessionId);
-  cancelUsageResume(sessionId);
-  activeSessionByCard.delete(card.id);
-  await updateSession(
-    supabase,
-    sessionId,
-    {
-      status: "done",
-      endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      ...card.column_name === "fim" ? { agentState: "done" } : {}
-    },
-    { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
-  );
-  logger.card.info(card.id, `Session ${sessionId} stopped.`);
-  await dispatchRunnerQueue(supabase, config);
+function stopAll() {
+  for (const key of [...previews.keys()]) {
+    const entry = previews.get(key);
+    if (!entry) continue;
+    killProcessTree(entry.child);
+    entry.tunnelChild?.kill();
+    previews.delete(key);
+  }
 }
-async function restartCardSession(supabase, config, card) {
-  const sessionId = activeSessionByCard.get(card.id) ?? (await getActiveSessionForCard(supabase, card.id))?.id;
-  if (sessionId) {
-    intentionallyStoppedSessionIds.add(sessionId);
-    stopPtySession(sessionId);
-    cancelUsageResume(sessionId);
-    activeSessionByCard.delete(card.id);
-    await updateSession(
-      supabase,
-      sessionId,
-      { status: "failed", claudeSessionId: null, endedAt: (/* @__PURE__ */ new Date()).toISOString() },
-      { projectId: card.project_id, cardId: card.id, userId: config.ownerUserId }
-    );
-    logger.card.info(card.id, `Session ${sessionId} abandoned by "Reiniciar sess\xE3o"; starting a fresh one.`);
+
+// src/git.ts
+import { execFile as execFile4 } from "node:child_process";
+import { promisify as promisify5 } from "node:util";
+var execFileAsync4 = promisify5(execFile4);
+async function pushBranchToMain(repoPath) {
+  try {
+    await execFileAsync4("git", ["push", "origin", "HEAD:main"], { cwd: repoPath });
+    return { ok: true };
+  } catch (err) {
+    const stderr = err.stderr;
+    const error = stderr?.trim() || (err instanceof Error ? err.message : String(err));
+    return { ok: false, error };
   }
-  await updateCard(supabase, card.id, { restartRequestedAt: null });
-  await enqueueCard(supabase, config, card);
 }
 
 // src/deploy.ts
@@ -3490,7 +3654,9 @@ async function handleDeployRequested(supabase, config, project) {
 }
 async function runDeploy(supabase, config, project) {
   const allCards = await listCardsInColumn(supabase, project.id, "deploy");
-  const cards = allCards.filter((card) => card.assigned_user_id === config.ownerUserId);
+  const cards = (await Promise.all(allCards.map(async (card) => await isEffectiveOwner(supabase, card, config) ? card : null))).filter(
+    (card) => card !== null
+  );
   if (cards.length === 0) {
     logger.runner.info("DEPLOY", `Deploy requested for project ${project.id} but no cards assigned to this runner's user are waiting in "deploy".`);
     await clearProjectDeployRequest(supabase, project.id);
@@ -3570,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;
@@ -3667,7 +3847,7 @@ async function checkPendingPreviews(supabase, config) {
   for (const registered of config.registeredProjects) {
     const cards = await listCardsInColumn(supabase, registered.id, "revisao");
     for (const card of cards) {
-      if (card.assigned_user_id !== config.ownerUserId) continue;
+      if (!await isEffectiveOwner(supabase, card, config)) continue;
       if (card.preview_urls.length > 0) continue;
       await handleCardEnteredRevisao(supabase, config, card);
     }
@@ -3682,7 +3862,9 @@ async function handleDevServerRestartRequested(supabase, config, project) {
   }
   stopProjectPreviews(project.id);
   const allCards = await listCardsInColumn(supabase, project.id, "revisao");
-  const cards = allCards.filter((card) => card.assigned_user_id === config.ownerUserId);
+  const cards = (await Promise.all(allCards.map(async (card) => await isEffectiveOwner(supabase, card, config) ? card : null))).filter(
+    (card) => card !== null
+  );
   if (cards.length === 0) {
     logger.runner.info("REVIEW", `Dev server restart requested for project ${project.id} but no card assigned to this runner's user is in "revisao" \u2014 nothing to respawn.`);
     await clearDevServerRestartRequest(supabase, project.id);
@@ -3815,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",
@@ -3823,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);
@@ -3838,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);
     }
@@ -3863,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) {
@@ -4042,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,
@@ -4059,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.");
@@ -4089,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;
@@ -4099,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)");