mixdog 1.2.1 → 1.2.3

package/src/runtime/agent/orchestrator/session/send-with-recovery.mjs

@@ -12,6 +12,7 @@ import {
   isRetryableWireErrorEvent,
   isRetryableStreamErrorEvent,
   isProviderRecoveryExhausted,
+  isProviderRecoveryTerminal,
   isServerUnavailable,
   isStreamCut,
   isToolInputCut,
@@ -20,7 +21,9 @@ import {
   resetStallRetryBudget,
   resolveStallRetryBudget,
   retryAfterMsFromError,
+  sleepWithAbort,
 } from '../providers/retry-classifier.mjs';
+import { DETERMINISTIC_KINDS, providerErrorKind } from '../providers/provider-error-kind.mjs';
 import {
   persistsConfirmedImageRejection,
   promptHasInlineImages,
@@ -34,7 +37,6 @@ import {
   isThinkingReplayRejection,
   repairThinkingReplayInPlace,
 } from './thinking-replay-recovery.mjs';
-import { setTimeout as sleepMs } from 'node:timers/promises';
 import { readStreamOutcome } from '../providers/lib/stream-outcome.mjs';
 import { cloneProviderReplay } from '../providers/lib/provider-replay.mjs';
 import { resolveWorkerCompactPolicy } from './loop/compact-policy.mjs';
@@ -42,6 +44,7 @@ import { agentContextOverflowError } from './loop/context-overflow.mjs';
 import { estimateMessagesTokensSafe } from './loop/compact-debug.mjs';
 import { isOutputLimitStopReason } from './loop/termination.mjs';
 import { instrumentSendCallbacks } from './send-instrumentation.mjs';
+import { rejectedToolSchema } from './tool-schema-rejection.mjs';
 
 function normalizedIncompleteUsage(raw) {
   if (!raw || typeof raw !== 'object') return undefined;
@@ -126,10 +129,10 @@ const RECOVERY_RETRY_BACKOFF_MS = retryLadderFromEnv(
   [15_000, 30_000, 60_000, 60_000, 60_000]
 );
 
-// A server-advised wait (Retry-After) replaces the ladder step: a provider that
-// names its own cooldown knows better, within reason — one loop-level wait
-// never parks longer than this.
-const LOOP_RETRY_AFTER_CAP_MS = 120_000;
+// A server-advised wait (Retry-After / retryAfterMs) replaces the ladder step
+// and is honored in full, never shortened. The ladder length
+// still bounds how many replays run, the wait stays cancellable, and the
+// reconnecting stage reports its remaining delay (retryAt).
 
 // Jittering every backoff by 0.9–1.1 means parallel workers that lose the
 // same uplink do not resume in lockstep; our provider layers already jitter
@@ -138,14 +141,42 @@ const TRANSPORT_RETRY_JITTER_RATIO = 0.1;
 
 /** The ladder this failure class is entitled to: an unreachable network, a
  *  provider still unavailable after its own retries, or an ordinary fault. */
-function retryLadderFor(error) {
+function retryLadderFor(error, state = null) {
   if (isConnectFailure(error)) return CONNECTION_RETRY_BACKOFF_MS;
-  if (isProviderRecoveryExhausted(error) && isServerUnavailable(error)) return RECOVERY_RETRY_BACKOFF_MS;
+  if (isProviderRecoveryExhausted(error) && isServerUnavailable(error) && recoveryCyclesEnabled(state)) {
+    return RECOVERY_RETRY_BACKOFF_MS;
+  }
   return TRANSPORT_RETRY_BACKOFF_MS;
 }
 
-function retryBudgetFor(error) {
-  return retryLadderFor(error).length;
+// retryPolicy.recoveryCycles:false — a provider that already ran its own full
+// ladder surfaces its spent failure instead of parking on
+// the 15/30/60/60/60s recovery cycles.
+function recoveryCyclesEnabled(state) {
+  return loopRetryPolicy(state).recoveryCycles !== false;
+}
+
+// Per-provider loop retry policy, read off the provider object
+// (`provider.retryPolicy`), default = the bounded ladders:
+//   unboundedConnectionRetry — a connect failure keeps waiting on the
+//     5/10/20/40/60s… ladder (last step repeating) until the network returns;
+//     still cancellable, with "waiting for network" progress.
+//   contentFilterRetryable   — a content_filter refusal is replayed
+//     under the transport budget with a contextual guidance notice.
+//   inBandInvalidRequestRetryable — an in-band stream error whose only
+//     deterministic evidence is its invalid_request envelope is replayed.
+function loopRetryPolicy(state) {
+  const policy = state?.provider?.retryPolicy;
+  return policy && typeof policy === 'object' ? policy : {};
+}
+
+function waitsForNetwork(error, state) {
+  return loopRetryPolicy(state).unboundedConnectionRetry === true && isConnectFailure(error);
+}
+
+function retryBudgetFor(error, state = null) {
+  if (waitsForNetwork(error, state)) return Number.POSITIVE_INFINITY;
+  return retryLadderFor(error, state).length;
 }
 
 // A provider ladder spent on a connect failure has only shown that the network
@@ -153,15 +184,19 @@ function retryBudgetFor(error) {
 // unavailable parks on the recovery cycles, but only while nothing has reached
 // the user — a replay would otherwise re-show output or re-run a tool. Every
 // other exhausted failure surfaces as-is.
-function providerRecoveryEnded(error, outcome) {
+// A provider VERDICT that recovery is over (an advice-gated denial, the
+// repeated-overload stop) always ends it: the loop never overrides it.
+function providerRecoveryEnded(error, outcome, state = null) {
+  if (isProviderRecoveryTerminal(error)) return true;
   if (!isProviderRecoveryExhausted(error) || isConnectFailure(error)) return false;
+  if (!recoveryCyclesEnabled(state)) return true;
   return !(outcome.replaySafe === true && isServerUnavailable(error));
 }
 
-function transportRetryWaitMs(attemptIndex, error) {
+function transportRetryWaitMs(attemptIndex, error, state = null) {
   const advisedMs = retryAfterMsFromError(error);
-  if (advisedMs != null) return Math.min(advisedMs, LOOP_RETRY_AFTER_CAP_MS);
-  const ladder = retryLadderFor(error);
+  if (advisedMs != null) return advisedMs;
+  const ladder = retryLadderFor(error, state);
   const base = ladder[Math.min(Math.max(attemptIndex, 0), ladder.length - 1)];
   return jitterDelayMs(base, TRANSPORT_RETRY_JITTER_RATIO);
 }
@@ -258,6 +293,46 @@ function traceLoop({ sessionId, nextIteration }, kind, fields) {
 // 5s/15s wait rendered as a frozen turn with no explanation, so the stage
 // change surfaces "Reconnecting... n/max" instead of leaving the user
 // staring at a stalled stream.
+// Unbounded connect-failure wait (retryPolicy.unboundedConnectionRetry): no
+// "n/max" — the turn waits until the network is back, counting down each step.
+function emitWaitingForNetwork(opts, { attempt, waitMs, classifier, error }) {
+  if (typeof opts?.onStageChange !== 'function') return;
+  try {
+    const wait = Math.max(0, Number(waitMs) || 0);
+    opts.onStageChange('reconnecting', {
+      attempt,
+      max: null,
+      waitMs: wait,
+      retryAt: Date.now() + wait,
+      reason: 'waiting for network',
+      waitingForNetwork: true,
+      classifier: classifier || error?.code || null,
+      message: `Reconnecting… waiting for network · attempt ${attempt}${wait > 0 ? ` in ${Math.ceil(wait / 1000)}s` : ''}`,
+    });
+  } catch {
+    /* display-only */
+  }
+}
+
+// content_filter on a path that opted in (retryPolicy.contentFilterRetryable,
+// or the provider boundary stamping `contentFilterRetryable` on the error).
+// A provider-terminal verdict outranks the opt-in.
+function isReplayableContentFilter(sendErr, state) {
+  if (isProviderRecoveryTerminal(sendErr)) return false;
+  const optedIn = loopRetryPolicy(state).contentFilterRetryable === true || sendErr?.contentFilterRetryable === true;
+  return optedIn && providerErrorKind(sendErr).code === 'content_filter';
+}
+
+// The guidance travels as a contextual runtime fragment: the
+// [mixdog-runtime] prefix keeps it out of the visible transcript.
+const CONTENT_FILTER_NOTICE =
+  '[mixdog-runtime] The previous response was stopped by the provider content filter before it completed. ' +
+  'Continue the task, but rephrase or avoid the content that likely triggered the filter; do not repeat it verbatim.';
+
+function contentFilterNotice() {
+  return { role: 'user', content: CONTENT_FILTER_NOTICE, meta: { source: 'content-filter-recovery' } };
+}
+
 function emitLoopReconnectProgress(opts, { attempt, maxAttempts, waitMs, classifier, error }) {
   emitProviderRetryStage(opts?.onStageChange, {
     attempt,
@@ -331,6 +406,7 @@ async function recoverFromSendError(sendErr, state) {
     transportRetriesUsed = 0,
     imageStripUsed = false,
     thinkingReplayRepairUsed = false,
+    toolSchemaDropUsed = false,
     relayWitness,
   } = state;
   const outcome = readStreamOutcome(sendErr, relayWitness);
@@ -353,13 +429,36 @@ async function recoverFromSendError(sendErr, state) {
   }
   // Clean transient transport failure with zero exposure: replay the send
   // after a bounded wait instead of failing the turn.
+  if (isReplayableContentFilter(sendErr, state)) {
+    if (transportRetriesUsed < TRANSPORT_RETRY_MAX && (outcome.replaySafe === true || (await retract()))) {
+      return scheduleTransportReplay(sendErr, state, {
+        budget: TRANSPORT_RETRY_MAX,
+        note: `[loop] content filter stopped the response (${loopTag(state)}); replaying with guidance`,
+        trace: { kind: 'content_filter_retry' },
+        classifier: 'content_filter',
+        notice: contentFilterNotice(),
+      });
+    }
+    throw sendErr;
+  }
   if (
-    transportRetriesUsed < retryBudgetFor(sendErr) &&
-    !providerRecoveryEnded(sendErr, outcome) &&
-    (await transportReplayPermitted(sendErr, outcome, retract))
+    transportRetriesUsed < retryBudgetFor(sendErr, state) &&
+    !providerRecoveryEnded(sendErr, outcome, state) &&
+    (await transportReplayPermitted(sendErr, outcome, retract, state))
   ) {
     return retryTransport(sendErr, state);
   }
+  // A 400 naming one tool's input schema: the session drops that tool (with
+  // the notice) and the turn is replayed once without it. Nothing was
+  // generated, and the same body would fail every later turn.
+  if (toolSchemaDropUsed !== true) {
+    const exclusion = rejectedToolSchema(sendErr, state);
+    if (exclusion) {
+      logLoop(`[loop] provider rejected tool schema "${exclusion.name}" (${loopTag(state)}); dropping it and replaying once`);
+      traceLoop(state, 'tool_schema_drop', { tool: exclusion.name });
+      return { action: 'retry_tool_schema_drop', exclusion };
+    }
+  }
   // Anthropic replay-shape refusal: the latest assistant turn carries
   // thinking blocks the API will not accept back (a thinking run it did not
   // produce, or an empty text block). This is deterministic — the same body
@@ -373,7 +472,7 @@ async function recoverFromSendError(sendErr, state) {
   ) {
     return repairThinkingReplay(recoveryMessages, state);
   }
-  // Grok Build RetryWithImageStrip: drop inline images and replay once. Safe
+  // Image-strip retry: drop inline images and replay once. Safe
   // only when no tool was dispatched. Text exposure must be retracted first;
   // reasoning-only high-effort streams can retry without a text reset.
   if (
@@ -464,7 +563,7 @@ function isExposedNoToolStall(sendErr, outcome) {
 // 'transient' and never fired).
 async function recoverExposedStall(sendErr, outcome, state, retract) {
   const { transportRetriesUsed = 0 } = state;
-  const exposedRetryBudget = retryBudgetFor(sendErr);
+  const exposedRetryBudget = retryBudgetFor(sendErr, state);
   const len = sendErr.partialContent.length;
   if (transportRetriesUsed < exposedRetryBudget && !isProviderRecoveryExhausted(sendErr) && (await retract())) {
     return scheduleTransportReplay(sendErr, state, {
@@ -491,12 +590,17 @@ async function recoverExposedStall(sendErr, outcome, state, retract) {
 async function scheduleTransportReplay(sendErr, state, { budget, note, trace, classifier, notice = null }) {
   const { opts, signal, transportRetriesUsed = 0 } = state;
   const attempt = transportRetriesUsed + 1;
-  const waitMs = transportRetryWaitMs(transportRetriesUsed, sendErr);
+  const waitMs = transportRetryWaitMs(transportRetriesUsed, sendErr, state);
   logLoop(`${note}; transport retry ${attempt}/${budget} after ${waitMs}ms`);
   const { kind, ...fields } = trace;
   traceLoop(state, kind, { attempt, waitMs, ...fields });
-  emitLoopReconnectProgress(opts, { attempt, maxAttempts: budget, waitMs, classifier, error: sendErr });
-  await sleepMs(waitMs, undefined, signal ? { signal } : undefined);
+  if (Number.isFinite(budget)) {
+    emitLoopReconnectProgress(opts, { attempt, maxAttempts: budget, waitMs, classifier, error: sendErr });
+  } else {
+    emitWaitingForNetwork(opts, { attempt, waitMs, classifier, error: sendErr });
+  }
+  // Chunked, abortable sleep: honored advice may exceed one timer's range.
+  await sleepWithAbort(waitMs, signal, undefined, 'transport retry wait aborted');
   return beginFreshTransportAttempt(opts, budget, notice);
 }
 
@@ -542,7 +646,7 @@ function continueFromShownText(sendErr, state, relayWitness) {
 // budget still bounds it.
 async function recoverToolInputCut(sendErr, outcome, state, retract) {
   const { transportRetriesUsed = 0 } = state;
-  const budget = retryBudgetFor(sendErr);
+  const budget = retryBudgetFor(sendErr, state);
   if (transportRetriesUsed < budget && (outcome.replaySafe === true || (await retract()))) {
     return scheduleTransportReplay(sendErr, state, {
       budget,
@@ -650,20 +754,55 @@ function recoverPartialToolCalls(sendErr, state, toolCalls, outcome) {
 // reasoning/text exposure makes classifyError() intentionally permanent,
 // non-terminal close, or a dropped connection (undici `terminated`, socket
 // reset) — then retract the exposed text and replay.
-async function transportReplayPermitted(sendErr, outcome, retract) {
-  if (outcome.replaySafe === true && classifyError(sendErr) === 'transient') return true;
-  const transportSymptom =
+async function transportReplayPermitted(sendErr, outcome, retract, state) {
+  if (!isSemanticallyRetryable(sendErr, state)) return false;
+  // Existing replay-safety gate: an unexposed failure replays outright only
+  // when it is typed-transient (or an opted-in in-band invalid_request); a
+  // named symptom replays after retraction.
+  if (
+    outcome.replaySafe === true &&
+    (classifyError(sendErr) === 'transient' || inBandInvalidRequestReplay(sendErr, state))
+  ) {
+    return true;
+  }
+  return await retract();
+}
+
+// The ONE semantic verdict on whether this failure is worth re-issuing,
+// independent of what was exposed (the replay-safety gate decides that
+// afterwards): never a deterministic refusal (quota, plan, billing, policy,
+// auth, permission, context or size) — server advice never makes one
+// retryable — and otherwise a named transient/transport symptom.
+function inBandInvalidRequestReplay(sendErr, state) {
+  return (
+    loopRetryPolicy(state).inBandInvalidRequestRetryable === true &&
+    providerErrorKind(sendErr).kind === 'invalid_request' &&
+    isRetryableStreamErrorEvent(sendErr)
+  );
+}
+
+function isSemanticallyRetryable(sendErr, state) {
+  if (isProviderRecoveryTerminal(sendErr)) return false;
+  // Opt-in (retryPolicy.inBandInvalidRequestRetryable): a provider whose
+  // in-band stream errors carry an invalid_request envelope for server faults
+  // replays one with no other deterministic evidence; for every other
+  // provider it is a final refusal.
+  const { kind } = providerErrorKind(sendErr);
+  if (DETERMINISTIC_KINDS.has(kind) && !inBandInvalidRequestReplay(sendErr, state)) {
+    return false;
+  }
+  return (
     classifyError(sendErr) === 'transient' ||
     isStreamCut(sendErr) ||
     isRetryableWireErrorEvent(sendErr) ||
     isRetryableStreamErrorEvent(sendErr) ||
-    isCursorTransientTransportError(sendErr);
-  return transportSymptom && (await retract());
+    isCursorTransientTransportError(sendErr)
+  );
 }
 
 function retryTransport(sendErr, state) {
   return scheduleTransportReplay(sendErr, state, {
-    budget: retryBudgetFor(sendErr),
+    budget: retryBudgetFor(sendErr, state),
     note:
       `[loop] transient send failure with no dispatched tools (${loopTag(state)} code=${sendErr?.code ?? 'n/a'} ` +
       `wsCloseCode=${sendErr?.wsCloseCode ?? 'n/a'} httpStatus=${sendErr?.httpStatus ?? sendErr?.status ?? 'n/a'})`,
@@ -700,7 +839,7 @@ function imageStripEligible(
       hasImages: promptHasInlineImages(recoveryMessages),
       alreadyStripped: imageStripUsed === true,
     }) ||
-      // Grok Build RetryWithImageStrip only: a bare stream error on a Grok
+      // Grok only: a bare stream error on a Grok
       // upload may be the image body being rejected. Other providers' transient
       // stream errors are not evidence about images and use normal transport retry.
       (isGrok &&

package/src/runtime/agent/orchestrator/session/side-question-store.mjs

@@ -0,0 +1,96 @@
+// side-question-store.mjs — the in-memory state behind /btw side questions:
+// per session, the latest provider request the main loop sent (the request a
+// side question forks) and the side question in flight. It holds live
+// provider/tool objects, so it never reaches the session record or disk.
+import { isAgentOwner } from '../agent-owner.mjs';
+
+// sessionId -> { provider, model, messages, tools, opts, response }
+const requests = new Map();
+// sessionId -> AbortController of the side question in flight.
+const inFlight = new Map();
+
+// Send options that steer the live loop rather than shape the request: its
+// abort signal, a one-shot cache-break trace tag and the per-request stall
+// budget. A forced tool choice is dropped too (a side question must be able
+// to answer in text); the hard-cap `none` choice is kept.
+const LOOP_ONLY_OPTIONS = new Set(['signal', 'cacheBreakIntent', '_stallRetryBudget', 'toolChoice']);
+
+function requestOptions(opts) {
+  const out = {};
+  for (const [key, value] of Object.entries(opts || {})) {
+    if (typeof value === 'function' || LOOP_ONLY_OPTIONS.has(key)) continue;
+    out[key] = value;
+  }
+  if (opts?.toolChoice === 'none') out.toolChoice = 'none';
+  return out;
+}
+
+/** A request in the stored shape: its own message list and only the send
+ *  options a fork may reuse. `response` is null until the reply settles. */
+export function sideQuestionRequestSnapshot({ provider, model, messages, tools, opts }) {
+  return {
+    provider,
+    model,
+    messages: [...messages],
+    tools: Array.isArray(tools) ? tools : [],
+    opts: requestOptions(opts),
+    response: null,
+  };
+}
+
+/**
+ * Record a provider request the main loop is sending as the session's latest
+ * one. Agent sessions record nothing (/btw is a Lead command). The handle
+ * attaches the reply once the send proceeds, or puts the previous request
+ * back when this one fails, so only a successfully sent request is kept.
+ */
+export function captureSideQuestionRequest({ sessionId, sessionRef, provider, model, messages, tools, opts }) {
+  if (!sessionId || !provider || isAgentOwner(sessionRef)) return null;
+  const previous = requests.get(sessionId);
+  const request = sideQuestionRequestSnapshot({ provider, model, messages, tools, opts });
+  requests.set(sessionId, request);
+  return {
+    settle(response) {
+      request.response = response || null;
+    },
+    discard() {
+      if (requests.get(sessionId) !== request) return;
+      if (previous) requests.set(sessionId, previous);
+      else requests.delete(sessionId);
+    },
+  };
+}
+
+export function sideQuestionRequest(sessionId) {
+  return (sessionId && requests.get(sessionId)) || null;
+}
+
+/** Start the session's side question, aborting the one still in flight. */
+export function beginSideQuestion(sessionId) {
+  cancelSideQuestion(sessionId);
+  const controller = new AbortController();
+  inFlight.set(sessionId, controller);
+  return {
+    signal: controller.signal,
+    end() {
+      if (inFlight.get(sessionId) === controller) inFlight.delete(sessionId);
+    },
+  };
+}
+
+export function cancelSideQuestion(sessionId) {
+  const controller = sessionId ? inFlight.get(sessionId) : null;
+  if (!controller) return false;
+  inFlight.delete(sessionId);
+  controller.abort(new Error('Side question canceled.'));
+  return true;
+}
+
+/** The transcript the saved request carried is gone (clear, rewind): a later
+ *  side question waits for the next request. `cancel` also aborts the side
+ *  question in flight (session close / runtime unload). */
+export function forgetSideQuestion(sessionId, { cancel = false } = {}) {
+  if (!sessionId) return;
+  requests.delete(sessionId);
+  if (cancel) cancelSideQuestion(sessionId);
+}

package/src/runtime/agent/orchestrator/session/side-question.mjs

@@ -0,0 +1,192 @@
+// side-question.mjs — /btw: a quick question answered while the main turn
+// keeps working. The answer comes from a cache-sharing fork of the session's
+// latest provider request (side-question-store.mjs): the same model, system
+// prompt, tools and cache-relevant options and the same message prefix, so
+// the provider's prompt cache serves the prefix. Only the reply that request
+// produced and one question are appended. One provider call, no tool loop;
+// the answer is returned to the caller and never enters the transcript.
+import { collectAssistantToolCallIds } from './context-tool-pairs.mjs';
+import { buildIntermediateAssistantMessage, buildToolCallAssistantMessage } from './loop/assistant-commit.mjs';
+import { logSessionLlmUsage } from './manager/ask-turn-commit.mjs';
+import { disposeTransportScope, forkTransportScope } from '../providers/transport-scope.mjs';
+import { isAgentOwner } from '../agent-owner.mjs';
+import { getProvider } from '../providers/registry.mjs';
+import { prepareTurnEffortConfiguration } from '../providers/effort-configuration.mjs';
+import { providerNativeToolPrefixCount } from '../runtime-core/provider-request-tools.mjs';
+import { snapshotProviderRequestTools } from '../runtime-core/tool-catalog.mjs';
+import { repairTranscriptBeforeProviderSend } from './loop/transcript-repair.mjs';
+import { buildRequestSendOptions } from './manager/ask-turn-loop-options.mjs';
+import { filterModelVisibleSessionMessages } from './manager/message-sanitize.mjs';
+import { hasUserConversationMessage } from './manager/prompt-utils.mjs';
+import { loadSession } from './store.mjs';
+import { projectSyntheticUserEnvelopes } from './synthetic-user-envelope.mjs';
+import { beginSideQuestion, sideQuestionRequest, sideQuestionRequestSnapshot } from './side-question-store.mjs';
+
+export { cancelSideQuestion } from './side-question-store.mjs';
+
+export const SIDE_QUESTION_NO_REQUEST = 'Send a message first, then try /btw.';
+export const SIDE_QUESTION_TOOL_ATTEMPT =
+  'The model tried to use a tool instead of answering. A side question cannot run tools; try asking it differently.';
+const SIDE_QUESTION_EMPTY_ANSWER = 'The model returned no answer.';
+
+// The reply's tool calls run in the main session; the fork only needs each
+// call answered so the request stays well-formed.
+const SIDE_QUESTION_TOOL_STUB =
+  'This tool call belongs to the main task and is handled there; its result is not part of this side question.';
+
+function sideQuestionPrompt(question) {
+  return [
+    '<side-question>',
+    'The user is asking you a quick side question. The main agent keeps working on the task on its own;',
+    'this exchange does not reach it and does not change that work.',
+    'Answer directly, in this one response, from what this conversation already contains.',
+    'No tools are available here: do not call any, and do not offer or promise to do anything.',
+    'If the conversation does not tell you the answer, say that you do not know.',
+    '',
+    question,
+    '</side-question>',
+  ].join('\n');
+}
+
+// The assistant turn the saved request produced, built the way the loop
+// commits it (without the turn's one-shot transcript metadata), plus a stub
+// result per tool call.
+function replyMessages(response) {
+  if (!response) return [];
+  const reply = response.toolCalls?.length
+    ? buildToolCallAssistantMessage(response, { calls: response.toolCalls, suppressMidTurnText: false, opts: {} })
+    : buildIntermediateAssistantMessage(response, {});
+  if (!reply) return [];
+  const stubs = collectAssistantToolCallIds(reply).map((id) => ({
+    role: 'tool',
+    toolCallId: id,
+    content: SIDE_QUESTION_TOOL_STUB,
+  }));
+  return [reply, ...stubs];
+}
+
+/**
+ * The fork of a saved request: its messages unchanged, then the reply and
+ * the question. The send options are the saved ones; the provider
+ * continuation state follows the reply when it is appended, exactly as the
+ * main loop's next request would carry it. `sharedCachePrefixCount` (the
+ * shared prefix's message count, which survives model-proxy serialization)
+ * keeps an Anthropic message breakpoint on the shared prefix, so the fork reads the
+ * saved request's cache entry and writes none for its suffix.
+ */
+export function buildSideQuestionRequest(request, question) {
+  const reply = replyMessages(request.response);
+  const opts = { ...request.opts };
+  if (reply.length && Object.hasOwn(request.response, 'providerState')) {
+    opts.providerState = request.response.providerState;
+  }
+  if (request.messages.length) opts.sharedCachePrefixCount = request.messages.length;
+  const messages = [
+    ...request.messages,
+    ...reply,
+    // A user interjection keeps its own turn (never folded into a preceding
+    // tool result), so the prefix's last block reaches the provider unchanged.
+    { role: 'user', content: sideQuestionPrompt(question), meta: { source: 'steering' } },
+  ];
+  return { messages, opts };
+}
+
+/**
+ * The request the main loop would send next for a session that has none saved
+ * (the runtime restarted, or the saved one was forgotten): the session's own
+ * provider, model, tools, send options and transcript, assembled by the same
+ * pieces the loop uses, without the loop's side effects (no compaction, no
+ * transcript repair in place, nothing written to the session). Null when the
+ * session has no conversation, no resolvable provider, or is an agent's.
+ */
+function nextMainRequest(sessionId) {
+  const session = sessionId ? loadSession(sessionId) : null;
+  if (!session || session.closed === true || isAgentOwner(session)) return null;
+  if (!hasUserConversationMessage(session.messages)) return null;
+  const provider = getProvider(session.provider);
+  if (!provider) return null;
+  const transcript = filterModelVisibleSessionMessages(session.messages);
+  repairTranscriptBeforeProviderSend(transcript, sessionId);
+  const opts = buildRequestSendOptions({
+    sessionId,
+    session,
+    turnEffort: session.effort || null,
+    effortConfiguration: prepareTurnEffortConfiguration(session, provider),
+    stepAutoEffort: null,
+    codexTurnId: null,
+    startedAtMs: Date.now(),
+    signal: undefined,
+  });
+  const sendTools = snapshotProviderRequestTools({
+    provider: session.provider || provider.name,
+    tools: session.tools,
+    nativeTools: opts.nativeTools,
+    messages: transcript,
+    session,
+  });
+  opts.iteration = 1;
+  opts.providerToolSnapshotAuthoritative = true;
+  opts.providerNativeToolPrefixCount = providerNativeToolPrefixCount(sendTools);
+  return sideQuestionRequestSnapshot({
+    provider,
+    model: session.model,
+    messages: projectSyntheticUserEnvelopes(transcript).messages,
+    tools: sendTools,
+    opts,
+  });
+}
+
+function answerText(response) {
+  if (response?.toolCalls?.length) return SIDE_QUESTION_TOOL_ATTEMPT;
+  const text = typeof response?.content === 'string' ? response.content.trim() : '';
+  return text || SIDE_QUESTION_EMPTY_ANSWER;
+}
+
+/**
+ * Answer `question` from the session's latest provider request. One side
+ * question runs per session: a new one aborts the previous, and
+ * cancelSideQuestion aborts it. A session without a saved request forks the
+ * request its next turn would send. Rejects when the session has no
+ * conversation or provider, with the provider's error, or with the cancel
+ * reason.
+ */
+export async function askSideQuestion(sessionId, question) {
+  const text = typeof question === 'string' ? question.trim() : '';
+  if (!text) throw new TypeError('Side question is empty.');
+  const request = sideQuestionRequest(sessionId) || nextMainRequest(sessionId);
+  if (!request) throw new Error(SIDE_QUESTION_NO_REQUEST);
+  const run = beginSideQuestion(sessionId);
+  const startedAt = Date.now();
+  // The fork keeps the session id (prompt cache routing) but runs on its own
+  // transport scope: no pooled socket, response-chain anchor, turn-state
+  // token or provider run of the main session is waited on, read or replaced.
+  const transportScope = forkTransportScope(sessionId, 'side');
+  try {
+    const { messages, opts } = buildSideQuestionRequest(request, text);
+    let response;
+    try {
+      response = await request.provider.send(messages, request.model, request.tools.length ? request.tools : undefined, {
+        ...opts,
+        transportScope,
+        admissionOwner: sessionId,
+        signal: run.signal,
+      });
+    } catch (error) {
+      throw run.signal.aborted ? run.signal.reason : error;
+    }
+    if (run.signal.aborted) throw run.signal.reason;
+    const session = request.opts.session;
+    if (response?.usage && session?.id) {
+      void logSessionLlmUsage({
+        session: { ...session, model: request.model },
+        usage: response.usage,
+        startedAt,
+        mode: 'side-question',
+      }).catch(() => {});
+    }
+    return { text: answerText(response) };
+  } finally {
+    run.end();
+    disposeTransportScope(transportScope, request.provider);
+  }
+}

package/src/runtime/agent/orchestrator/session/store/lifecycle-barriers.mjs

@@ -158,9 +158,23 @@ function _logSessionCloseMetric(id, existing, closedAt, reason) {
   }
 }
 
+/**
+ * A barrier that found no record at all — nothing on disk and no live or
+ * pending copy in memory — fenced nothing because there is nothing to fence:
+ * its pending writes were already cancelled under the commit lock. It still
+ * returns null (no generation exists), but a caller passing `options.outcome`
+ * learns that the record was legitimately gone rather than vetoed, contended
+ * or failed.
+ */
+function _recordAbsent(options) {
+  if (options?.outcome && typeof options.outcome === 'object') options.outcome.absent = true;
+  return null;
+}
+
 /**
  * Atomically mark a session closed on disk with a bumped generation.
  * Returns the new generation, or null if the session file doesn't exist.
+ * `options.outcome` (an object) gets `absent: true` when no record existed.
  * Used by closeSession() to plant a tombstone that races against in-flight
  * saveSession() calls.
  */
@@ -187,7 +201,7 @@ export function markSessionClosed(id, reason = 'manual', options = {}) {
     _cancelSessionWrites(id);
     _uncacheSessionSummary(id);
     const existing = loadSession(id);
-    if (!existing) return null;
+    if (!existing) return _recordAbsent(options);
     // Re-close idempotence: a session that is ALREADY tombstoned keeps its
     // ORIGINAL close time (updatedAt) and generation. The old code refreshed
     // updatedAt=Date.now() on every call, so the 5-min idle sweep re-closing a
@@ -253,7 +267,7 @@ export function markSessionClosed(id, reason = 'manual', options = {}) {
  * of clobbering whatever the resumed session writes next.
  * Returns the new generation, or null if the session file doesn't exist.
  */
-export function bumpSessionGeneration(id, reason = 'detach') {
+export function bumpSessionGeneration(id, reason = 'detach', options = {}) {
   clearSessionLifecycleCommitError(id);
   // The detach barrier is a canonical write and MUST take the same commit
   // lock as markSessionClosed. Cancellation alone is not a barrier: a writer
@@ -278,7 +292,7 @@ export function bumpSessionGeneration(id, reason = 'detach') {
     _cancelSessionWrites(id);
     _uncacheSessionSummary(id);
     const existing = loadSession(id);
-    if (!existing) return null;
+    if (!existing) return _recordAbsent(options);
     const newGen = (typeof existing.generation === 'number' ? existing.generation : 0) + 1;
     const detached = { ...existing, generation: newGen, updatedAt: Date.now(), detachedReason: reason };
     if (!_writeLifecycleRecord(id, detached, existing, reason)) return null;