@oar-sh/oar 0.9.2 → 0.9.4

package/server/copilot-worker/copilot-sdk-session-worker.mjs

@@ -4,8 +4,7 @@
 // control polling, activity channels) but executes turns through the Copilot
 // SDK's headless runtime instead of the `copilot` TUI under a PTY.
 //
-// Dormant until phase 3 registers a worker kind for it. Run it by hand against
-// a live relay with:
+// Run it by hand against a live relay with:
 //
 //   COPILOT_WEB_RELAY_CONFIG=server/config.json \
 //   COPILOT_WORKSPACE_ROOT=/path/to/workspace \
@@ -21,6 +20,10 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import {
+  createRunnerLinkBridge,
+  failSettlingRowsOnShutdown,
+} from '../../shared/worker-runtime/runner-link-wiring.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import {
@@ -69,8 +72,29 @@ async function main() {
     api,
     sdkSessionId,
     abortAckNote: 'copilot session aborted',
+    // A subagent lane's Stop. Lanes are keyed on the envelope agentId, which
+    // is also the runtime's task id, so `rpc.tasks.cancel` is tried; the
+    // runtime refuses ids it does not track (then the control answers "not
+    // supported" and the whole-turn Stop remains). Background agents have no
+    // lane — their Stop is the task panel's. (Late-bound: controls only poll
+    // while a turn is live.)
+    onAbortSubagent: (subagentRunId) => turnRunner.stopBackgroundTask(subagentRunId),
     dbg,
   });
