@inetafrica/open-claudia 2.15.0 → 3.0.0

package/core/runner.js

@@ -1,36 +1,43 @@
-// Backend runner — Claude Code, Cursor Agent, OpenAI Codex. Owns
+// Provider runner — Claude Code and OpenAI Codex. Owns
 // argv construction, subprocess lifecycle, stream parsing, and the
 // progress UI. All IO routes through core/io.js so the same runner
 // works on every channel.
 
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const { spawn, execFileSync } = require("child_process");
 const {
-  CLAUDE_PATH, DEFAULT_CLAUDE_MODEL, resolvedCursorPath, resolvedCodexPath,
-  AUTO_COMPACT_TOKENS, MIN_COMPACT_INTERVAL_MS, MAX_PROCESS_TIMEOUT, COMPACT_SUMMARY_TIMEOUT, botSubprocessEnv,
+  AUTO_COMPACT_TOKENS, MIN_COMPACT_INTERVAL_MS, MAX_PROCESS_TIMEOUT, COMPACT_SUMMARY_TIMEOUT,
   CONFIG_DIR, WORKSPACE, config,
 } = require("./config");
-const { currentState, saveState, recordSession, userOwnsClaudeSession, resetSessionUsage, acquireRunLock } = require("./state");
-const { chatContext, currentChannelId, currentAdapter, currentUserId } = require("./context");
-const { splitLeadingOriginGroup } = require("./queue-drain");
-const { buildSystemPrompt, promptWithDynamicContext } = require("./system-prompt");
+const {
+  currentState, saveState, recordSession,
+  resetSessionUsage, acquireRunLock, getActiveProvider, getProjectKey,
+  getProviderSession, setProviderSession, clearProviderSession, getUsageForSession, commitProviderCompaction,
+} = require("./state");
+const { chatContext, currentChannelId, currentAdapter } = require("./context");
+const { buildTurnPrompt } = require("./system-prompt");
+const { getProvider, resolveProviderForRun } = require("./providers");
+const { validateInvocation } = require("./providers/contract");
+const { selectTerminalText } = require("./providers/events");
+const {
+  bindRunInputs,
+  captureRunContext,
+  deepFreeze,
+  sameCapturedProject,
+} = require("./run-context");
 const { redactSensitive } = require("./redact");
-const { send, editMessage, sendVoice, sendVoiceEnd, splitMessage } = require("./io");
+const { createSideChatPromptBuilder, sideChatCoordinator } = require("./side-chat");
+const { send, sendVoice, sendVoiceEnd, splitMessage } = require("./io");
 const { textToVoice, splitSentences, synthSentenceMp3 } = require("./media");
-const { killProcessTree } = require("./process-tree");
+const { killProcessTree, waitForPidsExit } = require("./process-tree");
 const {
   appendProjectTranscript, transcriptProjectInfo,
   stripTranscriptPointerForStorage,
 } = require("./transcripts");
-const { getClaudeOAuthToken, claudeAuthRecoveryMessage, isClaudeAuthErrorText, claudeUsageLimitMessage, isClaudeUsageLimitText, runClaudeAuthStatusDiagnostic, claudeSubprocessEnv } = require("./auth-flow");
 const loopback = require("./loopback");
-const skillsLib = require("./skills");
-const packsLib = require("./packs");
-const entitiesLib = require("./entities");
-const toolsLib = require("./tools");
 const packReview = require("./pack-review");
