@inetafrica/open-claudia 2.14.8 → 3.0.0

package/test-provider-run-lifecycle.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { EventEmitter } = require("events");
+const { PassThrough } = require("stream");
+const { createClaudeProvider } = require("./core/providers/claude");
+const { createClaudeParserState } = require("./core/providers/claude-events");
+const { executeProviderInvocation } = require("./core/runner");
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
+
+function nextTurn() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+function fakeChild() {
+  const child = new EventEmitter();
+  child.pid = 4242;
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+  child.stdin = new PassThrough();
+  child.exitCode = null;
+  child.signalCode = null;
+  child.kill = (signal = "SIGTERM") => {
+    child.signalCode = signal;
+    setImmediate(() => child.emit("close", null, signal));
+    return true;
+  };
+  return child;
+}
+
+function provider() {
+  return createClaudeProvider({
+    hookTransport: false,
+    resolveExecutable: () => "/fixture/claude",
+    buildEnv: () => ({ PATH: "/fixture" }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+  });
+}
+
+function invocation() {
+  return {
+    binary: "/fixture/claude",
+    args: ["fixture"],
+    env: { PATH: "/fixture" },
+    stdin: null,
+    parserState: createClaudeParserState(),
+  };
+}
+
+function context() {
+  return Object.freeze({
+    runId: "lifecycle-run",
+    canonicalUserId: "fixture-user",
+    project: Object.freeze({ name: "fixture-project", dir: "/fixture/project" }),
+    provider: "claude",
+    providerSettings: Object.freeze({ model: "fixture-model" }),
+    sessionId: null,
+    purpose: "foreground",
+    channelId: "fixture-channel",
+    origin: Object.freeze({ transport: "telegram", channelId: "fixture-channel" }),
+  });
+}
+
+async function assertPending(promise, message) {
+  const marker = Symbol("pending");
+  const observed = await Promise.race([promise, nextTurn().then(() => marker)]);
+  assert.strictEqual(observed, marker, message);
+}
+
+async function main() {
+  const child = fakeChild();
+  const cleanupGate = deferred();
+  const transcriptGate = deferred();
+  const usageGate = deferred();
+  const sessionGate = deferred();
+  const deliveryGate = deferred();
+  const calls = [];
+
+  const run = executeProviderInvocation({
+    runContext: context(),
+    provider: provider(),
+    invocation: invocation(),
+    cwd: "/fixture/project",
+    spawnProcess: () => child,
+    timeoutMs: 10000,
+    cleanup: async () => { calls.push("cleanup"); await cleanupGate.promise; },
+    persistTranscript: async () => { calls.push("transcript"); await transcriptGate.promise; },
+    persistUsage: async () => { calls.push("usage"); await usageGate.promise; },
+    persistSession: async () => { calls.push("session"); await sessionGate.promise; },
+    deliver: async () => { calls.push("delivery"); await deliveryGate.promise; return { ok: true }; },
+  });
+
+  child.stdout.write(`${JSON.stringify({ type: "system", subtype: "init", session_id: "terminal-session" })}\n`);
+  child.stdout.write(`${JSON.stringify({ type: "assistant", message: { content: [{ type: "text", text: "terminal text" }] } })}\n`);
+  child.stdout.write(`${JSON.stringify({ type: "result", subtype: "success", session_id: "terminal-session", result: "terminal text", usage: { input_tokens: 1, output_tokens: 1 } })}\n`);
+  await nextTurn();
+  await assertPending(run, "terminal provider event must not resolve the run");
+
+  child.stdout.end();
+  await nextTurn();
+  await assertPending(run, "stdout EOF must not resolve before child close");
+
+  child.exitCode = 0;
+  child.emit("close", 0, null);
+  await nextTurn();
+  assert.deepStrictEqual(calls, ["cleanup"]);
+  await assertPending(run, "cleanup is part of terminal settlement");
+
+  cleanupGate.resolve();
+  await nextTurn();
+  assert.deepStrictEqual(calls, ["cleanup", "transcript"]);
+  await assertPending(run, "transcript persistence is required");
+
+  transcriptGate.resolve();
+  await nextTurn();
+  assert.deepStrictEqual(calls, ["cleanup", "transcript", "usage"]);
+  await assertPending(run, "usage persistence is required");
+
+  usageGate.resolve();
+  await nextTurn();
+  assert.deepStrictEqual(calls, ["cleanup", "transcript", "usage", "session"]);
+  await assertPending(run, "session persistence is required");
+
+  sessionGate.resolve();
+  await nextTurn();
+  assert.deepStrictEqual(calls, ["cleanup", "transcript", "usage", "session", "delivery"]);
+  await assertPending(run, "required delivery is part of terminal settlement");
+
+  deliveryGate.resolve();
+  const result = await run;
+  assert.strictEqual(result.ok, true);
+  assert.strictEqual(result.status, "succeeded");
+  assert.strictEqual(result.text, "terminal text");
+  assert.strictEqual(result.sessionId, "terminal-session");
+  assert.strictEqual(result.exitCode, 0);
+  assert.strictEqual(result.signal, null);
+  assert.strictEqual(result.terminalSeen, true);
+  assert.strictEqual(result.stdoutEnded, true);
+  assert.deepStrictEqual(calls, ["cleanup", "transcript", "usage", "session", "delivery"]);
+
+  async function completedRun({
+    exitCode = 0,
+    signal = null,
+    terminal = true,
+    duplicate = false,
+    persistenceFailure = null,
+    deliveryFailure = false,
+  } = {}) {
+    const proc = fakeChild();
+    let transcriptCalls = 0;
+    let deliveryCalls = 0;
+    const promise = executeProviderInvocation({
+      runContext: context(),
+      provider: provider(),
+      invocation: invocation(),
+      cwd: "/fixture/project",
+      spawnProcess: () => proc,
+      timeoutMs: 10000,
+      cleanup: async () => {},
+      persistTranscript: async () => {
+        transcriptCalls += 1;
+        if (persistenceFailure === "transcript") throw new Error("transcript failed");
+      },
+      persistUsage: async () => {
+        if (persistenceFailure === "usage") throw new Error("usage failed");
+      },
+      persistSession: async () => {
+        if (persistenceFailure === "session") throw new Error("session failed");
+      },
+      deliver: async () => {
+        deliveryCalls += 1;
+        if (deliveryFailure) throw new Error("delivery failed");
+        return { ok: true };
+      },
+    });
+    proc.stdout.write(`${JSON.stringify({ type: "system", subtype: "init", session_id: "fixture-session" })}\n`);
+    proc.stdout.write(`${JSON.stringify({ type: "assistant", message: { content: [{ type: "text", text: "fixture" }] } })}\n`);
+    if (terminal) {
+      const event = `${JSON.stringify({ type: "result", subtype: "success", session_id: "fixture-session", result: "fixture" })}\n`;
+      proc.stdout.write(event);
+      if (duplicate) proc.stdout.write(event);
+    }
+    proc.stdout.end();
+    proc.exitCode = exitCode;
+    proc.signalCode = signal;
+    proc.emit("close", exitCode, signal);
+    const settled = await promise;
+    return { settled, transcriptCalls, deliveryCalls };
+  }
+
+  const duplicate = await completedRun({ duplicate: true });
+  assert.strictEqual(duplicate.settled.ok, true);
+  assert.strictEqual(duplicate.transcriptCalls, 1, "duplicate terminal events persist once");
+  assert.strictEqual(duplicate.deliveryCalls, 1, "duplicate terminal events deliver once");
+
+  const nonZero = await completedRun({ exitCode: 23 });
+  assert.strictEqual(nonZero.settled.ok, false);
+  assert.strictEqual(nonZero.settled.exitCode, 23);
+  assert.match(nonZero.settled.error.message, /code 23/i);
+
+  const signalled = await completedRun({ exitCode: null, signal: "SIGTERM" });
+  assert.strictEqual(signalled.settled.ok, false);
+  assert.strictEqual(signalled.settled.signal, "SIGTERM");
+
+  const missingTerminal = await completedRun({ terminal: false });
+  assert.strictEqual(missingTerminal.settled.ok, false);
+  assert.match(missingTerminal.settled.error.message, /terminal/i);
+
+  {
+    const proc = fakeChild();
+    const malformedRun = executeProviderInvocation({
+      runContext: context(),
+      provider: provider(),
+      invocation: invocation(),
+      cwd: "/fixture/project",
+      spawnProcess: () => proc,
+      cleanup: async () => {},
+    });
+    proc.stdout.write("{not-json}\n");
+    proc.stdout.write(`${JSON.stringify({ type: "result", subtype: "success", session_id: "fixture-session", result: "fixture" })}\n`);
+    proc.stdout.end();
+    proc.emit("close", 0, null);
+    const malformed = await malformedRun;
+    assert.strictEqual(malformed.ok, false);
+    assert.match(malformed.error.message, /Malformed provider JSONL record/);
+  }
+
+  {
+    // stdin EPIPE (child exits before the prompt pipe flushes) must neither
+    // crash the process as an uncaughtException nor fail a run whose child
+    // completed successfully — the exit code decides.
+    const proc = fakeChild();
+    const stdinRun = executeProviderInvocation({
+      runContext: context(),
+      provider: provider(),
+      invocation: { ...invocation(), stdin: "prompt payload" },
+      cwd: "/fixture/project",
+      spawnProcess: () => proc,
+      cleanup: async () => {},
+    });
+    proc.stdin.emit("error", Object.assign(new Error("write EPIPE"), { code: "EPIPE" }));
+    proc.stdout.write(`${JSON.stringify({ type: "system", subtype: "init", session_id: "fixture-session" })}\n`);
+    proc.stdout.write(`${JSON.stringify({ type: "result", subtype: "success", session_id: "fixture-session", result: "fixture" })}\n`);
+    proc.stdout.end();
+    proc.emit("close", 0, null);
+    const stdinResult = await stdinRun;
+    assert.strictEqual(stdinResult.ok, true, "stdin EPIPE must not fail a run the child completed successfully");
+    assert.strictEqual(stdinResult.status, "succeeded");
+    assert.match(stdinResult.stderr, /\[stdin\] write EPIPE/, "stdin failure must surface as a diagnostic in stderr");
+  }
+
+  for (const stage of ["transcript", "usage", "session"]) {
+    const failed = await completedRun({ persistenceFailure: stage });
+    assert.strictEqual(failed.settled.ok, false, `${stage} persistence failure must fail the RunResult`);
+    assert.strictEqual(failed.settled.persistence[stage].ok, false);
+  }
+
+  const deliveryFailed = await completedRun({ deliveryFailure: true });
+  assert.strictEqual(deliveryFailed.settled.ok, false);
+  assert.strictEqual(deliveryFailed.settled.delivery.ok, false);
+
+  const spawnFailure = await executeProviderInvocation({
+    runContext: context(),
+    provider: provider(),
+    invocation: invocation(),
+    cwd: "/fixture/project",
+    spawnProcess: () => { throw new Error("spawn fixture failed"); },
+    cleanup: async () => {},
+  });
+  assert.strictEqual(spawnFailure.ok, false);
+  assert.match(spawnFailure.error.message, /spawn fixture failed/);
+
+  const timeoutChild = fakeChild();
+  const timeoutRun = executeProviderInvocation({
+    runContext: context(),
+    provider: provider(),
+    invocation: invocation(),
+    cwd: "/fixture/project",
+    spawnProcess: () => timeoutChild,
+    timeoutMs: 20,
+    killTree: (_pid, signal) => timeoutChild.kill(signal),
+    killGraceMs: 5,
+    cleanup: async () => {},
+  });
+  const timedOut = await timeoutRun;
+  assert.strictEqual(timedOut.ok, false);
+  assert.strictEqual(timedOut.timedOut, true);
+
+  const processTreeRoot = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-run-tree-"));
+  const descendantCapture = path.join(processTreeRoot, "descendant.json");
+  let descendantPid = null;
+  try {
+    const realTreeRun = executeProviderInvocation({
+      runContext: context(),
+      provider: provider(),
+      invocation: {
+        binary: path.join(__dirname, "test-fixtures", "fake-agent-cli.js"),
+        args: ["fixture"],
+        env: {
+          PATH: process.env.PATH || "",
+          HOME: processTreeRoot,
+          FAKE_AGENT_KIND: "claude",
+          FAKE_AGENT_SCENARIO: "forced-termination",
+          FAKE_AGENT_DESCENDANT_CAPTURE: descendantCapture,
+          FAKE_AGENT_DESCENDANT_DETACHED: "1",
+          FAKE_AGENT_DESCENDANT_IGNORE_SIGTERM: "1",
+          FAKE_AGENT_LEAVE_DESCENDANT: "1",
+        },
+        stdin: null,
+        parserState: createClaudeParserState(),
+      },
+      cwd: processTreeRoot,
+      timeoutMs: 120,
+      killGraceMs: 250,
+      cleanup: async () => {},
+    });
+    const treeResult = await realTreeRun;
+    assert.strictEqual(treeResult.timedOut, true);
+    descendantPid = JSON.parse(fs.readFileSync(descendantCapture, "utf8")).pid;
+    assert.throws(
+      () => process.kill(descendantPid, 0),
+      (error) => error.code === "ESRCH",
+      "timeout result must not settle while a detached TERM-resistant descendant survives",
+    );
+  } finally {
+    if (descendantPid) {
+      try { process.kill(descendantPid, "SIGKILL"); } catch (_) {}
+    }
+    fs.rmSync(processTreeRoot, { recursive: true, force: true });
+  }
+
+  console.log("provider run lifecycle OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/test-provider-runner.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { createClaudeProvider } = require("./core/providers/claude");
+const { createCodexProvider } = require("./core/providers/codex");
+const { captureRunContext } = require("./core/run-context");
+const runner = require("./core/runner");
+const { capturedTranscriptMetadata, createRunnerService } = runner;
+
+const fixture = path.join(__dirname, "test-fixtures", "fake-agent-cli.js");
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-provider-runner-"));
+const projectA = path.join(root, "project-a");
+const projectB = path.join(root, "project-b");
+fs.mkdirSync(projectA);
+fs.mkdirSync(projectB);
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((res) => { resolve = res; });
+  return { promise, resolve };
+}
+
+function providerEnv(kind, capturePath, extra = {}) {
+  return {
+    HOME: root,
+    PATH: process.env.PATH || path.dirname(process.execPath),
+    FAKE_AGENT_KIND: kind,
+    FAKE_AGENT_CAPTURE: capturePath,
+    FAKE_AGENT_TOOL: "1",
+    FAKE_AGENT_CHUNK_MODE: "split",
+    FAKE_AGENT_FINAL_NEWLINE: "0",
+    ...extra,
+  };
+}
+
+function makeProviders(captures, controls = {}) {
+  return {
+    claude: createClaudeProvider({
+      hookTransport: false,
+      resolveExecutable: () => fixture,
+      defaultModel: "claude-fixture-model",
+      buildEnv: () => providerEnv("claude", captures.claude, controls.claude),
+      getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    }),
+    codex: createCodexProvider({
+      hookTransport: false,
+      resolveExecutable: () => fixture,
+      defaultModel: "codex-fixture-model",
+      buildEnv: () => providerEnv("codex", captures.codex, controls.codex),
+      getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    }),
+  };
+}
+
+function state() {
+  return {
+    userId: "fixture-user",
+    currentSession: { name: "project-a", dir: projectA },
+    settings: {
+      backend: "claude",
+      model: "claude-fixture-model",
+      effort: null,
+      budget: null,
+      permissionMode: "plan",
+      worktree: false,
+    },
+    activeSessions: { "project-a": {} },
+    providerSettings: {
+      claude: { model: "claude-fixture-model", effort: null, budget: null, permissionMode: "plan", worktree: false },
+      codex: { model: "codex-fixture-model", effort: null, budget: null, permissionMode: "plan", worktree: false },
+    },
+    lastInputWasVoice: false,
+  };
+}
+
+function simpleBundle(prompt, { runContext, provider }) {
+  return {
+    coreInstructions: "RUNNER CORE SENTINEL",
+    dynamicContext: `RUNNER DYNAMIC ${runContext.project.name} ${provider.id}`,
+    userPrompt: prompt,
+    transcriptPaths: { transcriptsDir: path.join(root, "transcripts") },
+    recallMetadata: { status: "included", omitted: false, packDirs: [] },
+  };
+}
+
+async function main() {
+  assert.ok(fs.existsSync(fixture));
+  assert.strictEqual(Object.prototype.hasOwnProperty.call(runner, "runClaude"), false, "deprecated foreground alias must be removed");
+  assert.strictEqual(Object.prototype.hasOwnProperty.call(runner, "runClaudeCapture"), false, "deprecated capture alias must be removed");
+  assert.strictEqual(Object.prototype.hasOwnProperty.call(runner, "runClaudeSilent"), false, "deprecated silent alias must be removed");
+  const mutable = state();
+  const captured = captureRunContext({
+    state: mutable,
+    prompt: "capture",
+    cwd: projectA,
+    replyToMsgId: "message-1",
+    opts: {
+      purpose: "foreground",
+      imagePaths: ["/fixture/image.png"],
+      origin: { transport: "telegram", channelId: "fixture-channel" },
+    },
+    channelId: "fixture-channel",
+    canonicalUserId: "fixture-user",
+    runId: "captured-run",
+  });
+  assert.strictEqual(captured.runId, "captured-run");
+  assert.strictEqual(captured.provider, "claude");
+  assert.strictEqual(captured.project.dir, projectA);
+  assert.strictEqual(captured.purpose, "foreground");
+  assert.deepStrictEqual(captured.imagePaths, ["/fixture/image.png"]);
+  assert.ok(Object.isFrozen(captured));
+  assert.ok(Object.isFrozen(captured.project));
+  assert.ok(Object.isFrozen(captured.providerSettings));
+  assert.ok(Object.isFrozen(captured.origin));
+  assert.ok(Object.isFrozen(captured.imagePaths));
+  assert.throws(() => { captured.providerSettings.model = "changed"; }, TypeError);
+  assert.deepStrictEqual(capturedTranscriptMetadata(captured), {
+    provider: "claude",
+    project: "project-a",
+    projectPath: projectA,
+    runId: "captured-run",
+    purpose: "foreground",
+  });
+
+  const captures = {
+    claude: path.join(root, "claude-capture.json"),
+    codex: path.join(root, "codex-capture.json"),
+  };
+  const providers = makeProviders(captures);
+  const persisted = [];
+  const delivered = [];
+  const service = createRunnerService({
+    getState: () => mutable,
+    getStore: () => ({ channelId: "fixture-channel", transport: "telegram" }),
+    resolveProvider: (id) => providers[id],
+    buildTurnPrompt: simpleBundle,
+    persistTranscript: async (result, runContext) => persisted.push(["transcript", runContext.provider, runContext.project.name, result.sessionId]),
+    persistUsage: async (result, runContext) => persisted.push(["usage", runContext.provider, result.usageScope]),
+    persistSession: async (result, runContext) => persisted.push(["session", runContext.provider, runContext.project.name, result.sessionId]),
+    deliver: async (result, runContext) => {
+      delivered.push([runContext.provider, runContext.project.name, result.text]);
+      return { ok: true };
+    },
+    cleanup: async () => {},
+  });
+
+  const claude = await service.runAgentCapture("CLAUDE USER SENTINEL", projectA, { fresh: true });
+  assert.strictEqual(claude.ok, true);
+  assert.strictEqual(claude.provider, "claude");
+  assert.strictEqual(claude.text, "fixture says café 👋");
+  assert.strictEqual(claude.sessionId, "claude-fresh-session");
+  assert.ok(claude.tools.some((event) => event.type === "tool_start" && event.name === "Read"));
+  const claudeCapture = JSON.parse(fs.readFileSync(captures.claude, "utf8"));
+  assert.ok(claudeCapture.argv.includes("--append-system-prompt"));
+  assert.ok(claudeCapture.argv.includes("RUNNER CORE SENTINEL"));
+  assert.ok(claudeCapture.argv.at(-1).includes("RUNNER DYNAMIC project-a claude"));
+  assert.ok(claudeCapture.argv.at(-1).includes("CLAUDE USER SENTINEL"));
+
+  mutable.settings = { ...mutable.settings, backend: "codex", model: "codex-fixture-model" };
+  mutable.activeSessions["project-a"].codex = "codex-resume-thread";
+  const codex = await service.runAgentCapture("CODEX USER SENTINEL", projectA, {
+    resumeSessionId: "codex-resume-thread",
+  });
+  assert.strictEqual(codex.ok, true);
+  assert.strictEqual(codex.provider, "codex");
+  assert.strictEqual(codex.sessionId, "codex-resume-thread");
+  assert.strictEqual(codex.text, "fixture says café 👋");
+  assert.ok(codex.tools.some((event) => event.type === "tool_start" && event.name === "Shell"));
+  const codexCapture = JSON.parse(fs.readFileSync(captures.codex, "utf8"));
+  assert.deepStrictEqual(codexCapture.argv.slice(0, 2), ["exec", "resume"]);
+  assert.ok(codexCapture.argv.some((arg) => arg.includes("developer_instructions=")));
+  assert.ok(codexCapture.argv.at(-1).includes("RUNNER DYNAMIC project-a codex"));
+  assert.ok(codexCapture.argv.at(-1).includes("CODEX USER SENTINEL"));
+
+  const foreground = await service.runAgent("DELIVERY SENTINEL", projectA, "message-2", { fresh: true });
+  assert.strictEqual(foreground.ok, true);
+  assert.deepStrictEqual(delivered.at(-1), ["codex", "project-a", "fixture says café 👋"]);
+  assert.ok(persisted.some((entry) => entry[0] === "transcript" && entry[1] === "claude"));
+  assert.ok(persisted.some((entry) => entry[0] === "transcript" && entry[1] === "codex"));
+
+  // Admission must happen synchronously. Mutating every live routing field
+  // while prompt construction awaits cannot alter the admitted provider,
+  // project, settings, session, cwd, or parser.
+  const gate = deferred();
+  const raceCapture = path.join(root, "race-capture.json");
+  const raceProviders = makeProviders({ claude: raceCapture, codex: captures.codex });
+  mutable.currentSession = { name: "project-a", dir: projectA };
+  mutable.settings = { ...mutable.settings, backend: "claude", model: "claude-fixture-model", effort: "high" };
+  mutable.providerSettings.claude = { ...mutable.providerSettings.claude, model: "claude-fixture-model", effort: "high" };
+  mutable.activeSessions["project-a"].claude = "claude-race-session";
+  const raceService = createRunnerService({
+    getState: () => mutable,
+    getStore: () => ({ channelId: "fixture-channel", transport: "telegram" }),
+    resolveProvider: (id) => raceProviders[id],
+    async buildTurnPrompt(prompt, opts) {
+      await gate.promise;
+      return simpleBundle(prompt, opts);
+    },
+    persistTranscript: async () => {},
+    persistUsage: async () => {},
+    persistSession: async () => {},
+    cleanup: async () => {},
+  });
+  const racing = raceService.runAgentCapture("RACE SENTINEL", projectA);
+  mutable.currentSession = { name: "project-b", dir: projectB };
+  mutable.settings = { ...mutable.settings, backend: "codex", model: "codex-fixture-model", effort: "low" };
+  mutable.providerSettings.codex = { ...mutable.providerSettings.codex, model: "codex-fixture-model", effort: "low" };
+  mutable.activeSessions["project-a"].claude = "changed-claude-session";
+  mutable.activeSessions["project-a"].codex = "changed-codex-thread";
+  gate.resolve();
+  const race = await racing;
+  assert.strictEqual(race.ok, true);
+  assert.strictEqual(race.provider, "claude");
+  assert.strictEqual(race.project.name, "project-a");
+  assert.strictEqual(race.admittedSessionId, "claude-race-session");
+  const raceArgv = JSON.parse(fs.readFileSync(raceCapture, "utf8")).argv;
+  assert.ok(raceArgv.includes("claude-fixture-model"));
+  assert.ok(raceArgv.includes("claude-race-session"));
+  assert.ok(!raceArgv.includes("codex-fixture-model"));
+  assert.ok(!raceArgv.includes("changed-claude-session"));
+
+  let forbiddenSpawns = 0;
+  let failedDeliveries = 0;
+  mutable.currentSession = { name: "project-a", dir: projectA };
+  mutable.settings = { ...mutable.settings, backend: "claude", model: "claude-fixture-model" };
+  const failClosed = createRunnerService({
+    getState: () => mutable,
+    getStore: () => ({ channelId: "fixture-channel", transport: "telegram" }),
+    resolveProvider: (id) => providers[id],
+    async buildTurnPrompt() { throw new Error("mandatory prompt fixture failed"); },
+    spawnProcess() { forbiddenSpawns += 1; throw new Error("must not spawn"); },
+    persistTranscript: async () => {},
+    persistUsage: async () => {},
+    persistSession: async () => {},
+    deliver: async (result) => { failedDeliveries += 1; return { ok: !result.ok }; },
+  });
+  const promptFailure = await failClosed.runAgent("RAW PROMPT MUST NOT SPAWN", projectA, "message-fail");
+  assert.strictEqual(promptFailure.ok, false);
+  assert.match(promptFailure.error.message, /mandatory prompt fixture failed/);
+  assert.strictEqual(forbiddenSpawns, 0, "mandatory prompt failure must abort before spawn");
+  assert.strictEqual(failedDeliveries, 1, "foreground preflight failure still settles required delivery");
+
+  const authCapture = path.join(root, "auth-capture.json");
+  const authProviders = makeProviders(
+    { claude: authCapture, codex: captures.codex },
+    { claude: { FAKE_AGENT_SCENARIO: "auth-failure" } },
+  );
+  const authService = createRunnerService({
+    getState: () => mutable,
+    getStore: () => ({ channelId: "fixture-channel", transport: "telegram" }),
+    resolveProvider: (id) => authProviders[id],
+    buildTurnPrompt: simpleBundle,
+    cleanup: async () => {},
+  });
+  const authFailure = await authService.runAgentCapture("AUTH SENTINEL", projectA, { fresh: true });
+  assert.strictEqual(authFailure.ok, false);
+  assert.strictEqual(authFailure.error.code, "PROVIDER_UNAUTHENTICATED");
+  assert.match(authFailure.diagnostic, /Authentication failed/i);
+
+  console.log("provider runner OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => fs.rmSync(root, { recursive: true, force: true }));