@inetafrica/open-claudia 2.14.8 → 3.0.0

package/test-fixtures/migrations/malformed-partial/state.json

@@ -0,0 +1 @@
+{"users":{"broken":{"currentSession":

package/test-fixtures/migrations/malformed-partial/state.json.bak

@@ -0,0 +1,5 @@
+{
+  "currentSession": { "name": "fallback", "dir": "/workspace/fallback" },
+  "lastSessionId": "fallback-session",
+  "settings": { "backend": "claude" }
+}

package/test-fixtures/migrations/missing-project/jobs.json

@@ -0,0 +1,3 @@
+[
+  { "id": "orphan-job", "kind": "wakeup", "project": null, "sessionKey": "lastSessionId", "sessionId": "orphan-session", "prompt": "unresolved project" }
+]

package/test-fixtures/migrations/missing-project/sessions.json

@@ -0,0 +1,3 @@
+{
+  "unknown-project": [{ "id": "orphan-session", "title": "Missing project selection" }]
+}

package/test-fixtures/migrations/missing-project/state.json

@@ -0,0 +1,4 @@
+{
+  "lastSessionId": "orphan-session",
+  "settings": { "backend": "claude" }
+}

package/test-fixtures/migrations/multi-user/jobs.json

@@ -0,0 +1,4 @@
+[
+  { "id": "job-one", "kind": "wakeup", "canonicalUserId": "telegram:100", "project": "one", "sessionKey": "lastSessionId", "sessionId": "session-one", "prompt": "one" },
+  { "id": "job-two", "kind": "cron", "canonicalUserId": "person@example.test", "project": "two", "sessionKey": "codexSessionId", "sessionId": "thread-two", "prompt": "two" }
+]

package/test-fixtures/migrations/multi-user/sessions.json

@@ -0,0 +1,4 @@
+{
+  "telegram:100": { "one": [{ "id": "session-one", "title": "One" }] },
+  "person@example.test": { "two": [{ "id": "provider-ambiguous-two", "title": "Two" }] }
+}

package/test-fixtures/migrations/multi-user/state.json

@@ -0,0 +1,6 @@
+{
+  "users": {
+    "telegram:100": { "currentSession": { "name": "one", "dir": "/workspace/one" }, "lastSessionId": "session-one", "settings": { "backend": "claude" } },
+    "person@example.test": { "currentSession": { "name": "two", "dir": "/workspace/two" }, "codexSessionId": "thread-two", "settings": { "backend": "codex" } }
+  }
+}

package/test-fixtures/provider-event-samples.json

@@ -0,0 +1,17 @@
+{
+  "claude": {
+    "session": { "type": "system", "subtype": "init", "session_id": "claude-session-1" },
+    "delta": { "type": "stream_event", "event": { "type": "content_block_delta", "delta": { "type": "text_delta", "text": "Hello " } }, "session_id": "claude-session-1" },
+    "assistant": { "type": "assistant", "message": { "role": "assistant", "content": [{ "type": "text", "text": "world" }], "usage": { "input_tokens": 12, "output_tokens": 3 } }, "session_id": "claude-session-1" },
+    "toolUse": { "type": "assistant", "message": { "role": "assistant", "content": [{ "type": "tool_use", "id": "tool-1", "name": "Read", "input": { "file_path": "fixture.txt" } }] }, "session_id": "claude-session-1" },
+    "toolResult": { "type": "user", "message": { "role": "user", "content": [{ "type": "tool_result", "tool_use_id": "tool-1", "content": "fixture output", "is_error": false }] }, "session_id": "claude-session-1" },
+    "result": { "type": "result", "subtype": "success", "is_error": false, "session_id": "claude-session-1", "result": "Hello world", "usage": { "input_tokens": 12, "output_tokens": 3 }, "total_cost_usd": 0 }
+  },
+  "codex": {
+    "session": { "type": "thread.started", "thread_id": "codex-thread-1" },
+    "toolStart": { "type": "item.started", "item": { "id": "item-1", "type": "command_execution", "command": "printf fixture", "status": "in_progress" } },
+    "toolEnd": { "type": "item.completed", "item": { "id": "item-1", "type": "command_execution", "command": "printf fixture", "aggregated_output": "fixture", "exit_code": 0, "status": "completed" } },
+    "assistant": { "type": "item.completed", "item": { "id": "item-final", "type": "agent_message", "text": "Hello from Codex" } },
+    "result": { "type": "turn.completed", "usage": { "input_tokens": 20, "cached_input_tokens": 5, "output_tokens": 4 } }
+  }
+}

package/test-learning-e2e.js

@@ -73,6 +73,11 @@ if (haveFts) {
 const transferred = packs.recordCoUse(["pack:mobile-app-deploy", "pack:chat-mobile"]);
 assert.deepStrictEqual(transferred.map((t) => t.project), ["chat-mobile"], "Stage 4: reuse recorded from real use");
 assert.deepStrictEqual(packs.readPack("mobile-app-deploy").applied_on, ["spaces", "chat-mobile"], "Stage 4: applied_on grew");
+const learnedAbilityFile = path.join(process.env.PACKS_DIR, "mobile-app-deploy", "PACK.md");
+assert.ok(fs.existsSync(`${learnedAbilityFile}.bak`), "learning updates retain a last-good pack backup");
+assert.strictEqual(fs.statSync(learnedAbilityFile).mode & 0o777, 0o600, "learning files stay owner-only");
+assert.deepStrictEqual(fs.readdirSync(path.dirname(learnedAbilityFile)).filter((name) => name.endsWith(".tmp")), [],
+  "atomic learning writes leave no partial temporary file");
 if (haveGraph) {
   graph.syncFromCorpus(packs, entStub);
   const fromChat = graph.expand([{ id: "pack:chat-mobile", score: 4 }], {});

package/test-memory-mutation-queue.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-memory-queue-"));
+process.env.OPEN_CLAUDIA_TEST = "1";
+process.env.OPEN_CLAUDIA_CONFIG_DIR = path.join(root, "config");
+fs.mkdirSync(process.env.OPEN_CLAUDIA_CONFIG_DIR, { recursive: true });
+
+const {
+  MemoryMutationQueue,
+  MutationQueueError,
+} = require("./core/memory-mutation-queue");
+const { atomicWriteFileSync } = require("./core/fsutil");
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
+
+function wait(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+async function main() {
+  const lockDir = path.join(root, "shared.lock");
+  const journalFile = path.join(root, "mutation-journal.jsonl");
+  const firstQueue = new MemoryMutationQueue({ lockDir, journalFile, maxPending: 5, lockPollMs: 5 });
+  const secondQueue = new MemoryMutationQueue({ lockDir, journalFile, maxPending: 5, lockPollMs: 5 });
+  const gate = deferred();
+  const events = [];
+
+  const first = firstQueue.enqueue("review", async () => {
+    events.push("review:start");
+    await gate.promise;
+    events.push("review:end");
+    return "reviewed";
+  }, { provider: "codex", model: "fixture" });
+  while (!events.includes("review:start")) await wait(5);
+  const second = secondQueue.enqueue("dream", async () => {
+    events.push("dream:start");
+    await wait(5);
+    events.push("dream:end");
+    return "dreamed";
+  });
+  await wait(30);
+  assert.deepStrictEqual(events, ["review:start"], "independent queue instances serialize through the shared lock");
+  gate.resolve();
+  assert.deepStrictEqual(await Promise.all([first, second]), ["reviewed", "dreamed"]);
+  assert.deepStrictEqual(events, ["review:start", "review:end", "dream:start", "dream:end"]);
+  assert.ok(!fs.existsSync(lockDir), "shared lock is removed after every mutation");
+
+  const liveLockDir = path.join(root, "live-stale.lock");
+  const liveGate = deferred();
+  const liveOwner = new MemoryMutationQueue({
+    lockDir: liveLockDir,
+    journalFile,
+    maxPending: 2,
+    lockPollMs: 5,
+    staleLockMs: 10,
+  });
+  const liveContender = new MemoryMutationQueue({
+    lockDir: liveLockDir,
+    journalFile,
+    maxPending: 2,
+    lockPollMs: 5,
+    staleLockMs: 10,
+    lockTimeoutMs: 50,
+  });
+  const liveMutation = liveOwner.enqueue("long-dream", async () => liveGate.promise);
+  while (!fs.existsSync(path.join(liveLockDir, "owner.json"))) await wait(5);
+  await wait(20);
+  await assert.rejects(
+    liveContender.enqueue("must-not-steal", async () => "stolen"),
+    (error) => error.code === "MEMORY_MUTATION_LOCK_TIMEOUT",
+    "an old lock owned by a live process cannot be stolen from a long dream mutation",
+  );
+  liveGate.resolve("complete");
+  assert.strictEqual(await liveMutation, "complete");
+
+  const deadLockDir = path.join(root, "dead-stale.lock");
+  fs.mkdirSync(deadLockDir);
+  fs.writeFileSync(path.join(deadLockDir, "owner.json"), JSON.stringify({ token: "dead", pid: 2147483647 }));
+  const old = new Date(Date.now() - 10_000);
+  fs.utimesSync(deadLockDir, old, old);
+  const deadRecovery = new MemoryMutationQueue({
+    lockDir: deadLockDir,
+    journalFile,
+    lockPollMs: 5,
+    staleLockMs: 10,
+    lockTimeoutMs: 200,
+  });
+  assert.strictEqual(await deadRecovery.enqueue("recover-dead-lock", async () => "recovered"), "recovered");
+
+  const failureQueue = new MemoryMutationQueue({
+    lockDir: path.join(root, "failure.lock"),
+    journalFile,
+    maxPending: 3,
+    lockPollMs: 5,
+  });
+  await assert.rejects(
+    failureQueue.enqueue("broken-review", async () => { throw new Error("write fixture failed"); }),
+    /write fixture failed/,
+  );
+  assert.strictEqual(await failureQueue.enqueue("after-failure", async () => "still runs"), "still runs",
+    "one failed mutation never poisons the serial chain");
+
+  const boundedGate = deferred();
+  const bounded = new MemoryMutationQueue({
+    lockDir: path.join(root, "bounded.lock"),
+    journalFile,
+    maxPending: 1,
+    lockPollMs: 5,
+  });
+  const held = bounded.enqueue("held", async () => boundedGate.promise);
+  await wait(10);
+  await assert.rejects(
+    bounded.enqueue("overflow", async () => {}),
+    (error) => error instanceof MutationQueueError && error.code === "MEMORY_MUTATION_QUEUE_FULL",
+  );
+  boundedGate.resolve("released");
+  assert.strictEqual(await held, "released");
+
+  const shutdownGate = deferred();
+  const shutdownQueue = new MemoryMutationQueue({
+    lockDir: path.join(root, "shutdown.lock"),
+    journalFile,
+    maxPending: 3,
+    lockPollMs: 5,
+  });
+  const pending = shutdownQueue.enqueue("pending-review", async () => shutdownGate.promise, { provider: "claude" });
+  await wait(10);
+  shutdownQueue.stopAdmission("test shutdown");
+  await assert.rejects(
+    shutdownQueue.enqueue("late-review", async () => {}),
+    (error) => error.code === "MEMORY_MUTATION_QUEUE_CLOSED",
+  );
+  const timedDrain = await shutdownQueue.drain({ timeoutMs: 25 });
+  assert.strictEqual(timedDrain.drained, false);
+  assert.strictEqual(timedDrain.pending.length, 1);
+  assert.strictEqual(timedDrain.pending[0].label, "pending-review");
+  const journalBeforeRelease = fs.readFileSync(journalFile, "utf8");
+  assert.match(journalBeforeRelease, /"status":"pending_on_shutdown"/);
+  assert.ok(!journalBeforeRelease.includes("provider prompt"), "queue journal stores metadata only, never prompts");
+  shutdownGate.resolve("done");
+  assert.strictEqual(await pending, "done");
+  const finalDrain = await shutdownQueue.drain({ timeoutMs: 100 });
+  assert.strictEqual(finalDrain.drained, true);
+  assert.deepStrictEqual(finalDrain.pending, []);
+
+  const atomicFile = path.join(root, "atomic", "memory.md");
+  atomicWriteFileSync(atomicFile, "old complete memory\n", { mode: 0o600, backup: true });
+  const originalRename = fs.renameSync;
+  fs.renameSync = () => { throw new Error("rename fault fixture"); };
+  try {
+    assert.throws(
+      () => atomicWriteFileSync(atomicFile, "new incomplete memory\n", { mode: 0o600, backup: true }),
+      /rename fault fixture/,
+    );
+  } finally {
+    fs.renameSync = originalRename;
+  }
+  assert.strictEqual(fs.readFileSync(atomicFile, "utf8"), "old complete memory\n",
+    "failed atomic replacement preserves the complete previous file");
+  assert.deepStrictEqual(
+    fs.readdirSync(path.dirname(atomicFile)).filter((name) => name.endsWith(".tmp")),
+    [],
+    "failed atomic replacement cleans its temporary file",
+  );
+  atomicWriteFileSync(atomicFile, "new complete memory\n", { mode: 0o600, backup: true });
+  assert.strictEqual(fs.readFileSync(atomicFile, "utf8"), "new complete memory\n");
+  assert.strictEqual(fs.readFileSync(`${atomicFile}.bak`, "utf8"), "old complete memory\n");
+  assert.strictEqual(fs.statSync(atomicFile).mode & 0o777, 0o600);
+
+  const journal = fs.readFileSync(journalFile, "utf8").trim().split("\n").map(JSON.parse);
+  assert.ok(journal.some((entry) => entry.label === "broken-review" && entry.status === "failed"));
+  assert.ok(journal.some((entry) => entry.label === "after-failure" && entry.status === "completed"));
+  assert.ok(journal.every((entry) => !Object.prototype.hasOwnProperty.call(entry, "payload")));
+
+  console.log("memory mutation queue OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => fs.rmSync(root, { recursive: true, force: true }));

package/test-provider-boot-matrix.js

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const http = require("http");
+const { spawnSync } = require("child_process");
+
+const root = __dirname;
+
+function writeProviderCli(filePath, kind, mode, logPath) {
+  const source = `#!/usr/bin/env node
+"use strict";
+const fs = require("fs");
+const args = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(logPath)}, JSON.stringify({ kind: ${JSON.stringify(kind)}, args }) + "\\n");
+const same = (...wanted) => args.length === wanted.length && args.every((value, index) => value === wanted[index]);
+if (same("--version")) {
+  process.stdout.write(${JSON.stringify(kind === "claude" ? "1.2.3\n" : "codex-cli 0.144.0\n")});
+} else if (${JSON.stringify(kind)} === "claude" && same("--help")) {
+  process.stdout.write(${JSON.stringify(mode === "incompatible"
+    ? "--output-format --resume --permission-mode --settings\n"
+    : "--append-system-prompt --output-format --resume --permission-mode --settings\n")});
+} else if (${JSON.stringify(kind)} === "claude" && same("auth", "status")) {
+  if (${JSON.stringify(mode)} === "unauthenticated") {
+    process.stderr.write("not logged in\\n");
+    process.exitCode = 1;
+  } else process.stdout.write("authenticated via fixture store\\n");
+} else if (${JSON.stringify(kind)} === "codex" && (same("exec", "--help") || same("exec", "resume", "--help"))) {
+  process.stdout.write(${JSON.stringify(mode === "incompatible"
+    ? "--config --json --sandbox --model --skip-git-repo-check --strict-config --ignore-user-config --dangerously-bypass-hook-trust\n"
+    : "--config --json --sandbox --image --model --skip-git-repo-check --strict-config --ignore-user-config --dangerously-bypass-hook-trust\n")});
+} else if (${JSON.stringify(kind)} === "codex" && args[0] === "features" && args.at(-1) === "list") {
+  process.stdout.write("hooks stable true\\nplugins stable false\\nunified_exec stable false\\n");
+} else if (${JSON.stringify(kind)} === "codex" && same("login", "status")) {
+  if (${JSON.stringify(mode)} === "unauthenticated") {
+    process.stderr.write("not logged in\\n");
+    process.exitCode = 1;
+  } else process.stdout.write("logged in\\n");
+} else {
+  process.stderr.write("MODEL_PROMPT_INVOCATION " + JSON.stringify(args) + "\\n");
+  process.exitCode = 70;
+}
+`;
+  fs.writeFileSync(filePath, source, { mode: 0o755 });
+}
+
+function readCommandLog(logPath) {
+  if (!fs.existsSync(logPath)) return [];
+  return fs.readFileSync(logPath, "utf8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function isLocalStatusProbe(entry) {
+  const joined = entry.args.join(" ");
+  if (entry.kind === "claude") {
+    return joined === "--version" || joined === "--help" || joined === "auth status";
+  }
+  return joined === "--version"
+    || joined === "exec --help"
+    || joined === "exec resume --help"
+    || joined === "login status"
+    || (entry.args[0] === "features" && entry.args.at(-1) === "list");
+}
+
+async function childProbe() {
+  const config = require("./core/config");
+  const providers = require("./core/providers");
+  const setup = require("./setup");
+  const health = require("./health");
+  const doctor = require("./core/doctor");
+  const web = require("./web");
+  const stateApi = require("./core/state");
+  const { captureRunContext } = require("./core/run-context");
+
+  const selection = providers.selectDefaultProvider(config.DEFAULT_PROVIDER);
+  const freshState = stateApi.currentState();
+  const stateProvider = stateApi.getActiveProvider(freshState);
+  const setupStatus = setup.inspectProviderSetup();
+  const healthStatus = await health.runHealthChecks({ quick: false, skipNetwork: true });
+  const doctorChecks = doctor.runDoctorChecks();
+  const webStatus = web.providerConfigurationStatus();
+
+  // Startup, not merely import, must remain available without a provider.
+  const server = web.startWebServer();
+  if (!server.listening) await new Promise((resolve) => server.once("listening", resolve));
+  await new Promise((resolve) => server.close(resolve));
+
+  let afterDisappear = null;
+  if (process.env.DISAPPEAR_PROVIDER) {
+    const providerId = process.env.DISAPPEAR_PROVIDER;
+    const executable = config.discoverProviderExecutable(providerId);
+    if (executable) fs.rmSync(executable, { force: true });
+    afterDisappear = {
+      status: providers.providerStatus(providerId),
+      selection: providers.selectDefaultProvider(config.DEFAULT_PROVIDER),
+    };
+    try {
+      providers.resolveProviderForRun(providerId);
+    } catch (error) {
+      afterDisappear.runError = error.code;
+    }
+  }
+
+  let noProviderTurn = null;
+  if (!selection.providerId) {
+    let admissionError;
+    try {
+      captureRunContext({ state: freshState, prompt: "must not spawn", cwd: process.cwd() });
+    } catch (error) {
+      admissionError = error;
+    }
+    const sent = [];
+    const { runInChat } = require("./core/context");
+    const { deliverRouterError } = require("./core/router");
+    const delivered = await runInChat({
+      adapter: { type: "fixture", send: async (_channelId, message) => { sent.push(message); return true; } },
+      channelId: "fixture-chat",
+      canonicalUserId: "telegram:fixture-chat",
+      userId: "fixture-chat",
+    }, () => deliverRouterError(admissionError));
+    noProviderTurn = { admissionCode: admissionError?.code || null, delivered, sent };
+  }
+
+  process.stdout.write(`BOOT_MATRIX:${JSON.stringify({
+    selection,
+    stateProvider,
+    setupStatus,
+    healthStatus,
+    doctorChecks,
+    webStatus,
+    afterDisappear,
+    noProviderTurn,
+  })}\n`);
+}
+
+function httpRequest(port, pathname, options = {}) {
+  return new Promise((resolve, reject) => {
+    const body = options.body === undefined ? null : JSON.stringify(options.body);
+    const req = http.request({
+      hostname: "127.0.0.1",
+      port,
+      path: pathname,
+      method: options.method || "GET",
+      headers: {
+        ...(body ? { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) } : {}),
+        ...(options.cookie ? { Cookie: options.cookie } : {}),
+      },
+    }, (res) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => resolve({
+        status: res.statusCode,
+        headers: res.headers,
+        body: data ? JSON.parse(data) : null,
+      }));
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+async function webHttpProbe() {
+  const web = require("./web");
+  const server = web.startWebServer({
+    telegramGet: async () => ({ ok: true, result: { id: 1, username: "fixture_bot", first_name: "Fixture" } }),
+  });
+  if (!server.listening) await new Promise((resolve) => server.once("listening", resolve));
+  const port = server.address().port;
+  const login = await httpRequest(port, "/api/login", {
+    method: "POST",
+    body: { password: process.env.WEB_PASSWORD },
+  });
+  assert.strictEqual(login.status, 200);
+  const cookie = String(login.headers["set-cookie"][0]).split(";")[0];
+  const setup = await httpRequest(port, "/api/setup", {
+    method: "POST",
+    cookie,
+    body: {
+      botToken: "fixture-token",
+      chatId: "fixture-chat",
+      workspace: process.env.WEB_FIXTURE_WORKSPACE,
+      claudePath: "",
+      codexPath: process.env.WEB_FIXTURE_CODEX,
+      defaultProvider: "codex",
+      utilityProvider: "active",
+      providerFallbacks: "claude",
+    },
+  });
+  assert.strictEqual(setup.status, 200, JSON.stringify(setup.body));
+  const status = await httpRequest(port, "/api/status", { cookie });
+  const configUpdate = await httpRequest(port, "/api/config", {
+    method: "POST",
+    cookie,
+    body: { UTILITY_PROVIDER: "codex", DREAM_PROVIDER: "codex" },
+  });
+  const config = await httpRequest(port, "/api/config", { cookie });
+  const soulUpdate = await httpRequest(port, "/api/soul", {
+    method: "POST",
+    cookie,
+    body: { content: "# Soul\n\nProvider-neutral fixture soul.\n" },
+  });
+  const soul = await httpRequest(port, "/api/soul", { cookie });
+  await new Promise((resolve) => server.close(resolve));
+  const envPath = path.join(process.env.OPEN_CLAUDIA_CONFIG_DIR, ".env");
+  process.stdout.write(`WEB_HTTP:${JSON.stringify({
+    setup: setup.body,
+    status: status.body,
+    configUpdate: configUpdate.body,
+    config: config.body,
+    soulUpdate: soulUpdate.body,
+    soul: soul.body,
+    envMode: fs.statSync(envPath).mode & 0o777,
+  })}\n`);
+}
+
+if (process.argv[2] === "--probe") {
+  childProbe().catch((error) => {
+    process.stderr.write(`${error.stack || error.message}\n`);
+    process.exitCode = 1;
+  });
+} else if (process.argv[2] === "--web-http-probe") {
+  webHttpProbe().catch((error) => {
+    process.stderr.write(`${error.stack || error.message}\n`);
+    process.exitCode = 1;
+  });
+} else {
+  const scenarios = [
+    { name: "claude-only", providers: { claude: "ok" }, expectedDefault: "claude" },
+    { name: "codex-only", providers: { codex: "ok" }, expectedDefault: "codex" },
+    { name: "codex-path-only", providers: { codex: "ok" }, pathOnly: true, expectedDefault: "codex" },
+    { name: "dual", providers: { claude: "ok", codex: "ok" }, expectedDefault: "claude" },
+    { name: "explicit-codex", providers: { claude: "ok", codex: "ok" }, defaultProvider: "codex", expectedDefault: "codex" },
+    { name: "neither", providers: {}, expectedDefault: null },
+    { name: "missing-executable", providers: { claude: "missing" }, expectedDefault: null },
+    { name: "incompatible", providers: { claude: "incompatible" }, expectedDefault: null },
+    { name: "unauthenticated", providers: { codex: "unauthenticated" }, expectedDefault: "codex", expectedAuth: "unauthenticated" },
+    { name: "disappearing", providers: { claude: "ok" }, expectedDefault: "claude", disappear: "claude" },
+  ];
+
+  const setupApi = require("./setup");
+  const resumed = setupApi.upgradeSetupState({
+    completedSteps: ["prerequisites", "telegram"],
+    data: { claudePath: "/legacy/claude" },
+  });
+  assert.ok(!resumed.completedSteps.includes("prerequisites"), "legacy setup state must revisit provider discovery");
+  assert.ok(resumed.completedSteps.includes("telegram"), "unrelated completed setup steps are preserved");
+
+  for (const scenario of scenarios) {
+    const temp = fs.mkdtempSync(path.join(os.tmpdir(), `open-claudia-boot-${scenario.name}-`));
+    const home = path.join(temp, "home");
+    const configDir = path.join(temp, "config");
+    const workspace = path.join(temp, "workspace");
+    const binDir = path.join(temp, "bin");
+    const commandLog = path.join(temp, "provider-commands.jsonl");
+    fs.mkdirSync(home);
+    fs.mkdirSync(configDir);
+    fs.mkdirSync(workspace);
+    fs.mkdirSync(binDir);
+
+    const envLines = [
+      "CHANNELS=",
+      "TELEGRAM_BOT_TOKEN=fixture-token",
+      "TELEGRAM_CHAT_ID=fixture-chat",
+      `WORKSPACE=${workspace}`,
+    ];
+    for (const providerId of ["claude", "codex"]) {
+      const mode = scenario.providers[providerId];
+      if (!mode) continue;
+      const envKey = providerId === "claude" ? "CLAUDE_PATH" : "CODEX_PATH";
+      if (mode === "missing") {
+        envLines.push(`${envKey}=${path.join(binDir, `${providerId}-missing`)}`);
+        continue;
+      }
+      const executable = path.join(binDir, providerId);
+      writeProviderCli(executable, providerId, mode, commandLog);
+      if (!scenario.pathOnly) envLines.push(`${envKey}=${executable}`);
+    }
+    if (scenario.defaultProvider) envLines.push(`DEFAULT_PROVIDER=${scenario.defaultProvider}`);
+    fs.writeFileSync(path.join(configDir, ".env"), `${envLines.join("\n")}\n`);
+
+    const child = spawnSync(process.execPath, [__filename, "--probe"], {
+      cwd: root,
+      env: {
+        HOME: home,
+        PATH: [binDir, path.dirname(process.execPath), "/usr/bin", "/bin"].join(path.delimiter),
+        OPEN_CLAUDIA_CONFIG_DIR: configDir,
+        OPEN_CLAUDIA_TEST: "1",
+        WEB_PORT: "0",
+        DISAPPEAR_PROVIDER: scenario.disappear || "",
+      },
+      encoding: "utf8",
+      timeout: 30000,
+    });
+
+    try {
+      assert.ifError(child.error);
+      assert.strictEqual(child.status, 0, child.stderr || child.stdout);
+      const marker = child.stdout.split(/\r?\n/).find((line) => line.startsWith("BOOT_MATRIX:"));
+      assert.ok(marker, `${scenario.name}: missing boot-matrix output`);
+      const output = JSON.parse(marker.slice("BOOT_MATRIX:".length));
+      assert.strictEqual(output.selection.providerId, scenario.expectedDefault, `${scenario.name}: deterministic default`);
+      assert.strictEqual(output.stateProvider, scenario.expectedDefault, `${scenario.name}: fresh state adopts the default`);
+      assert.strictEqual(output.setupStatus.defaultProvider.providerId, scenario.expectedDefault, `${scenario.name}: terminal setup default`);
+      assert.strictEqual(output.webStatus.defaultProvider.providerId, scenario.expectedDefault, `${scenario.name}: web default`);
+      assert.strictEqual(output.healthStatus.providerSummary.defaultProvider.providerId, scenario.expectedDefault, `${scenario.name}: health default`);
+
+      for (const providerId of ["claude", "codex"]) {
+        const expectedMode = scenario.providers[providerId];
+        const setupProvider = output.setupStatus.providers.find((entry) => entry.id === providerId);
+        const webProvider = output.webStatus.providers.find((entry) => entry.id === providerId);
+        assert.ok(setupProvider && webProvider, `${scenario.name}: ${providerId} must be enumerated`);
+        assert.strictEqual(webProvider.availability.state, setupProvider.availability.state);
+        if (expectedMode === "missing") assert.strictEqual(setupProvider.availability.state, "missing");
+        else if (!expectedMode) assert.strictEqual(setupProvider.availability.state, "unconfigured");
+        else assert.strictEqual(setupProvider.availability.state, "available");
+        if (expectedMode === "incompatible") assert.strictEqual(setupProvider.compatibility.state, "incompatible");
+        if (providerId === scenario.expectedDefault && scenario.expectedAuth) {
+          assert.strictEqual(setupProvider.auth.state, scenario.expectedAuth);
+        }
+      }
+
+      const doctorLabels = output.doctorChecks.map((check) => check.label);
+      assert.ok(doctorLabels.includes("Claude Code availability"), `${scenario.name}: doctor enumerates Claude`);
+      assert.ok(doctorLabels.includes("OpenAI Codex availability"), `${scenario.name}: doctor enumerates Codex`);
+      assert.ok(doctorLabels.includes("Default provider"), `${scenario.name}: doctor reports the default choice`);
+
+      if (scenario.disappear) {
+        assert.strictEqual(output.afterDisappear.status.availability.state, "missing");
+        assert.strictEqual(output.afterDisappear.selection.providerId, null);
+        assert.strictEqual(output.afterDisappear.runError, "PROVIDER_UNAVAILABLE");
+      }
+      if (!scenario.expectedDefault) {
+        assert.strictEqual(output.noProviderTurn.admissionCode, "NO_AVAILABLE_PROVIDER");
+        assert.strictEqual(output.noProviderTurn.delivered.error.code, "NO_AVAILABLE_PROVIDER");
+        assert.strictEqual(output.noProviderTurn.sent.length, 1, `${scenario.name}: no-provider error is user-visible`);
+      }
+
+      const commands = readCommandLog(commandLog);
+      assert.ok(commands.every(isLocalStatusProbe), `${scenario.name}: health/setup invoked a model prompt: ${JSON.stringify(commands)}`);
+    } finally {
+      fs.rmSync(temp, { recursive: true, force: true });
+    }
+  }
+
+  const webTemp = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-web-boot-"));
+  try {
+    const configDir = path.join(webTemp, "new-config");
+    const home = path.join(webTemp, "home");
+    const binDir = path.join(webTemp, "bin");
+    const workspace = path.join(webTemp, "workspace");
+    const commandLog = path.join(webTemp, "provider-commands.jsonl");
+    fs.mkdirSync(home);
+    fs.mkdirSync(binDir);
+    const codexPath = path.join(binDir, "codex");
+    writeProviderCli(codexPath, "codex", "ok", commandLog);
+    const webChild = spawnSync(process.execPath, [__filename, "--web-http-probe"], {
+      cwd: root,
+      env: {
+        HOME: home,
+        PATH: [binDir, path.dirname(process.execPath), "/usr/bin", "/bin"].join(path.delimiter),
+        OPEN_CLAUDIA_CONFIG_DIR: configDir,
+        OPEN_CLAUDIA_TEST: "1",
+        WEB_PORT: "0",
+        WEB_PASSWORD: "FixturePass1!",
+        WEB_FIXTURE_CODEX: codexPath,
+        WEB_FIXTURE_WORKSPACE: workspace,
+      },
+      encoding: "utf8",
+      timeout: 30000,
+    });
+    assert.ifError(webChild.error);
+    assert.strictEqual(webChild.status, 0, webChild.stderr || webChild.stdout);
+    const marker = webChild.stdout.split(/\r?\n/).find((line) => line.startsWith("WEB_HTTP:"));
+    assert.ok(marker, "fresh web startup must complete HTTP setup probe");
+    const output = JSON.parse(marker.slice("WEB_HTTP:".length));
+    assert.strictEqual(output.setup.ok, true);
+    assert.strictEqual(output.status.defaultProvider.providerId, "codex", "web setup refreshes cached default status");
+    assert.strictEqual(output.status.providers.find((provider) => provider.id === "codex").availability.state, "available");
+    assert.strictEqual(output.configUpdate.ok, true, "web config POST is reachable");
+    assert.strictEqual(output.config.UTILITY_PROVIDER, "codex");
+    assert.strictEqual(output.config.DREAM_PROVIDER, "codex");
+    assert.strictEqual(output.soulUpdate.ok, true, "web soul POST is reachable");
+    assert.match(output.soul.content, /Provider-neutral fixture soul/);
+    assert.strictEqual(output.envMode, 0o600, "web config is private");
+    assert.ok(readCommandLog(commandLog).every(isLocalStatusProbe), "web setup/status must not invoke a model prompt");
+  } finally {
+    fs.rmSync(webTemp, { recursive: true, force: true });
+  }
+
+  console.log("provider boot matrix OK");
+}