agent-board-runner 0.1.7 → 0.1.8

package/dist/cli.js

@@ -202,7 +202,7 @@ var BOX_DRAWING_PATTERN = /[─-╿]/g;
 var WORKING_PATTERN = /esc to interrupt/i;
 var BACKGROUND_SHELL_PATTERN = /\b[1-9]\d*\s+shells?\b/i;
 function isAgentHookMoment(value) {
-  return value === "implementing" || value === "tool_active" || value === "waiting_plan_approval" || value === "commit_detected" || value === "turn_stopped" || value === "notification";
+  return value === "implementing" || value === "tool_active" || value === "waiting_plan_approval" || value === "waiting_prototype_review" || value === "commit_detected" || value === "turn_stopped" || value === "notification";
 }
 var USAGE_LIMIT_PATTERN = /(usage limit reached|limit reached[^\n]{0,60}resets|reached your (?:usage|session) limit|out of (?:weekly|session) (?:usage|limit))/i;
 var PLAN_APPROVAL_PATTERN = /would you like to proceed\??/i;
@@ -246,6 +246,14 @@ var AgentActivityWatcher = class {
   lastOutputAt = Date.now();
   usageLimited = false;
   planApprovalPending = false;
+  /**
+   * Latched like planApprovalPending, but with no text-fallback path: there is no on-screen CLI
+   * prompt for this (see publish_prototype / docs/ai-knowledges/prototipacao-visual.md), only the
+   * PostToolUse hook. The agent's own instructions have it stop the turn right after calling that
+   * tool, so the Stop event normally right behind it must not downgrade this to "done"/
+   * "waiting_user" — see the guard in reportHookMoment's "turn_stopped" case.
+   */
+  prototypeReviewPending = false;
   toolCallPending = false;
   commitDetected = false;
   timer;
@@ -287,6 +295,7 @@ var AgentActivityWatcher = class {
       case "implementing":
         this.usageLimited = false;
         this.planApprovalPending = false;
+        this.prototypeReviewPending = false;
         this.commitDetected = false;
         this.setState("implementing");
         break;
@@ -298,11 +307,16 @@ var AgentActivityWatcher = class {
         this.planApprovalPending = true;
         this.setState("waiting_plan_approval");
         break;
+      case "waiting_prototype_review":
+        this.prototypeReviewPending = true;
+        this.setState("waiting_prototype_review");
+        break;
       case "commit_detected":
         this.commitDetected = true;
         break;
       case "turn_stopped":
         if (this.usageLimited) break;
+        if (this.prototypeReviewPending) break;
         if (BACKGROUND_SHELL_PATTERN.test(this.recentOutput())) {
           this.setState("waiting_background");
           break;
@@ -767,7 +781,7 @@ async function getRunningSessionForProject(supabase, projectId, ownerUserId) {
 }
 async function listQueuedSessionsForRunner(supabase, ownerUserId) {
   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)"
+    "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 });
   if (error) throw error;
   return data;
@@ -814,9 +828,11 @@ async function updateSession(supabase, sessionId, changes, activityContext) {
   }
 }
 async function getActiveSessionForCard(supabase, cardId) {
-  const { data, error } = await supabase.from("sessions").select("id, status").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").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
-  return data;
+  if (!data) return null;
+  const row = data;
+  return { id: row.id, status: row.status, agentState: row.agent_state };
 }
 async function pauseRunningSession(supabase, sessionId, activityContext) {
   const { data, error } = await supabase.from("sessions").update({ status: "paused" }).eq("id", sessionId).eq("status", "running").select("id");
@@ -839,6 +855,10 @@ async function getLastClaudeSessionIdForCard(supabase, cardId) {
   return data?.claude_session_id ?? null;
 }
 async function getLatestAgentStateForCard(supabase, cardId) {
+  const { data: card, error: cardError } = await supabase.from("cards").select("column_name").eq("id", cardId).maybeSingle();
+  if (cardError) throw cardError;
+  const column = card?.column_name;
+  if (column && BOARD_COLUMNS.indexOf(column) > BOARD_COLUMNS.indexOf("desenvolvimento")) return "done";
   const { data, error } = await supabase.from("sessions").select("agent_state").eq("card_id", cardId).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
   return data?.agent_state ?? null;
@@ -1063,6 +1083,13 @@ function detectMoment(input) {
   // or self-corrects within a beat \u2014 never gets stuck on "waiting_plan_approval" forever.
   if (eventName === "PostToolUse" && input.tool_name === "ExitPlanMode") return "implementing";
 
+  // The agent just published a prototype Artifact and recorded it on the card (see
+  // publish_prototype in boardTools.ts and docs/ai-knowledges/prototipacao-visual.md). Its own
+  // instructions tell it to stop the turn right after this call, so the Stop event normally
+  // right behind this one must not downgrade this to "turn_stopped" \u2014 see the
+  // prototypeReviewPending latch in agentActivity.ts's reportHookMoment.
+  if (eventName === "PostToolUse" && input.tool_name === "mcp__agent-board__publish_prototype") return "waiting_prototype_review";
+
   // A commit that actually succeeded, read off the Bash tool's own structured result instead
   // of guessing from scrollback text (exact, and immune to locale/color/format changes to
   // git's own banner). Any other Bash completion still reports "tool_active" below, same as
@@ -2834,18 +2861,18 @@ async function enterPlanMode(pty, cardId) {
     subscription.dispose();
   }
 }
-function sendContinue(pty, cardId) {
+function sendMessageToIdleSession(pty, cardId, message) {
   try {
-    pty.write(`${PASTE_START}continue${PASTE_END}`);
+    pty.write(`${PASTE_START}${message}${PASTE_END}`);
     setTimeout(() => {
       try {
         pty.write("\r");
       } catch (err) {
-        logger.card.error(cardId, 'Failed to submit the auto-resume "continue" message:', 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 the auto-resume "continue" message:', err);
+    logger.card.error(cardId, "Failed to send a message to the idle session:", err);
   }
 }
 function resumeAgentPty(repoPath, claudeSessionId, sessionId, ticket) {
@@ -2931,6 +2958,46 @@ function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
 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.`;
 }
 
+// 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.`;
+}
+
 // src/usageResume.ts
 var RESET_BUFFER_MS = 3e4;
 var UNKNOWN_RESET_RETRY_MS = 5 * 6e4;
@@ -2952,7 +3019,7 @@ function scheduleUsageResume(supabase, config, cardId, sessionId, pty) {
     );
     const timer = setTimeout(() => {
       pending.delete(sessionId);
-      sendContinue(pty, cardId);
+      sendMessageToIdleSession(pty, cardId, "continue");
     }, delay);
     timer.unref();
     pending.set(sessionId, timer);
@@ -3020,7 +3087,7 @@ async function reconcileStaleSessions(supabase, config, projectId) {
   }
   const stale = data ?? [];
   if (stale.length === 0) return;
-  for (const { id: sessionId, card_id: cardId } of stale) {
+  for (const { id: sessionId, card_id: cardId, cards } of stale) {
     intentionallyStoppedSessionIds.add(sessionId);
     stopPtySession(sessionId);
     cancelUsageResume(sessionId);
@@ -3028,7 +3095,13 @@ async function reconcileStaleSessions(supabase, config, projectId) {
     await updateSession(
       supabase,
       sessionId,
-      { status: "done", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+      {
+        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).`);
@@ -3039,6 +3112,7 @@ async function dispatchRunnerQueue(supabase, config) {
   if (dispatchingRunner) return;
   dispatchingRunner = true;
   let queued = [];
+  const promotedCardIds = /* @__PURE__ */ new Set();
   try {
     queued = await listQueuedSessionsForRunner(supabase, config.ownerUserId);
     if (queued.length === 0) return;
@@ -3048,7 +3122,7 @@ async function dispatchRunnerQueue(supabase, config) {
     for (const project of config.registeredProjects) {
       const running = await getRunningSessionForProject(supabase, project.id, config.ownerUserId);
       if (!running) continue;
-      if (running.agentState === "done" && queuedProjectIds.has(project.id)) {
+      if ((running.agentState === "done" || running.agentState === "waiting_prototype_review") && queuedProjectIds.has(project.id)) {
         await pauseFinishedSession(supabase, config, project.id, running.cardId, running.id);
         continue;
       }
@@ -3075,22 +3149,24 @@ async function dispatchRunnerQueue(supabase, config) {
       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).catch(
+    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) {
+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);
@@ -3108,6 +3184,9 @@ async function publishQueueSnapshots(supabase, config, queued) {
     });
   }
 }
+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) {
@@ -3120,6 +3199,13 @@ async function promoteQueuedSession(supabase, config, entry) {
     );
     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)
+      );
+    }
     return;
   }
   const spawned = await spawnSessionPty(supabase, config, entry);
@@ -3151,9 +3237,12 @@ async function spawnSessionPty(supabase, config, entry) {
     } else {
       const attachmentPaths = await downloadCardAttachments(supabase, cardId);
       const instructions = buildInstructionsWithMcpContext(
-        buildInstructionsWithFileReferences(
-          buildInstructionsWithAttachments(card.instructions, attachmentPaths),
-          card.file_references
+        buildInstructionsWithPrototypeGate(
+          buildInstructionsWithFileReferences(
+            buildInstructionsWithAttachments(card.instructions, attachmentPaths),
+            card.file_references
+          ),
+          card.prototype_first
         ),
         cardId,
         card.project_id
@@ -3233,7 +3322,7 @@ function watchAgentActivity(supabase, config, projectId, cardId, sessionId, pty)
     } else {
       cancelUsageResume(sessionId);
     }
-    if (state === "done") void dispatchRunnerQueue(supabase, config);
+    if (state === "done" || state === "waiting_prototype_review") void dispatchRunnerQueue(supabase, config);
   });
   pty.onData((chunk) => watcher.push(chunk));
   registerAgentActivityWatcher(sessionId, watcher);
@@ -3247,16 +3336,27 @@ async function pauseFinishedSession(supabase, config, projectId, cardId, session
 }
 async function requeuePausedCard(supabase, config, card) {
   const active = await getActiveSessionForCard(supabase, card.id);
-  if (!active || active.status !== "paused") return;
-  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);
+  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;
+  }
+  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.`);
+    }
+  }
 }
 async function reconcileOrphanedSessions(supabase, config) {
   for (const project of config.registeredProjects) {
@@ -3315,7 +3415,11 @@ async function stopCardSession(supabase, config, card) {
   await updateSession(
     supabase,
     sessionId,
-    { status: "done", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+    {
+      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.`);

package/dist/index.js

@@ -40,7 +40,7 @@ var BOX_DRAWING_PATTERN = /[─-╿]/g;
 var WORKING_PATTERN = /esc to interrupt/i;
 var BACKGROUND_SHELL_PATTERN = /\b[1-9]\d*\s+shells?\b/i;
 function isAgentHookMoment(value) {
-  return value === "implementing" || value === "tool_active" || value === "waiting_plan_approval" || value === "commit_detected" || value === "turn_stopped" || value === "notification";
+  return value === "implementing" || value === "tool_active" || value === "waiting_plan_approval" || value === "waiting_prototype_review" || value === "commit_detected" || value === "turn_stopped" || value === "notification";
 }
 var USAGE_LIMIT_PATTERN = /(usage limit reached|limit reached[^\n]{0,60}resets|reached your (?:usage|session) limit|out of (?:weekly|session) (?:usage|limit))/i;
 var PLAN_APPROVAL_PATTERN = /would you like to proceed\??/i;
@@ -84,6 +84,14 @@ var AgentActivityWatcher = class {
   lastOutputAt = Date.now();
   usageLimited = false;
   planApprovalPending = false;
+  /**
+   * Latched like planApprovalPending, but with no text-fallback path: there is no on-screen CLI
+   * prompt for this (see publish_prototype / docs/ai-knowledges/prototipacao-visual.md), only the
+   * PostToolUse hook. The agent's own instructions have it stop the turn right after calling that
+   * tool, so the Stop event normally right behind it must not downgrade this to "done"/
+   * "waiting_user" — see the guard in reportHookMoment's "turn_stopped" case.
+   */
+  prototypeReviewPending = false;
   toolCallPending = false;
   commitDetected = false;
   timer;
@@ -125,6 +133,7 @@ var AgentActivityWatcher = class {
       case "implementing":
         this.usageLimited = false;
         this.planApprovalPending = false;
+        this.prototypeReviewPending = false;
         this.commitDetected = false;
         this.setState("implementing");
         break;
@@ -136,11 +145,16 @@ var AgentActivityWatcher = class {
         this.planApprovalPending = true;
         this.setState("waiting_plan_approval");
         break;
+      case "waiting_prototype_review":
+        this.prototypeReviewPending = true;
+        this.setState("waiting_prototype_review");
+        break;
       case "commit_detected":
         this.commitDetected = true;
         break;
       case "turn_stopped":
         if (this.usageLimited) break;
+        if (this.prototypeReviewPending) break;
         if (BACKGROUND_SHELL_PATTERN.test(this.recentOutput())) {
           this.setState("waiting_background");
           break;
@@ -605,7 +619,7 @@ async function getRunningSessionForProject(supabase, projectId, ownerUserId) {
 }
 async function listQueuedSessionsForRunner(supabase, ownerUserId) {
   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)"
+    "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 });
   if (error) throw error;
   return data;
@@ -652,9 +666,11 @@ async function updateSession(supabase, sessionId, changes, activityContext) {
   }
 }
 async function getActiveSessionForCard(supabase, cardId) {
-  const { data, error } = await supabase.from("sessions").select("id, status").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").eq("card_id", cardId).in("status", ["queued", "running", "waiting_input", "paused"]).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
-  return data;
+  if (!data) return null;
+  const row = data;
+  return { id: row.id, status: row.status, agentState: row.agent_state };
 }
 async function pauseRunningSession(supabase, sessionId, activityContext) {
   const { data, error } = await supabase.from("sessions").update({ status: "paused" }).eq("id", sessionId).eq("status", "running").select("id");
@@ -677,6 +693,10 @@ async function getLastClaudeSessionIdForCard(supabase, cardId) {
   return data?.claude_session_id ?? null;
 }
 async function getLatestAgentStateForCard(supabase, cardId) {
+  const { data: card, error: cardError } = await supabase.from("cards").select("column_name").eq("id", cardId).maybeSingle();
+  if (cardError) throw cardError;
+  const column = card?.column_name;
+  if (column && BOARD_COLUMNS.indexOf(column) > BOARD_COLUMNS.indexOf("desenvolvimento")) return "done";
   const { data, error } = await supabase.from("sessions").select("agent_state").eq("card_id", cardId).order("created_at", { ascending: false }).limit(1).maybeSingle();
   if (error) throw error;
   return data?.agent_state ?? null;
@@ -901,6 +921,13 @@ function detectMoment(input) {
   // or self-corrects within a beat \u2014 never gets stuck on "waiting_plan_approval" forever.
   if (eventName === "PostToolUse" && input.tool_name === "ExitPlanMode") return "implementing";
 
+  // The agent just published a prototype Artifact and recorded it on the card (see
+  // publish_prototype in boardTools.ts and docs/ai-knowledges/prototipacao-visual.md). Its own
+  // instructions tell it to stop the turn right after this call, so the Stop event normally
+  // right behind this one must not downgrade this to "turn_stopped" \u2014 see the
+  // prototypeReviewPending latch in agentActivity.ts's reportHookMoment.
+  if (eventName === "PostToolUse" && input.tool_name === "mcp__agent-board__publish_prototype") return "waiting_prototype_review";
+
   // A commit that actually succeeded, read off the Bash tool's own structured result instead
   // of guessing from scrollback text (exact, and immune to locale/color/format changes to
   // git's own banner). Any other Bash completion still reports "tool_active" below, same as
@@ -2773,18 +2800,18 @@ async function enterPlanMode(pty, cardId) {
     subscription.dispose();
   }
 }
-function sendContinue(pty, cardId) {
+function sendMessageToIdleSession(pty, cardId, message) {
   try {
-    pty.write(`${PASTE_START}continue${PASTE_END}`);
+    pty.write(`${PASTE_START}${message}${PASTE_END}`);
     setTimeout(() => {
       try {
         pty.write("\r");
       } catch (err) {
-        logger.card.error(cardId, 'Failed to submit the auto-resume "continue" message:', 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 the auto-resume "continue" message:', err);
+    logger.card.error(cardId, "Failed to send a message to the idle session:", err);
   }
 }
 function resumeAgentPty(repoPath, claudeSessionId, sessionId, ticket) {
@@ -2870,6 +2897,46 @@ function buildInstructionsWithMcpContext(instructions, cardId, projectId) {
 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.`;
 }
 
+// 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.`;
+}
+
 // src/usageResume.ts
 var RESET_BUFFER_MS = 3e4;
 var UNKNOWN_RESET_RETRY_MS = 5 * 6e4;
@@ -2891,7 +2958,7 @@ function scheduleUsageResume(supabase, config, cardId, sessionId, pty) {
     );
     const timer = setTimeout(() => {
       pending.delete(sessionId);
-      sendContinue(pty, cardId);
+      sendMessageToIdleSession(pty, cardId, "continue");
     }, delay);
     timer.unref();
     pending.set(sessionId, timer);
@@ -2959,7 +3026,7 @@ async function reconcileStaleSessions(supabase, config, projectId) {
   }
   const stale = data ?? [];
   if (stale.length === 0) return;
-  for (const { id: sessionId, card_id: cardId } of stale) {
+  for (const { id: sessionId, card_id: cardId, cards } of stale) {
     intentionallyStoppedSessionIds.add(sessionId);
     stopPtySession(sessionId);
     cancelUsageResume(sessionId);
@@ -2967,7 +3034,13 @@ async function reconcileStaleSessions(supabase, config, projectId) {
     await updateSession(
       supabase,
       sessionId,
-      { status: "done", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+      {
+        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).`);
@@ -2978,6 +3051,7 @@ async function dispatchRunnerQueue(supabase, config) {
   if (dispatchingRunner) return;
   dispatchingRunner = true;
   let queued = [];
+  const promotedCardIds = /* @__PURE__ */ new Set();
   try {
     queued = await listQueuedSessionsForRunner(supabase, config.ownerUserId);
     if (queued.length === 0) return;
@@ -2987,7 +3061,7 @@ async function dispatchRunnerQueue(supabase, config) {
     for (const project of config.registeredProjects) {
       const running = await getRunningSessionForProject(supabase, project.id, config.ownerUserId);
       if (!running) continue;
-      if (running.agentState === "done" && queuedProjectIds.has(project.id)) {
+      if ((running.agentState === "done" || running.agentState === "waiting_prototype_review") && queuedProjectIds.has(project.id)) {
         await pauseFinishedSession(supabase, config, project.id, running.cardId, running.id);
         continue;
       }
@@ -3014,22 +3088,24 @@ async function dispatchRunnerQueue(supabase, config) {
       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).catch(
+    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) {
+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);
@@ -3047,6 +3123,9 @@ async function publishQueueSnapshots(supabase, config, queued) {
     });
   }
 }
+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) {
@@ -3059,6 +3138,13 @@ async function promoteQueuedSession(supabase, config, entry) {
     );
     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)
+      );
+    }
     return;
   }
   const spawned = await spawnSessionPty(supabase, config, entry);
@@ -3090,9 +3176,12 @@ async function spawnSessionPty(supabase, config, entry) {
     } else {
       const attachmentPaths = await downloadCardAttachments(supabase, cardId);
       const instructions = buildInstructionsWithMcpContext(
-        buildInstructionsWithFileReferences(
-          buildInstructionsWithAttachments(card.instructions, attachmentPaths),
-          card.file_references
+        buildInstructionsWithPrototypeGate(
+          buildInstructionsWithFileReferences(
+            buildInstructionsWithAttachments(card.instructions, attachmentPaths),
+            card.file_references
+          ),
+          card.prototype_first
         ),
         cardId,
         card.project_id
@@ -3172,7 +3261,7 @@ function watchAgentActivity(supabase, config, projectId, cardId, sessionId, pty)
     } else {
       cancelUsageResume(sessionId);
     }
-    if (state === "done") void dispatchRunnerQueue(supabase, config);
+    if (state === "done" || state === "waiting_prototype_review") void dispatchRunnerQueue(supabase, config);
   });
   pty.onData((chunk) => watcher.push(chunk));
   registerAgentActivityWatcher(sessionId, watcher);
@@ -3186,16 +3275,27 @@ async function pauseFinishedSession(supabase, config, projectId, cardId, session
 }
 async function requeuePausedCard(supabase, config, card) {
   const active = await getActiveSessionForCard(supabase, card.id);
-  if (!active || active.status !== "paused") return;
-  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);
+  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;
+  }
+  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.`);
+    }
+  }
 }
 async function reconcileOrphanedSessions(supabase, config) {
   for (const project of config.registeredProjects) {
@@ -3254,7 +3354,11 @@ async function stopCardSession(supabase, config, card) {
   await updateSession(
     supabase,
     sessionId,
-    { status: "done", endedAt: (/* @__PURE__ */ new Date()).toISOString() },
+    {
+      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.`);

package/package.json

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