@inetafrica/open-claudia 2.15.0 → 3.0.0

package/test-provider-side-chat.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const crypto = require("crypto");
+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 {
+  ACTIVE_TASK_DESCRIPTION_MAX,
+  SideChatCoordinator,
+  createSideChatPromptBuilder,
+  createSideChatRequest,
+  readRuntimeMode,
+} = require("./core/side-chat");
+const {
+  createSideChatQueueItem,
+  createSideChatService,
+  finalizeSideChatQueueItem,
+  shouldStartSideChat,
+} = require("./core/runner");
+
+const fixture = path.join(__dirname, "test-fixtures", "fake-agent-cli.js");
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-side-chat-"));
+const project = path.join(root, "project-a");
+fs.mkdirSync(project);
+
+function providerEnv(kind, capturePath) {
+  const env = {
+    HOME: root,
+    PATH: process.env.PATH || path.dirname(process.execPath),
+    FAKE_AGENT_KIND: kind,
+    FAKE_AGENT_CAPTURE: capturePath,
+    FAKE_AGENT_TEXT: `${kind} isolated side response`,
+    FAKE_AGENT_CHUNK_MODE: "split",
+    FAKE_AGENT_FINAL_NEWLINE: "0",
+  };
+  if (kind === "claude") env.ANTHROPIC_API_KEY = "fixture-claude-presence-only";
+  else env.OPENAI_API_KEY = "fixture-openai-presence-only";
+  return env;
+}
+
+function makeProvider(kind, capturePath) {
+  const common = {
+    hookTransport: false,
+    resolveExecutable: () => fixture,
+    defaultModel: `${kind}-fixture-model`,
+    buildEnv: () => providerEnv(kind, capturePath),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+  };
+  return kind === "claude" ? createClaudeProvider(common) : createCodexProvider(common);
+}
+
+function mainState(provider) {
+  return {
+    userId: "fixture-user",
+    currentSession: { name: "project-a", dir: project },
+    settings: {
+      backend: provider,
+      model: `${provider}-fixture-model`,
+      effort: null,
+      budget: null,
+      permissionMode: null,
+      worktree: false,
+    },
+    activeSessions: { "project-a": { claude: "claude-main-session", codex: "codex-main-thread" } },
+    providerSettings: {
+      claude: { model: "claude-fixture-model", permissionMode: "plan" },
+      codex: { model: "codex-fixture-model", permissionMode: "plan" },
+    },
+    sessionUsage: { turns: 7, inputTokens: 123, outputTokens: 45 },
+    lastCompactedAt: 999,
+    messageQueue: [],
+    isCompacting: false,
+  };
+}
+
+function captureMainRun(state, prompt, runId) {
+  return captureRunContext({
+    state,
+    prompt,
+    cwd: project,
+    replyToMsgId: `message-${runId}`,
+    opts: { purpose: "foreground" },
+    channelId: "fixture-channel",
+    canonicalUserId: state.userId,
+    runId,
+    store: {
+      adapter: { id: "telegram-fixture", type: "telegram" },
+      channelId: "fixture-channel",
+      canonicalUserId: state.userId,
+      userId: state.userId,
+    },
+  });
+}
+
+async function providerProbe(kind) {
+  const capturePath = path.join(root, `${kind}-capture.json`);
+  const provider = makeProvider(kind, capturePath);
+  const state = mainState(kind);
+  const before = structuredClone(state);
+  const incoming = captureMainRun(state, `${kind} side question`, `${kind}-incoming`);
+  const active = captureMainRun(state, `heavy ${kind} task sk-ant-side-secret ${"x".repeat(1000)}`, `${kind}-main`);
+  const request = createSideChatRequest({
+    runContext: incoming,
+    activeRunContext: active,
+    store: { marker: `${kind}-origin-store` },
+    token: `${kind}-token`,
+  });
+
+  assert.ok(Object.isFrozen(request));
+  assert.ok(Object.isFrozen(request.runContext));
+  assert.strictEqual(request.runContext.provider, kind);
+  assert.strictEqual(request.runContext.project.name, "project-a");
+  assert.strictEqual(request.runContext.origin.transport, "telegram");
+  assert.strictEqual(request.runContext.sessionId, null);
+  assert.strictEqual(request.runContext.resumeSessionId, null);
+  assert.strictEqual(request.runContext.continueSession, false);
+  assert.strictEqual(request.runContext.fresh, true);
+  assert.strictEqual(request.runContext.purpose, "side-chat");
+  assert.ok(request.activeTaskDescription.length <= ACTIVE_TASK_DESCRIPTION_MAX);
+  assert.ok(!request.activeTaskDescription.includes("sk-ant-side-secret"));
+  assert.match(request.activeTaskDescription, /REDACTED/);
+
+  // Switching every mutable main selector after admission must not retarget the
+  // side response or make it attach to either native main session.
+  state.settings.backend = kind === "claude" ? "codex" : "claude";
+  state.currentSession = { name: "project-b", dir: path.join(root, "project-b") };
+  state.activeSessions["project-a"].claude = "changed-claude-session";
+  state.activeSessions["project-a"].codex = "changed-codex-thread";
+
+  const forbiddenEffects = [];
+  const service = createSideChatService({
+    resolveProvider: (id) => {
+      assert.strictEqual(id, kind);
+      return provider;
+    },
+    buildCoreInstructions: () => "SIDE CORE SENTINEL",
+    persistTranscript: () => forbiddenEffects.push("transcript"),
+    persistUsage: () => forbiddenEffects.push("usage"),
+    persistSession: () => forbiddenEffects.push("session"),
+    deliver: () => forbiddenEffects.push("delivery"),
+    memoryReview: () => forbiddenEffects.push("review"),
+    compact: () => forbiddenEffects.push("compact"),
+  });
+  const result = await service.run(request);
+  assert.strictEqual(result.ok, true);
+  assert.strictEqual(result.provider, kind);
+  assert.strictEqual(result.purpose, "side-chat");
+  assert.strictEqual(result.text, `${kind} isolated side response`);
+  assert.deepStrictEqual(forbiddenEffects, []);
+
+  const capture = JSON.parse(fs.readFileSync(capturePath, "utf8"));
+  const argvText = capture.argv.join("\n");
+  assert.ok(!argvText.includes("claude-main-session"));
+  assert.ok(!argvText.includes("codex-main-thread"));
+  assert.ok(!argvText.includes("changed-claude-session"));
+  assert.ok(!argvText.includes("changed-codex-thread"));
+  const expectedBundle = await createSideChatPromptBuilder(() => "SIDE CORE SENTINEL")(
+    request.originalMessage,
+    { runContext: request.runContext, provider },
+  );
+  const protectedPrompt = `${expectedBundle.dynamicContext}\n\n${expectedBundle.userPrompt}`;
+  assert.match(protectedPrompt, /side question/);
+  assert.match(protectedPrompt, /heavy .* task/);
+  assert.ok(protectedPrompt.length < 12000, "active-task context stays bounded");
+  assert.ok(!argvText.includes("side question"), "private side question is absent from argv");
+  assert.deepStrictEqual(capture.stdin, {
+    present: true,
+    bytes: Buffer.byteLength(protectedPrompt),
+    sha256: crypto.createHash("sha256").update(protectedPrompt).digest("hex"),
+  }, "side-chat fixture captures only protected prompt size/hash");
+  if (kind === "claude") {
+    assert.strictEqual(capture.envPresence.ANTHROPIC_API_KEY, true);
+    assert.strictEqual(capture.envPresence.OPENAI_API_KEY, false);
+    assert.ok(capture.argv.includes("--no-session-persistence"));
+    assert.ok(!capture.argv.includes("--resume"));
+    assert.ok(!capture.argv.includes("--continue"));
+    assert.deepStrictEqual(capture.argv.slice(capture.argv.indexOf("--permission-mode"), capture.argv.indexOf("--permission-mode") + 2), ["--permission-mode", "plan"]);
+  } else {
+    assert.strictEqual(capture.envPresence.OPENAI_API_KEY, true);
+    assert.strictEqual(capture.envPresence.ANTHROPIC_API_KEY, false);
+    assert.strictEqual(capture.envPresence.CLAUDE_CODE_OAUTH_TOKEN, false);
+    assert.strictEqual(capture.argv[0], "exec");
+    assert.notStrictEqual(capture.argv[1], "resume");
+    assert.ok(capture.argv.includes("--ephemeral"));
+    assert.deepStrictEqual(capture.argv.slice(capture.argv.indexOf("--sandbox"), capture.argv.indexOf("--sandbox") + 2), ["--sandbox", "read-only"]);
+  }
+
+  const expected = structuredClone(before);
+  expected.settings.backend = state.settings.backend;
+  expected.currentSession = state.currentSession;
+  expected.activeSessions = state.activeSessions;
+  assert.deepStrictEqual(state, expected, "side execution must not mutate main state");
+}
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((res) => { resolve = res; });
+  return { promise, resolve };
+}
+
+async function coordinatorProbe() {
+  const state = mainState("claude");
+  const active = captureMainRun(state, "long main operation", "active-main");
+  const first = captureMainRun(state, "what is its status?", "side-one");
+  const second = captureMainRun(state, "also include tests", "side-two");
+  const gate = deferred();
+  const runs = [];
+  const deliveries = [];
+  const enqueued = [];
+  const tokens = ["token-one", "token-two"];
+  let clock = 1000;
+  const coordinator = new SideChatCoordinator({
+    tokenFactory: () => tokens.shift(),
+    now: () => clock,
+    runSideChat: async (request) => {
+      runs.push(request);
+      await gate.promise;
+      return { ok: true, text: "fresh side answer", diagnostic: null };
+    },
+    deliver: async (payload) => { deliveries.push(payload); return { ok: true }; },
+    enqueueMain: (request, store, lineage) => {
+      enqueued.push({ request, store, lineage });
+      return { queued: true, position: 1 };
+    },
+  });
+
+  const firstPending = coordinator.respond({ runContext: first, activeRunContext: active, store: { id: "origin-one" } });
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.strictEqual(runs.length, 1);
+  assert.strictEqual(coordinator.isActive("fixture-user"), true);
+
+  const busy = await coordinator.respond({ runContext: second, activeRunContext: active, store: { id: "origin-two" } });
+  assert.strictEqual(busy.status, "busy");
+  assert.strictEqual(runs.length, 1, "only one side provider run is allowed per user");
+  assert.strictEqual(deliveries.length, 1);
+  assert.strictEqual(deliveries[0].action.callbackData, "sc:q:token-two");
+
+  gate.resolve();
+  const firstResult = await firstPending;
+  assert.strictEqual(firstResult.ok, true);
+  assert.strictEqual(coordinator.isActive("fixture-user"), false);
+  assert.strictEqual(deliveries.length, 2);
+  assert.strictEqual(deliveries[1].text, "fresh side answer");
+  assert.strictEqual(deliveries[1].action.callbackData, "sc:q:token-one");
+
+  coordinator.noteMainResult(active, { ok: true, sessionId: "main-minted-session" });
+  const denied = await coordinator.enqueue("token-one", "different-user");
+  assert.strictEqual(denied.status, "forbidden");
+  assert.strictEqual(enqueued.length, 0);
+  const accepted = await coordinator.enqueue("token-one", "fixture-user");
+  assert.strictEqual(accepted.status, "queued");
+  assert.strictEqual(enqueued.length, 1);
+  assert.strictEqual(enqueued[0].request.originalRunContext.runId, "side-one");
+  assert.strictEqual(enqueued[0].request.originalRunContext.provider, "claude");
+  assert.strictEqual(enqueued[0].request.originalRunContext.project.name, "project-a");
+  assert.strictEqual(enqueued[0].request.originalRunContext.origin.transport, "telegram");
+  assert.deepStrictEqual(enqueued[0].store, { id: "origin-one" });
+  assert.deepStrictEqual(enqueued[0].lineage, { mainRunId: "active-main", mainSessionId: "main-minted-session" });
+  const replay = await coordinator.enqueue("token-one", "fixture-user");
+  assert.strictEqual(replay.status, "expired");
+  clock += 20 * 60 * 1000;
+  const expired = await coordinator.enqueue("token-two", "fixture-user");
+  assert.strictEqual(expired.status, "expired");
+
+  const deliveryAttempts = [];
+  const failingDelivery = new SideChatCoordinator({
+    tokenFactory: () => "delivery-failure-token",
+    runSideChat: async () => ({ ok: true, text: "must be delivered once" }),
+    deliver: async (payload) => { deliveryAttempts.push(payload); throw new Error("fixture delivery failed"); },
+    enqueueMain: () => ({ queued: true }),
+  });
+  const failed = await failingDelivery.respond({ runContext: first, activeRunContext: active });
+  assert.strictEqual(failed.ok, false);
+  assert.strictEqual(deliveryAttempts.length, 1, "delivery failure must not trigger a second send");
+  assert.strictEqual(failingDelivery.isActive("fixture-user"), false);
+}
+
+function modeAndLineageProbe() {
+  const modeDir = path.join(root, "mode");
+  fs.mkdirSync(modeDir);
+  const modeFile = path.join(modeDir, ".bot-mode");
+  assert.strictEqual(readRuntimeMode(modeDir), "direct");
+  fs.writeFileSync(modeFile, "invalid\n");
+  assert.strictEqual(readRuntimeMode(modeDir), "direct");
+  fs.writeFileSync(modeFile, "direct\n");
+  assert.strictEqual(readRuntimeMode(modeDir), "direct");
+  fs.writeFileSync(modeFile, "agent\n");
+  assert.strictEqual(readRuntimeMode(modeDir), "agent");
+
+  const state = mainState("claude");
+  state.runningProcess = { pid: 123 };
+  const incoming = captureMainRun(state, "queue me", "lineage-incoming");
+  const active = captureMainRun(state, "fresh main", "lineage-main");
+  state.activeRunContext = active;
+  assert.strictEqual(shouldStartSideChat(state, incoming, {}, { enabled: () => false }), false);
+  assert.strictEqual(shouldStartSideChat(state, incoming, {}, { enabled: () => true }), true);
+  assert.strictEqual(shouldStartSideChat(state, incoming, { sideChat: false }, { enabled: () => true }), false);
+
+  const request = createSideChatRequest({ runContext: incoming, activeRunContext: active, token: "lineage-token" });
+  const pending = createSideChatQueueItem(request, { id: "origin" }, {
+    mainRunId: active.runId,
+    mainSessionId: null,
+  }, state, { resolve() {}, reject() {}, promise: Promise.resolve() });
+  assert.strictEqual(pending.runContext, null, "pre-completion action remains a pending intent, not a mutable admitted run");
+  assert.strictEqual(finalizeSideChatQueueItem(pending, active, { ok: true, sessionId: "fresh-main-minted" }), true);
+  assert.ok(Object.isFrozen(pending.runContext));
+  assert.strictEqual(pending.runContext.provider, "claude");
+  assert.strictEqual(pending.runContext.project.name, "project-a");
+  assert.strictEqual(pending.runContext.resumeSessionId, "fresh-main-minted");
+  assert.strictEqual(pending.runContext.fresh, false);
+
+  const afterCompletion = createSideChatQueueItem(request, null, {
+    mainRunId: active.runId,
+    mainSessionId: "already-minted",
+  }, { ...state, activeRunContext: null }, { promise: Promise.resolve() });
+  assert.strictEqual(afterCompletion.runContext.resumeSessionId, "already-minted");
+  assert.ok(Object.isFrozen(afterCompletion.runContext));
+}
+
+async function main() {
+  await providerProbe("claude");
+  await providerProbe("codex");
+  await coordinatorProbe();
+  modeAndLineageProbe();
+  console.log("provider side chat OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => fs.rmSync(root, { recursive: true, force: true }));

package/test-provider-state-migration.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const root = __dirname;
+const fixturesRoot = path.join(root, "test-fixtures", "migrations");
+const apiConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-state-api-"));
+process.env.OPEN_CLAUDIA_CONFIG_DIR = apiConfigDir;
+const fixtureNames = [
+  "claude-only",
+  "dual-provider",
+  "cursor-selected",
+  "multi-user",
+  "missing-project",
+];
+
+// Keep state/config imports after the fixture-independent environment setup in
+// the child integration probe below. The pure migration API must not write.
+const stateApi = require("./core/state");
+const migration = require("./core/migration-backup");
+
+function readFixture(name) {
+  return JSON.parse(fs.readFileSync(path.join(fixturesRoot, name, "state.json"), "utf8"));
+}
+
+function onlyUser(document) {
+  const entries = Object.entries(document.users || {});
+  assert.strictEqual(entries.length, 1);
+  return entries[0][1];
+}
+
+function fixtureMigrationProbe() {
+  for (const name of fixtureNames) {
+    const raw = readFixture(name);
+    const migrated = stateApi.migrateStateDocument(raw, {
+      defaultUserId: "telegram:fixture",
+      canonicalizeUserId: (value) => String(value),
+    });
+    assert.strictEqual(migrated.schemaVersion, stateApi.STATE_SCHEMA_VERSION, `${name}: schema version`);
+    assert.deepStrictEqual(
+      stateApi.migrateStateDocument(migrated, {
+        defaultUserId: "telegram:fixture",
+        canonicalizeUserId: (value) => String(value),
+      }),
+      migrated,
+      `${name}: migration is idempotent`,
+    );
+  }
+
+  const claude = onlyUser(stateApi.migrateStateDocument(readFixture("claude-only"), {
+    defaultUserId: "telegram:fixture",
+    canonicalizeUserId: (value) => String(value),
+  }));
+  assert.strictEqual(claude.activeSessions.alpha.claude, "claude-session-alpha");
+  assert.strictEqual(claude.providerSettings.claude.model, "claude-sonnet");
+  assert.strictEqual(claude.settings.backend, "claude");
+  assert.ok(!Object.prototype.hasOwnProperty.call(claude.settings, "model"));
+
+  const dual = stateApi.migrateStateDocument(readFixture("dual-provider"), {
+    defaultUserId: "telegram:fixture",
+    canonicalizeUserId: (value) => String(value),
+  }).users["owner@example.test"];
+  assert.deepStrictEqual(dual.activeSessions.parity, { claude: "claude-session-parity" });
+  assert.strictEqual(dual.legacyProviderState.unresolvedSessionPointers.codex, "codex-thread-parity",
+    "legacy process-global Codex pointers are not guessed into currentSession");
+  assert.strictEqual(dual.providerSettings.codex.model, "gpt-fixture");
+
+  const cursor = onlyUser(stateApi.migrateStateDocument(readFixture("cursor-selected"), {
+    defaultUserId: "telegram:fixture",
+    canonicalizeUserId: (value) => String(value),
+  }));
+  assert.strictEqual(cursor.settings.backend, null);
+  assert.deepStrictEqual(cursor.activeSessions, { "legacy-cursor": { claude: "claude-neighbor" } });
+  assert.strictEqual(cursor.legacyProviderState.archivedSessionPointers.cursor, "cursor-session-unresolved");
+  assert.strictEqual(cursor.legacyProviderState.archivedActiveSessions["legacy-cursor"].cursor, "cursor-session-unresolved");
+  assert.strictEqual(cursor.legacyProviderState.archivedProviderSettings.cursor.model, "cursor-model");
+  assert.strictEqual(cursor.legacyProviderState.providerSelectionRequired, true);
+
+  const missing = onlyUser(stateApi.migrateStateDocument(readFixture("missing-project"), {
+    defaultUserId: "telegram:fixture",
+    canonicalizeUserId: (value) => String(value),
+  }));
+  assert.deepStrictEqual(missing.activeSessions, {});
+  assert.strictEqual(missing.legacyProviderState.unresolvedSessionPointers.claude, "orphan-session");
+
+  const multi = stateApi.migrateStateDocument(readFixture("multi-user"), {
+    defaultUserId: "telegram:fixture",
+    canonicalizeUserId: (value) => String(value),
+  });
+  assert.strictEqual(multi.users["telegram:100"].activeSessions.one.claude, "session-one");
+  assert.deepStrictEqual(multi.users["person@example.test"].activeSessions, {});
+  assert.strictEqual(multi.users["person@example.test"].legacyProviderState.unresolvedSessionPointers.codex, "thread-two");
+}
+
+function helperAndBoundProbe() {
+  const usageBySession = {};
+  for (let index = 0; index < stateApi.MAX_USAGE_ENTRIES + 15; index += 1) {
+    usageBySession[`project-${index}\0claude\0session-${index}`] = { turns: index };
+  }
+  const migrated = stateApi.migrateStateDocument({
+    users: {
+      owner: {
+        currentSession: { name: "alpha", dir: "/workspace/alpha" },
+        activeSessions: { alpha: { claude: "claude-a", codex: "codex-a" } },
+        providerSettings: { claude: { model: "sonnet" }, codex: { model: "gpt" } },
+        settings: { backend: "codex", compactWindow: 123, recallEngine: "classic" },
+        usageBySession,
+      },
+    },
+  }, { canonicalizeUserId: (value) => String(value) });
+  const saved = migrated.users.owner;
+  assert.ok(Object.keys(saved.usageBySession).length <= stateApi.MAX_USAGE_ENTRIES);
+  assert.ok(saved.usageBySession[`project-${stateApi.MAX_USAGE_ENTRIES + 14}\0claude\0session-${stateApi.MAX_USAGE_ENTRIES + 14}`]);
+
+  const recentUsageState = { usageBySession: structuredClone(saved.usageBySession) };
+  const oldestRetainedKey = Object.keys(recentUsageState.usageBySession)[0];
+  const [oldestProject, oldestProvider, oldestSession] = oldestRetainedKey.split("\0");
+  stateApi.getUsageForSession(recentUsageState, oldestProject, oldestProvider, oldestSession);
+  stateApi.getUsageForSession(recentUsageState, "new-project", "claude", "new-session");
+  assert.ok(recentUsageState.usageBySession[oldestRetainedKey], "access refreshes an active usage entry before bounding");
+
+  const state = {
+    settings: { backend: "codex" },
+    currentSession: { name: "alpha", dir: "/workspace/alpha" },
+    activeSessions: structuredClone(saved.activeSessions),
+    providerSettings: structuredClone(saved.providerSettings),
+    usageBySession: {},
+  };
+  assert.strictEqual(stateApi.getActiveProvider(state), "codex");
+  assert.strictEqual(stateApi.getProjectKey(state), "alpha");
+  assert.strictEqual(stateApi.getProviderSession(state, "claude", "alpha"), "claude-a");
+  assert.strictEqual(stateApi.getProviderSession(state, "codex", "alpha"), "codex-a");
+  stateApi.setProviderSession(state, "codex", "alpha", "codex-next");
+  assert.strictEqual(stateApi.getProviderSession(state, "codex", "alpha"), "codex-next");
+  stateApi.clearProviderSession(state, "codex", "alpha");
+  assert.strictEqual(stateApi.getProviderSession(state, "codex", "alpha"), null);
+  assert.strictEqual(stateApi.getProviderSettings(state, "claude").model, "sonnet");
+  assert.strictEqual(stateApi.getActiveUsage(state).turns, 0);
+  assert.ok(Object.keys(state.usageBySession)[0].includes("alpha\0codex\0new"));
+
+  const legacyRuntime = onlyUser(stateApi.migrateStateDocument({
+    currentSession: { name: "alpha", dir: "/workspace/alpha" },
+    codexSessionId: "codex-a",
+    codexUsageSnapshots: { "codex-a": { input_tokens: 50, output_tokens: 5 } },
+    sessionUsage: { turns: 4, inputTokens: 40, outputTokens: 8 },
+    lastCompactedAt: 123456,
+    settings: {
+      backend: "codex",
+      model: "gpt-fixture",
+      effort: "high",
+      budget: 2,
+      permissionMode: "plan",
+      worktree: true,
+      compactWindow: 200000,
+      recallEngine: "discoverer",
+      showToolTrace: true,
+    },
+  }, { defaultUserId: "owner", canonicalizeUserId: (value) => String(value) }));
+  assert.deepStrictEqual(legacyRuntime.legacyProviderState.unresolvedCodexUsageSnapshots["codex-a"], {
+    input_tokens: 50,
+    output_tokens: 5,
+  });
+  assert.ok(!Object.prototype.hasOwnProperty.call(legacyRuntime, "codexUsageSnapshots"));
+  assert.deepStrictEqual(legacyRuntime.legacyProviderState.unresolvedUsage, {
+    turns: 4,
+    inputTokens: 40,
+    outputTokens: 8,
+  });
+  assert.strictEqual(legacyRuntime.legacyProviderState.unresolvedSessionPointers.codex, "codex-a");
+  assert.ok(!Object.keys(legacyRuntime.usageBySession).some((key) => key.includes("codex-a")));
+  assert.deepStrictEqual(legacyRuntime.providerSettings.codex, {
+    model: "gpt-fixture",
+    effort: "high",
+    budget: 2,
+    permissionMode: "plan",
+    worktree: true,
+  });
+  assert.strictEqual(legacyRuntime.settings.compactWindow, 200000);
+  assert.strictEqual(legacyRuntime.settings.recallEngine, "discoverer");
+  assert.strictEqual(legacyRuntime.settings.showToolTrace, true);
+  assert.strictEqual(legacyRuntime.lastCompactedAt, 123456);
+
+  const provenCodexOwner = onlyUser(stateApi.migrateStateDocument({
+    currentSession: { name: "other", dir: "/workspace/other" },
+    activeSessions: { proven: { codex: "codex-proven" } },
+    codexSessionId: "codex-proven",
+    codexUsageSnapshots: { "codex-proven": { input_tokens: 7 } },
+    sessionUsage: { turns: 2 },
+    settings: { backend: "codex" },
+  }, { defaultUserId: "owner", canonicalizeUserId: (value) => String(value) }));
+  assert.strictEqual(provenCodexOwner.activeSessions.proven.codex, "codex-proven");
+  assert.strictEqual(provenCodexOwner.usageBySession["proven\0codex\0codex-proven"].turns, 2);
+  assert.strictEqual(
+    provenCodexOwner.usageBySession["proven\0codex\0codex-proven"].providerUsageSnapshot.input_tokens,
+    7,
+  );
+  assert.throws(
+    () => stateApi.migrateStateDocument({ schemaVersion: stateApi.STATE_SCHEMA_VERSION + 1, users: {} }),
+    (error) => error.code === "UNSUPPORTED_STATE_SCHEMA",
+  );
+}
+
+function atomicIntegrationProbe() {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-state-migration-"));
+  try {
+    const configDir = path.join(temp, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.cpSync(path.join(fixturesRoot, "claude-only"), configDir, { recursive: true });
+    const original = fs.readFileSync(path.join(configDir, "state.json"));
+    const childScript = [
+      "const state = require('./core/state');",
+      "state.currentState();",
+      "if (!state.saveState({ strict: true })) process.exit(2);",
+    ].join("\n");
+    const env = {
+      ...process.env,
+      OPEN_CLAUDIA_CONFIG_DIR: configDir,
+      TELEGRAM_CHAT_ID: "fixture",
+      CHANNELS: "telegram",
+      OPEN_CLAUDIA_TEST: "1",
+    };
+    const first = spawnSync(process.execPath, ["-e", childScript], { cwd: root, env, encoding: "utf8" });
+    assert.strictEqual(first.status, 0, first.stderr || first.stdout);
+
+    const live = JSON.parse(fs.readFileSync(path.join(configDir, "state.json"), "utf8"));
+    assert.strictEqual(live.schemaVersion, stateApi.STATE_SCHEMA_VERSION);
+    assert.strictEqual(live.users["telegram:fixture"].activeSessions.alpha.claude, "claude-session-alpha");
+    const journal = migration.readMigrationJournal(configDir);
+    assert.ok(journal.components.state, "state component must activate after the atomic schema write");
+    const snapshotDir = path.join(migration.migrationRoot(configDir), ...journal.snapshot.split("/"));
+    migration.validateMigrationSnapshot(snapshotDir);
+    assert.deepStrictEqual(fs.readFileSync(path.join(snapshotDir, "originals", "state.json")), original);
+
+    // A restart between component migrations must keep the original rollback
+    // snapshot even though state.json now intentionally differs from it.
+    const resumed = migration.ensureMigrationSnapshot({
+      configDir,
+      sources: migration.defaultMigrationSources({ configDir }),
+    });
+    assert.strictEqual(resumed.snapshotDir, snapshotDir);
+    assert.strictEqual(resumed.reused, true);
+
+    const afterFirst = fs.readFileSync(path.join(configDir, "state.json"));
+    const second = spawnSync(process.execPath, ["-e", childScript], { cwd: root, env, encoding: "utf8" });
+    assert.strictEqual(second.status, 0, second.stderr || second.stdout);
+    assert.deepStrictEqual(fs.readFileSync(path.join(configDir, "state.json")), afterFirst);
+    assert.strictEqual(migration.readMigrationJournal(configDir).snapshot, journal.snapshot);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function interruptedActivationProbe() {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-state-interrupt-"));
+  try {
+    const configDir = path.join(temp, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.cpSync(path.join(fixturesRoot, "dual-provider"), configDir, { recursive: true });
+    const original = fs.readFileSync(path.join(configDir, "state.json"));
+    const env = {
+      ...process.env,
+      OPEN_CLAUDIA_CONFIG_DIR: configDir,
+      TELEGRAM_CHAT_ID: "fixture",
+      CHANNELS: "telegram",
+      OPEN_CLAUDIA_TEST: "1",
+    };
+    const interrupted = spawnSync(process.execPath, ["-e", [
+      "const state = require('./core/state');",
+      "state.currentState();",
+      "try {",
+      "  state.saveState({ strict: true, faultInjector(point) { if (point === 'after-state-write') throw Object.assign(new Error('stop after rename'), { code: 'FIXTURE_INTERRUPTION' }); } });",
+      "  process.exit(3);",
+      "} catch (error) { if (error.code !== 'FIXTURE_INTERRUPTION') throw error; }",
+    ].join("\n")], { cwd: root, env, encoding: "utf8" });
+    assert.strictEqual(interrupted.status, 0, interrupted.stderr || interrupted.stdout);
+    const pending = migration.readMigrationJournal(configDir);
+    assert.ok(pending.pendingComponents.state);
+    assert.strictEqual(pending.components.state, null);
+    assert.strictEqual(JSON.parse(fs.readFileSync(path.join(configDir, "state.json"), "utf8")).schemaVersion, stateApi.STATE_SCHEMA_VERSION);
+
+    // This is the same pre-state-import check bot.js performs on restart.
+    const resumedSnapshot = migration.ensureMigrationSnapshot({
+      configDir,
+      sources: migration.defaultMigrationSources({ configDir }),
+    });
+    assert.strictEqual(resumedSnapshot.journal.snapshot, pending.snapshot);
+    const snapshotDir = resumedSnapshot.snapshotDir;
+    assert.deepStrictEqual(fs.readFileSync(path.join(snapshotDir, "originals", "state.json")), original);
+
+    const completed = spawnSync(process.execPath, ["-e", [
+      "const state = require('./core/state');",
+      "state.currentState();",
+      "state.saveState({ strict: true });",
+    ].join("\n")], { cwd: root, env, encoding: "utf8" });
+    assert.strictEqual(completed.status, 0, completed.stderr || completed.stdout);
+    const journal = migration.readMigrationJournal(configDir);
+    assert.ok(journal.components.state);
+    assert.ok(!journal.pendingComponents.state);
+    assert.strictEqual(journal.snapshot, pending.snapshot);
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+fixtureMigrationProbe();
+helperAndBoundProbe();
+atomicIntegrationProbe();
+interruptedActivationProbe();
+fs.rmSync(apiConfigDir, { recursive: true, force: true });
+console.log("provider state migration OK");