+  // The relay's *Background task timeout* slider (0 = unlimited) rides every
+  // delivery payload, exactly as for the Claude worker: background agents and
+  // shells now have cards and a Stop, so the slider governs them too and a cap
+  // expiry CANCELS them rather than forgetting them. The env var is an
+  // emergency override only.
+  const backgroundTaskTimeoutOverrideMs = readOptionalMs('COPILOT_SDK_RELAY_BACKGROUND_TASK_TIMEOUT_MS');
+  let backgroundTaskTimeoutMs = backgroundTaskTimeoutOverrideMs ?? 0;
+  // The runner reports every flip of its delivery gate; the bridge turns them
+  // into the link's worker.unready / worker.ready frames, so a message queued
+  // while a question card is open is held in the relay queue and steers into
+  // the resumed turn one round trip after the answer.
+  const linkBridge = createRunnerLinkBridge();
+  // Late-bound: the heartbeat controller is built after the runner.
+  let heartbeat = null;
   const turnRunner = createCopilotSdkSessionRunner({
     api,
     sdkSessionId,
@@ -82,23 +106,22 @@ async function main() {
     // How long a deferred model switch may wait for its drain before the
     // explicit selection fails the row (default 10s).
     modelSwitchTimeoutMs: readOptionalMs('COPILOT_SDK_RELAY_MODEL_SWITCH_TIMEOUT_MS'),
-    // How long live detached shells alone may hold the runtime open (0 = no
-    // limit). Deliberately NOT the relay's `background_task_timeout_minutes`
-    // slider that rides every delivery payload: that slider defaults to
-    // 0/unlimited and governs Claude's background tasks, which the composer
-    // lists and can stop. A Copilot detached shell has neither, so consuming it
-    // would make "a forgotten shell pins a runtime forever" the default with
-    // nothing in the UI to reveal it. The runner's own 30-minute cap applies
-    // unless this says otherwise.
-    ...(() => {
-      const override = readOptionalMs('COPILOT_SDK_RELAY_BACKGROUND_TASK_TIMEOUT_MS');
-      return override === undefined ? {} : { getBackgroundTaskTimeoutMs: () => override };
-    })(),
+    getBackgroundTaskTimeoutMs: () => backgroundTaskTimeoutMs,
+    // A readiness flip is a hold starting or ending (question card, approval,
+    // compaction): the composer's steering snapshot changed with it.
+    onDeliveryReadinessChange: (ready) => {
+      linkBridge.onDeliveryReadinessChange(ready);
+      heartbeat?.requestPulse();
+    },
+    // A message became (or stopped being) cancellable: report it now rather
+    // than on the next 10 s heartbeat (coalesced by the controller).
+    onCancellableChange: () => heartbeat?.requestPulse(),
+    canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
     dbg,
   });
 
   let heartbeatTimer = null;
-  const heartbeat = createHeartbeatController({
+  heartbeat = createHeartbeatController({
     api,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
@@ -110,6 +133,12 @@ async function main() {
     // the crash guard below takes the entries whole so its requeues stay
     // fenced to this attempt.
     getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds().map((entry) => entry.id),
+    // The composer's steering snapshot (Steer / Queue + the hold reason, the
+    // un-steerable rows) and the consumed steers whose settle the runner gave
+    // up on — the relay fails those itself, never re-running them.
+    getSteeringState: () => turnRunner.steeringState(),
+    getSettleFailed: () => turnRunner.getSettleFailed(),
+    onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -119,8 +148,22 @@ async function main() {
     getSessionReady: () => true,
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
+    // Mid-turn steering opt-in: the link keeps signalling readiness while a
+    // delivery is in flight as long as the runner can absorb another message
+    // into the live turn, and withdraws it while the runner holds.
+    getSteeringReady: () => turnRunner.canAcceptSteering(),
+    getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
+    // A relay that just (re)started knows nothing of this worker until it
+    // heartbeats; the composer's steering snapshot rides that beat.
+    onServerHello: () => heartbeat.requestPulse(),
     onDeliver: async (pending, reason) => {
       dbg('queue.deliver received', `reason=${reason}`, `msgId=${pending?.message?.id || 'none'}`);
+      // Slider changes reach a running worker on its next delivery; an
+      // explicit env override pins the value regardless.
+      const deliveredTimeout = Number(pending?.settings?.backgroundTaskTimeoutMs);
+      if (backgroundTaskTimeoutOverrideMs === undefined && Number.isFinite(deliveredTimeout) && deliveredTimeout >= 0) {
+        backgroundTaskTimeoutMs = deliveredTimeout;
+      }
       try {
         return await turnRunner.handlePendingPayload(pending);
       } catch (error) {
@@ -129,19 +172,38 @@ async function main() {
       }
     },
     onControl: (control) => {
-      // Background-task controls have no Copilot SDK equivalent yet: the
-      // runtime's `session.background_tasks_changed` carries an empty payload
-      // (23 of them fire during a single bash call), so there is no task id to
-      // stop. Logged rather than silently dropped.
-      dbg('worker control ignored (unsupported by the SDK worker)', String(control?.type || '(none)'));
+      const type = String(control?.type || '').trim();
+      if (type === 'cancel_pushed_message') {
+        // Un-steer: pull a pushed-but-unconsumed message back out of the
+        // runtime's queue and cancel its row.
+        void turnRunner.cancelPushedMessage(control?.messageId).catch((error) => {
+          dbg('un-steer failed', error?.message || String(error));
+        });
+        return;
+      }
+      if (type === 'stop_background_task') {
+        // The task panel's per-card Stop → rpc.tasks.cancel.
+        const taskId = String(control?.taskId || '').trim();
+        dbg('stop background task control', taskId);
+        void turnRunner.stopBackgroundTask(taskId).catch((error) => {
+          dbg('stop background task failed', error?.message || String(error));
+        });
+        return;
+      }
+      dbg('worker control ignored (unsupported by the SDK worker)', type || '(none)');
     },
   });
+  linkBridge.attach(wsLink);
 
   const shutdown = async (signal) => {
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
+    // Rows whose prompt the runtime consumed and whose settle marker has not
+    // landed are failed terminally, never left for dead-worker recovery to
+    // requeue (that would run the prompt twice). Bounded.
+    try { await failSettlingRowsOnShutdown({ api, runner: turnRunner }); } catch {}
     // Bounded, like the Cursor worker: stopping the runtime is an RPC, and a
     // hung stop must never make the process ignore the supervisor's SIGTERM.
     try {

package/server/cursor-worker/cursor-remote-relay-tool.mjs

@@ -0,0 +1,65 @@
+/**
+ * The relay's `remote_relay` custom tool for the Cursor worker. SDK-free: the
+ * turn runner passes the returned `{ description, inputSchema, execute }` into
+ * `customTools.remote_relay`, and every call goes through the shared tool core
+ * to the local relay endpoint.
+ *
+ * A call can legitimately run for many minutes (a remote turn plus an approval
+ * card), during which the SDK emits nothing. `onCallStart`/`onCallEnd` bracket
+ * every execution — errors included — so the runner can count it as pending
+ * client work and hold its stall watchdog, exactly as it does for ask_user.
+ *
+ * The SDK hands `execute` no cancellation of its own (the context is only
+ * `{ toolCallId }`), so `getAbortSignal` supplies the running turn's: a Stop
+ * aborts it, which cancels the pending relay request and ends the hold.
+ */
+
+import {
+  REMOTE_RELAY_CALL_FAILED,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_NAME,
+  cloneRemoteRelayToolInputSchema,
+  executeRemoteRelayTool,
+  formatRemoteRelayToolResult,
+} from '../../shared/remote-relay-tool-core.mjs';
+
+export function createRemoteRelayTool({
+  api,
+  getConversationId = () => '',
+  onCallStart = () => {},
+  onCallEnd = () => {},
+  getAbortSignal = () => null,
+  dbg = () => {},
+} = {}) {
+  async function execute(args) {
+    onCallStart();
+    try {
+      const result = await executeRemoteRelayTool(args, {
+        api,
+        conversationId: String(getConversationId() || ''),
+        signal: getAbortSignal?.() || null,
+      });
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }],
+      };
+    } catch (error) {
+      // A tool exception must never kill the run.
+      const message = error?.message || String(error);
+      dbg('remote_relay tool failed', message);
+      const result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }],
+      };
+    } finally {
+      onCallEnd();
+    }
+  }
+  return {
+    name: REMOTE_RELAY_TOOL_NAME,
+    description: REMOTE_RELAY_TOOL_DESCRIPTION,
+    inputSchema: cloneRemoteRelayToolInputSchema(),
+    execute,
+  };
+}

package/server/cursor-worker/cursor-turn-runner.mjs

@@ -12,6 +12,8 @@ import {
 } from './cursor-sdk-adapter.mjs';
 import { createAskUserTool } from './cursor-ask-user-tool.mjs';
 import { createPreviewTool } from './cursor-preview-tool.mjs';
+import { createRemoteRelayTool } from './cursor-remote-relay-tool.mjs';
+import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import {
   buildCursorSubagentAgents,
   cursorSubagentRosterFingerprint,
@@ -120,6 +122,9 @@ export function createCursorTurnRunner({
   resolveModelParamsImpl = resolveCursorReasoningParams,
   createNormalizerImpl = createSdkMessageNormalizer,
   buildUserMessageImpl = buildCursorUserMessage,
+  // Whether agent handles carry the relay's `remote_relay` tool
+  // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
+  remoteRelayToolGate = null,
   dbg = () => {},
 } = {}) {
   // Unlike the Claude worker, the agent handle (and the custom tools bound
@@ -140,6 +145,9 @@ export function createCursorTurnRunner({
   // Open ask_user round-trips: the merged-stream stall watchdog defers while
   // a human is thinking about a question card.
   let pendingAskUserCalls = 0;
+  // Running remote_relay calls, same family: the relay may be waiting up to
+  // 600 s for a remote turn (plus an approval card) with no SDK traffic.
+  let pendingRemoteRelayCalls = 0;
   // Mirrors the Copilot extension's lastPromptedRelayMode: full mode
   // instructions ride on the first message of a mode and on mode changes only.
   let lastNudgedRelayMode = '';
@@ -188,6 +196,39 @@ export function createCursorTurnRunner({
       execute: previewTool.execute,
     },
   };
+  // `remote_relay` joins the set only while this relay has paired remotes.
+  // Asked once when the worker starts; the first handle waits for the answer
+  // (it is created asynchronously anyway), and every handle creation refreshes
+  // it so a later rebuild picks up a remote paired in the meantime.
+  const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
+  void remoteRelayGate.refresh();
+  const remoteRelayTool = createRemoteRelayTool({
+    api,
+    getConversationId: () => activeMessage?.conversationId || sdkSessionId || '',
+    onCallStart: () => { pendingRemoteRelayCalls += 1; },
+    onCallEnd: () => { pendingRemoteRelayCalls -= 1; },
+    // The running turn's signal, read when the call starts: a Stop (or the
+    // auth retry burning a dead attempt) cancels the pending relay request.
+    // Between turns there is none — the last turn's may be aborted already.
+    getAbortSignal: () => (waitingForTurn ? currentAbortController?.signal || null : null),
+    dbg,
+  });
+
+  function customToolsForHandle() {
+    if (!remoteRelayGate.isEnabled()) return customTools;
+    return {
+      ...customTools,
+      [remoteRelayTool.name]: {
+        description: remoteRelayTool.description,
+        inputSchema: remoteRelayTool.inputSchema,
+        execute: remoteRelayTool.execute,
+      },
+    };
+  }
+
+  function hasPendingClientWork() {
+    return pendingAskUserCalls > 0 || pendingRemoteRelayCalls > 0;
+  }
 
   function getActiveQueueMessageId() {
     return waitingForTurn ? String(activeMessage?.id || '') : '';
@@ -262,7 +303,9 @@ export function createCursorTurnRunner({
     if (!agentHandle) {
       const durableId = String(message.cursorAgentId || '').trim() || cursorAgentId;
       const agents = buildCursorSubagentAgents(rosterModels);
-      const options = { apiKey, model, cwd, storeDir, sdkSessionId, customTools, agents, dbg };
+      await remoteRelayGate.ready();
+      const options = { apiKey, model, cwd, storeDir, sdkSessionId, customTools: customToolsForHandle(), agents, dbg };
+      void remoteRelayGate.refresh();
       try {
         agentHandle = await createAgentHandleImpl({ ...options, agentId: durableId });
       } catch (error) {
@@ -565,7 +608,7 @@ export function createCursorTurnRunner({
             // The SDK's documented recovery for a wedged persisted run —
             // armed by the second busy retry below.
             sendLocal: forceNextSend ? { force: true } : null,
-            hasPendingClientWork: () => pendingAskUserCalls > 0,
+            hasPendingClientWork,
             dbg,
           });
           forceNextSend = false;

package/server/cursor-worker/sdk-message-normalizer.mjs

@@ -1,6 +1,11 @@
 import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
 import { capThought } from '../../shared/thought-cap.mjs';
 import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
+import {
+  REMOTE_RELAY_TOOL_NAME,
+  isRemoteRelayToolName,
+  remoteRelayActivitySummary,
+} from '../../shared/remote-relay-tool-core.mjs';
 
 const MAX_TOOL_DETAIL_LENGTH = 140;
 const SUBAGENT_TOOL_NAMES = new Set(['task', 'agent']);
@@ -39,7 +44,27 @@ export function summarizeToolInput(toolName, input) {
   }
 }
 
+/**
+ * The relay's custom tools reach the stream as the SDK's generic MCP call
+ * (`name: 'mcp'`, args `{ providerIdentifier: 'custom-user-tools', toolName,
+ * args }`). `remote_relay` is shown as itself with the contract's one-line
+ * summary, so the transcript reads `Tool (remote_relay): send → …` like every
+ * other provider's; null for any other tool.
+ */
+function remoteRelayCallArgs(toolName, input) {
+  if (isRemoteRelayToolName(toolName)) return input || {};
+  if (String(toolName || '').trim().toLowerCase() !== 'mcp' || !input || typeof input !== 'object') return null;
+  return isRemoteRelayToolName(input.toolName) ? (input.args || {}) : null;
+}
+
 export function formatToolActivityText(toolName, input) {
+  const remoteArgs = remoteRelayCallArgs(toolName, input);
+  if (remoteArgs) {
+    const remoteSummary = remoteRelayActivitySummary(remoteArgs);
+    return truncate(remoteSummary
+      ? `Tool (${REMOTE_RELAY_TOOL_NAME}): ${remoteSummary}`
+      : `Tool (${REMOTE_RELAY_TOOL_NAME})`);
+  }
   const summary = summarizeToolInput(toolName, input);
   return truncate(summary ? `Tool (${toolName}): ${summary}` : `Tool (${toolName})`);
 }

package/server/db-schema.mjs

@@ -9,6 +9,8 @@
 // final schema either way.
 import { rebuildRecentWorkspaceRootsTable } from './migrations/0002-recent-workspace-roots-path-key.mjs';
 import { ensurePushSubscriptionsTable } from './migrations/0003-push-subscriptions.mjs';
+import { migrateSteerSettleMarkers } from './migrations/0004-steer-settle-markers.mjs';
+import { migrateRemoteRelays } from './migrations/0005-remote-relays.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -637,6 +639,13 @@ if (!queueColumns.includes('parked_at')) {
 if (!queueColumns.includes('parked_target_session_id')) {
   db.exec(`ALTER TABLE queue ADD COLUMN parked_target_session_id TEXT`);
 }
+if (!queueColumns.includes('consumed_at')) {
+  // Set when the Claude CLI has provably taken a row's prompt (a steer still
+  // pending when the turn it was pushed into finished). A consumed row is
+  // at-most-once: every recovery path fails it terminally instead of
+  // requeueing it, because a re-delivery would run the prompt a second time.
+  db.exec(`ALTER TABLE queue ADD COLUMN consumed_at TEXT`);
+}
 if (!queueColumns.includes('kind')) {
   // 'continuation' rows are synthetic turns for the Claude worker's
   // background-task continuations: born 'processing', never deliverable, and
@@ -682,6 +691,25 @@ db.exec(`CREATE INDEX IF NOT EXISTS idx_queue_owner_pending ON queue(status, own
 db.exec(`CREATE INDEX IF NOT EXISTS idx_queue_parked_release ON queue(status, parked_transaction_id, parked_target_session_id, parked_at, timestamp)`);
 db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_queue_continuation_op ON queue(continuation_op_id) WHERE continuation_op_id IS NOT NULL`);
 migrateImageConversationSchema(db);
+// After the queue's response_message_id exists: the source-link backfill
+// reads it. Not boot-critical — every reader of its columns tolerates their
+// absence — so a failure (e.g. SQLITE_BUSY) is logged and retried next boot
+// instead of keeping the relay down.
+try {
+  const steerSettleMarkersMigration = migrateSteerSettleMarkers(db);
+  if (steerSettleMarkersMigration.foldStubsRekinded) {
+    console.log(`[steering] re-kinded ${steerSettleMarkersMigration.foldStubsRekinded} fold stub(s) as 'folded'`);
+  }
+} catch (error) {
+  console.warn(`[steering] migration 0004 failed; retrying on next boot: ${error?.message || error}`);
+}
+// Remote relays: additive columns and the unlock table. Readers tolerate their
+// absence, so a failure is logged and retried next boot like 0004.
+try {
+  migrateRemoteRelays(db);
+} catch (error) {
+  console.warn(`[remote-relays] migration 0005 failed; retrying on next boot: ${error?.message || error}`);
+}
 
 const runtimeSessionColumns = db.prepare(`PRAGMA table_info(runtime_sessions)`).all().map((c) => c.name);
 if (runtimeSessionColumns.length) {

package/server/grok-worker/acp-client.mjs

@@ -17,6 +17,40 @@ function whichCommand(command = 'grok') {
 // ceiling bounds a single prompt absolutely. Both are overridable per call.
 export const ACP_PROMPT_INACTIVITY_MS = 120_000;
 export const ACP_PROMPT_MAX_TURN_MS = 1_800_000;
+// How long the watchdog waits for its `holdStall` question before treating
+// the silence as a stall after all.
+export const ACP_HOLD_CHECK_TIMEOUT_MS = 10_000;
+
+/**
+ * An MCP server launch (`{ command, args, env }`, see
+ * server/mcp/oar-mcp-server.mjs `buildOarMcpServerLaunch`) in the ACP stdio
+ * shape `session/new` and `session/load` take: no `type` field (that marks the
+ * http/sse transports), `args` and `env` always present, `env` as a list of
+ * `{ name, value }` pairs.
+ */
+export function toAcpStdioMcpServer(launch, name = 'oar') {
+  const env = launch?.env && typeof launch.env === 'object' ? launch.env : {};
+  return {
+    name: String(name || '').trim() || 'oar',
+    command: String(launch?.command || ''),
+    args: Array.isArray(launch?.args) ? launch.args.map((arg) => String(arg)) : [],
+    env: Object.entries(env).map(([key, value]) => ({ name: key, value: String(value ?? '') })),
+  };
+}
+
+/**
+ * An AcpClient class whose sessions carry `mcpServers` unless the caller
+ * passes its own. Lets the turn runner hand the adapter (which builds the
+ * client and opens the session in one step) a client that already knows them.
+ */
+export function withAcpMcpServers(BaseClient, mcpServers = []) {
+  const servers = Array.isArray(mcpServers) ? mcpServers : [];
+  return class AcpClientWithMcpServers extends BaseClient {
+    constructor(opts = {}) {
+      super({ ...opts, mcpServers: Array.isArray(opts?.mcpServers) ? opts.mcpServers : servers });
+    }
+  };
+}
 
 /**
  * Pick the one-shot allow option from an ACP permission request. A blanket
@@ -47,10 +81,13 @@ export class AcpClient extends EventEmitter {
    * @param {string} [opts.cwd]
    * @param {NodeJS.ProcessEnv} [opts.env]
    * @param {boolean} [opts.alwaysApprove]
+   * @param {Array<object>} [opts.mcpServers] ACP McpServer entries every
+   *   session/new and session/load carries (see toAcpStdioMcpServer)
    * @param {typeof spawn} [opts.spawnImpl]
    */
   constructor(opts = {}) {
     super();
+    this.mcpServers = Array.isArray(opts.mcpServers) ? opts.mcpServers.map((server) => ({ ...server })) : [];
     this.command = whichCommand(opts.command || 'grok');
     this.args = Array.isArray(opts.args) ? [...opts.args] : ['agent', '--no-leader', 'stdio'];
     if (opts.alwaysApprove && !this.args.includes('--always-approve') && !this.args.includes('--yolo')) {
@@ -276,10 +313,12 @@ export class AcpClient extends EventEmitter {
     return this.initializeResult;
   }
 
+  // MCP servers are per session in ACP, and a loaded session does not keep the
+  // ones it was created with — both calls pass them.
   async sessionNew(cwd, extra = {}) {
     return this.request('session/new', {
       cwd,
-      mcpServers: [],
+      mcpServers: this.mcpServers,
       ...extra,
     });
   }
@@ -288,7 +327,7 @@ export class AcpClient extends EventEmitter {
     return this.request('session/load', {
       sessionId,
       cwd,
-      mcpServers: [],
+      mcpServers: this.mcpServers,
       ...extra,
     });
   }
@@ -305,8 +344,15 @@ export class AcpClient extends EventEmitter {
    * @param {string} sessionId
    * @param {Array} prompt content blocks
    * @param {(update: object) => void} [onUpdate]
+   * `holdStall` (async, optional) is asked once the inactivity window has run
+   * out: `true` re-arms the full window instead of failing the prompt. It is
+   * for work the agent is blocked on that this client cannot see — a
+   * remote_relay call the agent runs through its MCP server, which the relay
+   * reports as in flight. A question that fails or takes longer than
+   * `holdCheckTimeoutMs` counts as `false`.
+   *
    * @param {object} [extra] additional session/prompt params (e.g. `_meta`)
-   * @param {object} [watchdog] { inactivityMs, maxTurnMs, hasPendingWork }
+   * @param {object} [watchdog] { inactivityMs, maxTurnMs, hasPendingWork, holdStall, holdCheckTimeoutMs }
    */
   async sessionPrompt(sessionId, prompt, onUpdate, extra = {}, watchdog = {}) {
     const inactivityMs = Number(watchdog?.inactivityMs) > 0
@@ -322,6 +368,10 @@ export class AcpClient extends EventEmitter {
     const hasPendingWork = typeof watchdog?.hasPendingWork === 'function'
       ? watchdog.hasPendingWork
       : () => false;
+    const holdStall = typeof watchdog?.holdStall === 'function' ? watchdog.holdStall : null;
+    const holdCheckTimeoutMs = Number(watchdog?.holdCheckTimeoutMs) > 0
+      ? Number(watchdog.holdCheckTimeoutMs)
+      : ACP_HOLD_CHECK_TIMEOUT_MS;
     const handler = (msg) => {
       if (msg.method !== 'session/update') return;
       if (msg.params?.sessionId && msg.params.sessionId !== sessionId) return;
@@ -329,8 +379,40 @@ export class AcpClient extends EventEmitter {
     };
     this.on('notification', handler);
     let watchdogTimer = null;
+    let settled = false;
+    // A granted hold restarts the window without faking ACP traffic.
+    let heldAt = 0;
+    let holdCheck = null;
+    const quietSince = () => Math.max(this.lastActivityAt, heldAt);
     const startedAt = Date.now();
     const stallPromise = new Promise((_, reject) => {
+      const stall = () => {
+        if (settled) return;
+        try { this.sessionCancel(sessionId); } catch { /* ignore */ }
+        reject(new Error(`grok turn stalled: no ACP activity for ${Math.round(inactivityMs / 1000)}s`));
+      };
+      const askForHold = () => {
+        let timer = null;
+        holdCheck = Promise.race([
+          Promise.resolve().then(() => holdStall()),
+          new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), holdCheckTimeoutMs);
+            timer.unref?.();
+          }),
+        ])
+          .then((hold) => hold === true, () => false)
+          .then((hold) => {
+            if (timer) clearTimeout(timer);
+            holdCheck = null;
+            if (settled) return;
+            if (hold) {
+              heldAt = Date.now();
+              return;
+            }
+            // Traffic that arrived while the question ran re-armed it anyway.
+            if (Date.now() - quietSince() >= inactivityMs) stall();
+          });
+      };
       const pollMs = Math.max(250, Math.min(5000, Math.floor(inactivityMs / 4)));
       watchdogTimer = setInterval(() => {
         const now = Date.now();
@@ -340,10 +422,13 @@ export class AcpClient extends EventEmitter {
           return;
         }
         if (hasPendingWork()) return;
-        if (now - this.lastActivityAt >= inactivityMs) {
-          try { this.sessionCancel(sessionId); } catch { /* ignore */ }
-          reject(new Error(`grok turn stalled: no ACP activity for ${Math.round(inactivityMs / 1000)}s`));
+        if (now - quietSince() < inactivityMs) return;
+        if (!holdStall) {
+          stall();
+          return;
         }
+        // Before the abort: is the agent blocked on work only the relay sees?
+        if (!holdCheck) askForHold();
       }, pollMs);
       if (typeof watchdogTimer.unref === 'function') watchdogTimer.unref();
     });
@@ -360,6 +445,7 @@ export class AcpClient extends EventEmitter {
         stallPromise,
       ]);
     } finally {
+      settled = true;
       clearInterval(watchdogTimer);
       this.off('notification', handler);
     }