@oar-sh/oar 0.9.19 → 0.9.21

package/server/routes/messages-routes.mjs

@@ -15,6 +15,7 @@ import {
 } from '../services/relay-queue-gate-service.mjs';
 import {
   persistConversationModelPreference as persistConversationModelPreferenceTx,
+  readPlanOnly,
 } from '../services/conversation-preferences-service.mjs';
 import { fallbackReasoningEffort, inheritedConversationModel } from '../services/conversation-model-fallback.mjs';
 import { killTmuxSession } from '../services/session-worker-launch-service.mjs';
@@ -44,6 +45,7 @@ import { DEFAULT_CLAUDE_REASONING_EFFORTS } from '../services/provider-reasoning
 import { claudeBaseModelId, claudeLongContextModelId } from '../../shared/model-id.mjs';
 import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
 import { normalizeBackgroundTaskDigest } from '../../shared/worker-runtime/background-task-digest.mjs';
+import { normalizeBuildId } from '../../shared/build-id.mjs';
 import {
   DEFAULT_TASK_STALL_MINUTES,
   TASK_OUTPUT_LIMITS,
@@ -86,8 +88,11 @@ import {
 import { TASK_OUTPUT_NONE_MESSAGES } from '../public/app/task-console-render.mjs';
 import { recordClaudeCliStart } from '../services/claude-session-leftovers.mjs';
 import { normalizeClaudeBilling } from '../services/claude-billing-switch-service.mjs';
+import { normalizeTurnTokenUsageReport } from '../../shared/turn-token-usage.mjs';
 import { createClaudeApiStopNoteLedger } from '../services/plan-usage-claude-api.mjs';
 import { normalizeClaudeApiUsageReport } from '../services/claude-api-usage-service.mjs';
+import { planBoundaryHoldSql } from '../repositories/message-repository.mjs';
+import { PLAN_ONLY_REFUSAL, planOnlyRefusesMode } from '../../shared/plan-only.mjs';
 import {
   admitRemoteRelayRequest,
   readRemoteRelayRequest,
@@ -921,6 +926,23 @@ export function resolveResponderConversationMismatch({
   };
 }
 
+/**
+ * Whether a pending row must wait for its conversation's live turn to end
+ * instead of being handed to the worker, which would steer it into that turn.
+ * A steer switches the live turn's mode (the Claude worker re-applies the
+ * permission mode on every delivery), so across plan mode it would change
+ * what the running turn may do: an "Approve plan" follow-up would give a
+ * running plan turn write access, and a plan message would take it from a
+ * running write turn. Rows on the same side of plan mode steer as before.
+ */
+export function crossesPlanBoundaryOfLiveTurn({ stmts, row } = {}) {
+  const conversationId = String(row?.conversation_id || '').trim();
+  if (!conversationId || typeof stmts?.listProcessingQueueByConversation?.all !== 'function') return false;
+  const isPlan = (mode) => String(mode || '').trim().toLowerCase() === 'plan';
+  const pendingIsPlan = isPlan(row.relay_mode);
+  return stmts.listProcessingQueueByConversation.all(conversationId)
+    .some((live) => String(live?.id || '') !== String(row.id || '') && isPlan(live?.relay_mode) !== pendingIsPlan);
+}
 export function dequeuePendingMessage({
   db,
   stmts,
@@ -970,6 +992,10 @@ export function dequeuePendingMessage({
         : stmts.findPending.get(currentIso);
     }
     if (!next) return null;
+    // Across plan mode, a row waits for the live turn instead of steering in.
+    // The claim statements leave such rows out (planBoundaryHoldSql); this is
+    // the fail-closed backstop for one that does not.
+    if (crossesPlanBoundaryOfLiveTurn({ stmts, row: next })) return null;
     // One processing attempt = one attempt_id. Minted here for every claim —
     // even for callers that never echo it back — so finalization, requeue, and
     // question writes can be fenced to the attempt that actually owns the row.
@@ -1176,6 +1202,12 @@ export async function dequeuePendingMessageForWorkerLoop({
   workerKind = null,
   onBillingFence = null,
   claudeApiClaimCheck = null,
+  // () → true while the replacement fence (services/worker-replacement.mjs)
+  // is up for the requesting process. The caller asks it before calling; it
+  // is asked again before every claim, since ensureWorker and a transient
+  // error's backoff both wait, and the worker recycle can raise the fence
+  // meanwhile.
+  isReplacementFenced = null,
 } = {}) {
   const requesterSid = normalizeSessionWorkerId(requesterSessionId);
   const routingWithWorker = routingEnabled && requesterSid;
@@ -1250,6 +1282,18 @@ export async function dequeuePendingMessageForWorkerLoop({
 
   let attempt = 0;
   while (attempt <= retryLimit) {
+    // The process asking is being replaced: no row is claimed for it, the
+    // same answer as the caller's own fence check gives.
+    if (routingWithWorker && typeof isReplacementFenced === 'function' && isReplacementFenced() === true) {
+      return {
+        message: null,
+        blockedReason: 'worker-replacement',
+        worker: supervisor?.getWorkerState?.(requesterSid) || null,
+        lifecycle: supervisor?.getLifecycleState?.(requesterSid) || null,
+        fallbackRestart: null,
+        attempts: attempt,
+      };
+    }
     const currentIso = String(nowIso || '').trim() || new Date().toISOString();
     try {
       const message = dequeuePendingMessage({
@@ -2040,6 +2084,9 @@ export function registerMessagesRoutes(app, deps) {
     // killTmuxSessionImpl). Tests must inject these instead of relying on the
     // host OS, so the suite behaves identically on Windows and POSIX.
     sessionWorkerStopOverrides = null,
+    // The replacement fence (services/worker-replacement.mjs): a worker
+    // process the recycle is replacing is handed no work by /api/pending.
+    workerReplacementFence = null,
     resolveSessionStateRoot,
     fetchUsageSummary = null,
     planUsageService = null,
@@ -2049,6 +2096,8 @@ export function registerMessagesRoutes(app, deps) {
     claudeBillingSwitchService = null,
     // The Claude API booking (claude-api-usage-service.mjs).
     claudeApiUsageService = null,
+    // Tokens per turn for every provider (token-usage-service.mjs).
+    tokenUsageService = null,
     // The delivery fence's runtime half for GET /api/pending, as on the
     // socket: the Claude API claim check (null: no refusal) and what a fenced
     // row does (the swap, or fail closed).
@@ -2640,6 +2689,7 @@ export function registerMessagesRoutes(app, deps) {
           AND rs.sdk_session_id = ?
       )
       AND (q.next_attempt_at IS NULL OR q.next_attempt_at <= ?)
+      AND ${planBoundaryHoldSql('q')}
     ORDER BY q.timestamp ASC, q.rowid ASC
     LIMIT 1
   `);
@@ -4804,6 +4854,12 @@ export function registerMessagesRoutes(app, deps) {
       ? normalizeRelayMode(existingConversation.preferred_relay_mode)
       : null;
     const requestedRelayMode = savedRelayMode || normalizeRelayMode(relayMode || mode);
+    // Plan-only: an agent's send that names another mode is refused
+    // and nothing is queued (nor a billing switched). Without a mode it runs
+    // in the session's own. The owner's own sends are not limited.
+    if (remoteRequest.remote && readPlanOnly(existingConversation) && planOnlyRefusesMode(relayMode || mode)) {
+      return res.status(409).json({ ...PLAN_ONLY_REFUSAL, conversationId });
+    }
     const trimmedText = stripRelayPromptContext(text, requestedRelayMode || relayMode || mode);
     const normalizedAttachments = normalizeAttachments(rawAttachments);
     const requestedAttachmentCount = Math.min(
@@ -6211,7 +6267,10 @@ export function registerMessagesRoutes(app, deps) {
           // Whether a billing swap may replace the worker now, and why not.
           || (stored.releasable ?? null) !== (steering.releasable ?? null)
           || (stored.releaseHold || null) !== (steering.releaseHold || null)
-          || (stored.backgroundTaskCount || 0) !== (steering.backgroundTaskCount || 0);
+          || (stored.backgroundTaskCount || 0) !== (steering.backgroundTaskCount || 0)
+          // Whether the worker's CLI child still runs: the worker recycle
+          // waits for it to be gone, so a flip must be stored.
+          || (stored.cliAlive ?? null) !== (steering.cliAlive ?? null);
         if (workerForSteering && changed) {
           sessionWorkerRegistry?.upsertWorker?.({ ...workerForSteering, steering });
           // Pushed rather than left for the clients' status poll: the
@@ -6229,6 +6288,16 @@ export function registerMessagesRoutes(app, deps) {
           sessionWorkerRegistry?.upsertWorker?.({ ...workerForKind, kind: heartbeatKind });
         }
       }
+      // The build id of the code the worker started on, recorded the same way:
+      // only when it says one and the registry has another, so quiet
+      // heartbeats stay write-free.
+      const heartbeatBuildId = normalizeBuildId(req.body?.buildId);
+      if (heartbeatBuildId) {
+        const workerForBuild = sessionWorkerRegistry?.getWorker?.(requesterSessionId) || null;
+        if (workerForBuild && workerForBuild.buildId !== heartbeatBuildId) {
+          sessionWorkerRegistry?.upsertWorker?.({ ...workerForBuild, buildId: heartbeatBuildId });
+        }
+      }
       sessionWorkerSupervisor?.noteSessionHeartbeat?.(requesterSessionId);
       // The worker's digest of its live background-task ids against the set
       // held for it (keyed as the worker posts, by its session id). They
@@ -6611,6 +6680,59 @@ export function registerMessagesRoutes(app, deps) {
     res.json({ ok: true, billing: booked.billing, basis: booked.basis, models: booked.booked.map((entry) => entry.model) });
   });
 
+  // POST /api/turn-token-usage — every worker reports, after a turn, the
+  // turn's tokens per model (`models`), or a Claude cloud worker the
+  // session's running totals (`sessionTotals`), keyed by turn, run and model
+  // (shared/turn-token-usage.mjs). Advisory and idempotent: a retried or
+  // reordered report books only what it adds (token-usage-service.mjs).
+  // Who ran the turn is the relay's to say: the chat's provider, and for a
+  // Claude chat the posting worker's registered kind (the billing can switch
+  // between turns). A body that says otherwise is logged. A deleted chat
+  // takes no report, so a late retry cannot book its turn a second time; an
+  // archived one does.
+  app.post('/api/turn-token-usage', auth, (req, res) => {
+    touchCli();
+    if (!tokenUsageService) return res.status(501).json({ error: 'Token usage storage is unavailable' });
+    const parsed = normalizeTurnTokenUsageReport(req.body);
+    if (!parsed.ok) return res.status(400).json({ error: parsed.error });
+    const { report } = parsed;
+    const conversationId = report.conversationId;
+    if (!stmts.getConv?.get?.(conversationId)) return res.status(404).json({ error: 'Conversation not found' });
+    // The binding's provider wins over the report's. A chat whose binding is
+    // gone for a moment (a cache rebuild) still books, as the provider the
+    // report states.
+    const runtimeSession = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+    const chatProvider = String(runtimeSession?.provider_type || report.provider || '').trim().toLowerCase();
+    let provider = chatProvider;
+    let billing = '';
+    if (chatProvider === 'openai') {
+      // A chat on the user's own OpenAI key runs on the Copilot SDK.
+      provider = 'github';
+      billing = 'byok-openai';
+    } else if (chatProvider === 'github') {
+      billing = report.billing;
+    } else if (normalizeClaudeBilling(chatProvider)) {
+      const requesterSid = normalizeSessionWorkerId(readBridgeIdentity(req)?.sessionId);
+      const registeredKind = normalizeClaudeBilling(requesterSid ? sessionWorkerRegistry?.getWorker?.(requesterSid)?.kind : '');
+      // The worker that ran the turn, then the chat's billing; the report's
+      // own word only when the chat has no binding.
+      provider = registeredKind || normalizeClaudeBilling(chatProvider);
+    } else if (!['claude-cloud', 'deepseek', 'cursor', 'grok'].includes(chatProvider)) {
+      return res.status(409).json({ error: 'Conversation keeps no token usage' });
+    }
+    if (report.provider && report.provider !== provider) {
+      console.warn(`[${ts()}] token usage conv=${conversationId.slice(0, 8)} stated=${report.provider} booked=${provider}`);
+    }
+    if (report.sessionTotals && provider !== 'claude-cloud') {
+      return res.status(400).json({ error: 'sessionTotals is for Claude cloud only' });
+    }
+    const booked = report.sessionTotals
+      ? tokenUsageService.recordCloudSessionTotals({ conversationId, provider, billing, report })
+      : tokenUsageService.recordTurn({ conversationId, provider, billing, report });
+    if (!booked) return res.status(501).json({ error: 'Token usage storage is unavailable' });
+    res.json({ ok: true, provider, billing, models: booked.map((entry) => entry.model) });
+  });
+
   // POST /api/claude-plan-usage — Claude worker reports the session's
   // structured /usage data (plan rate-limit windows + session cost totals).
   //
@@ -6922,6 +7044,24 @@ export function registerMessagesRoutes(app, deps) {
           restartOrchestrator: relayRestartOrchestrator?.getState?.() || null,
         });
       }
+      // The process asking is being replaced (the worker recycle): no work,
+      // as for a killed session, so no turn starts on the pid being stopped.
+      // Unlike the killed marker, the fence outlives the marker's grace and
+      // every clearRestartSchedule; the new worker has another pid and takes
+      // what waited meanwhile.
+      if (workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true) {
+        return res.json({
+          message: null,
+          routing: {
+            enabled: true,
+            requesterSessionId,
+            blockedReason: 'worker-replacement',
+            lifecycle: sessionWorkerSupervisor?.getLifecycleState?.(requesterSessionId) || null,
+            fallbackRestart: null,
+          },
+          restartOrchestrator: relayRestartOrchestrator?.getState?.() || null,
+        });
+      }
       sessionWorkerSupervisor?.noteSessionHeartbeat?.(requesterSessionId);
     }
     if (runtimeState.relayPaused) return res.json({ message: null, paused: true });
@@ -7016,6 +7156,8 @@ export function registerMessagesRoutes(app, deps) {
         workerKind: httpPendingWorkerKind(requesterSessionId),
         claudeApiClaimCheck,
         onBillingFence: onClaudeBillingFence,
+        // The fence check above, asked again before every claim.
+        isReplacementFenced: () => workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true,
         telemetry: (payload = {}) => {
           if (!sessionWorkerRoutingEnabled) return;
           emitSessionWorkerTelemetry(payload.event, {
@@ -7236,6 +7378,7 @@ export function registerMessagesRoutes(app, deps) {
                 workerKind: httpPendingWorkerKind(requesterSessionId),
                 claudeApiClaimCheck,
                 onBillingFence: onClaudeBillingFence,
+                isReplacementFenced: () => workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true,
               });
               if (recoveryDequeue?.message) {
                 msg = recoveryDequeue.message;

package/server/routes/relay-ask-routes.mjs

@@ -27,12 +27,15 @@
 //                                          relay from its Inbox: asks only;
 //                                          an approval or any other card is
 //                                          never answered over the pairing
-//   GET  /api/relay-asks/remote/inbox      what its Inbox shows of this relay
+//   GET  /api/relay-asks/remote/inbox      what its Inbox shows of this relay;
+//                                          `?push=1`: it can push, and each
+//                                          card a turn waits on says who does
+//                                          (`notice`)
 //
 // Every text of an ask or card is an agent's: it goes out as data, and the
 // browser shows it as plain text.
 
-import { REMOTE_RELAY_ERROR_CODES } from '../../shared/remote-relay-contract.mjs';
+import { REMOTE_INBOX_CLAIMS, REMOTE_INBOX_NOTICES, REMOTE_RELAY_ERROR_CODES } from '../../shared/remote-relay-contract.mjs';
 import { RELAY_ASK_LIMITS, relayQuestionKind } from '../../shared/relay-asks.mjs';
 import { schemaFields } from '../../shared/question-schema.mjs';
 import { findOriginRemoteRelay, admitRemoteRelayRequest, readRemoteRelayRequest } from '../services/remote-relay-inbound.mjs';
@@ -53,6 +56,8 @@ const RELAY_ASK_ERROR_STATUS = Object.freeze({
 const INBOX_REMOTE_TIMEOUT_MS = 5_000;
 // Cards answered in the last day are listed under the divider, at most these.
 const INBOX_ANSWERED_CARDS_MAX = 50;
+// Plan cards, pending (one per session) and settled in the last day, at most these each.
+const INBOX_PLAN_CARDS_MAX = 50;
 // Registry states that mean "do not even try" for the Inbox.
 const UNREACHABLE_STATES = new Set(['offline', 'unauthorized']);
 
@@ -90,7 +95,15 @@ export function inboxItemOfCard(question, session, { forRemote = false } = {}) {
     createdAt: question?.createdAt || null,
     ...(question?.status === 'answered' ? { answeredAt: question?.answeredAt || null } : {}),
   };
-  if (forRemote && kind === 'approval') return { ...base, question: '' };
+  // Its kind and summary say what it is about, never what it would send.
+  if (forRemote && kind === 'approval') {
+    return {
+      ...base,
+      question: '',
+      ...(toText(context.variant) ? { variant: toText(context.variant) } : {}),
+      ...(toText(context.summary) ? { summary: toText(context.summary) } : {}),
+    };
+  }
   const fields = schemaFields(question?.requestSchema);
   return {
     ...base,
@@ -107,6 +120,37 @@ export function inboxItemOfCard(question, session, { forRemote = false } = {}) {
   };
 }
 
+/**
+ * One Inbox item of a plan card (a formatted relay board). A paired
+ * relay's Inbox gets its title and status alone, "Open there": a card is
+ * never answered over the pairing. `question` repeats the title for one
+ * that does not know plan items (0.9.19 shows it as a card's question).
+ */
+export function inboxItemOfPlanBoard(board, session, { forRemote = false } = {}) {
+  const title = toText(board?.title) || 'Plan ready for review';
+  const status = toText(board?.status) || 'pending';
+  const base = {
+    id: toText(board?.id),
+    kind: 'plan',
+    session,
+    title,
+    status,
+    createdAt: board?.createdAt || null,
+  };
+  if (forRemote) return { ...base, question: title };
+  return {
+    ...base,
+    ...(status !== 'pending' ? { actedAt: board?.actedAt || null } : {}),
+    body: String(board?.body || ''),
+    actions: (Array.isArray(board?.actions) ? board.actions : [])
+      .map((action) => ({ id: toText(action?.id), label: toText(action?.label) || toText(action?.id) }))
+      .filter((action) => action.id),
+    recommendedAction: toText(board?.recommendedAction) || null,
+    planOnly: board?.planOnly === true,
+    selectedAction: toText(board?.selectedAction) || null,
+  };
+}
+
 /** One Inbox item of an ask (relay-ask-service.mjs shape). */
 export function inboxItemOfAsk(ask) {
   const {
@@ -139,6 +183,8 @@ export function registerRelayAskRoutes(app, deps) {
     db,
     stmts,
     formatQuestionRow,
+    // Plan cards (relay boards) in the Inbox, formatted as their routes do.
+    formatRelayBoardRow = null,
     relayAskService = null,
     relayAskLinkService = null,
     remoteRelayInbound = null,
@@ -146,6 +192,9 @@ export function registerRelayAskRoutes(app, deps) {
     // calls them (remote-relay-client.mjs): the Inbox of paired relays.
     remoteRelayRegistry = null,
     remoteRelayClient = null,
+    // push-dispatch-service.mjs questionNotice: whether this relay's own push
+    // of a card reached a device.
+    questionNotice = null,
     now = () => Date.now(),
   } = deps;
 
@@ -154,6 +203,26 @@ export function registerRelayAskRoutes(app, deps) {
     SELECT * FROM relay_questions WHERE status = 'answered' AND answered_at >= ? ORDER BY answered_at DESC LIMIT ?
   `) || null;
 
+  // Plan cards: of each session that is neither deleted nor
+  // archived the newest pending one (an older one stays in its session),
+  // and the ones settled in the last day.
+  const planBoardSessionFilter = `c.status != 'deleted' AND COALESCE(c.archived, 0) = 0`;
+  const pendingPlanBoardsStmt = db?.prepare?.(`
+    SELECT b.* FROM relay_boards b JOIN conversations c ON c.id = b.conversation_id
+    WHERE b.status = 'pending' AND b.board_type = 'plan_ready' AND ${planBoardSessionFilter}
+      AND NOT EXISTS (
+        SELECT 1 FROM relay_boards newer
+        WHERE newer.conversation_id = b.conversation_id AND newer.status = 'pending' AND newer.board_type = 'plan_ready'
+          AND (newer.created_at > b.created_at OR (newer.created_at = b.created_at AND newer.rowid > b.rowid))
+      )
+    ORDER BY b.created_at DESC LIMIT ?
+  `) || null;
+  const settledPlanBoardsStmt = db?.prepare?.(`
+    SELECT b.* FROM relay_boards b JOIN conversations c ON c.id = b.conversation_id
+    WHERE b.status IN ('acted', 'dismissed') AND b.board_type = 'plan_ready' AND b.acted_at >= ? AND ${planBoardSessionFilter}
+    ORDER BY b.acted_at DESC LIMIT ?
+  `) || null;
+
   function sessionOf(id) {
     let row = null;
     try {
@@ -204,13 +273,20 @@ export function registerRelayAskRoutes(app, deps) {
     return { relayId, name: toText(paired?.name) || claimed || toText(request.origin?.relayName) || relayId };
   }
 
-  /** What an Inbox shows of this relay: its asks, and the cards turns wait on. */
-  function localInboxItems({ forRemote = false } = {}) {
+  /**
+   * What an Inbox shows of this relay: its asks, and the cards turns wait on.
+   * `read`, when given, learns whether the pending cards could be read
+   * (`read.pendingCards`): a failed read lists none, which is not "none pending".
+   */
+  function localInboxItems({ forRemote = false, read = null } = {}) {
     const items = (relayAskService?.isAvailable?.() ? relayAskService.listHere() : []).map(inboxItemOfAsk);
     let pending = [];
     try {
       pending = stmts.listQuestions.all('pending', null, null).map(formatQuestionRow).filter(Boolean);
-    } catch {}
+      if (read) read.pendingCards = true;
+    } catch {
+      if (read) read.pendingCards = false;
+    }
     let answered = [];
     try {
       const since = new Date(now() - RELAY_ASK_LIMITS.answeredKeepMs).toISOString();
@@ -219,6 +295,19 @@ export function registerRelayAskRoutes(app, deps) {
     for (const question of [...pending, ...answered]) {
       items.push(inboxItemOfCard(question, sessionOf(question.conversationId), { forRemote }));
     }
+    if (typeof formatRelayBoardRow === 'function') {
+      let boards = [];
+      try {
+        const since = new Date(now() - RELAY_ASK_LIMITS.answeredKeepMs).toISOString();
+        boards = [
+          ...(pendingPlanBoardsStmt?.all(INBOX_PLAN_CARDS_MAX) || []),
+          ...(settledPlanBoardsStmt?.all(since, INBOX_PLAN_CARDS_MAX) || []),
+        ].map(formatRelayBoardRow).filter(Boolean);
+      } catch {}
+      for (const board of boards) {
+        items.push(inboxItemOfPlanBoard(board, sessionOf(board.conversationId), { forRemote }));
+      }
+    }
     return items.sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')));
   }
 
@@ -375,11 +464,52 @@ export function registerRelayAskRoutes(app, deps) {
     }
   });
 
-  // GET /api/relay-asks/remote/inbox — what a paired relay's Inbox shows of this one.
+  // Who pushes a card a turn waits on: question id → the paired
+  // relay (its id) that claimed it. In memory: after a restart a
+  // card is just claimable again.
+  const claims = new Map();
+
+  /**
+   * `notice` (and with `you`, `claimed`) for each pending approval and
+   * ask_user item, for a caller that can push: this relay's own push
+   * decides first, then the first caller to find it missed claims it.
+   */
+  function addNotices(items, callerRelayId) {
+    const pendingIds = new Set();
+    const noticed = items.map((item) => {
+      if (item.status !== 'pending' || (item.kind !== 'approval' && item.kind !== 'ask_user')) return item;
+      pendingIds.add(item.id);
+      let own = null;
+      try {
+        own = typeof questionNotice === 'function' ? questionNotice(item.id) : null;
+      } catch {}
+      if (own === 'reached') return { ...item, notice: REMOTE_INBOX_NOTICES.here };
+      if (own === 'pending') return { ...item, notice: REMOTE_INBOX_NOTICES.wait };
+      const claim = claims.get(item.id);
+      if (!claim) {
+        claims.set(item.id, callerRelayId);
+        return { ...item, notice: REMOTE_INBOX_NOTICES.you, claimed: REMOTE_INBOX_CLAIMS.now };
+      }
+      if (claim === callerRelayId) return { ...item, notice: REMOTE_INBOX_NOTICES.you, claimed: REMOTE_INBOX_CLAIMS.before };
+      return { ...item, notice: REMOTE_INBOX_NOTICES.other };
+    });
+    // A card no longer pending needs no claim.
+    for (const id of claims.keys()) {
+      if (!pendingIds.has(id)) claims.delete(id);
+    }
+    return noticed;
+  }
+
+  // GET /api/relay-asks/remote/inbox — what a paired relay's Inbox shows of
+  // this one. `?push=1`: the caller can push, and learns who pushes each card.
   app.get('/api/relay-asks/remote/inbox', auth, (req, res) => {
     const caller = admitPairedRelay(req, res);
     if (!caller) return;
-    const items = localInboxItems({ forRemote: true });
+    const read = {};
+    let items = localInboxItems({ forRemote: true, read });
+    // Pending cards that could not be read are not "no card pending": the
+    // claims stay, and no card is claimed or offered on this read.
+    if (toText(req.query?.push) === '1' && read.pendingCards) items = addNotices(items, caller.relayId);
     res.json({ ok: true, items, pending: pendingOf(items) });
   });
 

package/server/routes/relay-board-routes.mjs

@@ -1,7 +1,14 @@
 'use strict';
 
-import { persistConversationPreferences } from '../services/conversation-preferences-service.mjs';
+import { persistConversationPreferences, readPlanOnly } from '../services/conversation-preferences-service.mjs';
 import { fallbackReasoningEffort } from '../services/conversation-model-fallback.mjs';
+import {
+  PLAN_BOARD_APPROVE_ONLY,
+  isPendingPlanBoard,
+  planBoardActionLabel,
+  planBoardFollowupMode,
+  planBoardFollowupText,
+} from '../../shared/plan-board-actions.mjs';
 
 function normalizeId(value) {
   const text = String(value || '').trim();
@@ -20,34 +27,6 @@ function normalizeBoardType(value) {
   return text.replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'generic';
 }
 
-function labelForAction(actionId) {
-  const id = String(actionId || '').trim().toLowerCase();
-  if (id === 'autopilot') return 'Implement in autopilot';
-  if (id === 'autopilot_fleet') return 'Implement with autopilot fleet';
-  if (id === 'interactive') return 'Stop here and prompt myself';
-  if (id === 'exit_only') return 'Stop here';
-  return id.replace(/[_-]+/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase()) || 'Select';
-}
-
-function defaultPromptForAction(actionId, board = null) {
-  const summary = String(board?.body || '').trim();
-  if (actionId === 'autopilot') {
-    return `Please implement the approved plan now.\n\nPlan summary:\n${summary}`;
-  }
-  if (actionId === 'autopilot_fleet') {
-    return `Please implement the approved plan using autopilot_fleet where useful.\n\nPlan summary:\n${summary}`;
-  }
-  if (actionId === 'interactive') {
-    return `I approved the plan. Let's proceed interactively with implementation.\n\nPlan summary:\n${summary}`;
-  }
-  return '';
-}
-
-function modeForAction(actionId, fallbackMode) {
-  if (actionId === 'autopilot' || actionId === 'autopilot_fleet') return 'autopilot';
-  if (actionId === 'interactive') return 'agent';
-  return fallbackMode;
-}
 
 function normalizeBoardActions(rawActions) {
   const input = Array.isArray(rawActions) ? rawActions : [];
@@ -61,7 +40,7 @@ function normalizeBoardActions(rawActions) {
     const id = String(item.id || item.actionId || item.value || '').trim().toLowerCase();
     if (!id || seen.has(id)) continue;
     seen.add(id);
-    const label = String(item.label || item.title || labelForAction(id)).trim().slice(0, 120) || labelForAction(id);
+    const label = String(item.label || item.title || planBoardActionLabel(id)).trim().slice(0, 120) || planBoardActionLabel(id);
     const mode = normalizeId(item.mode);
     const prompt = normalizeBoardText(item.prompt || '', '');
     normalized.push({
@@ -99,6 +78,7 @@ export function registerRelayBoardRoutes(app, deps) {
     DEFAULT_MODEL,
     formatRelayBoardRow,
     pushDispatchService,
+    relayEventService,
   } = deps;
 
   /**
@@ -201,7 +181,12 @@ export function registerRelayBoardRoutes(app, deps) {
     const boardId = uuidv4();
     const relayMode = normalizeRelayMode(mode || q.relay_mode) || DEFAULT_RELAY_MODE;
     const normalizedActions = normalizeBoardActions(actions);
-    const normalizedRecommended = normalizeId(recommendedAction);
+    // A plan-only session's plan card recommends "Approve plan", whatever the
+    // worker or the Copilot CLI recommended.
+    const boardConversationId = normalizeId(conversationId) || q.conversation_id;
+    const planOnly = normalizedBoardType === 'plan_ready'
+      && readPlanOnly(stmts.getConvAnyStatus?.get?.(boardConversationId));
+    const normalizedRecommended = planOnly ? PLAN_BOARD_APPROVE_ONLY : normalizeId(recommendedAction);
     const boardContext = parseContext(context);
 
     stmts.insertBoard.run(
@@ -240,23 +225,43 @@ export function registerRelayBoardRoutes(app, deps) {
     }
 
     const board = formatRelayBoardRow(row);
+    const conversationRow = stmts.getConvAnyStatus?.get?.(String(board?.conversationId || '').trim()) || null;
+    if (conversationRow && String(conversationRow.status || '').trim() === 'deleted') {
+      return res.status(404).json({ error: 'Conversation not found' });
+    }
     const actions = Array.isArray(board?.actions) ? board.actions : [];
-    const selected = actions.find((item) => String(item?.id || '').trim().toLowerCase() === actionId.toLowerCase());
+    const chosen = actionId.toLowerCase();
+    // "Approve plan" is taken on any pending plan card, also one stored
+    // before the button existed.
+    const selected = actions.find((item) => String(item?.id || '').trim().toLowerCase() === chosen)
+      || (chosen === PLAN_BOARD_APPROVE_ONLY && isPendingPlanBoard(board)
+        ? { id: PLAN_BOARD_APPROVE_ONLY, label: planBoardActionLabel(PLAN_BOARD_APPROVE_ONLY), mode: planBoardFollowupMode(PLAN_BOARD_APPROVE_ONLY) }
+        : null);
     if (!selected) return res.status(400).json({ error: 'Unknown board action' });
 
     const now = new Date().toISOString();
-    const shouldDismiss = actionId.toLowerCase() === 'exit_only';
-    if (shouldDismiss) {
-      stmts.dismissBoard.run(actionId, now, now, boardId);
-    } else {
-      stmts.markBoardAction.run(actionId, now, now, boardId);
+    const shouldDismiss = chosen === 'exit_only';
+    const approveOnly = chosen === PLAN_BOARD_APPROVE_ONLY;
+    // Only a pending card is settled: a second press (here or in the Inbox)
+    // finds it settled already and queues nothing.
+    const settledRow = shouldDismiss
+      ? stmts.dismissBoard.run(chosen, now, now, boardId)
+      : stmts.markBoardAction.run(chosen, now, now, boardId);
+    if (Number(settledRow?.changes) !== 1) {
+      const current = stmts.getBoard.get(boardId);
+      return res.status(409).json({ error: `Board already ${current?.status || 'settled'}`, board: formatRelayBoardRow(current) });
     }
 
     let queuedMessageId = null;
     if (!shouldDismiss) {
-      const followupPrompt = normalizeBoardText(selected.prompt || defaultPromptForAction(actionId.toLowerCase(), board), '');
+      // approve_only says exactly its line; the others may carry their own.
+      const followupPrompt = normalizeBoardText(approveOnly ? planBoardFollowupText(chosen) : (selected.prompt || planBoardFollowupText(chosen)), '');
       if (followupPrompt) {
-        const relayMode = normalizeRelayMode(selected.mode || modeForAction(actionId.toLowerCase(), board.mode)) || DEFAULT_RELAY_MODE;
+        // approve_only runs this one turn in agent mode (plan mode blocks
+        // the writes its plan-only steps need); the session stays in plan.
+        const relayMode = normalizeRelayMode(approveOnly
+          ? planBoardFollowupMode(chosen)
+          : (selected.mode || planBoardFollowupMode(chosen) || board.mode)) || DEFAULT_RELAY_MODE;
         const convId = String(board?.conversationId || '').trim();
         const runtimeSession = stmts.getRuntimeSessionByConversation?.get?.(convId) || null;
         const latestModel = stmts.getLatestConversationModel?.get?.(convId)?.model || null;
@@ -323,11 +328,21 @@ export function registerRelayBoardRoutes(app, deps) {
             timestamp: now,
           },
         });
-        followChosenMode(convId, relayMode, now);
+        if (!approveOnly) followChosenMode(convId, relayMode, now);
       }
     }
 
     const updated = formatRelayBoardRow(stmts.getBoard.get(boardId));
+    try {
+      relayEventService?.noteBoardSettled?.(String(updated?.conversationId || board?.conversationId || ''), {
+        boardId,
+        boardType: updated?.boardType || board?.boardType || null,
+        action: chosen,
+        actionLabel: String(selected.label || '').trim() || planBoardActionLabel(chosen),
+        title: updated?.title || board?.title || '',
+        queuedMessageId,
+      });
+    } catch {}
     io.emit('relay_board_updated', { board: updated });
     io.emit('relay_board_changed', { conversationId: updated?.conversationId || null, boardId });
     return res.json({