-const { recallNodeFromPath } = require("./recall/read-signal");
 const {
   appendUsageRecord,
   loadUsageHistory,
@@ -56,7 +63,10 @@ function usageNumber(usage, ...keys) {
   return 0;
 }
 
-function usageParts(usage, backend = "claude") {
+function usageParts(usage, backend) {
+  if (!new Set(["claude", "codex"]).has(backend)) {
+    throw Object.assign(new TypeError("usage accounting requires an explicit provider"), { code: "INVALID_PROVIDER" });
+  }
   const input = usageNumber(usage, "input_tokens");
   const cacheRead = backend === "codex"
     ? usageNumber(usage, "cached_input_tokens", "cache_read_input_tokens")
@@ -85,36 +95,35 @@ function clampUsageDelta(current, previous) {
   };
 }
 
-function snapshotCodexUsage(state, sessionId, usage) {
+function snapshotCodexUsage(state, sessionId, usage, options = {}) {
   if (!state || !sessionId || !usage) return null;
-  const snapshots = state.codexUsageSnapshots && typeof state.codexUsageSnapshots === "object"
-    ? state.codexUsageSnapshots
-    : {};
-  const previous = snapshots[sessionId] || null;
-  snapshots[sessionId] = {
+  const project = options.project || getProjectKey(state);
+  if (!project) return null;
+  const bucket = getUsageForSession(state, project, "codex", sessionId);
+  const previous = bucket.providerUsageSnapshot || null;
+  bucket.providerUsageSnapshot = {
     input_tokens: usageNumber(usage, "input_tokens"),
     cached_input_tokens: usageNumber(usage, "cached_input_tokens"),
     output_tokens: usageNumber(usage, "output_tokens"),
   };
-  const keys = Object.keys(snapshots);
-  if (keys.length > 20) {
-    for (const key of keys.slice(0, keys.length - 20)) delete snapshots[key];
-  }
-  state.codexUsageSnapshots = snapshots;
   return previous;
 }
 
-function normalizeCodexUsage(state, sessionId, usage) {
-  const previous = snapshotCodexUsage(state, sessionId, usage);
+function normalizeCodexUsage(state, sessionId, usage, options = {}) {
+  const previous = snapshotCodexUsage(state, sessionId, usage, options);
   if (!previous) return { usage, usageScope: "session_total", rawUsage: usage };
   return { usage: clampUsageDelta(usage, previous), usageScope: "turn_delta", rawUsage: usage };
 }
 
 function applyUsageToState(state, usage, costUsd, opts = {}) {
   if (!usage) return null;
-  const backend = state.settings?.backend || "claude";
+  const backend = opts.backend || getActiveProvider(state);
   const parts = usageParts(usage, backend);
-  const u = state.sessionUsage;
+  const project = opts.project || null;
+  const sessionId = opts.sessionId || null;
+  const u = project
+    ? getUsageForSession(state, project, backend, sessionId)
+    : state.sessionUsage;
   u.turns += 1;
   u.inputTokens += parts.input;
   u.outputTokens += parts.output;
@@ -130,7 +139,7 @@ function applyUsageToState(state, usage, costUsd, opts = {}) {
 
 function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
   if (!usage) return null;
-  const backend = state.settings?.backend || "claude";
+  const backend = opts.backend || getActiveProvider(state);
   const parts = usageParts(usage, backend);
   const usageScope = opts.usageScope || "turn_delta";
   // `parts.context` is the per-turn SUM of every API call's prefix, inflated
@@ -142,9 +151,16 @@ function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
     ts: new Date().toISOString(),
     version: PKG_VERSION,
     backend,
-    model: state.settings?.model || (backend === "claude" ? DEFAULT_CLAUDE_MODEL : null),
-    userId: state.userId || null,
-    sessionId: state[getActiveSessionKey(state)] || null,
+    provider: backend,
+    model: Object.prototype.hasOwnProperty.call(opts, "model")
+      ? (opts.model || null)
+      : (state.providerSettings?.[backend]?.model || getProvider(backend).defaultModel()),
+    userId: opts.userId || state.userId || null,
+    sessionId: Object.prototype.hasOwnProperty.call(opts, "sessionId")
+      ? (opts.sessionId || null)
+      : getProviderSession(state, backend, getProjectKey(state)),
+    runId: opts.runId || null,
+    project: opts.project || null,
     usageScope,
     inputTokens: parts.input,
     outputTokens: parts.output,
@@ -162,7 +178,7 @@ function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
     record.rawContextTokens = raw.context;
   }
   const previousRecords = loadUsageHistory();
-  appendUsageRecord(record);
+  appendUsageRecord(record, { strict: !!opts.strict });
 
   const policy = usageAlertPolicy(config);
   const lastAlertAt = state.usageAlertLastAt || 0;
@@ -194,69 +210,656 @@ function telegramHtmlOpts(extra = {}) {
   return adapter?.type === "telegram" ? { ...extra, parseMode: "HTML" } : extra;
 }
 
-function chatEnvOverlay() {
-  const adapter = currentAdapter();
-  const channelId = currentChannelId();
-  const lb = loopback.info();
-  const overlay = {};
-  if (adapter && adapter.id) overlay.OC_CHANNEL_ADAPTER = adapter.id;
-  if (channelId) overlay.OC_CHANNEL_ID = String(channelId);
-  // Raw per-user id (distinct from channelId on Kazee) so subprocess egress
-  // guards classify the speaker by person, not room — matching in-process
-  // relationship.speakerFor. On Telegram this equals channelId.
-  const uid = currentUserId();
-  if (uid) overlay.OC_CHANNEL_USER_ID = String(uid);
-  if (lb) {
-    overlay.OC_SEND_URL = lb.url;
-    overlay.OC_SEND_TOKEN = lb.token;
-  }
-  const tinfo = transcriptProjectInfo();
-  if (tinfo && tinfo.transcriptPath) overlay.OC_TRANSCRIPT_PATH = tinfo.transcriptPath;
+function stableRunError(message, code = "PROVIDER_RUN_FAILED", details = {}) {
+  const error = new Error(redactSensitive(String(message || "Provider run failed")));
+  error.name = "ProviderRunError";
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function createPersistenceOutcome() {
+  return {
+    transcript: { ok: true, skipped: true },
+    usage: { ok: true, skipped: true },
+    session: { ok: true, skipped: true },
+  };
+}
+
+// Provider-neutral child lifecycle. It owns framing/normalization and resolves
+// only after EOF, child close, cleanup, required persistence, and delivery.
+// Expected provider/process failures are values, not rejected promises.
+async function executeProviderInvocation(options = {}) {
+  const {
+    runContext,
+    provider,
+    cwd,
+    spawnProcess = spawn,
+    timeoutMs = MAX_PROCESS_TIMEOUT,
+    killTree = killProcessTree,
+    killGraceMs = 5000,
+    cleanup = async () => {},
+    persistTranscript = null,
+    persistUsage = null,
+    persistSession = null,
+    deliver = null,
+    onEvent = null,
+    onSpawn = null,
+    onStderr = null,
+    idleTimeoutMs = 0,
+  } = options;
+  const startedAt = Date.now();
+  const invocation = validateInvocation(options.invocation);
+  const persistence = createPersistenceOutcome();
+  const delivery = { ok: true, skipped: !deliver };
+  const cleanupOutcome = { ok: true, skipped: false };
+  const rawErrors = [];
+  const usageEvents = [];
+  const tools = [];
+  const textDeltas = [];
+  const textFinals = [];
+  let resultText = "";
+  let sessionId = runContext?.sessionId || null;
+  let terminalSeen = false;
+  let stdoutEnded = false;
+  let timedOut = false;
+  let watchdogTripped = false;
+  let spawnError = null;
+  let stderr = "";
+  let proc = null;
+  let closeInfo = null;
+  let lastActivity = Date.now();
+  let timeoutTimer = null;
+  let killTimer = null;
+  let idleTimer = null;
+  let terminationStarted = false;
+  let terminationForced = false;
+  let resolveTermination;
+  let terminationPromise = Promise.resolve();
+  const terminationDescendants = new Set();
+  let decoderEnded = false;
+  let eventChain = Promise.resolve();
+  const decoder = provider.createEventDecoder();
+
+  const rememberDescendants = (value) => {
+    if (!Array.isArray(value)) return;
+    for (const pid of value) {
+      const number = Number(pid);
+      if (Number.isSafeInteger(number) && number > 0 && number !== proc?.pid) terminationDescendants.add(number);
+    }
+  };
+
+  const forceTermination = async () => {
+    if (!terminationStarted || terminationForced) return;
+    terminationForced = true;
+    if (killTimer) clearTimeout(killTimer);
+    try {
+      if (!closeInfo) {
+        try { rememberDescendants(killTree(proc?.pid, "SIGKILL")); } catch (_) {}
+      }
+      for (const pid of [...terminationDescendants]) {
+        try { rememberDescendants(killTree(pid, "SIGKILL")); } catch (_) {}
+      }
+      const survivors = await waitForPidsExit(
+        [...terminationDescendants],
+        Math.max(100, Math.min(2000, Number(killGraceMs) || 100)),
+      );
+      if (survivors.length) {
+        cleanupOutcome.ok = false;
+        cleanupOutcome.error = stableRunError("Provider descendants survived forced termination", "RUN_CLEANUP_FAILED", { pids: survivors });
+      }
+    } finally {
+      resolveTermination?.();
+    }
+  };
+
+  const beginTermination = (idle = false) => {
+    if (terminationStarted) return;
+    terminationStarted = true;
+    timedOut = true;
+    watchdogTripped = idle;
+    terminationPromise = new Promise((resolve) => { resolveTermination = resolve; });
+    killTimer = setTimeout(() => { void forceTermination(); }, Math.max(0, killGraceMs));
+    try { rememberDescendants(killTree(proc?.pid, "SIGTERM")); } catch (_) {}
+  };
+
+  const handleNormalizedEvent = (event) => {
+    if (!event || typeof event !== "object") return;
+    if (event.type === "session" && event.sessionId) sessionId = event.sessionId;
+    else if (event.type === "text_delta" && typeof event.text === "string") textDeltas.push(event.text);
+    else if (event.type === "text_final" && typeof event.text === "string") textFinals.push(event.text);
+    else if (event.type === "tool_start" || event.type === "tool_end") tools.push(event);
+    else if (event.type === "usage") usageEvents.push(event);
+    else if (event.type === "result") {
+      terminalSeen = true;
+      if (event.sessionId) sessionId = event.sessionId;
+      if (typeof event.text === "string" && event.text) resultText = event.text;
+    } else if (event.type === "error") {
+      terminalSeen = true;
+      rawErrors.push(event);
+    }
+    if (onEvent) {
+      eventChain = eventChain.then(() => onEvent(event)).catch((error) => {
+        rawErrors.push({
+          type: "error",
+          message: `run event handler failed: ${error.message}`,
+          authError: false,
+          usageLimit: false,
+        });
+      });
+    }
+  };
+
+  const handleRawEvents = (rawEvents) => {
+    for (const rawEvent of rawEvents || []) {
+      let normalized;
+      try { normalized = provider.normalizeEvent(rawEvent, invocation.parserState); }
+      catch (error) {
+        normalized = [{ type: "error", message: `provider event normalization failed: ${error.message}`, authError: false, usageLimit: false }];
+      }
+      const list = Array.isArray(normalized) ? normalized : (normalized ? [normalized] : []);
+      for (const event of list) handleNormalizedEvent(event);
+    }
+  };
+
+  const finishDecoder = () => {
+    if (decoderEnded) return;
+    decoderEnded = true;
+    stdoutEnded = true;
+    try { handleRawEvents(decoder.end()); }
+    catch (error) {
+      handleNormalizedEvent({ type: "error", message: `provider stream finalization failed: ${error.message}`, authError: false, usageLimit: false });
+    }
+  };
+
+  let resolveStdout;
+  const stdoutPromise = new Promise((resolve) => { resolveStdout = resolve; });
+  let resolveClose;
+  const closePromise = new Promise((resolve) => { resolveClose = resolve; });
+
   try {
-    const state = currentState();
-    if (state) {
-      if (state.userId) overlay.OC_CANONICAL_USER_ID = String(state.userId);
-      const key = getActiveSessionKey(state);
-      const sid = state[key];
-      if (sid) {
-        overlay.OC_LAST_SESSION_ID = String(sid);
-        overlay.OC_LAST_SESSION_KEY = key;
+    proc = spawnProcess(invocation.binary, invocation.args, {
+      cwd,
+      env: invocation.env,
+      stdio: [invocation.stdin === null ? "ignore" : "pipe", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+    });
+  } catch (error) {
+    spawnError = error;
+    finishDecoder();
+    resolveStdout();
+    resolveClose({ code: null, signal: null });
+  }
+
+  if (proc) {
+    try { if (onSpawn) onSpawn(proc); }
+    catch (error) { rawErrors.push({ type: "error", message: `spawn observer failed: ${error.message}`, authError: false, usageLimit: false }); }
+
+    proc.stdout.on("data", (data) => {
+      lastActivity = Date.now();
+      try { handleRawEvents(decoder.push(data)); }
+      catch (error) {
+        handleNormalizedEvent({ type: "error", message: `provider stream decoding failed: ${error.message}`, authError: false, usageLimit: false });
+      }
+    });
+    proc.stdout.once("end", () => {
+      finishDecoder();
+      resolveStdout();
+    });
+    proc.stdout.once("close", () => {
+      if (timedOut || spawnError) {
+        finishDecoder();
+        resolveStdout();
+      }
+    });
+    proc.stdout.once("error", (error) => {
+      handleNormalizedEvent({ type: "error", message: `provider stdout failed: ${error.message}`, authError: false, usageLimit: false });
+      finishDecoder();
+      resolveStdout();
+    });
+    proc.stderr.on("data", (data) => {
+      lastActivity = Date.now();
+      const chunk = data.toString("utf8");
+      stderr = (stderr + chunk).slice(-64 * 1024);
+      if (onStderr) onStderr(chunk);
+    });
+    proc.stderr.once("error", (error) => {
+      rawErrors.push({ type: "error", message: `provider stderr failed: ${error.message}`, authError: false, usageLimit: false });
+    });
+    proc.once("error", (error) => {
+      spawnError = error;
+      resolveClose({ code: null, signal: null });
+      if (!stdoutEnded) {
+        try { proc.stdout.destroy(); } catch (_) {}
+        finishDecoder();
+        resolveStdout();
       }
+    });
+    proc.once("close", (code, signal) => {
+      closeInfo = { code, signal };
+      resolveClose(closeInfo);
+      if (terminationStarted) void forceTermination();
+      if ((timedOut || spawnError) && !stdoutEnded) {
+        try { proc.stdout.destroy(); } catch (_) {}
+        finishDecoder();
+        resolveStdout();
+      }
+    });
+
+    if (invocation.stdin !== null && proc.stdin) {
+      // EPIPE here (child died before the pipe flushed) must not become an
+      // uncaughtException; the close handler settles the run via exit code.
+      proc.stdin.once("error", (error) => {
+        stderr = (stderr + `\n[stdin] ${error.message}`).slice(-64 * 1024);
+      });
+      proc.stdin.end(invocation.stdin);
+    }
+
+    const effectiveTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : MAX_PROCESS_TIMEOUT;
+    timeoutTimer = setTimeout(() => beginTermination(false), effectiveTimeout);
+
+    if (Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0) {
+      idleTimer = setInterval(() => {
+        if (watchdogTripped) return;
+        if (Date.now() - lastActivity <= idleTimeoutMs) return;
+        beginTermination(true);
+      }, Math.min(1000, Math.max(10, Math.floor(idleTimeoutMs / 4))));
+    }
+  }
+
+  await Promise.all([stdoutPromise, closePromise]);
+  closeInfo = closeInfo || { code: null, signal: null };
+  if (timeoutTimer) clearTimeout(timeoutTimer);
+  if (idleTimer) clearInterval(idleTimer);
+  if (terminationStarted) await terminationPromise;
+  else if (killTimer) clearTimeout(killTimer);
+  await eventChain;
+
+  try { await cleanup(proc, { timedOut, watchdogTripped, closeInfo }); }
+  catch (error) {
+    cleanupOutcome.ok = false;
+    cleanupOutcome.error = stableRunError(error.message, "RUN_CLEANUP_FAILED");
+  }
+
+  const finalUsage = usageEvents.length ? usageEvents[usageEvents.length - 1] : null;
+  const text = selectTerminalText({
+    resultText,
+    finalText: textFinals.join(""),
+    deltaText: textDeltas.join(""),
+  });
+  let failure = null;
+  if (spawnError) failure = stableRunError(spawnError.message, "PROVIDER_SPAWN_FAILED");
+  else if (timedOut) failure = stableRunError(
+    watchdogTripped ? "Provider run stopped after becoming idle" : "Provider run timed out",
+    watchdogTripped ? "PROVIDER_IDLE_TIMEOUT" : "PROVIDER_TIMEOUT",
+  );
+  else if (closeInfo.signal) failure = stableRunError(`Provider process exited on signal ${closeInfo.signal}`, "PROVIDER_SIGNAL_EXIT", { signal: closeInfo.signal });
+  else if (rawErrors.length) {
+    const event = rawErrors[0];
+    failure = stableRunError(event.message || "Provider reported an error", event.authError ? "PROVIDER_UNAUTHENTICATED" : (event.usageLimit ? "PROVIDER_USAGE_LIMIT" : "PROVIDER_EVENT_ERROR"), event);
+  } else if (closeInfo.code !== 0) failure = stableRunError(`Provider process exited with code ${closeInfo.code}`, "PROVIDER_NONZERO_EXIT", { exitCode: closeInfo.code });
+  else if (!terminalSeen) failure = stableRunError("Provider stream ended without a terminal event", "PROVIDER_MISSING_TERMINAL");
+  else if (!cleanupOutcome.ok) failure = cleanupOutcome.error;
+
+  const result = {
+    ok: !failure,
+    status: failure ? "failed" : "succeeded",
+    runId: runContext?.runId || null,
+    provider: runContext?.provider || provider.id,
+    project: runContext?.project || null,
+    admittedSessionId: runContext?.sessionId || null,
+    sessionId,
+    purpose: runContext?.purpose || "foreground",
+    text: redactSensitive(String(text || "").trim()),
+    usage: finalUsage?.usage || null,
+    usageScope: finalUsage?.scope || null,
+    usageEvents,
+    costUsd: Number.isFinite(invocation.parserState.totalCostUsd) ? invocation.parserState.totalCostUsd : 0,
+    tools,
+    exitCode: closeInfo.code,
+    signal: closeInfo.signal,
+    timedOut,
+    watchdogTripped,
+    terminalSeen,
+    stdoutEnded,
+    stderr: redactSensitive(stderr),
+    error: failure,
+    diagnostic: failure ? failure.message : null,
+    cleanup: cleanupOutcome,
+    persistence,
+    delivery,
+    timings: { startedAt, finishedAt: null, durationMs: null },
+  };
+
+  const runStage = async (name, hook) => {
+    if (!hook) return;
+    persistence[name] = { ok: true, skipped: false };
+    try { await hook(result, runContext); }
+    catch (error) {
+      persistence[name] = { ok: false, skipped: false, error: stableRunError(error.message, `RUN_${name.toUpperCase()}_PERSIST_FAILED`) };
+      if (!result.error) result.error = persistence[name].error;
+      result.ok = false;
+      result.status = "failed";
+      result.diagnostic = result.error.message;
+    }
+  };
+
+  await runStage("transcript", persistTranscript);
+  await runStage("usage", persistUsage);
+  await runStage("session", persistSession);
+
+  if (deliver) {
+    delivery.skipped = false;
+    try {
+      const outcome = await deliver(result, runContext);
+      if (outcome && outcome.ok === false) throw new Error(outcome.error?.message || "required delivery failed");
+      delivery.ok = true;
+      if (outcome !== undefined) delivery.result = outcome;
+    } catch (error) {
+      delivery.ok = false;
+      delivery.error = stableRunError(error.message, "RUN_DELIVERY_FAILED");
+      if (!result.error) result.error = delivery.error;
+      result.ok = false;
+      result.status = "failed";
+      result.diagnostic = result.error.message;
     }
-  } catch (e) { /* no chat context (e.g. startup) — skip */ }
-  return overlay;
+  }
+
+  result.timings.finishedAt = Date.now();
+  result.timings.durationMs = result.timings.finishedAt - startedAt;
+  return result;
+}
+
+function capabilitySupported(provider, name) {
+  return provider.capabilities?.[name]?.support === "native"
+    || provider.capabilities?.[name]?.support === "emulated";
+}
+
+function invocationContextForRun(runContext, bundle, provider) {
+  const providerSettings = { ...(runContext.providerSettings || {}) };
+  if (!capabilitySupported(provider, "budget")) providerSettings.budget = null;
+  if (!capabilitySupported(provider, "worktree")) providerSettings.worktree = false;
+  const context = {
+    ...runContext,
+    ...bundle,
+    providerSettings,
+    sessionId: runContext.sessionId,
+    resumeSessionId: runContext.resumeSessionId,
+    continueSession: runContext.continueSession,
+    fresh: runContext.fresh,
+    maxTurns: capabilitySupported(provider, "maxTurns") ? runContext.maxTurns : null,
+    imagePaths: capabilitySupported(provider, "imageFlag") ? runContext.imagePaths : [],
+    voiceStream: capabilitySupported(provider, "partialStreaming") && runContext.voiceStream,
+    transcriptPaths: bundle.transcriptPaths || null,
+    toolHookSettings: capabilitySupported(provider, "preToolHook") ? runContext.toolHookSettings : null,
+  };
+  return Object.freeze(context);
 }
 
-function subprocessEnv() {
-  return { ...claudeSubprocessEnv(), ...chatEnvOverlay() };
+function preflightFailureResult(runContext, provider, failure) {
+  const error = stableRunError(
+    failure?.message || `${provider.label} is unavailable`,
+    failure?.code || "PROVIDER_PREFLIGHT_FAILED",
+    { providerId: provider.id },
+  );
+  return {
+    ok: false,
+    status: "failed",
+    runId: runContext.runId,
+    provider: runContext.provider,
+    project: runContext.project,
+    admittedSessionId: runContext.sessionId,
+    sessionId: runContext.sessionId,
+    purpose: runContext.purpose,
+    text: "",
+    usage: null,
+    usageScope: null,
+    usageEvents: [],
+    tools: [],
+    exitCode: null,
+    signal: null,
+    timedOut: false,
+    terminalSeen: false,
+    stdoutEnded: false,
+    stderr: "",
+    error,
+    diagnostic: error.message,
+    cleanup: { ok: true, skipped: true },
+    persistence: createPersistenceOutcome(),
+    delivery: { ok: true, skipped: true },
+    timings: { startedAt: Date.now(), finishedAt: Date.now(), durationMs: 0 },
+  };
 }
 
-function parseStreamEvents(data) {
-  const events = [];
-  for (const line of data.split("\n").filter((l) => l.trim())) {
-    try { events.push(JSON.parse(line)); } catch (e) { /* partial */ }
+async function settleImmediateRunResult(result, runContext, dependencies, capture) {
+  for (const [name, hook] of [
+    ["transcript", dependencies.persistTranscript],
+    ["usage", dependencies.persistUsage],
+    ["session", dependencies.persistSession],
+  ]) {
+    if (!hook) continue;
+    result.persistence[name] = { ok: true, skipped: false };
+    try { await hook(result, runContext); }
+    catch (error) {
+      result.persistence[name] = { ok: false, skipped: false, error: stableRunError(error.message, `RUN_${name.toUpperCase()}_PERSIST_FAILED`) };
+      if (!result.error) result.error = result.persistence[name].error;
+      result.ok = false;
+      result.status = "failed";
+    }
+  }
+  if (!capture && dependencies.deliver) {
+    result.delivery.skipped = false;
+    try {
+      const outcome = await dependencies.deliver(result, runContext);
+      if (outcome && outcome.ok === false) throw new Error(outcome.error?.message || "required delivery failed");
+      result.delivery.ok = true;
+      result.delivery.result = outcome;
+    } catch (error) {
+      result.delivery.ok = false;
+      result.delivery.error = stableRunError(error.message, "RUN_DELIVERY_FAILED");
+      if (!result.error) result.error = result.delivery.error;
+      result.ok = false;
+      result.status = "failed";
+    }
   }
-  return events;
+  result.diagnostic = result.error?.message || result.diagnostic;
+  result.timings.finishedAt = Date.now();
+  result.timings.durationMs = result.timings.finishedAt - result.timings.startedAt;
+  return result;
 }
 
-function getActiveBinary() {
-  const { settings } = currentState();
-  if (settings.backend === "cursor") return resolvedCursorPath;
-  if (settings.backend === "codex") return resolvedCodexPath;
-  return CLAUDE_PATH;
+function createRunnerService(dependencies = {}) {
+  const getState = dependencies.getState || currentState;
+  const getStore = dependencies.getStore || (() => chatContext.getStore());
+  const resolveProvider = dependencies.resolveProvider || getProvider;
+  const promptBuilder = dependencies.buildTurnPrompt || buildTurnPrompt;
+  const invocationBuilder = dependencies.buildInvocation
+    || ((provider, context) => provider.buildMainInvocation(context));
+
+  function admit(prompt, cwd, replyToMsgId, opts = {}) {
+    const state = getState();
+    const store = getStore() || null;
+    return opts.runContext || captureRunContext({
+      state,
+      store,
+      prompt,
+      cwd,
+      replyToMsgId,
+      opts,
+      channelId: opts.channelId || store?.channelId || currentChannelId(),
+      canonicalUserId: opts.canonicalUserId || state.userId,
+      runId: opts.runId || null,
+    });
+  }
+
+  async function executeCaptured(prompt, runContext, { capture = false } = {}) {
+    const immediateFailure = (provider, failure) => settleImmediateRunResult(
+      preflightFailureResult(runContext, provider, failure),
+      runContext,
+      dependencies,
+      capture,
+    );
+    let provider;
+    try {
+      provider = resolveProvider(runContext.provider);
+    } catch (error) {
+      return immediateFailure({ id: runContext.provider, label: runContext.provider }, error);
+    }
+    if (!provider) {
+      return immediateFailure({ id: runContext.provider, label: runContext.provider }, {
+        code: "UNKNOWN_PROVIDER",
+        message: `Unknown provider: ${runContext.provider}`,
+      });
+    }
+    try {
+      const authFailure = typeof provider.preflightAuth === "function" ? provider.preflightAuth() : null;
+      if (authFailure) return immediateFailure(provider, authFailure);
+    } catch (error) {
+      return immediateFailure(provider, error);
+    }
+
+    let bundle;
+    let invocation;
+    try {
+      bundle = await promptBuilder(prompt, { runContext, provider });
+      invocation = invocationBuilder(provider, invocationContextForRun(runContext, bundle, provider));
+      if (dependencies.decorateInvocation) {
+        invocation = dependencies.decorateInvocation(invocation, runContext, bundle, provider);
+      }
+      invocation = validateInvocation(invocation);
+      for (const warning of invocation.warnings || []) {
+        if (dependencies.onInvocationWarning) {
+          await dependencies.onInvocationWarning(warning, runContext, provider);
+        } else {
+          console.warn(`[provider-warning] ${warning.code}: ${warning.message}`);
+        }
+      }
+    } catch (error) {
+      return immediateFailure(provider, error);
+    }
+
+    const result = await executeProviderInvocation({
+      runContext,
+      provider,
+      invocation,
+      cwd: runContext.cwd || runContext.project?.dir || process.cwd(),
+      spawnProcess: dependencies.spawnProcess || spawn,
+      timeoutMs: runContext.timeoutMs || dependencies.timeoutMs || MAX_PROCESS_TIMEOUT,
+      killTree: dependencies.killTree || killProcessTree,
+      killGraceMs: dependencies.killGraceMs,
+      cleanup: dependencies.cleanup
+        ? (proc, details) => dependencies.cleanup(proc, details, runContext)
+        : (async () => {}),
+      persistTranscript: dependencies.persistTranscript || null,
+      persistUsage: dependencies.persistUsage || null,
+      persistSession: dependencies.persistSession || null,
+      deliver: capture ? null : (dependencies.deliver || null),
+      onEvent: dependencies.onEvent ? (event) => dependencies.onEvent(event, runContext) : null,
+      onSpawn: dependencies.onSpawn ? (proc) => dependencies.onSpawn(proc, runContext) : null,
+      onStderr: dependencies.onStderr ? (chunk) => dependencies.onStderr(chunk, runContext) : null,
+      idleTimeoutMs: dependencies.idleTimeoutMs || 0,
+    });
+    result.recallMetadata = bundle.recallMetadata || null;
+    result.transcriptPaths = bundle.transcriptPaths || null;
+    return result;
+  }
+
+  // These wrappers are intentionally not async: admission and deep-freezing
+  // happen synchronously before prompt construction can yield.
+  function runAgentCapture(prompt, cwd, opts = {}) {
+    const admitted = admit(prompt, cwd, null, { ...opts, requiredDelivery: false });
+    const runContext = bindRunInputs(admitted, {
+      userPrompt: prompt,
+      imagePaths: opts.imagePaths !== undefined ? opts.imagePaths : admitted.imagePaths,
+      attachments: opts.attachments !== undefined ? opts.attachments : admitted.attachments,
+    });
+    return executeCaptured(prompt, runContext, { capture: true });
+  }
+
+  function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
+    const admitted = admit(prompt, cwd, replyToMsgId, opts);
+    const runContext = bindRunInputs(admitted, {
+      userPrompt: prompt,
+      imagePaths: opts.imagePaths !== undefined ? opts.imagePaths : admitted.imagePaths,
+      attachments: opts.attachments !== undefined ? opts.attachments : admitted.attachments,
+    });
+    return executeCaptured(prompt, runContext, { capture: false });
+  }
+
+  function runAgentSilent(prompt, cwd, label, opts = {}) {
+    return runAgent(prompt, cwd, null, { ...opts, label, purpose: opts.purpose || "silent" });
+  }
+
+  return {
+    admit,
+    executeCaptured,
+    runAgent,
+    runAgentCapture,
+    runAgentSilent,
+  };
 }
 
-function getActiveSessionId() {
-  const state = currentState();
-  if (state.settings.backend === "cursor") return state.cursorSessionId;
-  if (state.settings.backend === "codex") return state.codexSessionId;
-  return state.lastSessionId;
+function createSideChatService(dependencies = {}) {
+  const promptBuilder = createSideChatPromptBuilder(dependencies.buildCoreInstructions);
+  const service = createRunnerService({
+    resolveProvider: dependencies.resolveProvider || resolveForegroundProvider,
+    buildTurnPrompt: dependencies.buildTurnPrompt || promptBuilder,
+    buildInvocation(provider, context) {
+      const isolated = Object.freeze({
+        ...context,
+        fresh: true,
+        sessionId: null,
+        admittedSessionId: null,
+        previousSessionId: null,
+        resumeSessionId: null,
+        continueSession: false,
+        readOnly: true,
+        permissionMode: "plan",
+        toolHookSettings: null,
+        imagePaths: [],
+      });
+      if (typeof provider.buildUtilityInvocation !== "function") {
+        throw stableRunError(`${provider.label || provider.id} does not support isolated side responses`, "UNSUPPORTED_PROVIDER_CAPABILITY");
+      }
+      return provider.buildUtilityInvocation(isolated);
+    },
+    decorateInvocation(invocation, runContext) {
+      return {
+        ...invocation,
+        env: {
+          ...invocation.env,
+          OC_PROVIDER: runContext.provider,
+          OC_RUN_ID: runContext.runId,
+        },
+      };
+    },
+    spawnProcess: dependencies.spawnProcess,
+    timeoutMs: dependencies.timeoutMs,
+    killTree: dependencies.killTree,
+    killGraceMs: dependencies.killGraceMs,
+    onSpawn: dependencies.onSpawn || ((proc, runContext) => sideChatCoordinator.attachProcess(runContext.canonicalUserId, proc)),
+    onStderr: dependencies.onStderr || ((chunk) => console.error("SIDE PROVIDER STDERR:", redactSensitive(chunk))),
+    cleanup: dependencies.cleanup || (async (proc, details, runContext) => {
+      sideChatCoordinator.detachProcess(runContext.canonicalUserId, proc);
+    }),
+  });
+  return {
+    run(request) {
+      if (!request?.runContext || request.runContext.purpose !== "side-chat") {
+        throw new TypeError("an isolated side-chat request is required");
+      }
+      return service.executeCaptured(request.runContext.userPrompt, request.runContext, { capture: true });
+    },
+  };
+}
+
+function resolveForegroundProvider(providerId) {
+  return resolveProviderForRun(providerId);
 }
 
-function getActiveSessionKey(state = currentState()) {
-  if (state.settings.backend === "cursor") return "cursorSessionId";
-  if (state.settings.backend === "codex") return "codexSessionId";
-  return "lastSessionId";
+function getActiveSessionId() {
+  const state = currentState();
+  return getProviderSession(state, getActiveProvider(state), getProjectKey(state));
 }
 
 function resolveRunCwd(cwd) {
@@ -267,10 +870,9 @@ function resolveRunCwd(cwd) {
   const fallback = WORKSPACE && fs.existsSync(WORKSPACE) ? WORKSPACE : process.cwd();
   if (state.currentSession && state.currentSession.dir === requested) {
     console.warn(`[session-guard] repairing missing session dir ${requested} -> ${fallback}`);
+    const project = getProjectKey(state);
     state.currentSession = { ...state.currentSession, dir: fallback };
-    state.lastSessionId = null;
-    state.cursorSessionId = null;
-    state.codexSessionId = null;
+    for (const provider of ["claude", "codex"]) clearProviderSession(state, provider, project);
     resetSessionUsage(state);
     saveState();
   } else {
@@ -288,147 +890,21 @@ function effectiveCompactThreshold(state = currentState()) {
 
 function shouldAutoCompact(state = currentState(), opts = {}) {
   if (opts.skipAutoCompact || opts.fresh || opts.continueSession || state.isCompacting) return false;
-  if (!state[getActiveSessionKey(state)]) return false;
+  if (!getProviderSession(state, getActiveProvider(state), getProjectKey(state))) return false;
   const threshold = effectiveCompactThreshold(state);
   if (threshold === 0) return false;
-  const contextTokens = state.sessionUsage?.liveContextTokens || state.sessionUsage?.lastInputTokens || 0;
+  const activeUsage = state.sessionUsage;
+  const contextTokens = activeUsage?.liveContextTokens || activeUsage?.lastInputTokens || 0;
   if (contextTokens < threshold) return false;
   const minInterval = Number.isFinite(MIN_COMPACT_INTERVAL_MS) ? MIN_COMPACT_INTERVAL_MS : 1800000;
   const farOverThreshold = contextTokens >= threshold * 2;
-  if (!farOverThreshold && state.lastCompactedAt && (Date.now() - state.lastCompactedAt) < minInterval) return false;
+  const checkpointTime = Date.parse(activeUsage?.compactionCheckpoint?.at || "");
+  const scopedLastCompactedAt = Number(activeUsage?.lastCompactedAt)
+    || (Number.isFinite(checkpointTime) ? checkpointTime : 0);
+  if (!farOverThreshold && scopedLastCompactedAt && (Date.now() - scopedLastCompactedAt) < minInterval) return false;
   return true;
 }
 
-async function buildClaudeArgs(prompt, opts = {}) {
-  const state = currentState();
-  const { settings } = state;
-  if (settings.backend === "cursor") return buildCursorArgs(prompt, opts);
-  if (settings.backend === "codex") return buildCodexArgs(prompt, opts);
-  const args = ["-p", "--verbose", "--output-format", "stream-json",
-    "--append-system-prompt", buildSystemPrompt()];
-  // Tool-first deny-gate (5b): PreToolUse hook on Bash via --settings. A
-  // failure to write the settings file just means no gate this turn (fail-open).
-  try { args.push("--settings", require("./tool-guard").ensureHookSettings()); } catch (e) {}
-  const transcriptInfo = transcriptProjectInfo(state);
-  if (transcriptInfo) args.push("--add-dir", transcriptInfo.transcriptsDir);
-  if (opts.resumeSessionId) args.push("--resume", opts.resumeSessionId);
-  else if (opts.continueSession) args.push("--continue");
-  else if (state.lastSessionId && !opts.fresh) {
-    if (userOwnsClaudeSession(state.userId, state.lastSessionId)) {
-      args.push("--resume", state.lastSessionId);
-    } else {
-      console.warn(`[session-guard] dropping stale lastSessionId=${state.lastSessionId.slice(0, 8)} for ${state.userId}; not present in sessions.json — starting fresh`);
-      state.lastSessionId = null;
-    }
-  }
-  args.push("--model", settings.model || DEFAULT_CLAUDE_MODEL);
-  if (opts.maxTurns) args.push("--max-turns", String(opts.maxTurns));
-  if (settings.effort) args.push("--effort", settings.effort);
-  if (settings.budget) args.push("--max-budget-usd", String(settings.budget));
-  if (settings.permissionMode) args.push("--permission-mode", settings.permissionMode);
-  else args.push("--dangerously-skip-permissions");
-  if (settings.worktree) args.push("--worktree");
-  // Voice turns stream partial text so the spoken reply can start mid-generation
-  // (see the streaming-out handler in the runner). Strictly gated to the voice
-  // channel — zero behaviour change for Telegram/Kazee.
-  if (state.lastInputWasVoice) {
-    try {
-      const { currentTransport } = require("./context");
-      if (currentTransport() === "voice") args.push("--include-partial-messages");
-    } catch { /* context not ready — skip streaming flag */ }
-  }
-  // Dynamic state rides in the user prompt so the appended system prompt
-  // stays byte-stable across turns and the prompt-cache prefix survives.
-  args.push(await promptWithDynamicContext(prompt));
-  return args;
-}
-
-function buildCursorArgs(prompt, opts = {}) {
-  const state = currentState();
-  const { settings } = state;
-  const args = ["--print", "--trust", "--output-format", "stream-json"];
-  if (opts.resumeSessionId) args.push("--resume", opts.resumeSessionId);
-  else if (opts.continueSession) args.push("--continue");
-  else if (state.cursorSessionId && !opts.fresh) args.push("--resume", state.cursorSessionId);
-  if (settings.model) args.push("--model", settings.model);
-  if (settings.permissionMode === "plan") args.push("--mode", "plan");
-  else if (settings.permissionMode === "ask") args.push("--mode", "ask");
-  if (settings.worktree) args.push("--worktree");
-  args.push(prompt);
-  return args;
-}
-
-async function buildCodexArgs(prompt, opts = {}) {
-  const state = currentState();
-  const { settings, codexSessionId } = state;
-  const args = [];
-  const resumeId = opts.resumeSessionId || ((!opts.fresh && !opts.continueSession) ? codexSessionId : null);
-  if (opts.continueSession && codexSessionId) args.push("exec", "resume", codexSessionId);
-  else if (resumeId) args.push("exec", "resume", resumeId);
-  else args.push("exec");
-  args.push("--json", "--skip-git-repo-check");
-  if (settings.permissionMode === "plan") args.push("--sandbox", "read-only");
-  else args.push("--dangerously-bypass-approvals-and-sandbox");
-  if (settings.model) args.push("--model", settings.model);
-  args.push(await promptWithDynamicContext(prompt, { includeTranscriptPointer: true }));
-  return args;
-}
-
-function preflightClaudeAuthMessage() {
-  const state = currentState();
-  if (state.settings.backend !== "claude") return null;
-  if (getClaudeOAuthToken().value) return null;
-  try {
-    const { execSync } = require("child_process");
-    const output = execSync(`"${CLAUDE_PATH}" auth status`, {
-      cwd: process.env.HOME || require("os").homedir(),
-      env: subprocessEnv(),
-      encoding: "utf8",
-      timeout: 10000,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    if (isClaudeAuthErrorText(output)) return claudeAuthRecoveryMessage(output.trim().slice(-500));
-    return null;
-  } catch (e) {
-    const output = `${e.stdout || ""}\n${e.stderr || ""}\n${e.message || ""}`;
-    if (isClaudeAuthErrorText(output)) return claudeAuthRecoveryMessage(output.trim().slice(-500));
-    return null;
-  }
-}
-
-function claudeEmptyFailureMessage(code, stderrText = "") {
-  const backend = currentState().settings.backend || "claude";
-  const stderr = redactSensitive(String(stderrText || "").trim());
-  if (backend === "claude") {
-    if (isClaudeUsageLimitText(stderr)) return claudeUsageLimitMessage(stderr.slice(-1200));
-    if (isClaudeAuthErrorText(stderr)) return claudeAuthRecoveryMessage(stderr.slice(-1200));
-    const authStatus = runClaudeAuthStatusDiagnostic();
-    if (isClaudeAuthErrorText(authStatus)) return claudeAuthRecoveryMessage(authStatus.slice(-1200));
-    if (isClaudeUsageLimitText(authStatus)) return claudeUsageLimitMessage(authStatus.slice(-1200));
-    return [
-      `Claude exited with code ${code} but produced no assistant output.`,
-      stderr ? `\nStderr:\n${stderr.slice(-1200)}` : "\nStderr: (empty)",
-      authStatus ? `\nAuth status:\n${redactSensitive(authStatus).slice(-1200)}` : "",
-      "",
-      "Useful next steps:",
-      "• /auth_status — verify Claude auth",
-      "• /model sonnet — switch away from Opus if usage-limited",
-      "• /setup_token — create a launchd-safe OAuth token if Keychain is the issue",
-    ].filter(Boolean).join("\n");
-  }
-  const label = backend === "codex" ? "Codex" : "Cursor";
-  const nextSteps = backend === "codex"
-    ? ["• /codex_auth_status — verify Codex auth", "• /codex_login — device-code login", "• /codex_setup_token — paste an OpenAI API key"]
-    : ["• /backend — confirm Cursor is selected", "• Run `agent login` on the host machine", "• /claude — fall back to Claude if Cursor stays broken"];
-  return [
-    `${label} exited with code ${code} but produced no assistant output.`,
-    stderr ? `\nStderr:\n${stderr.slice(-1200)}` : "\nStderr: (empty)",
-    "",
-    "Useful next steps:",
-    ...nextSteps,
-  ].filter(Boolean).join("\n");
-}
-
 function compactSummaryPrompt() {
   return [
     "Summarize this conversation for a fresh compacted continuation.",
@@ -624,1141 +1100,792 @@ function collectRecentTurns(state = currentState(), maxTurns = 6, maxCharsPerTur
   }
 }
 
-function formatProgress(text, tools, currentTool, elapsed, toolDetail) {
-  const mins = Math.floor(elapsed / 60);
-  const secs = elapsed % 60;
-  const time = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
-  const parts = [];
-  let status = currentTool ? `Working: ${currentTool}` : (tools.length > 0 ? "Processing..." : "Thinking...");
-  if (currentTool && toolDetail) status += ` — ${toolDetail}`;
-  parts.push(`${status} (${time})`);
-  if (tools.length > 1) parts.push(`Steps: ${[...new Set(tools)].join(" > ")}`);
-  if (text) parts.push(text.length > 800 ? "..." + text.slice(-800) : text);
-  return parts.join("\n\n");
+function ensureCompactionAckSchemaPath() {
+  const directory = path.join(CONFIG_DIR, "provider-contracts");
+  const filePath = path.join(directory, "compaction-ack.schema.json");
+  const schema = {
+    type: "object",
+    properties: {
+      acknowledgement: { type: "string", minLength: 1, maxLength: 240 },
+    },
+    required: ["acknowledgement"],
+    additionalProperties: false,
+  };
+  const expected = `${JSON.stringify(schema, null, 2)}\n`;
+  try {
+    if (fs.readFileSync(filePath, "utf8") === expected) return filePath;
+  } catch (_) {}
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  require("./fsutil").atomicWriteFileSync(filePath, expected);
+  try { fs.chmodSync(filePath, 0o600); } catch (_) {}
+  return filePath;
 }
 
-async function runClaudeCapture(prompt, cwd, opts = {}) {
-  const state = currentState();
-  const store = chatContext.getStore();
-  if (state.runningProcess) throw new Error("Another task is already running.");
-  const authPreflight = preflightClaudeAuthMessage();
-  if (authPreflight) throw new Error(authPreflight);
-  cwd = resolveRunCwd(cwd);
-
-  const args = await buildClaudeArgs(prompt, { ...opts, skipAutoCompact: true });
-  return new Promise((resolve, reject) => {
-    let assistantText = "";
-    let stderrBuffer = "";
-    let streamBuffer = "";
-    let sessionId = null;
-    appendProjectTranscript(opts.transcriptRole || "system-note", stripTranscriptPointerForStorage(prompt), {
-      capture: true,
-      label: opts.label || null,
-      fresh: !!opts.fresh,
-      continueSession: !!opts.continueSession,
-      resumeSessionId: opts.resumeSessionId || null,
-    }, state, getActiveSessionId);
-    const proc = spawn(getActiveBinary(), args, {
-      cwd,
-      env: subprocessEnv(),
-      stdio: ["ignore", "pipe", "pipe"],
-      detached: process.platform !== "win32",
+function deriveCompactionRunContext(base, overrides = {}) {
+  const providerSettings = {
+    ...(base.providerSettings || {}),
+    budget: null,
+    worktree: false,
+    permissionMode: "plan",
+  };
+  return deepFreeze({
+    ...base,
+    runId: overrides.runId || (typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${base.runId}-${Date.now()}`),
+    admittedAt: Date.now(),
+    userPrompt: String(overrides.userPrompt || ""),
+    purpose: overrides.purpose,
+    label: overrides.label,
+    providerSettings,
+    sessionId: overrides.sessionId ?? null,
+    admittedSessionId: overrides.sessionId ?? null,
+    previousSessionId: overrides.previousSessionId ?? base.sessionId ?? null,
+    resumeSessionId: overrides.resumeSessionId ?? null,
+    continueSession: false,
+    fresh: !!overrides.fresh,
+    skipAutoCompact: true,
+    requiredDelivery: false,
+    readOnly: true,
+    permissionMode: "plan",
+    maxTurns: base.provider === "claude" ? 1 : null,
+    outputSchemaPath: overrides.outputSchemaPath || null,
+    imagePaths: [],
+    attachments: [],
+    voiceStream: false,
+    lastInputWasVoice: false,
+  });
+}
+
+function successfulTerminalCapture(result, { requireSession = false } = {}) {
+  return !!result?.ok && result.status === "succeeded" && result.terminalSeen === true
+    && (!requireSession || (typeof result.sessionId === "string" && !!result.sessionId));
+}
+
+function createCompactionService(dependencies = {}) {
+  const getState = dependencies.getState || currentState;
+  const captureContext = dependencies.captureRunContext || admitRunContext;
+  const runCapture = dependencies.runCapture || runAgentCapture;
+  const commitCompaction = dependencies.commitCompaction || commitProviderCompaction;
+  const archiveBrief = dependencies.archiveBrief || archiveCompactionBrief;
+  const appendDaySeed = dependencies.appendDaySeed || ((entry) => require("./day-seeds").appendDaySeed(entry));
+  const collectRepoFacts = dependencies.collectRepoFacts || collectRepoStateFacts;
+  const collectRecent = dependencies.collectRecentTurns || collectRecentTurns;
+  const ackSchemaPath = dependencies.ackSchemaPath || ensureCompactionAckSchemaPath;
+  const drainQueue = dependencies.drainQueue || drainQueuedMessages;
+
+  async function compact(cwd, opts = {}) {
+    const state = getState();
+    if (state.isCompacting) return { compacted: false, reason: "Compaction already in progress." };
+    if (state.runningProcess || (state.preparingRun && !opts.admissionHeld)) {
+      return { compacted: false, reason: "Finish or stop the active run before compacting." };
+    }
+    const provider = getActiveProvider(state);
+    const project = getProjectKey(state);
+    const oldSessionId = getProviderSession(state, provider, project);
+    if (!project || !oldSessionId) return { compacted: false, reason: "No conversation." };
+    const summaryPrompt = compactSummaryPrompt();
+    const admitted = captureContext(summaryPrompt, cwd, null, {
+      provider,
+      resumeSessionId: oldSessionId,
+      skipAutoCompact: true,
+      label: "compact-summary",
+      purpose: "compact-summary",
+      requiredDelivery: false,
+      timeoutMs: COMPACT_SUMMARY_TIMEOUT,
+    });
+    const summaryContext = deriveCompactionRunContext(admitted, {
+      userPrompt: summaryPrompt,
+      purpose: "compact-summary",
+      label: "compact-summary",
+      sessionId: oldSessionId,
+      resumeSessionId: oldSessionId,
+      previousSessionId: oldSessionId,
+      fresh: false,
     });
-    state.runningProcess = proc;
-    const timeout = setTimeout(() => {
-      if (state.runningProcess === proc) {
-        killProcessTree(proc.pid, "SIGTERM");
-        setTimeout(() => killProcessTree(proc.pid, "SIGKILL"), 5000);
+    const operationId = opts.operationId || (typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `compact-${Date.now()}`);
+    const recentTurns = collectRecent(state);
+    state.isCompacting = true;
+    try {
+      if (opts.notify) await send(opts.message || "Context is getting large, compacting first so this stays fast…");
+      const summaryRun = await runCapture(summaryPrompt, summaryContext.cwd || cwd, {
+        runContext: summaryContext,
+        persist: false,
+      });
+      if (!successfulTerminalCapture(summaryRun)) {
+        return { compacted: false, reason: summaryRun?.diagnostic || "Compaction summary did not finish successfully." };
       }
-    }, opts.timeoutMs || MAX_PROCESS_TIMEOUT);
-
-    proc.stdout.on("data", (data) => {
-      streamBuffer += data.toString();
-      const events = parseStreamEvents(streamBuffer);
-      const lastNewline = streamBuffer.lastIndexOf("\n");
-      streamBuffer = lastNewline >= 0 ? streamBuffer.slice(lastNewline + 1) : streamBuffer;
-      for (const evt of events) {
-        if (evt.type === "assistant" && evt.message?.content) {
-          for (const block of evt.message.content) {
-            if (block.type === "text") assistantText += block.text;
-          }
-        }
-        if (evt.type === "item.completed" && evt.item?.type === "agent_message" && typeof evt.item.text === "string") {
-          assistantText += (assistantText ? "\n" : "") + evt.item.text;
-        }
-        if (evt.type === "thread.started" && evt.thread_id) {
-          state.codexSessionId = evt.thread_id;
-          sessionId = evt.thread_id;
-          saveState();
-        }
-        if (evt.type === "result" && evt.session_id) {
-          if (state.settings.backend === "cursor") state.cursorSessionId = evt.session_id;
-          else state.lastSessionId = evt.session_id;
-          sessionId = evt.session_id;
-          if (evt.usage) {
-            applyUsageToState(state, evt.usage, 0, { usageScope: "turn_delta" });
-          }
-          if (typeof evt.total_cost_usd === "number") state.sessionUsage.costUsd += evt.total_cost_usd;
-          saveState();
-        }
-        // evt.result only carries the FINAL text segment of the turn. Using it
-        // as anything but a fallback would clobber text streamed before tool
-        // calls (the "long reply, then tools, then short closing line" shape).
-        if (evt.type === "result" && evt.result && !assistantText.trim()) assistantText = evt.result;
+      const summary = summaryRun.text || "No prior context was returned by the summarizer.";
+      const { fullBrief, condensed } = splitCompactionBrief(summary);
+      const seedSummary = condensed ? `${fullBrief}\n\n${condensed}` : fullBrief;
+      const repoFacts = collectRepoFacts(summaryContext.cwd || cwd);
+      let seedPrompt = compactSeedPrompt(seedSummary, {
+        briefPath: null,
+        condensed: false,
+        repoFacts,
+        recentTurns,
+      });
+      let outputSchemaPath = null;
+      if (provider === "codex") {
+        outputSchemaPath = ackSchemaPath();
+        seedPrompt += "\n\nReturn JSON matching the supplied output schema. Put the one short acknowledgement in the acknowledgement field.";
       }
-    });
-    proc.stderr.on("data", (d) => { stderrBuffer += d.toString(); });
-    proc.on("close", (code) => chatContext.run(store, () => {
-      if (state.runningProcess === proc) state.runningProcess = null;
-      clearTimeout(timeout);
-      if (code !== 0 && code !== null) {
-        const failureText = claudeEmptyFailureMessage(code, stderrBuffer);
-        appendProjectTranscript("system-note", failureText, { capture: true, label: opts.label || null, exitCode: code, kind: "backend-error" }, state, getActiveSessionId);
-        reject(new Error(failureText));
-        return;
+      const seedContext = deriveCompactionRunContext(summaryContext, {
+        userPrompt: seedPrompt,
+        purpose: "compact-seed",
+        label: "compact-seed",
+        sessionId: null,
+        resumeSessionId: null,
+        previousSessionId: oldSessionId,
+        fresh: true,
+        outputSchemaPath,
+      });
+      const seedRun = await runCapture(seedPrompt, seedContext.cwd || cwd, {
+        runContext: seedContext,
+        persist: false,
+      });
+      if (!successfulTerminalCapture(seedRun, { requireSession: true })) {
+        return { compacted: false, reason: seedRun?.diagnostic || "Compaction seed did not finish successfully." };
       }
-      const cleanText = redactSensitive(assistantText.trim());
-      appendProjectTranscript("assistant", cleanText, { capture: true, label: opts.label || null, exitCode: code }, state, getActiveSessionId);
-      resolve({ text: cleanText, sessionId });
-    }));
-    proc.on("error", (err) => chatContext.run(store, () => {
-      if (state.runningProcess === proc) state.runningProcess = null;
-      clearTimeout(timeout);
-      reject(err);
-    }));
-  });
+      if (seedRun.sessionId === oldSessionId) {
+        return { compacted: false, reason: "Compaction seed did not create a fresh provider session." };
+      }
+      let commit;
+      try {
+        commit = await commitCompaction(state, {
+          operationId,
+          canonicalUserId: summaryContext.canonicalUserId,
+          project: summaryContext.project.name,
+          provider: summaryContext.provider,
+          previousSessionId: oldSessionId,
+          newSessionId: seedRun.sessionId,
+          title: `Compacted ${new Date().toLocaleDateString()}`,
+          seedUsage: seedRun.usage || null,
+        });
+      } catch (error) {
+        return { compacted: false, reason: `Compaction commit failed: ${redactSensitive(error.message)}` };
+      }
+      let briefPath = null;
+      try { briefPath = archiveBrief(fullBrief, capturedStateView(state, summaryContext)); } catch (_) {}
+      try {
+        appendDaySeed({
+          summary: condensed || fullBrief,
+          project: `${summaryContext.project.name} (${summaryContext.project.dir})`,
+          channel: summaryContext.channelId,
+          briefPath,
+        });
+      } catch (_) {}
+      return {
+        compacted: true,
+        operationId,
+        oldSessionId,
+        newSessionId: seedRun.sessionId,
+        provider: summaryContext.provider,
+        project: summaryContext.project.name,
+        summary,
+        commit,
+      };
+    } finally {
+      state.isCompacting = false;
+      try { await drainQueue(state); }
+      catch (error) { console.warn(`[compact] queue drain failed: ${redactSensitive(error.message)}`); }
+    }
+  }
+
+  return { compact };
 }
 
 async function compactActiveSession(cwd, opts = {}) {
-  const state = currentState();
-  const sessionKey = getActiveSessionKey(state);
-  const oldSessionId = state[sessionKey];
-  if (!oldSessionId) return { compacted: false, reason: "No conversation." };
-  if (state.isCompacting) return { compacted: false, reason: "Compaction already in progress." };
-
-  state.isCompacting = true;
-  let summary;
-  const recentTurns = collectRecentTurns(state);
-  try {
-    if (opts.notify) await send(opts.message || "Context is getting large, compacting first so this stays fast…");
-    const summaryRun = await runClaudeCapture(compactSummaryPrompt(), cwd, { resumeSessionId: oldSessionId, skipAutoCompact: true, label: "compact-summary", timeoutMs: COMPACT_SUMMARY_TIMEOUT });
-    summary = summaryRun.text || "No prior context was returned by the summarizer.";
-  } finally {
-    state.isCompacting = false;
-    saveState();
-  }
+  return createCompactionService().compact(cwd, opts);
+}
 
-  const { fullBrief, condensed } = splitCompactionBrief(summary);
-  const briefPath = archiveCompactionBrief(fullBrief, state);
-  // Append the condensed digest to today's per-day seed file so the nightly
-  // dream can review what was worked on across the day. Best-effort.
-  try {
-    require("./day-seeds").appendDaySeed({
-      summary: condensed || fullBrief,
-      project: state.currentSession ? `${state.currentSession.name} (${state.currentSession.dir})` : null,
-      channel: currentChannelId(),
-      briefPath,
-    });
-  } catch (e) {}
-  // Only seed with the condensed version when the full text actually made it to disk.
-  const seedSummary = (condensed && briefPath) ? condensed : (condensed ? `${fullBrief}\n\n${condensed}` : fullBrief);
-  const repoFacts = collectRepoStateFacts(cwd);
-  // The old session id stays in place until the seed succeeds: if the seed
-  // dies (timeout, /stop, crash) the conversation keeps resuming the
-  // pre-compaction session instead of being orphaned. maxTurns: 1 hard-stops
-  // a seed that ignores the no-work instruction and reaches for tools.
-  const seedRun = await runClaudeCapture(compactSeedPrompt(seedSummary, { briefPath, condensed: !!(condensed && briefPath), repoFacts, recentTurns }), cwd, { fresh: true, skipAutoCompact: true, label: "compact-seed", timeoutMs: COMPACT_SUMMARY_TIMEOUT, maxTurns: 1 });
-  const newSessionId = seedRun.sessionId || null;
-  state[sessionKey] = newSessionId;
-  state.isFirstMessage = false;
-  state.lastCompactedAt = Date.now();
-  state.sessionUsage = { turns: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, costUsd: 0, lastInputTokens: 0, liveContextTokens: 0, lastUsageScope: "turn_delta" };
-  state.codexUsageSnapshots = {};
-  saveState();
-
-  if (newSessionId && state.currentSession) {
-    const title = `Compacted ${new Date().toLocaleDateString()}`;
-    recordSession(state.userId, state.currentSession.name, newSessionId, title);
-  }
-  return { compacted: true, oldSessionId, newSessionId, summary };
+function capturedStateView(state, runContext) {
+  return {
+    ...state,
+    userId: runContext.canonicalUserId || state.userId,
+    currentSession: runContext.project
+      ? { name: runContext.project.name, dir: runContext.project.dir }
+      : null,
+    settings: {
+      ...(runContext.providerSettings || {}),
+      backend: runContext.provider,
+    },
+  };
 }
 
-async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
-  const state = currentState();
-  const store = chatContext.getStore();
-  const channelId = currentChannelId();
-  const adapter = currentAdapter();
-  const { settings } = state;
-  // A streaming status/preview message id is only editable on the channel it
-  // was minted on. Under unified identity the owner's Telegram + Kazee turns
-  // share one per-canonical state object, so a message id minted on one channel
-  // must never be used as an edit target under the other adapter (Telegram int
-  // vs Kazee ObjectId → PUT /message/<id> 500s). Also rejects the non-string
-  // "sent, no id" sentinel a socket adapter returns, so we edit only real ids.
-  const canEditStatus = () => typeof state.statusMessageId === "string" && state.statusMessageChannel === channelId;
-  // Owner-vs-external, resolved once per turn. All internal-activity chatter
-  // (recall banners, tool/skill traces, usage alerts) is owner-only so nothing
-  // about how the assistant works leaks to an external speaker.
-  let externalSpeaker = false;
-  try { externalSpeaker = require("./relationship").isCurrentSpeakerGuarded(); } catch (e) {}
-  cwd = resolveRunCwd(cwd);
+function capturedTranscriptMetadata(runContext, extra = {}) {
+  return {
+    provider: runContext.provider,
+    project: runContext.project?.name || null,
+    projectPath: runContext.project?.dir || null,
+    runId: runContext.runId,
+    purpose: runContext.purpose,
+    ...(runContext.occurrenceId ? { occurrenceId: runContext.occurrenceId } : {}),
+    ...(runContext.scheduledJobId ? { scheduledJobId: runContext.scheduledJobId } : {}),
+    ...(runContext.originRunId ? { originRunId: runContext.originRunId } : {}),
+    ...extra,
+  };
+}
 
-  if (!acquireRunLock(state)) {
-    // Capture the origin channel so the drained reply routes back to where the
-    // message came from. Under unified identity the owner's channels share one
-    // run-lock and queue, so a Kazee message queued during a Telegram run must
-    // still be answered on Kazee — not wherever the finishing turn happens to be.
-    state.messageQueue.push({ prompt, replyToMsgId, opts, queuedAt: Date.now(), origin: store ? { ...store } : null });
-    await send(state.isCompacting ? "Compacting context, will pick this up next…" : "Queued.", { replyTo: replyToMsgId });
-    return;
+function providerRunDiagnostic(result, runContext) {
+  if (result.ok) return null;
+  let provider;
+  try { provider = getProvider(runContext.provider); }
+  catch (_) { provider = { label: runContext.provider, authHelp: () => "" }; }
+  const label = provider.label || runContext.provider;
+  const code = result.error?.code || "PROVIDER_RUN_FAILED";
+  if (code === "PROVIDER_UNAUTHENTICATED") {
+    const help = typeof provider.authHelp === "function" ? provider.authHelp() : "";
+    return `${label} authentication failed.${help ? `\n\n${help}` : ""}`;
   }
-
-  const authPreflight = preflightClaudeAuthMessage();
-  if (authPreflight) {
-    // Lock was armed synchronously above; release it before bailing so the
-    // next turn isn't wedged behind a run that never spawned.
-    state.preparingRun = false;
-    await send(authPreflight, { replyTo: replyToMsgId });
-    return;
+  if (code === "PROVIDER_USAGE_LIMIT") {
+    return `${label} reported a usage or rate limit. Check that provider's account status or select another configured provider.`;
   }
+  const detail = result.stderr ? `\n\nStderr:\n${result.stderr.slice(-1200)}` : "";
+  return `${label} run failed: ${result.error?.message || "unknown provider failure"}${detail}`;
+}
 
-  if (state.currentSession && shouldAutoCompact(state, opts)) {
-    try {
-      await compactActiveSession(state.currentSession.dir, { notify: true, message: "Context is getting large, compacting before I handle this…" });
-    } catch (e) {
-      console.warn(`[preflight-compact] failed: ${redactSensitive(e.message)}`);
-    }
-  }
+async function persistForegroundTranscript(result, runContext, state = currentState()) {
+  const view = capturedStateView(state, runContext);
+  const session = () => result.sessionId || runContext.sessionId || null;
+  appendProjectTranscript(
+    runContext.transcriptRole || "user",
+    stripTranscriptPointerForStorage(runContext.userPrompt),
+    capturedTranscriptMetadata(runContext, {
+      sourceMessageId: runContext.replyToMsgId,
+      fresh: runContext.fresh,
+      continueSession: runContext.continueSession,
+      resumeSessionId: runContext.resumeSessionId,
+      label: runContext.label,
+    }),
+    view,
+    session,
+    { strict: true },
+  );
+  const role = result.ok ? "assistant" : "system-note";
+  const text = result.ok
+    ? (result.text || "(no output)")
+    : (providerRunDiagnostic(result, runContext) || result.diagnostic || "Provider run failed");
+  appendProjectTranscript(
+    role,
+    text,
+    capturedTranscriptMetadata(runContext, {
+      exitCode: result.exitCode,
+      signal: result.signal,
+      kind: result.ok ? undefined : "provider-error",
+      label: runContext.label,
+    }),
+    view,
+    session,
+    { strict: true },
+  );
+}
 
-  appendProjectTranscript("user", prompt, {
-    sourceMessageId: replyToMsgId || null,
-    fresh: !!opts.fresh,
-    continueSession: !!opts.continueSession,
-    resumeSessionId: opts.resumeSessionId || null,
-  }, state, getActiveSessionId);
-
-  // Typing heartbeat: keep the indicator alive continuously from message
-  // receipt through the recall/discoverer phase and into streaming, not just
-  // for the ~5s a single typing action lasts. Stored on state so /stop can
-  // clear it instantly. Cleared on close/error/cancel.
-  // While true, the bot is reasoning before its first output token, so the
-  // typing heartbeat advertises the richer "thinking" state. Flipped to false
-  // the moment the first assistant text / tool_use / text_delta arrives.
-  state.thinkingPhase = true;
-  const startTyping = () => {
-    if (!adapter || !channelId) return;
-    adapter.typing(channelId, state.thinkingPhase ? "thinking" : undefined).catch(() => {});
-    if (!state.typingHeartbeat) state.typingHeartbeat = setInterval(() => adapter.typing(channelId, state.thinkingPhase ? "thinking" : undefined).catch(() => {}), 4000);
-  };
-  // Called on the first real output token to leave the thinking phase and, if
-  // the turn is still live, immediately advertise plain "typing" so the client
-  // flips without waiting for the next 4s heartbeat.
-  const endThinking = () => {
-    if (!state.thinkingPhase) return;
-    state.thinkingPhase = false;
-    if (adapter && channelId && state.typingHeartbeat) adapter.typing(channelId).catch(() => {});
-  };
-  const stopTyping = () => {
-    state.thinkingPhase = false;
-    if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
-    // Telegram's chat action auto-expires, but socket-based channels (Kazee)
-    // keep showing "typing…" until told to stop. Optional on the adapter.
-    if (adapter && channelId) { try { adapter.typingStop?.(channelId); } catch (e) {} }
-  };
-  // Pre-spawn window (recall/compaction/auth): /stop has no process to kill, so
-  // it sets state.cancelRequested and we bail at the checkpoint before spawning.
-  // preparingRun was armed synchronously by acquireRunLock() at the top of this
-  // function so the lock already spans the auth/compact awaits above — no re-arm.
-  state.cancelRequested = false;
-  startTyping();
-  state.statusMessageId = null;
-  state.statusMessageChannel = null;
-  state.streamBuffer = "";
-  let assistantText = "";
-
-  // Phase 3 relationship guardrail: is this turn's speaker an EXTERNAL (a
-  // non-owner)? Computed once per turn. For the owner (and any no-context run)
-  // this is false, so every guardrail branch below — the streaming-preview
-  // suppression, the disabled unvetted voice-out, and the final-reply vet — is a
-  // strict no-op and the owner path stays byte-for-byte unchanged (R9/R14).
-  let guardedTurn = false;
-  try { guardedTurn = require("./relationship").isCurrentSpeakerGuarded(); } catch (e) { guardedTurn = false; }
-
-  // Voice streaming-out: on voice turns we speak each finished sentence as it is
-  // generated (off the partial text_delta events) so the first audio plays while
-  // the rest of the reply is still being written — far lower time-to-first-sound
-  // than synthesizing one pass over the whole reply at the end. Reads the delta
-  // stream only; the text/transcript channel still reads whole-message events, so
-  // chat transports are completely unaffected. Disabled for guarded turns: a
-  // streamed clip would speak unvetted text aloud before the guard sees it.
-  let voiceStreaming = false;
+async function persistForegroundUsage(result, runContext, state = currentState(), store = chatContext.getStore()) {
+  if (!result.usage) return;
+  const previousUsageBySession = structuredClone(state.usageBySession || {});
+  const previousAlertAt = state.usageAlertLastAt || 0;
   try {
-    const { currentTransport } = require("./context");
-    voiceStreaming = !guardedTurn && !!state.lastInputWasVoice && currentTransport() === "voice";
-  } catch { voiceStreaming = false; }
-  let spokenBuf = "";                 // text_delta accumulator awaiting a sentence boundary
-  let ttsChain = Promise.resolve();   // ordered send queue so clips play in order
-  let spokeAnyStreamed = false;
-  const SPOKEN_MIN_CHARS = 40;        // don't fire TTS on tiny fragments ("Hi.")
-  // Voice latency probe (measurement only) — timestamps filled in as the turn runs.
-  // Spawn time is `startTime` (captured just after spawn below).
-  let vlFirstSysAt = null, vlFirstTokenAt = null, vlFirstAudioAt = null, vlResultAt = null;
-  function dispatchSpoken(text) {
-    const clean = redactSensitive(text);
-    if (!clean.trim()) return;
-    spokeAnyStreamed = true;
-    const synthP = synthSentenceMp3(clean); // start synth now (parallel)
-    ttsChain = ttsChain.then(async () => {  // but send strictly in order
-      try {
-        const clip = await synthP;
-        if (clip) { await sendVoice(clip); if (vlFirstAudioAt == null) vlFirstAudioAt = Date.now(); }
-      } catch (e) { console.error("voice stream clip failed:", e.message); }
+    let usage = result.usage;
+    let usageScope = result.usageScope || "turn_delta";
+    let rawUsage = usage;
+    let liveContextTokens = usageParts(usage, runContext.provider).context;
+    const usageSessionId = result.sessionId || runContext.sessionId;
+    const usageProject = runContext.project?.name || null;
+    if (runContext.provider === "codex") {
+      const normalized = normalizeCodexUsage(state, usageSessionId, usage, { project: usageProject });
+      usage = normalized.usage;
+      usageScope = normalized.usageScope;
+      rawUsage = normalized.rawUsage;
+      liveContextTokens = usageParts(rawUsage, "codex").context;
+    }
+    result.usage = usage;
+    result.usageScope = usageScope;
+    applyUsageToState(state, usage, result.costUsd || 0, {
+      backend: runContext.provider,
+      usageScope,
+      liveContextTokens,
+      project: usageProject,
+      sessionId: usageSessionId,
     });
+    logTurnUsage(
+      state,
+      usage,
+      result.costUsd || 0,
+      (text) => chatContext.run(store, () => send(text)),
+      {
+        backend: runContext.provider,
+        model: runContext.providerSettings?.model || null,
+        userId: runContext.canonicalUserId,
+        sessionId: usageSessionId,
+        runId: runContext.runId,
+        project: usageProject,
+        usageScope,
+        liveContextTokens,
+        rawUsage,
+        strict: true,
+      },
+    );
+    saveState({ strict: true });
+  } catch (error) {
+    state.usageBySession = previousUsageBySession;
+    state.usageAlertLastAt = previousAlertAt;
+    throw error;
   }
-  function pumpSpoken(flush) {
-    // Cut the smallest prefix that ends in a sentence terminator and is at least
-    // SPOKEN_MIN_CHARS long, dispatch it, repeat. On flush, send whatever remains.
-    while (true) {
-      const re = /[.!?]+(?=\s|$)/g;
-      let idx = -1, m;
-      while ((m = re.exec(spokenBuf)) !== null) {
-        const end = m.index + m[0].length;
-        if (end >= SPOKEN_MIN_CHARS) { idx = end; break; }
-      }
-      if (idx === -1) break;
-      const sentence = spokenBuf.slice(0, idx).trim();
-      spokenBuf = spokenBuf.slice(idx).replace(/^\s+/, "");
-      if (sentence) dispatchSpoken(sentence);
-    }
-    if (flush) { const tail = spokenBuf.trim(); spokenBuf = ""; if (tail) dispatchSpoken(tail); }
+}
+
+async function persistForegroundSession(result, runContext, state = currentState()) {
+  if (!result.ok || !result.sessionId) return;
+  const liveProvider = state.settings?.backend || null;
+  const project = runContext.project?.name || null;
+  const pointerUnchanged = getProviderSession(state, runContext.provider, project) === (runContext.previousSessionId || null);
+  const attach = runContext.attachSession !== false && !!project && pointerUnchanged;
+  if (attach) {
+    setProviderSession(state, runContext.provider, project, result.sessionId);
+    if (liveProvider === runContext.provider && sameCapturedProject(state, runContext)) state.isFirstMessage = false;
+    saveState({ strict: true });
+  }
+  if (runContext.project?.name) {
+    const title = runContext.fresh
+      ? (runContext.userPrompt.length > 60 ? `${runContext.userPrompt.slice(0, 57)}...` : runContext.userPrompt)
+      : null;
+    recordSession(
+      runContext.canonicalUserId,
+      runContext.project.name,
+      runContext.provider,
+      result.sessionId,
+      title,
+      { strict: true },
+    );
   }
+  // A wakeup can be created inside a fresh provider turn before that turn's
+  // native session ID exists. The loopback stores the immutable origin run ID;
+  // once the terminal result reveals the session, bind every matching job to
+  // it before reporting session persistence complete.
+  require("./jobs").bindOriginRunSession(
+    runContext.runId,
+    runContext.provider,
+    runContext.project?.name,
+    result.sessionId,
+  );
+  result.sessionAttached = attach;
+}
 
-  let toolUses = [];
-  let currentTool = null;
-  let currentToolDetail = "";
-  // True context-window occupancy is the largest single API call's prefix
-  // (input + cache_read + cache_creation), NOT the per-turn sum the result
-  // event reports — that sum re-counts the cached prefix once per tool
-  // round-trip and balloons to millions. Track the peak per-call prefix.
-  let peakContextTokens = 0;
-
-  // Hermes-style skill announcements: one chat line when a learned skill
-  // is invoked or its SKILL.md is written/patched. Deduped per turn.
-  const skillNotified = new Set();
-  const notifySkill = (key, text) => {
-    if (externalSpeaker) return; // never leak internal activity to a non-owner
-    if (skillNotified.has(key)) return;
-    skillNotified.add(key);
-    chatContext.run(store, () => send(text).catch(() => {}));
-  };
-  // Tool-activity visibility (surfaced / ran / created-updated). Off by default,
-  // toggled per-channel with /tooltrace — mirrors /recall's showRecall. Dedup +
-  // delivery reuse notifySkill so a tool touched twice a turn announces once.
-  const notifyToolTrace = (key, text) => {
-    if (!settings.showToolTrace) return;
-    notifySkill(key, text);
-  };
-  const noteSkillToolUse = (toolName, input) => {
-    try {
-      if (toolName === "Skill" && input?.skill) {
-        notifySkill(`use:${input.skill}`, `Using skill: ${input.skill}`);
-        return;
-      }
-      const filePath = input?.file_path || input?.filePath;
-      if ((toolName === "Write" || toolName === "Edit") && filePath) {
-        const packDir = packsLib.packNameFromPath(filePath);
-        if (packDir) {
-          if (packsLib.readPack(packDir)) notifySkill(`pack:${packDir}`, `✏️ Updating my notes on ${packDir}…`);
-          else notifySkill(`pack:${packDir}`, `📦 Starting a new pack: ${packDir} — open-claudia pack show ${packDir} to peek.`);
-          try {
-            packsLib.recordForegroundWrite(packDir, {
-              tool: toolName,
-              oldString: input?.old_string ?? input?.oldString,
-              content: input?.content,
-            });
-          } catch (e) {}
-          return;
-        }
-        const entSlug = entitiesLib.entityNameFromPath(filePath);
-        if (entSlug) {
-          if (entitiesLib.readEntity(entSlug)) notifySkill(`entity:${entSlug}`, `👤 Updating what I know about ${entSlug}…`);
-          else notifySkill(`entity:${entSlug}`, `👤 New entity noted: ${entSlug} — open-claudia entity show ${entSlug} to peek.`);
-          return;
-        }
-        const toolName2 = toolsLib.toolNameFromPath(filePath);
-        if (toolName2) {
-          if (toolsLib.findTool(toolName2)) notifyToolTrace(`tool:${toolName2}`, `🔧 Updating tool: ${toolName2} — open-claudia tool show ${toolName2} to inspect.`);
-          else notifyToolTrace(`tool:${toolName2}`, `🔧 New tool: ${toolName2} — open-claudia tool run ${toolName2} to use it.`);
-          return;
-        }
-        const dir = skillsLib.skillNameFromPath(filePath);
-        if (!dir) return;
-        // The tool_use event precedes the actual write, so existence now
-        // distinguishes a brand-new skill from a patch.
-        if (skillsLib.skillExists(dir)) notifySkill(`write:${dir}`, `Updating skill: ${dir}`);
-        else notifySkill(`write:${dir}`, `Learning new skill: ${dir} — /skills show ${dir} to inspect, /skills remove ${dir} to drop it.`);
-      }
-    } catch (e) { /* announcements are best-effort */ }
-  };
+async function deliverForegroundResult(result, runContext, state = currentState()) {
+  if (runContext.lastInputWasVoice) state.lastInputWasVoice = false;
+  const diagnostic = providerRunDiagnostic(result, runContext);
+  if (diagnostic) result.diagnostic = diagnostic;
+  let finalText = result.ok ? (result.text || "(no output)") : (diagnostic || result.diagnostic || "Provider run failed");
 
-  // Read-side recall: fire "📖 Recalled my notes on …" only when the agent
-  // actually pulls a full pack/entity via the CLI (it decided it was worth
-  // reading), not when a headline was auto-injected. Deduped per turn through
-  // notifySkill's Set so repeated `pack show` calls don't spam the chat.
-  // Nodes the agent actually OPENED this turn (📖). This is the co-use signal
-  // the recall graph reinforces on — actually-read, not merely surfaced.
-  const openedThisTurn = new Set();
-  // Reusable tools the agent RAN this turn, in order, as { name, shape }. Feeds
-  // two graphs (core/tool-graph.js): names → directed follows-edges ("you ran X
-  // — you usually run Y next"); shapes → pack↔tool edges ("in this topic, tool X
-  // is used as `…`"). Order matters here (unlike openedThisTurn, a Set), because
-  // a tool chain is a pipeline.
-  const toolRunsThisTurn = [];
-  const noteRecallFromShell = (command) => {
-    try {
-      const cmd = String(command || "");
-      // 5c raw-op audit: every Bash command in the stream passes here, so
-      // operational work done raw — heredoc scripts, DB clients, mutating
-      // kubectl — gets stamped to the guard log for the dream's KPI pass.
-      // Observation only; blocking is the deny-gate hook's job, not this.
-      try { require("./tool-guard").noteRawOp(cmd); } catch (e) { /* best-effort */ }
-      if (!cmd.includes("open-claudia")) return;
-      let m;
-      const packRe = /\bpack\s+show\s+["']?([a-z0-9][\w.-]*)/gi;
-      while ((m = packRe.exec(cmd))) {
-        const dir = m[1];
-        const pack = packsLib.readPack(dir);
-        const name = (pack && (pack.name || pack.dir)) || dir;
-        openedThisTurn.add(`pack:${dir}`);
-        notifySkill(`recall:pack:${dir}`, `📖 Recalled my notes on: ${name}`);
-      }
-      const entRe = /\bentity\s+show\s+["']?([a-z0-9][\w.-]*)/gi;
-      while ((m = entRe.exec(cmd))) {
-        const slug = m[1];
-        const ent = entitiesLib.readEntity(slug);
-        const name = (ent && (ent.name || ent.slug)) || slug;
-        openedThisTurn.add(`entity:${slug}`);
-        notifySkill(`recall:entity:${slug}`, `📖 Recalled my notes on: ${name}`);
-      }
-      // `open-claudia tool run|exec <name> <args>` — record each run as
-      // { name, shape }. The name feeds the directed follows-graph (what runs
-      // next); the sanitized command shape feeds pack↔tool capture (how a tool
-      // is used in a topic). Parsing lives in tool-graph so it stays testable.
-      try {
-        for (const run of require("./tool-graph").parseToolRuns(cmd)) {
-          toolRunsThisTurn.push(run);
-          // Visibility (gated by /tooltrace): one 🔧 line per distinct
-          // tool+verb this turn — sanitized command shape plus the verb's own
-          // doc sentence (verbDoc: parsed mechanically from the tool header,
-          // zero model cost). Telemetry (recordRun) fires at end-of-turn.
-          const verb = (String(run.shape || "").split(/\s+/)[1] || "");
-          let doc = "";
-          try { doc = toolsLib.verbDoc(run.name, verb); } catch (e) {}
-          notifyToolTrace(`ran:${run.name}:${verb}`, `🔧 ${run.shape || run.name}${doc ? ` — ${doc}` : ""}`);
+  if (result.ok) {
+    let guarded = false;
+    try { guarded = require("./relationship").isCurrentSpeakerGuarded(); } catch (error) {
+      throw stableRunError(`Unable to classify reply recipient: ${error.message}`, "RUN_DELIVERY_GUARD_FAILED");
+    }
+    if (guarded) {
+      const guard = await require("./enforcer").guardOutboundReply(finalText);
+      if (!guard.allow) {
+        if (!guard.escalated) {
+          const held = await send("I need to check with the owner before I can answer that — I'll follow up.");
+          if (!held.ok) throw new Error("failed to deliver guarded-reply notice");
         }
-      } catch (e) { /* graph optional (old node) */ }
-      // `open-claudia tool add <src> [--name X]` — a tool being saved/updated.
-      // The Write/Edit path above only catches direct edits to TOOLS_DIR; `tool
-      // add` copies an external file in, so detect it here. Gated by /tooltrace.
-      const addRe = /\btool\s+add\s+(\S+)([^\n;|&]*)/gi;
-      while ((m = addRe.exec(cmd))) {
-        let name = (m[2].match(/--name\s+["']?([^\s"']+)/i) || [])[1];
-        if (!name) name = (String(m[1]).split(/[\\/]/).pop() || "").replace(/\.[^.]+$/, "");
-        name = toolsLib.sanitizeName(name);
-        if (name) notifyToolTrace(`added:${name}`, `🛠️ Saved tool: ${name} — open-claudia tool show ${name} to inspect.`);
+        return { ok: true, held: true };
       }
-    } catch (e) { /* announcements are best-effort */ }
-  };
-
-  // The same 📖 signal when the agent opens a note with the Read tool instead
-  // of the CLI: noteRecallFromShell only sees shell commands, so a raw-file
-  // read of a pack/entity would otherwise be invisible to both the banner and
-  // the co-use graph. Deduped against the CLI path via the shared notifySkill
-  // key, so reading the same node both ways still announces only once.
-  const noteRecallFromReadPath = (filePath) => {
-    try {
-      const node = recallNodeFromPath(filePath);
-      if (!node) return;
-      openedThisTurn.add(`${node.kind}:${node.id}`);
-      notifySkill(`recall:${node.kind}:${node.id}`, `📖 Recalled my notes on: ${node.name}`);
-    } catch (e) { /* announcements are best-effort */ }
-  };
+    }
+  }
 
-  let args;
-  try {
-    args = await buildClaudeArgs(prompt, opts);
-  } catch (e) {
-    state.preparingRun = false;
-    stopTyping();
-    throw e;
+  const chunks = splitMessage(finalText);
+  for (let index = 0; index < chunks.length; index += 1) {
+    let sent = await send(chunks[index], telegramHtmlOpts(index === 0 ? { replyTo: runContext.replyToMsgId } : {}));
+    if (!sent.ok) sent = await send(chunks[index], telegramHtmlOpts());
+    if (!sent.ok) throw new Error(`failed to deliver response chunk ${index + 1}`);
   }
-  // Recall announcements are now fired at READ time, not injection time:
-  // matched packs/entities enter context only as small headlines (see
-  // system-prompt.js recallHeadline). The "📖 Recalled my notes on …" line is
-  // emitted by noteRecallFromShell below when the agent actually runs
-  // `open-claudia pack show <dir>` / `entity show <slug>` — so the banner
-  // reflects what was read, not what was pushed. (consumeLastInjected is
-  // drained here to keep the per-turn buffer from leaking into the next turn.)
-  let turnRecallTier = "";
-  // Pack dirs surfaced (recall-matched) for this turn — joined with
-  // openedThisTurn at end-of-turn to tell the post-turn reviewer which packs
-  // this turn's work belongs to (attribution + safe State rewrites).
-  let surfacedPackDirs = [];
-  try {
-    const injected = require("./system-prompt").consumeLastInjected();
-    if (injected && Array.isArray(injected.packDirs)) surfacedPackDirs = injected.packDirs;
-    if (injected && injected.recall) {
-      const r = injected.recall;
-      turnRecallTier = String(r.tier || "");
-      const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-      const fmt = (arr, icon) => arr.map((x) => (x.why ? `${icon} <b>${esc(x.name)}</b> — ${esc(x.why)}` : `${icon} <b>${esc(x.name)}</b>`));
-      // Debug traces are owner-only: recall/tool/engine internals must never
-      // leak to an external speaker even when a debug toggle is left on.
-      const traceOwnerOnly = !externalSpeaker;
-      // 🧠 packs/entities recall — gated by /recall.
-      if (traceOwnerOnly && settings.showRecall) {
-        const lines = [...fmt(r.packs || [], "📦"), ...fmt(r.entities || [], "👤"), ...fmt(r.episodes || [], "📓")];
-        if (lines.length) send(`🧠 <b>Recall this turn</b> (${esc(r.engine)})\n${lines.join("\n")}`, telegramHtmlOpts()).catch(() => {});
-        else if (r.gated) send(`🧠 <b>Recall</b> (${esc(r.engine)}): skipped by pre-gate — trivial turn.`, telegramHtmlOpts()).catch(() => {});
+
+  if (result.ok && runContext.lastInputWasVoice) {
+    const { currentTransport } = require("./context");
+    if (currentTransport() === "voice") {
+      const sentences = splitSentences(finalText);
+      let spoke = false;
+      for (const sentence of sentences) {
+        const clip = await synthSentenceMp3(sentence);
+        if (clip) { spoke = true; await sendVoice(clip); }
       }
-      // 🔧 tools surfaced this turn (first-class discoverer nodes) — gated by /tooltrace.
-      if (traceOwnerOnly && settings.showToolTrace) {
-        const toolLines = fmt(r.tools || [], "🔧");
-        if (toolLines.length) send(`🔧 <b>Tools surfaced this turn</b>\n${toolLines.join("\n")}`, telegramHtmlOpts()).catch(() => {});
+      if (!spoke) {
+        const voicePath = await textToVoice(finalText);
+        if (voicePath) await sendVoice(voicePath);
       }
+      await sendVoiceEnd();
     }
-  } catch (e) { /* best-effort */ }
-  // /stop landed during the pre-spawn window (recall/compaction): bail before
-  // spawning. The /stop handler already acknowledged in chat, so stay silent.
-  if (state.cancelRequested) {
-    state.cancelRequested = false;
-    state.preparingRun = false;
-    stopTyping();
-    return;
   }
-  const binaryPath = getActiveBinary();
-  const proc = spawn(binaryPath, args, {
-    cwd,
-    env: subprocessEnv(),
-    stdio: ["ignore", "pipe", "pipe"],
-    detached: process.platform !== "win32",
-  });
-
-  state.runningProcess = proc;
-  state.preparingRun = false;
-  const startTime = Date.now();
-  let longRunningNotified = false;
-
-  // Inactivity watchdog. The live bot runs through this modular runner
-  // (`bot.js` → `core/runner.js`), so the guard must live here, not only in
-  // the legacy monolith. `state.runningProcess` is single-flight and normally
-  // clears only on child close/error; a silent wedged child can otherwise pin it
-  // forever and leave every later message queued. Treat child stdout/stderr as
-  // liveness and stop the process group if it goes quiet past the idle limit.
-  const idleLimitMs = Math.max(60000, parseInt(config.OC_TURN_IDLE_MS || process.env.OC_TURN_IDLE_MS || "", 10) || 10 * 60 * 1000);
-  let lastActivity = Date.now();
-  let watchdogTripped = false;
-  let watchdogNotice = null;
+  return { ok: true, chunks: chunks.length };
+}
 
-  const processTimeout = setTimeout(() => {
-    if (state.runningProcess === proc) {
-      killProcessTree(proc.pid, "SIGTERM");
-      setTimeout(() => killProcessTree(proc.pid, "SIGKILL"), 5000);
-      chatContext.run(store, () => send(`Task timed out after ${MAX_PROCESS_TIMEOUT / 60000} minutes. Stopped.`));
-    }
-  }, MAX_PROCESS_TIMEOUT);
+function decorateForegroundInvocation(invocation, runContext, bundle) {
+  const env = { ...invocation.env };
+  const lb = loopback.info();
+  const compactionStage = runContext.purpose === "compact-summary" || runContext.purpose === "compact-seed";
+  if (!compactionStage) {
+    if (runContext.origin?.adapterId) env.OC_CHANNEL_ADAPTER = runContext.origin.adapterId;
+    if (runContext.channelId) env.OC_CHANNEL_ID = String(runContext.channelId);
+    if (runContext.origin?.userId) env.OC_CHANNEL_USER_ID = String(runContext.origin.userId);
+    if (runContext.canonicalUserId) env.OC_CANONICAL_USER_ID = String(runContext.canonicalUserId);
+    if (runContext.sessionId) env.OC_LAST_SESSION_ID = String(runContext.sessionId);
+    if (lb?.url) env.OC_SEND_URL = lb.url;
+  }
+  env.OC_PROVIDER = runContext.provider;
+  env.OC_RUN_ID = runContext.runId;
+  if (runContext.project?.name) env.OC_PROJECT = String(runContext.project.name);
+  if (runContext.project?.dir) env.OC_PROJECT_DIR = String(runContext.project.dir);
+  if (runContext.sessionId) env.OC_SESSION_ID = String(runContext.sessionId);
+  if (runContext.previousSessionId) env.OC_PREVIOUS_SESSION_ID = String(runContext.previousSessionId);
+  if (runContext.providerSettings) env.OC_PROVIDER_SETTINGS = JSON.stringify(runContext.providerSettings);
+  if (runContext.occurrenceId) env.OC_OCCURRENCE_ID = String(runContext.occurrenceId);
+  if (runContext.scheduledJobId) env.OC_SCHEDULED_JOB_ID = String(runContext.scheduledJobId);
+  if (runContext.originRunId) env.OC_ORIGIN_RUN_ID = String(runContext.originRunId);
+  if (bundle.transcriptPaths?.transcriptPath) env.OC_TRANSCRIPT_PATH = bundle.transcriptPaths.transcriptPath;
+  return { ...invocation, env };
+}
 
-  let lastUpdate = "";
-  const scheduleUpdate = () => {
-    const elapsed = Math.floor((Date.now() - startTime) / 1000);
-    const interval = elapsed > 120 ? 5000 : 2000;
-    state.streamInterval = setTimeout(() => chatContext.run(store, updateProgress), interval);
+function startTypingHeartbeat(state, store) {
+  const adapter = store?.adapter || currentAdapter();
+  const channelId = store?.channelId || currentChannelId();
+  if (!adapter || !channelId) return () => {};
+  const tick = () => adapter.typing(channelId, state.thinkingPhase ? "thinking" : undefined).catch(() => {});
+  state.thinkingPhase = true;
+  tick();
+  state.typingHeartbeat = setInterval(tick, 4000);
+  return () => {
+    state.thinkingPhase = false;
+    if (state.typingHeartbeat) clearInterval(state.typingHeartbeat);
+    state.typingHeartbeat = null;
+    try { adapter.typingStop?.(channelId); } catch (_) {}
   };
+}
 
-  const drainQueuedMessages = async () => {
-    if (state.messageQueue.length === 0 || !state.currentSession) return;
-    const drained = state.messageQueue.splice(0);
-    // Handle one same-origin run at a time; requeue the remainder so the
-    // finishing turn's close→drain tail-recursion picks up the next origin
-    // group. Each group's reply is scoped to the channel it came from, so a
-    // message queued from one of the owner's channels during a run on another
-    // is still answered on its own channel (unified identity, one run-lock).
-    const { group, rest } = splitLeadingOriginGroup(drained);
-    if (rest.length) state.messageQueue.unshift(...rest);
-
-    const runGroup = async () => {
-      if (group.length === 1) {
-        const only = group[0];
-        await runClaude(only.prompt, state.currentSession.dir, only.replyToMsgId, only.opts);
-      } else {
-        const fmtTime = (ts) => {
-          const d = new Date(ts);
-          const hh = String(d.getHours()).padStart(2, "0");
-          const mm = String(d.getMinutes()).padStart(2, "0");
-          const ss = String(d.getSeconds()).padStart(2, "0");
-          return `${hh}:${mm}:${ss}`;
-        };
-        const numbered = group.map((m, idx) => `[${idx + 1}] (${fmtTime(m.queuedAt || Date.now())}) ${m.prompt}`).join("\n\n");
-        const batched =
-          `While you were working the user sent these ${group.length} follow-up messages (oldest first):\n\n` +
-          `${numbered}\n\n` +
-          `Treat each as a distinct follow-up request. Add them to your plan and handle them; ` +
-          `if any contradicts an earlier one, prefer the newer one and call out the conflict.`;
-        const last = group[group.length - 1];
-        await runClaude(batched, state.currentSession.dir, last.replyToMsgId, last.opts);
+function settleImmediateEffects(result, runContext, { state, store, capture }) {
+  const stages = [
+    ["transcript", persistForegroundTranscript],
+    ["usage", persistForegroundUsage],
+    ["session", persistForegroundSession],
+  ];
+  return (async () => {
+    for (const [name, hook] of stages) {
+      if (!result.persistence[name].skipped) continue;
+      result.persistence[name] = { ok: true, skipped: false };
+      try { await hook(result, runContext, state, store); }
+      catch (error) {
+        result.persistence[name] = { ok: false, skipped: false, error: stableRunError(error.message, `RUN_${name.toUpperCase()}_PERSIST_FAILED`) };
+        if (!result.error) result.error = result.persistence[name].error;
+        result.ok = false;
+        result.status = "failed";
       }
-    };
-
-    const origin = group[0].origin;
-    if (origin) await chatContext.run(origin, runGroup);
-    else await runGroup();
-  };
-
-  const updateProgress = async () => {
-    const elapsed = Math.floor((Date.now() - startTime) / 1000);
-    if (!watchdogTripped && state.runningProcess === proc && Date.now() - lastActivity > idleLimitMs) {
-      watchdogTripped = true;
-      const idleMin = Math.max(1, Math.floor((Date.now() - lastActivity) / 60000));
-      watchdogNotice = `Task stalled — no activity for ${idleMin}min, so I stopped it and I'm responsive again. Send /continue to resume, or just re-ask.`;
-      console.error(`[watchdog] child pid ${proc.pid} idle ${idleMin}min (limit ${Math.floor(idleLimitMs / 60000)}min) — killing`);
-      try { killProcessTree(proc.pid, "SIGTERM"); }
-      catch (e) { try { proc.kill("SIGTERM"); } catch (e2) {} }
-      setTimeout(() => { try { killProcessTree(proc.pid, "SIGKILL"); } catch (e) {} }, 3000);
-      setTimeout(() => chatContext.run(store, async () => {
-        if (state.runningProcess === proc) {
-          state.runningProcess = null;
-          state.preparingRun = false;
-          stopTyping();
-          clearTimeout(state.streamInterval); state.streamInterval = null;
-          clearTimeout(processTimeout);
-          state.statusMessageId = null;
-          if (settings.budget) settings.budget = null;
-          saveState();
-          await drainQueuedMessages();
-        }
-      }), 10000);
-      try { await send(watchdogNotice, { replyTo: replyToMsgId }); } catch (e) {}
-      state.statusMessageId = null;
-      return;
     }
-    try {
-      if (adapter && channelId) adapter.typing(channelId).catch(() => {});
-      // For guarded (external) turns the live preview must not echo unvetted
-      // assistant text — show tool/elapsed status only until the final reply is
-      // vetted and delivered.
-      const display = formatProgress(guardedTurn ? "" : assistantText, toolUses, currentTool, elapsed, currentToolDetail);
-      if (display && display !== lastUpdate) {
-        // A statusMessageId minted on another channel (shared per-canonical
-        // state under unified identity) can't be edited here — drop it so a
-        // fresh preview is created on this channel instead of 500-ing.
-        if (state.statusMessageId && state.statusMessageChannel !== channelId) {
-          state.statusMessageId = null;
-          state.statusMessageChannel = null;
-        }
-        if (!state.statusMessageId && assistantText) {
-          const previewResult = await send(display.length > 4000 ? display.slice(-4000) : display, telegramHtmlOpts({ replyTo: replyToMsgId }));
-          // Keep the real string id when the preview is editable (Telegram +
-          // Kazee both normalize to a string now); otherwise a truthy sentinel
-          // so we don't re-post a fresh preview each tick, while canEditStatus()
-          // (typeof string) still declines to edit an unaddressable message.
-          state.statusMessageId = previewResult.editable ? previewResult.messageId : (previewResult.ok ? true : null);
-          state.statusMessageChannel = channelId;
-        } else if (canEditStatus()) {
-          await editMessage(state.statusMessageId, display.length > 4000 ? display.slice(-4000) : display, telegramHtmlOpts({ streaming: true }));
-        }
-        lastUpdate = display;
-      }
-      if (elapsed > 300 && !longRunningNotified) {
-        longRunningNotified = true;
-        await send(`Still working (${Math.floor(elapsed / 60)}min)... Send /stop to cancel.`);
+    if (!capture && result.delivery.skipped) {
+      result.delivery.skipped = false;
+      try {
+        result.delivery.result = await deliverForegroundResult(result, runContext, state);
+        result.delivery.ok = true;
+      } catch (error) {
+        result.delivery.ok = false;
+        result.delivery.error = stableRunError(error.message, "RUN_DELIVERY_FAILED");
+        if (!result.error) result.error = result.delivery.error;
+        result.ok = false;
+        result.status = "failed";
       }
-    } catch (e) {
-      console.error("Progress update error:", e.message);
     }
-    if (state.runningProcess) scheduleUpdate();
-  };
-  scheduleUpdate();
-
-  proc.stdout.on("data", (data) => {
-    lastActivity = Date.now();
-    state.streamBuffer += data.toString();
-    const events = parseStreamEvents(state.streamBuffer);
-    const lastNewline = state.streamBuffer.lastIndexOf("\n");
-    state.streamBuffer = lastNewline >= 0 ? state.streamBuffer.slice(lastNewline + 1) : state.streamBuffer;
-    for (const evt of events) {
-      // Leave the "thinking" phase the moment the model produces any real
-      // output — streamed text, a finished assistant block, a tool call, or a
-      // terminal result. Idempotent (guards on state.thinkingPhase internally).
-      if (state.thinkingPhase && (
-        (evt.type === "stream_event" && evt.event?.type === "content_block_delta" && evt.event.delta?.type === "text_delta") ||
-        (evt.type === "assistant" && evt.message?.content) ||
-        (evt.type === "tool_call" && evt.subtype === "started") ||
-        evt.type === "result"
-      )) {
-        endThinking();
-      }
-      // Voice latency probe: first "system" event = CLI ready (cold-start done);
-      // "result" = generation finished (before the TTS tail drains).
-      if (voiceStreaming && vlFirstSysAt == null && evt.type === "system") vlFirstSysAt = Date.now();
-      if (voiceStreaming && vlResultAt == null && evt.type === "result") vlResultAt = Date.now();
-      // Voice streaming-out: speak finished sentences as the model writes them.
-      // Only text_delta is spoken; thinking_delta and tool events are ignored.
-      if (voiceStreaming && evt.type === "stream_event"
-          && evt.event?.type === "content_block_delta"
-          && evt.event.delta?.type === "text_delta"
-          && typeof evt.event.delta.text === "string") {
-        if (vlFirstTokenAt == null) vlFirstTokenAt = Date.now();
-        spokenBuf += evt.event.delta.text;
-        pumpSpoken(false);
-      }
-      if (evt.type === "assistant" && evt.message?.usage) {
-        const callPrefix = usageParts(evt.message.usage, settings.backend || "claude").context;
-        if (callPrefix > peakContextTokens) peakContextTokens = callPrefix;
-      }
-      if (evt.type === "assistant" && evt.message?.content) {
-        for (const block of evt.message.content) {
-          if (block.type === "text") assistantText += block.text;
-          else if (block.type === "tool_use") {
-            currentTool = block.name;
-            toolUses.push(block.name);
-            const input = block.input || {};
-            if (block.name === "Bash" && input.command) currentToolDetail = input.command.slice(0, 80);
-            else if (block.name === "Read" && input.file_path) currentToolDetail = input.file_path.split("/").slice(-2).join("/");
-            else if (block.name === "Edit" && input.file_path) currentToolDetail = input.file_path.split("/").slice(-2).join("/");
-            else if (block.name === "Write" && input.file_path) currentToolDetail = input.file_path.split("/").slice(-2).join("/");
-            else if (block.name === "Grep" && input.pattern) currentToolDetail = input.pattern.slice(0, 40);
-            else if (block.name === "Glob" && input.pattern) currentToolDetail = input.pattern;
-            else if (block.name === "Skill" && input.skill) currentToolDetail = input.skill;
-            else currentToolDetail = "";
-            noteSkillToolUse(block.name, input);
-            if (block.name === "Bash" && input.command) noteRecallFromShell(input.command);
-            else if (block.name === "Read") noteRecallFromReadPath(input.file_path || input.filePath);
-          }
-        }
-      }
-      if (evt.type === "tool_call" && evt.subtype === "started" && evt.tool_call) {
-        const tc = evt.tool_call;
-        if (tc.shellToolCall) {
-          const a = tc.shellToolCall.args || {};
-          currentTool = "Shell"; toolUses.push("Shell");
-          currentToolDetail = (a.description || a.command || "").slice(0, 80);
-          if (a.command) noteRecallFromShell(a.command);
-        } else if (tc.readToolCall) {
-          currentTool = "Read"; toolUses.push("Read");
-          const readPath = tc.readToolCall.args?.path;
-          currentToolDetail = (readPath || "").split("/").slice(-2).join("/");
-          noteRecallFromReadPath(readPath);
-        } else if (tc.editToolCall) {
-          currentTool = "Edit"; toolUses.push("Edit");
-          currentToolDetail = (tc.editToolCall.args?.filePath || "").split("/").slice(-2).join("/");
-          noteSkillToolUse("Edit", tc.editToolCall.args);
-        } else if (tc.writeToolCall) {
-          currentTool = "Write"; toolUses.push("Write");
-          currentToolDetail = (tc.writeToolCall.args?.filePath || "").split("/").slice(-2).join("/");
-          noteSkillToolUse("Write", tc.writeToolCall.args);
-        } else if (tc.grepToolCall) {
-          currentTool = "Grep"; toolUses.push("Grep");
-          currentToolDetail = (tc.grepToolCall.args?.pattern || "").slice(0, 40);
-        } else if (tc.globToolCall) {
-          currentTool = "Glob"; toolUses.push("Glob");
-          currentToolDetail = (tc.globToolCall.args?.globPattern || "").slice(0, 40);
-        } else if (tc.createPlanToolCall) {
-          currentTool = "Plan"; toolUses.push("Plan");
-          const plan = tc.createPlanToolCall.args || {};
-          let planText = "";
-          if (plan.name) planText += `**${plan.name}**\n\n`;
-          if (plan.plan) planText += plan.plan + "\n";
-          if (plan.todos && plan.todos.length) {
-            planText += "\n**Tasks:**\n";
-            for (const todo of plan.todos) {
-              planText += `• ${todo.content || todo.id}\n`;
-            }
-          }
-          if (planText) assistantText = planText;
-          currentToolDetail = plan.name || "creating plan";
-        } else {
-          const toolKey = Object.keys(tc)[0] || "unknown";
-          currentTool = toolKey.replace("ToolCall", ""); toolUses.push(currentTool);
-          currentToolDetail = "";
-        }
-      }
-      if (evt.type === "thread.started" && evt.thread_id) {
-        state.codexSessionId = evt.thread_id;
-        saveState();
-      }
-      if (evt.type === "item.started" && evt.item) {
-        const it = evt.item;
-        if (it.type === "command_execution" && it.command) {
-          currentTool = "Shell"; toolUses.push("Shell");
-          currentToolDetail = String(it.command).slice(0, 80);
-          noteRecallFromShell(it.command);
-        } else if (it.type === "file_change" && (it.path || it.file_path)) {
-          currentTool = "Edit"; toolUses.push("Edit");
-          const p = it.path || it.file_path;
-          currentToolDetail = String(p).split("/").slice(-2).join("/");
-        } else if (it.type === "web_search" && it.query) {
-          currentTool = "Web"; toolUses.push("Web");
-          currentToolDetail = String(it.query).slice(0, 60);
-        } else if (it.type) {
-          currentTool = it.type; toolUses.push(it.type);
-          currentToolDetail = "";
-        }
-      }
-      if (evt.type === "item.completed" && evt.item) {
-        const it = evt.item;
-        if (it.type === "agent_message" && typeof it.text === "string") {
-          assistantText += (assistantText ? "\n" : "") + it.text;
-        }
-      }
-      if (evt.type === "turn.completed" && evt.usage && settings.backend === "codex") {
-        const session = state.codexSessionId || evt.thread_id || getActiveSessionId();
-        const normalized = normalizeCodexUsage(state, session, evt.usage);
-        const rawParts = usageParts(evt.usage, "codex");
-        applyUsageToState(state, normalized.usage, 0, {
-          usageScope: normalized.usageScope,
-          liveContextTokens: rawParts.context,
-        });
-        logTurnUsage(state, normalized.usage, 0, (text) => chatContext.run(store, () => send(text)), normalized);
-        saveState();
+    result.diagnostic = result.ok ? null : (providerRunDiagnostic(result, runContext) || result.error?.message || "Provider run failed");
+    return result;
+  })();
+}
+
+function createForegroundService({ state, store, stopTyping, capture, ownsAdmissionLock, persistCapture = true }) {
+  const persistEffects = !capture || persistCapture;
+  return createRunnerService({
+    getState: () => state,
+    getStore: () => store,
+    resolveProvider: resolveForegroundProvider,
+    buildTurnPrompt,
+    buildInvocation(provider, context) {
+      if (context.purpose === "compact-seed" && typeof provider.buildCompactionInvocation === "function") {
+        return provider.buildCompactionInvocation(context);
       }
-      if (evt.type === "result" && evt.session_id) {
-        if (settings.backend === "cursor") { state.cursorSessionId = evt.session_id; }
-        else { state.lastSessionId = evt.session_id; }
-        // Codex already reports usage at turn.completed. A result usage block,
-        // if present, is the same cumulative total and must not be counted again.
-        if (evt.usage && settings.backend !== "codex") {
-          const peakOpts = { usageScope: "turn_delta" };
-          if (peakContextTokens > 0) peakOpts.liveContextTokens = peakContextTokens;
-          applyUsageToState(state, evt.usage, typeof evt.total_cost_usd === "number" ? evt.total_cost_usd : 0, peakOpts);
-          logTurnUsage(state, evt.usage, typeof evt.total_cost_usd === "number" ? evt.total_cost_usd : 0, (text) => chatContext.run(store, () => send(text)), peakOpts);
-        }
-        if (typeof evt.total_cost_usd === "number" && settings.backend === "codex") state.sessionUsage.costUsd += evt.total_cost_usd;
-        saveState();
+      return provider.buildMainInvocation(context);
+    },
+    decorateInvocation: decorateForegroundInvocation,
+    persistTranscript: persistEffects ? ((result, runContext) => persistForegroundTranscript(result, runContext, state)) : null,
+    persistUsage: persistEffects ? ((result, runContext) => persistForegroundUsage(result, runContext, state, store)) : null,
+    persistSession: persistEffects ? ((result, runContext) => persistForegroundSession(result, runContext, state)) : null,
+    deliver: capture ? null : (result, runContext) => deliverForegroundResult(result, runContext, state),
+    onSpawn(proc) {
+      state.runningProcess = proc;
+      if (ownsAdmissionLock) state.preparingRun = false;
+    },
+    onEvent(event) {
+      if (["text_delta", "text_final", "tool_start", "result", "error"].includes(event.type)) state.thinkingPhase = false;
+      if (event.type === "tool_start" && ["Shell", "Bash"].includes(event.name)) {
+        const command = typeof event.detail === "string" ? event.detail : event.detail?.command;
+        if (command) { try { require("./tool-guard").noteRawOp(command); } catch (_) {} }
       }
-      // Fallback only: evt.result is just the final text segment, and assigning
-      // it unconditionally wiped everything the model said before tool calls.
-      if (evt.type === "result" && evt.result && !assistantText.trim()) assistantText = evt.result;
-    }
+    },
+    onInvocationWarning(warning) {
+      return send(`⚠️ ${warning.message}`);
+    },
+    onStderr(chunk) { console.error("PROVIDER STDERR:", redactSensitive(chunk)); },
+    cleanup: async (proc) => {
+      if (state.runningProcess === proc) state.runningProcess = null;
+      // Keep the single-flight lock armed while transcript/usage/session
+      // persistence and required delivery settle after child close.
+      if (ownsAdmissionLock) state.preparingRun = true;
+      stopTyping();
+    },
+    idleTimeoutMs: Math.max(60000, parseInt(config.OC_TURN_IDLE_MS || process.env.OC_TURN_IDLE_MS || "", 10) || 10 * 60 * 1000),
   });
+}
 
-  let stderrBuffer = "";
-  proc.stderr.on("data", (d) => {
-    lastActivity = Date.now();
-    const chunk = d.toString();
-    stderrBuffer += chunk;
-    console.error("STDERR:", redactSensitive(chunk));
+async function handoffMemoryReview(result, runContext, store) {
+  if (!result.ok || !result.text || runContext.purpose !== "foreground") return;
+  const recall = result.recallMetadata || {};
+  packReview.reviewTurn({
+    userText: runContext.userPrompt,
+    assistantText: result.text,
+    channelId: runContext.channelId,
+    provider: runContext.provider,
+    runId: runContext.runId,
+    activePacks: recall.packDirs || [],
+    signals: { tier: recall.tier || "", wrote: result.tools.some((event) => event.type === "tool_start" && ["Edit", "Write", "Bash", "Shell"].includes(event.name)) },
+    source: (() => {
+      try {
+        const speaker = require("./people").findByHandle(store?.adapter?.type, String(store?.userId || store?.channelId || ""));
+        return speaker ? { name: speaker.name, isOwner: !!speaker.isOwner } : null;
+      } catch (_) { return null; }
+    })(),
+    announce: (text) => chatContext.run(store, () => send(text)),
   });
+}
 
-  proc.on("close", (code) => chatContext.run(store, async () => {
-    state.runningProcess = null;
-    state.preparingRun = false;
-    stopTyping();
-    clearTimeout(state.streamInterval); state.streamInterval = null;
-    clearTimeout(processTimeout);
-
-    if (watchdogTripped) {
-      const note = watchdogNotice || "Task stalled; watchdog stopped the child process.";
-      appendProjectTranscript("system-note", note, { exitCode: code, kind: "watchdog" }, state, getActiveSessionId);
-      if (settings.budget) settings.budget = null;
-      state.statusMessageId = null;
-      await drainQueuedMessages();
-      return;
-    }
-
-    if (settings.backend === "claude" && isClaudeAuthErrorText(stderrBuffer)) {
-      const authText = claudeAuthRecoveryMessage(stderrBuffer.trim().slice(-800));
-      appendProjectTranscript("system-note", authText, { kind: "auth-error" }, state, getActiveSessionId);
-      await send(authText, { replyTo: replyToMsgId });
-      return;
-    }
-    if (settings.backend === "cursor" && isClaudeAuthErrorText(stderrBuffer)) {
-      const authText = "Cursor authentication error. Run `agent login` on this machine, then retry.";
-      appendProjectTranscript("system-note", authText, { kind: "auth-error" }, state, getActiveSessionId);
-      await send(authText, { replyTo: replyToMsgId });
-      return;
-    }
-    if (settings.backend === "codex" && /not (?:logged in|authenticated)|please (?:log|sign) in|401 unauthorized|invalid api key/i.test(stderrBuffer)) {
-      const authText = "Codex authentication error. Try /codex_auth_status, then /codex_login or /codex_setup_token.";
-      appendProjectTranscript("system-note", authText, { kind: "auth-error" }, state, getActiveSessionId);
-      await send(authText, { replyTo: replyToMsgId });
-      return;
-    }
-
-    // Phase 3: set when an external reply is held by the guardrail — suppresses
-    // delivery AND the post-turn reviewer (a blocked turn must not accrete into
-    // the owner's memory). Declared out here so it's visible at reviewTurn below.
-    let suppressDelivery = false;
-    try {
-      if (code !== 0 && code !== null && !assistantText.trim()) {
-        const failureText = claudeEmptyFailureMessage(code, stderrBuffer);
-        appendProjectTranscript("system-note", failureText, { exitCode: code, kind: "backend-error" }, state, getActiveSessionId);
-        await send(failureText, { replyTo: replyToMsgId });
-        return;
-      }
+function deferredRunResult() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
 
-      const finalText = redactSensitive(assistantText || "(no output)");
-      appendProjectTranscript("assistant", finalText, {
-        exitCode: code,
-        sourceMessageId: typeof state.statusMessageId === "string" ? state.statusMessageId : null,
-      }, state, getActiveSessionId);
-
-      // Phase 3 (3.3): vet the outbound reply for external speakers. Owner/no-
-      // context → allow instantly (guardOutboundReply returns allow without a
-      // model call). On block/escalate the guard has already told the external
-      // "let me check with <owner>" and raised an owner approval, so we suppress
-      // delivery here; the vetted text is delivered later by the apr: handler on
-      // approval. The blocked text is still recorded to the transcript above so
-      // the owner can see what was held.
-      if (guardedTurn) {
-        let g = { allow: true };
-        try { g = await require("./enforcer").guardOutboundReply(finalText); }
-        catch (e) { g = { allow: false, escalated: false, reason: e.message }; }
-        if (!g.allow) {
-          suppressDelivery = true;
-          if (!g.escalated) {
-            try { await send("I need to check with the owner before I can answer that — I'll follow up."); } catch (e) {}
-          }
-        }
-      }
+function drainQueuedMessages(state) {
+  if (!Array.isArray(state.messageQueue) || !state.messageQueue.length || state.runningProcess || state.preparingRun) return Promise.resolve();
+  const item = state.messageQueue.shift();
+  state.preparingRun = true;
+  setImmediate(() => {
+    const execute = () => executeAdmittedRun(item.runContext, state, item.store, false, true);
+    const promise = item.store ? chatContext.run(item.store, execute) : execute();
+    promise.then(item.deferred.resolve, item.deferred.reject);
+  });
+  return Promise.resolve();
+}
 
-      const chunks = splitMessage(finalText);
-      const firstChunk = chunks[0];
-
-      if (suppressDelivery) {
-        // The reply was held for the owner: nothing is spoken or sent to the
-        // external now. Clear the voice-input flag so it can't leak into the
-        // next turn (no TTS flush runs on this path).
-        state.lastInputWasVoice = false;
-        if (canEditStatus()) { try { await editMessage(state.statusMessageId, "Checking with the owner…", telegramHtmlOpts()); } catch (e) {} }
-      } else if (canEditStatus() && chunks.length === 1) {
-        // Edit the streaming preview into the final reply — but only if that
-        // preview was minted on THIS channel. A foreign-channel id falls through
-        // to a fresh send below (never edited cross-channel, which would 500).
-        await editMessage(state.statusMessageId, firstChunk, telegramHtmlOpts({ streaming: true }));
-      } else {
-        const sent = await send(firstChunk, telegramHtmlOpts({ replyTo: replyToMsgId }));
-        if (!sent.ok) await send(firstChunk);
-        for (let i = 1; i < chunks.length; i++) {
-          await send(chunks[i], telegramHtmlOpts());
-        }
-      }
-      if (!suppressDelivery && code !== 0 && code !== null) await send(`Exit code: ${code}`);
-
-      if (!suppressDelivery && state.lastInputWasVoice) {
-        state.lastInputWasVoice = false;
-        if (voiceStreaming) {
-          // Sentences were already being spoken as the model wrote them. Flush
-          // the trailing partial sentence, wait for the ordered send queue to
-          // drain, then close the turn so the client re-arms the mic.
-          pumpSpoken(true);
-          await ttsChain;
-          if (!spokeAnyStreamed) {
-            // Tool-only / empty turn produced no spoken text — say the final
-            // text once so the user still hears a reply.
-            const voicePath = await textToVoice(finalText);
-            if (voicePath) await sendVoice(voicePath);
-          }
-          await sendVoiceEnd();
-          // Per-stage latency breakdown (measurement only — temporary debug footer).
-          try {
-            const vl = state.voiceLat || {};
-            const endAt = Date.now();
-            const sec = (n) => n != null ? (n / 1000).toFixed(1) + "s" : "?";
-            const diff = (a, b) => (a != null && b != null) ? sec(b - a) : "?";
-            const fromStart = (t) => diff(vl.startAt, t);
-            const line = `⏱ dl ${sec(vl.downloadMs)} · stt ${sec(vl.sttMs)}`
-              + ` · cli ${diff(startTime, vlFirstSysAt)} · ttft ${diff(vlFirstSysAt, vlFirstTokenAt)}`
-              + ` · gen ${diff(vlFirstTokenAt, vlResultAt)} · 1st-audio ${fromStart(vlFirstAudioAt)}`
-              + ` · total ${fromStart(endAt)}`;
-            console.log(`[VOICE-LAT] ${line}`);
-            await send(line);
-          } catch (e) { /* metrics best-effort */ }
-          state.voiceLat = null;
-        } else {
-          // Non-streamed fallback. Spoken replies belong to the hands-free voice
-          // channel; on chat transports (Telegram/Kazee) an auto voice note on
-          // every voice input is unwanted noise, so gate it to the voice channel.
-          const { currentTransport } = require("./context");
-          if (currentTransport() === "voice") {
-            const sentences = splitSentences(finalText);
-            let spokeAny = false;
-            for (const sentence of sentences) {
-              const clip = await synthSentenceMp3(sentence);
-              if (clip) { spokeAny = true; await sendVoice(clip); }
-            }
-            if (!spokeAny) {
-              const voicePath = await textToVoice(finalText);
-              if (voicePath) await sendVoice(voicePath);
-            }
-            await sendVoiceEnd();
-          }
-        }
-      }
-    } catch (e) {
-      console.error("Final message delivery failed:", e.message);
-      await send("Task completed but failed to deliver the response. Send /continue to see the result.");
+async function executeAdmittedRun(runContext, state, store, capture, ownsAdmissionLock, executionOptions = {}) {
+  const tracksMainRun = ownsAdmissionLock && !capture;
+  if (tracksMainRun) state.activeRunContext = runContext;
+  const stopTyping = startTypingHeartbeat(state, store);
+  const persistCapture = executionOptions.persistCapture !== false;
+  const internalCapture = capture && !persistCapture;
+  const service = createForegroundService({ state, store, stopTyping, capture, ownsAdmissionLock, persistCapture });
+  let result;
+  try {
+    result = await service.executeCaptured(runContext.userPrompt, runContext, { capture });
+    if ((result.persistence.transcript.skipped || (!capture && result.delivery.skipped)) && !internalCapture) {
+      result = await settleImmediateEffects(result, runContext, { state, store, capture });
     }
-    if (settings.budget) settings.budget = null;
-    state.statusMessageId = null;
-
-    // Outcome signal: only learn from turns that actually completed. A turn that
-    // errored out is not evidence that a recalled pattern "helped" — reinforcing
-    // or recording reuse on it would teach the wrong lesson (gap: reinforcement
-    // must track "helped", not merely "opened").
-    const turnSucceeded = (code === 0 || code === null);
-
-    // Hebbian co-use: nodes the agent actually opened together this turn get
-    // their `related` edges reinforced, so future spreading activation pulls
-    // the cluster together. Reinforce on co-USE (📖), never co-recall.
-    if (turnSucceeded && openedThisTurn.size > 0) {
-      try {
-        const recallGraph = require("./recall/graph");
-        if (openedThisTurn.size > 1) recallGraph.reinforceSet([...openedThisTurn]);
-        require("./recall/metrics").logUse([...openedThisTurn]);
-      } catch (e) { /* best-effort */ }
+  } catch (error) {
+    result = preflightFailureResult(runContext, { id: runContext.provider, label: runContext.provider }, error);
+    if (!internalCapture) {
+      result = await settleImmediateEffects(result, runContext, { state, store, capture });
     }
+  } finally {
+    if (tracksMainRun && state.runningProcess) state.runningProcess = null;
+    if (ownsAdmissionLock) state.preparingRun = false;
+    if (tracksMainRun && state.activeRunContext === runContext) state.activeRunContext = null;
+    stopTyping();
+  }
 
-    // Directed tool-graph: a chain of reusable tools run in succession this turn
-    // (auth → list → download) becomes follows-edges, so next time the first
-    // runs we can surface "usually followed by …". Kept in a tool-specific graph
-    // so it never bleeds into recall's spreading activation. Reinforce only on a
-    // successful turn, and only when ≥2 ran (a single run has no succession).
-    if (turnSucceeded && toolRunsThisTurn.length > 1) {
-      try { require("./tool-graph").reinforceSequence(toolRunsThisTurn.map((t) => t.name)); }
-      catch (e) { /* best-effort */ }
+  if (tracksMainRun) {
+    sideChatCoordinator.noteMainResult(runContext, result);
+    for (const item of state.messageQueue) {
+      finalizeSideChatQueueItem(item, runContext, result);
     }
-
-    // Tool usage telemetry: a JSON sidecar (runCount + lastUsed per tool) that
-    // works on every node version (unlike the SQLite graphs above). matchTools
-    // breaks score ties by runCount so well-worn tools surface first, and dream
-    // hygiene flags tools created-but-never-run. Fires for any successful run.
-    if (turnSucceeded && toolRunsThisTurn.length) {
-      try { for (const t of toolRunsThisTurn) toolsLib.recordRun(t.name); }
-      catch (e) { /* best-effort */ }
+  }
+  if (!internalCapture) await handoffMemoryReview(result, runContext, store);
+  if (!internalCapture && state.settings?.backend === runContext.provider && state.settings.budget) {
+    state.settings.budget = null;
+    try { saveState({ strict: true }); }
+    catch (error) {
+      result.ok = false;
+      result.status = "failed";
+      result.error = result.error || stableRunError(error.message, "RUN_SETTINGS_PERSIST_FAILED");
+      result.diagnostic = providerRunDiagnostic(result, runContext) || result.error.message;
     }
+  }
+  if (!capture && result.ok && state.messageQueue.length === 0 && sameCapturedProject(state, runContext) && shouldAutoCompact(state)) {
+    try { await compactActiveSession(runContext.project.dir, { notify: false }); }
+    catch (error) { console.warn(`[proactive-compact] failed: ${redactSensitive(error.message)}`); }
+  }
+  if (!internalCapture) await drainQueuedMessages(state);
+  return result;
+}
 
-    // Pack↔tool contextual edges: a reusable tool run while a context pack was
-    // open this turn records "this tool was used in this topic, as `<shape>`",
-    // so next time the pack is active the discoverer can surface the concrete
-    // invocation instead of leaving the agent to re-derive it. Fires even for a
-    // single run (one tool-in-a-pack is still a usage) — unlike the follows-graph
-    // above which needs a succession. Best-effort; never blocks the turn.
-    if (turnSucceeded && toolRunsThisTurn.length && openedThisTurn.size) {
-      try {
-        const tg = require("./tool-graph");
-        const packDirs = [...openedThisTurn].filter((n) => n.startsWith("pack:")).map((n) => n.slice(5));
-        for (const dir of packDirs) {
-          for (const run of toolRunsThisTurn) tg.recordPackTool(dir, run.name, { command: run.shape, bump: 1 });
-        }
-      } catch (e) { /* best-effort */ }
-    }
+function admissionOptions(state, opts = {}) {
+  const provider = opts.provider || state.settings?.backend || null;
+  return { ...opts, provider };
+}
 
-    // Close the learning loop: when an ABILITY pack is opened in the same turn
-    // as a project (context) pack, the ability was demonstrably applied while
-    // working on that project. recordCoUse grows the ability's applied_on, which
-    // forms the project→ability governed-by edge on the next structural sync —
-    // so reuse transfers AUTOMATICALLY from actual use, without waiting on the
-    // reviewer to infer it. This runs before the (async) reviewer, so it wins
-    // the race and the reviewer sees applied_on already set (no double-announce).
-    if (turnSucceeded && openedThisTurn.size > 1) {
-      try {
-        for (const t of packsLib.recordCoUse([...openedThisTurn])) {
-          notifySkill(`applied:${t.ability}:${t.project}`,
-            `🧩 Reused the "${t.abilityName}" ability on ${t.projectName} — it transfers there now too.`);
-        }
-      } catch (e) { /* best-effort */ }
-    }
+function admitRunContext(prompt, cwd, replyToMsgId, opts = {}) {
+  const state = currentState();
+  const store = chatContext.getStore() || null;
+  const resolvedCwd = resolveRunCwd(cwd);
+  return captureRunContext({
+    state,
+    store,
+    prompt,
+    cwd: resolvedCwd,
+    replyToMsgId,
+    opts: admissionOptions(state, opts),
+    channelId: currentChannelId(),
+    canonicalUserId: state.userId,
+    runId: opts.runId || null,
+  });
+}
 
-    // Post-turn pack review: fire-and-forget on a cheap model; never
-    // blocks queue drain or the next turn. Skipped when the reply was held by
-    // the external guardrail — a blocked turn must not accrete into memory.
-    if ((code === 0 || code === null) && assistantText.trim() && !suppressDelivery) {
-      const WRITE_TOOLS = new Set(["Edit", "Write", "NotebookEdit", "Bash", "Shell", "Skill", "Task", "Agent"]);
-      packReview.reviewTurn({
-        userText: prompt,
-        assistantText,
-        channelId,
-        // Packs this turn demonstrably worked with: surfaced by recall for the
-        // incoming message, or explicitly opened by the agent. The reviewer
-        // sees their full current sections and must attribute updates here —
-        // prevents cross-project misattribution and blind State rewrites.
-        activePacks: [...new Set([
-          ...surfacedPackDirs,
-          ...[...openedThisTurn].filter((n) => n.startsWith("pack:")).map((n) => n.slice(5)),
-        ])],
-        signals: { tier: turnRecallTier, wrote: toolUses.some((t) => WRITE_TOOLS.has(t)) },
-        // Provenance (2.5): who contributed this turn, so accreted Log/Journal
-        // lines from a non-owner get stamped "(via <name>)". Resolved from the
-        // live store here because the reviewer applies in an async continuation.
-        source: (() => {
-          try {
-            const sp = require("./people").findByHandle(store.adapter?.type, store.channelId);
-            if (sp) return { name: sp.name, isOwner: !!sp.isOwner };
-          } catch (e) {}
-          return null;
-        })(),
-        announce: (text) => chatContext.run(store, () => send(text)),
+function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
+  const state = currentState();
+  const store = chatContext.getStore() || null;
+  const admitted = opts.runContext || admitRunContext(prompt, cwd, replyToMsgId, opts);
+  const runContext = bindRunInputs(admitted, {
+    userPrompt: prompt,
+    imagePaths: opts.imagePaths !== undefined ? opts.imagePaths : admitted.imagePaths,
+    attachments: opts.attachments !== undefined ? opts.attachments : admitted.attachments,
+    lastInputWasVoice: opts.lastInputWasVoice !== undefined ? opts.lastInputWasVoice : admitted.lastInputWasVoice,
+    voiceStream: opts.voiceStream !== undefined ? opts.voiceStream : admitted.voiceStream,
+  });
+
+  if (!acquireRunLock(state)) {
+    if (shouldStartSideChat(state, runContext, opts, sideChatCoordinator)) {
+      return sideChatCoordinator.respond({
+        runContext,
+        activeRunContext: state.activeRunContext,
+        store,
       });
     }
+    const deferred = deferredRunResult();
+    state.messageQueue.push({ runContext, store, deferred, queuedAt: Date.now() });
+    send(state.isCompacting ? "Compacting context, will pick this up next…" : "Queued.", { replyTo: replyToMsgId }).catch(() => {});
+    return deferred.promise;
+  }
+  return executeAdmittedRun(runContext, state, store, false, true);
+}
 
-    if (state.lastSessionId && state.currentSession) {
-      const title = state.isFirstMessage ? (prompt.length > 60 ? prompt.slice(0, 57) + "..." : prompt) : null;
-      recordSession(state.userId, state.currentSession.name, state.lastSessionId, title);
-      state.isFirstMessage = false;
-    }
+function shouldStartSideChat(state, runContext, opts = {}, coordinator = sideChatCoordinator) {
+  return !!state?.runningProcess
+    && opts.sideChat !== false
+    && runContext?.purpose === "foreground"
+    && coordinator.enabled();
+}
 
-    if (state.messageQueue.length === 0 && state.currentSession && shouldAutoCompact(state)) {
-      try {
-        await compactActiveSession(state.currentSession.dir, { notify: false });
-      } catch (e) {
-        console.warn(`[proactive-compact] failed: ${redactSensitive(e.message)}`);
-      }
-    }
+function runSideChatRequest(request, dependencies = {}) {
+  return createSideChatService(dependencies).run(request);
+}
 
-    await drainQueuedMessages();
-  }));
+function withSideChatMainSession(runContext, sessionId) {
+  if (!sessionId) return runContext;
+  return deepFreeze({
+    ...runContext,
+    sessionId,
+    admittedSessionId: sessionId,
+    previousSessionId: sessionId,
+    resumeSessionId: sessionId,
+    continueSession: false,
+    fresh: false,
+  });
+}
 
-  proc.on("error", (err) => chatContext.run(store, async () => {
-    state.runningProcess = null;
-    state.preparingRun = false;
-    stopTyping();
-    clearTimeout(state.streamInterval);
-    clearTimeout(processTimeout);
-    await send(`Error: ${err.message}`);
-    state.statusMessageId = null;
-  }));
+function createSideChatQueueItem(request, store, lineage, state, deferred) {
+  const queuedContext = lineage.mainSessionId
+    ? withSideChatMainSession(request.originalRunContext, lineage.mainSessionId)
+    : request.originalRunContext;
+  const awaitsActiveMain = !lineage.mainSessionId
+    && lineage.mainRunId
+    && state.activeRunContext?.runId === lineage.mainRunId;
+  return {
+    runContext: awaitsActiveMain ? null : queuedContext,
+    store,
+    deferred,
+    queuedAt: Date.now(),
+    followMainRunId: awaitsActiveMain ? lineage.mainRunId : null,
+    pendingSideChat: awaitsActiveMain ? { originalRunContext: request.originalRunContext } : null,
+  };
 }
 
-async function runClaudeSilent(prompt, cwd, label) {
-  const dynamicPrompt = await promptWithDynamicContext(prompt);
-  return new Promise((resolve) => {
-    const args = ["-p", "--output-format", "text", "--verbose",
-      "--append-system-prompt", buildSystemPrompt(),
-      "--dangerously-skip-permissions", dynamicPrompt];
-    const proc = spawn(CLAUDE_PATH, args, {
-      cwd, env: claudeSubprocessEnv(),
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let output = "";
-    proc.stdout.on("data", (d) => { output += d.toString(); });
-    proc.on("close", async () => {
-      const chunks = splitMessage(`Cron: ${label}\n\n${redactSensitive(output.trim() || "(no output)")}`);
-      for (const c of chunks) await send(c);
-      resolve();
-    });
-    proc.on("error", async (err) => { await send(`Cron "${label}" failed: ${err.message}`); resolve(); });
+function finalizeSideChatQueueItem(item, mainRunContext, result) {
+  if (!item?.pendingSideChat || item.followMainRunId !== mainRunContext?.runId) return false;
+  item.runContext = result?.ok && result.sessionId
+    ? withSideChatMainSession(item.pendingSideChat.originalRunContext, result.sessionId)
+    : item.pendingSideChat.originalRunContext;
+  item.followMainRunId = null;
+  item.pendingSideChat = null;
+  return true;
+}
+
+function enqueueSideChatRequest(request, store = null, lineage = {}) {
+  if (!request?.originalRunContext || request.originalRunContext.purpose !== "foreground") {
+    throw new TypeError("side-chat enqueue requires the original foreground run context");
+  }
+  const state = currentState();
+  if (String(state.userId) !== String(request.canonicalUserId)) {
+    const error = new Error("side-chat action belongs to another user");
+    error.code = "SIDE_CHAT_FORBIDDEN";
+    throw error;
+  }
+  const deferred = deferredRunResult();
+  state.messageQueue.push(createSideChatQueueItem(request, store, lineage, state, deferred));
+  deferred.promise.catch((error) => console.error("side-chat queued run failed:", redactSensitive(error.message)));
+  if (!state.runningProcess && !state.preparingRun) drainQueuedMessages(state);
+  return { queued: true, position: state.messageQueue.length || 1 };
+}
+
+function runAgentCapture(prompt, cwd, opts = {}) {
+  const state = currentState();
+  const store = chatContext.getStore() || null;
+  const admitted = opts.runContext || admitRunContext(prompt, cwd, null, { ...opts, requiredDelivery: false });
+  const runContext = bindRunInputs(admitted, {
+    userPrompt: prompt,
+    imagePaths: opts.imagePaths !== undefined ? opts.imagePaths : admitted.imagePaths,
+    attachments: opts.attachments !== undefined ? opts.attachments : admitted.attachments,
+    lastInputWasVoice: opts.lastInputWasVoice !== undefined ? opts.lastInputWasVoice : admitted.lastInputWasVoice,
+    voiceStream: opts.voiceStream !== undefined ? opts.voiceStream : admitted.voiceStream,
   });
+  return executeAdmittedRun(runContext, state, store, true, false, { persistCapture: opts.persist !== false });
+}
+
+function runAgentSilent(prompt, cwd, label, opts = {}) {
+  return runAgent(prompt, cwd, null, { ...opts, label, purpose: opts.purpose || "silent" });
 }
 
 module.exports = {
-  runClaude,
-  runClaudeCapture,
-  runClaudeSilent,
+  admitRunContext,
+  capturedTranscriptMetadata,
+  decorateForegroundInvocation,
+  createRunnerService,
+  createSideChatService,
+  createSideChatQueueItem,
+  finalizeSideChatQueueItem,
+  executeProviderInvocation,
+  invocationContextForRun,
+  runAgent,
+  runAgentCapture,
+  runAgentSilent,
+  shouldStartSideChat,
+  runSideChatRequest,
+  enqueueSideChatRequest,
   compactActiveSession,
-  buildSystemPrompt,
+  createCompactionService,
+  deriveCompactionRunContext,
   getActiveSessionId,
-  getActiveBinary,
-  getActiveSessionKey,
   shouldAutoCompact,
   effectiveCompactThreshold,
   usageParts,
@@ -1770,7 +1897,4 @@ module.exports = {
   archiveCompactionBrief,
   collectRepoStateFacts,
   collectRecentTurns,
-  formatProgress,
-  preflightClaudeAuthMessage,
-  claudeEmptyFailureMessage,
 };