@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/pack-review.js

@@ -6,7 +6,9 @@
 // mutation is announced in chat (one line), per the no-silent-learning
 // rule.
 
-const { spawnSubagent } = require("./subagent");
+const crypto = require("crypto");
+const { spawnUtilityAgent, cancelUtilityAgents } = require("./utility-agent");
+const { memoryMutationQueue } = require("./memory-mutation-queue");
 const packs = require("./packs");
 const entities = require("./entities");
 const lessons = require("./lessons");
@@ -15,15 +17,21 @@ const { redactSensitive } = require("./redact");
 
 const MIN_TURN_CHARS = 400;
 const MAX_TEXT_CHARS = 16000;
-// Create/merge decisions need real judgement (the cheap model over-created
-// per-version/per-facet packs), so default to the latest Sonnet. Override with
-// PACK_REVIEW_MODEL if cost/latency of running it on every substantial turn matters.
-const REVIEW_MODEL = process.env.PACK_REVIEW_MODEL || "claude-sonnet-4-6";
 const MAX_ACTIONS = 2;
 const MAX_ENTITY_ACTIONS = 3;
 // Lessons are precious always-on budget — at most one promotion per turn,
 // and only when the turn shows a genuine miss.
 const MAX_LESSON_ACTIONS = 1;
+const REVIEW_OUTPUT_SCHEMA = Object.freeze({
+  type: "object",
+  required: ["actions", "entities", "lessons"],
+  additionalProperties: false,
+  properties: {
+    actions: { type: "array", items: { type: "object" } },
+    entities: { type: "array", items: { type: "object" } },
+    lessons: { type: "array", items: { type: "object" } },
+  },
+});
 
 function enabled() {
   return (process.env.PACK_REVIEW || "on").toLowerCase() !== "off";
@@ -381,8 +389,9 @@ function shouldSkipReview({ userText, assistantText, signals = {} }) {
   return null;
 }
 
-// Fire-and-forget. `announce` is an async (text) => void bound to the
-// originating channel; failures are logged, never thrown into the turn.
+// Callers may hand this off without awaiting it, but each review stays tracked
+// until model, serialized mutation, and announcement settlement. Announcement
+// failures never escape into the foreground turn.
 // Provenance (2.5): stamp appended Log/Journal lines with the contributing
 // person when they're NOT the owner. The owner is the default author, so
 // tagging their contributions would be pure noise — the signal is precisely
@@ -393,100 +402,298 @@ function provenanceTag(source) {
   return `(via ${String(source.name).trim()}) `;
 }
 
-function reviewTurn({ userText, assistantText, channelId, announce, signals, activePacks, source }) {
-  if (!enabled()) return;
-  const skip = shouldSkipReview({ userText, assistantText, signals });
-  if (skip) {
-    if (skip !== "short") { // count only the new gate's savings, not the old floor
-      try { require("./recall/metrics").logReviewerSkip(); } catch (e) {}
+function contentVersion(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(value ?? null)).digest("hex");
+}
+
+function snapshotMemoryVersions() {
+  const packVersions = {};
+  const entityVersions = {};
+  try {
+    for (const pack of packs.listPacks()) packVersions[pack.dir] = contentVersion(pack);
+  } catch (_) {}
+  try {
+    for (const entity of entities.listEntities()) entityVersions[entity.slug] = contentVersion(entity);
+  } catch (_) {}
+  return { packs: packVersions, entities: entityVersions };
+}
+
+function unchangedPack(dir, versions) {
+  const known = Object.prototype.hasOwnProperty.call(versions?.packs || {}, dir);
+  if (!known) {
+    try { return packs.readPack(dir) === null; }
+    catch (_) { return false; }
+  }
+  const expected = versions.packs[dir];
+  try { return contentVersion(packs.readPack(dir)) === expected; }
+  catch (_) { return false; }
+}
+
+function safeEntityAction(action, versions) {
+  let existing = null;
+  try { existing = entities.findEntity(action?.name); } catch (_) {}
+  if (!existing) return action;
+  const known = Object.prototype.hasOwnProperty.call(versions?.entities || {}, existing.slug);
+  const expected = known ? versions.entities[existing.slug] : null;
+  if (known && contentVersion(existing) === expected) return action;
+  // A dream or another review changed this entity while the model was
+  // deciding. Keep the append-only observation, but never replace newer
+  // current-truth/persona sections with a stale proposal.
+  return {
+    name: action.name,
+    type: action.type || existing.type,
+    log: action.log || "",
+  };
+}
+
+function applyDecisionBatch({ decision, activePacks, versions, source }) {
+  const activeSet = new Set(Array.isArray(activePacks) ? activePacks : []);
+  for (const dir of [...activeSet]) if (!unchangedPack(dir, versions)) activeSet.delete(dir);
+  const lines = [];
+  const usedIds = [];
+  const errors = [];
+  const tag = provenanceTag(source);
+
+  for (const original of decision.actions) {
+    const action = structuredClone(original);
+    try {
+      if (tag && typeof action.journal === "string" && action.journal.trim()) action.journal = tag + action.journal.trim();
+      const result = applyAction(action, activeSet);
+      if (result && (result.kind === "update" || result.kind === "create") && result.dir) usedIds.push(`pack:${result.dir}`);
+      if (result?.kind === "skipped") {
+        lines.push(`🛡️ Skipped a memory write that looked like an injected instruction (${result.reason}).`);
+      } else if (result?.kind === "create" && result.ability) {
+        lines.push(`🧩 New ability: ${result.name}${result.learned_on ? ` (learned on ${result.learned_on})` : ""}\n${clipWords(result.note, 180)}\n↳ open-claudia pack show ${result.dir}`);
+      } else if (result?.kind === "create") {
+        lines.push(`📦 New pack: ${result.name}${result.parent ? ` (filed under ${result.parent})` : ""}\n${clipWords(result.note, 180)}\n↳ open-claudia pack show ${result.dir}`);
+      } else if (result) {
+        const marks = [];
+        if (result.appliedTo) marks.push(` 🧩 (now also applies to ${result.appliedTo})`);
+        if (result.overwroteUserState) marks.push(" ⚠️ replaced a user-written State — check it kept your facts");
+        if (result.blindSkipped) marks.push(" (section rewrite dropped: pack wasn't active or changed while review was pending — journal only)");
+        lines.push(`✏️ ${result.name} — ${clipWords(result.note, 180)}${marks.join("")}\n↳ open-claudia pack show ${result.dir}`);
+      }
+    } catch (error) {
+      errors.push(error);
+      console.warn(`[pack-review] apply failed: ${error.message}`);
     }
-    return;
   }
 
-  const activeSet = Array.isArray(activePacks) && activePacks.length ? new Set(activePacks) : null;
-  const prompt = buildReviewPrompt(redactSensitive(String(userText || "")), redactSensitive(String(assistantText || "")), activePacks);
-
-  spawnSubagent(prompt, {
-    model: REVIEW_MODEL,
-    channelId,
-    timeoutMs: 3 * 60 * 1000,
-    systemPrompt: "You are a background memory reviewer. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
-  }).then(({ text }) => {
-    const decision = parseDecision(text);
-    if (!decision || (decision.actions.length === 0 && decision.entities.length === 0 && (decision.lessons || []).length === 0)) return;
-    const lines = [];
-    const usedIds = []; // nodes this turn's work demonstrably touched
-    const tag = provenanceTag(source);
-    for (const a of decision.actions) {
-      try {
-        if (tag && typeof a.journal === "string" && a.journal.trim()) a.journal = tag + a.journal.trim();
-        const r = applyAction(a, activeSet);
-        if (r && (r.kind === "update" || r.kind === "create") && r.dir) usedIds.push(`pack:${r.dir}`);
-        if (r && r.kind === "skipped") {
-          lines.push(`🛡️ Skipped a memory write that looked like an injected instruction (${r.reason}).`);
-        } else if (r && r.kind === "create" && r.ability) {
-          lines.push(`🧩 New ability: ${r.name}${r.learned_on ? ` (learned on ${r.learned_on})` : ""}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
-        } else if (r && r.kind === "create") {
-          lines.push(`📦 New pack: ${r.name}${r.parent ? ` (filed under ${r.parent})` : ""}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
-        } else if (r) {
-          const marks = [];
-          if (r.appliedTo) marks.push(` 🧩 (now also applies to ${r.appliedTo})`);
-          if (r.overwroteUserState) marks.push(" ⚠️ replaced a user-written State — check it kept your facts");
-          if (r.blindSkipped) marks.push(" (section rewrite dropped: pack wasn't active this turn — journal only)");
-          lines.push(`✏️ ${r.name} — ${clipWords(r.note, 180)}${marks.join("")}\n↳ open-claudia pack show ${r.dir}`);
-        }
-      } catch (e) {
-        console.warn(`[pack-review] apply failed: ${e.message}`);
+  for (const original of decision.entities) {
+    const action = structuredClone(original);
+    try {
+      if (tag && typeof action.log === "string" && action.log.trim()) action.log = tag + action.log.trim();
+      const result = applyEntityAction(safeEntityAction(action, versions));
+      if (result) {
+        if (result.slug) usedIds.push(`entity:${result.slug}`);
+        const emoji = ENTITY_EMOJI[result.type] || ENTITY_EMOJI.thing;
+        lines.push(result.kind === "create"
+          ? `${emoji} Now tracking ${result.name} (${result.type}) — ${clipWords(result.note, 160)}`
+          : `${emoji} ${result.name} — ${clipWords(result.note, 160)}`);
       }
+    } catch (error) {
+      errors.push(error);
+      console.warn(`[pack-review] entity apply failed: ${error.message}`);
     }
-    for (const ea of decision.entities) {
-      try {
-        if (tag && typeof ea.log === "string" && ea.log.trim()) ea.log = tag + ea.log.trim();
-        const r = applyEntityAction(ea);
-        if (r) {
-          if (r.slug) usedIds.push(`entity:${r.slug}`);
-          const emoji = ENTITY_EMOJI[r.type] || ENTITY_EMOJI.thing;
-          lines.push(r.kind === "create"
-            ? `${emoji} Now tracking ${r.name} (${r.type}) — ${clipWords(r.note, 160)}`
-            : `${emoji} ${r.name} — ${clipWords(r.note, 160)}`);
+  }
+
+  if (usedIds.length) {
+    try { require("./recall/metrics").logUse(usedIds, "reviewer"); } catch (_) {}
+    try { if (usedIds.length > 1) require("./recall/graph").reinforceSet(usedIds); } catch (_) {}
+  }
+
+  for (const original of decision.lessons || []) {
+    try {
+      const result = applyLessonAction(structuredClone(original));
+      if (!result) continue;
+      if (result.kind === "skipped") {
+        if (result.reason && /exfil|override|base64/.test(result.reason)) {
+          lines.push(`🛡️ Skipped a lesson that looked like an injected instruction (${result.reason}).`);
         }
-      } catch (e) {
-        console.warn(`[pack-review] entity apply failed: ${e.message}`);
+      } else if (result.kind === "create") {
+        lines.push(`📌 New lesson — I got this wrong before, so I'll always keep it loaded now:\n"${clipWords(result.text, 200)}"${result.overCap ? "\n(That's over the lessons cap — the nightly dream will tidy.)" : ""}`);
+      } else if (result.kind === "reinforce") {
+        lines.push(`📌 Reinforced a lesson I keep needing — clearly worth keeping front of mind:\n"${clipWords(result.text, 200)}"`);
       }
+    } catch (error) {
+      errors.push(error);
+      console.warn(`[pack-review] lesson apply failed: ${error.message}`);
+    }
+  }
+
+  if (errors.length) {
+    const error = new AggregateError(errors, `${errors.length} memory review mutation(s) failed`);
+    error.applied = { lines, usedIds };
+    throw error;
+  }
+  return { lines, usedIds };
+}
+
+function reviewerMetric(entry) {
+  try { require("./recall/metrics").logReviewerRun(entry); } catch (_) {}
+}
+
+function createPackReviewer(dependencies = {}) {
+  const runUtility = dependencies.spawnUtilityAgent || spawnUtilityAgent;
+  const queue = dependencies.mutationQueue || memoryMutationQueue;
+  const cancelUtilities = dependencies.cancelUtilityAgents || cancelUtilityAgents;
+  const handles = new Map();
+  let accepting = true;
+
+  function track(promise, metadata) {
+    const id = typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
+    handles.set(id, { id, promise, ...metadata });
+    promise.then(() => handles.delete(id), () => handles.delete(id));
+    return promise;
+  }
+
+  function reviewTurn({ userText, assistantText, channelId, announce, signals, activePacks, source, provider, runId } = {}) {
+    if (!enabled()) return Promise.resolve({ status: "skipped", reason: "disabled" });
+    const skip = shouldSkipReview({ userText, assistantText, signals });
+    if (skip) {
+      if (skip !== "short") { try { require("./recall/metrics").logReviewerSkip(); } catch (_) {} }
+      return Promise.resolve({ status: "skipped", reason: skip });
     }
-    // Weak-use signal: the reviewer deciding a pack/entity needed updating is
-    // evidence the turn genuinely worked on that node — use, observed after
-    // the fact, even when the agent never re-opened the note (it may already
-    // have been injected). Feeds the same precision metric as 📖 opens and
-    // reinforces co-use edges. This is co-WORK, never co-recall — surfacing
-    // alone still reinforces nothing.
-    if (usedIds.length) {
-      try { require("./recall/metrics").logUse(usedIds, "reviewer"); } catch (e) {}
-      try { if (usedIds.length > 1) require("./recall/graph").reinforceSet(usedIds); } catch (e) {}
+    if (!accepting) {
+      queue.record({ id: null, label: "review", status: "pending_intent_rejected", provider: provider || null, runId: runId || null });
+      return Promise.resolve({ status: "not_admitted", reason: "review shutdown in progress" });
     }
-    for (const la of (decision.lessons || [])) {
+
+    const capturedProvider = provider || null;
+    const versions = snapshotMemoryVersions();
+    const prompt = buildReviewPrompt(
+      redactSensitive(String(userText || "")),
+      redactSensitive(String(assistantText || "")),
+      activePacks,
+    );
+    const work = (async () => {
+      let utilityResult = null;
       try {
-        const r = applyLessonAction(la);
-        if (!r) continue;
-        if (r.kind === "skipped") {
-          if (r.reason && /exfil|override|base64/.test(r.reason)) {
-            lines.push(`🛡️ Skipped a lesson that looked like an injected instruction (${r.reason}).`);
-          }
-        } else if (r.kind === "create") {
-          lines.push(`📌 New lesson — I got this wrong before, so I'll always keep it loaded now:\n"${clipWords(r.text, 200)}"${r.overCap ? "\n(That's over the lessons cap — the nightly dream will tidy.)" : ""}`);
-        } else if (r.kind === "reinforce") {
-          lines.push(`📌 Reinforced a lesson I keep needing — clearly worth keeping front of mind:\n"${clipWords(r.text, 200)}"`);
+        utilityResult = await runUtility(prompt, {
+          purpose: "review",
+          activeProvider: capturedProvider,
+          tier: "medium",
+          modelEnvPrefix: "PACK_REVIEW_MODEL",
+          legacyClaudeModelEnv: "PACK_REVIEW_MODEL",
+          readOnly: true,
+          outputSchema: REVIEW_OUTPUT_SCHEMA,
+          timeoutMs: 3 * 60 * 1000,
+          cwd: process.cwd(),
+          systemPrompt: "You are a background memory reviewer. Reply with ONLY the requested JSON object. No prose, no markdown, no tool use.",
+        });
+        const decision = parseDecision(utilityResult.json ? JSON.stringify(utilityResult.json) : utilityResult.text);
+        if (!decision || (decision.actions.length === 0 && decision.entities.length === 0 && decision.lessons.length === 0)) {
+          reviewerMetric({ provider: utilityResult.provider, model: utilityResult.model, status: "no_change", fallbackUsed: utilityResult.fallbackUsed });
+          return { status: "no_change", provider: utilityResult.provider, model: utilityResult.model, fallbackUsed: !!utilityResult.fallbackUsed };
+        }
+        const applied = await queue.enqueue("review", () => applyDecisionBatch({
+          decision,
+          activePacks,
+          versions,
+          source,
+        }), {
+          provider: utilityResult.provider,
+          model: utilityResult.model,
+          purpose: "review",
+          runId,
+        });
+        let announcementFailed = false;
+        if (applied.lines.length && typeof announce === "function") {
+          try { await announce(formatAnnouncement(applied.lines)); }
+          catch (_) { announcementFailed = true; }
+        }
+        reviewerMetric({ provider: utilityResult.provider, model: utilityResult.model, status: "applied", fallbackUsed: utilityResult.fallbackUsed });
+        return {
+          status: "applied",
+          provider: utilityResult.provider,
+          model: utilityResult.model,
+          fallbackUsed: !!utilityResult.fallbackUsed,
+          lines: applied.lines,
+          announcementFailed,
+        };
+      } catch (error) {
+        const resolvedProvider = utilityResult?.provider || capturedProvider || "";
+        const partialLines = error.applied?.lines || [];
+        let announcementFailed = false;
+        if (partialLines.length && typeof announce === "function") {
+          try { await announce(formatAnnouncement(partialLines)); }
+          catch (_) { announcementFailed = true; }
         }
-      } catch (e) {
-        console.warn(`[pack-review] lesson apply failed: ${e.message}`);
+        reviewerMetric({ provider: resolvedProvider, model: utilityResult?.model || "", status: "failed", code: error.code || "REVIEW_FAILED" });
+        console.warn(`[pack-review] reviewer failed: ${error.message}`);
+        return {
+          status: "failed",
+          provider: resolvedProvider || null,
+          model: utilityResult?.model || null,
+          lines: partialLines,
+          announcementFailed,
+          error: { code: error.code || "REVIEW_FAILED", message: redactSensitive(error.message) },
+        };
       }
+    })();
+    return track(work, { provider: capturedProvider, channelId: channelId || null, runId: runId || null });
+  }
+
+  function stopAdmission(reason = "shutdown") {
+    accepting = false;
+    queue.record({ id: null, label: "review", status: "review_admission_stopped", reason: String(reason).slice(0, 160) });
+  }
+
+  async function drainReviews({ timeoutMs = 5000, cancelOnTimeout = false } = {}) {
+    stopAdmission("shutdown drain");
+    queue.stopAdmission("shutdown drain");
+    const snapshot = [...handles.values()];
+    let timer;
+    const settled = Promise.allSettled(snapshot.map((handle) => handle.promise)).then(() => true);
+    const drained = await Promise.race([
+      settled,
+      new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); }),
+    ]);
+    clearTimeout(timer);
+    if (!drained) {
+      for (const handle of snapshot.filter((entry) => handles.has(entry.id))) {
+        queue.record({ id: handle.id, label: "review", status: "pending_on_shutdown", provider: handle.provider, runId: handle.runId });
+      }
+      if (cancelOnTimeout && typeof cancelUtilities === "function") await cancelUtilities({ timeoutMs });
     }
-    if (lines.length > 0 && typeof announce === "function") {
-      announce(formatAnnouncement(lines)).catch(() => {});
+    let queueResult = await queue.drain({ timeoutMs });
+    if (!queueResult.drained && cancelOnTimeout && typeof cancelUtilities === "function") {
+      await cancelUtilities({ timeoutMs });
+      queueResult = await queue.drain({ timeoutMs });
     }
-  }).catch((e) => {
-    console.warn(`[pack-review] reviewer failed: ${e.message}`);
-  });
+    return {
+      drained: drained && queueResult.drained,
+      pendingReviews: [...handles.values()].map(({ id, provider: providerId, runId: reviewRunId }) => ({ id, provider: providerId, runId: reviewRunId })),
+      pendingMutations: queueResult.pending,
+    };
+  }
+
+  return {
+    activeReviewCount: () => handles.size,
+    drainReviews,
+    reviewTurn,
+    stopAdmission,
+  };
 }
 
-module.exports = { reviewTurn, shouldSkipReview, parseDecision, applyAction, applyEntityAction, applyLessonAction, buildReviewPrompt, clipWords, provenanceTag, ENTITY_EMOJI };
+const defaultReviewer = createPackReviewer();
+
+module.exports = {
+  ENTITY_EMOJI,
+  REVIEW_OUTPUT_SCHEMA,
+  applyAction,
+  applyDecisionBatch,
+  applyEntityAction,
+  applyLessonAction,
+  buildReviewPrompt,
+  clipWords,
+  contentVersion,
+  createPackReviewer,
+  drainReviews: defaultReviewer.drainReviews,
+  parseDecision,
+  provenanceTag,
+  reviewTurn: defaultReviewer.reviewTurn,
+  shouldSkipReview,
+  snapshotMemoryVersions,
+  stopReviewAdmission: defaultReviewer.stopAdmission,
+};

package/core/packs.js

@@ -11,6 +11,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { atomicWriteFileSync } = require("./fsutil");
 
 let DatabaseSync = null;
 try { ({ DatabaseSync } = require("node:sqlite")); } catch (e) { /* old node — matching disabled */ }
@@ -246,7 +247,7 @@ function writePack(pack) {
   ensureDir();
   const dir = path.join(PACKS_DIR, pack.dir);
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  fs.writeFileSync(packFile(pack.dir), serialize(pack), { mode: 0o600 });
+  atomicWriteFileSync(packFile(pack.dir), serialize(pack), { mode: 0o600, backup: true });
   markIndexDirty();
   return pack.dir;
 }
@@ -313,7 +314,7 @@ function setProvenance(dir, sectionNames, origin) {
   cur.ts = new Date().toISOString();
   try {
     fs.mkdirSync(path.join(PACKS_DIR, dir), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(provFile(dir), JSON.stringify(cur, null, 2), { mode: 0o600 });
+    atomicWriteFileSync(provFile(dir), JSON.stringify(cur, null, 2), { mode: 0o600, backup: true });
   } catch (e) {}
 }
 
@@ -465,7 +466,7 @@ function archivePack(nameOrDir) {
   ensureDir();
   fs.mkdirSync(archiveRoot(), { recursive: true, mode: 0o700 });
   pack.archived = new Date().toISOString();
-  try { fs.writeFileSync(packFile(pack.dir), serialize(pack), { mode: 0o600 }); } catch (e) {}
+  try { atomicWriteFileSync(packFile(pack.dir), serialize(pack), { mode: 0o600, backup: true }); } catch (e) {}
   const dest = path.join(archiveRoot(), pack.dir);
   fs.rmSync(dest, { recursive: true, force: true });
   fs.renameSync(path.join(PACKS_DIR, pack.dir), dest);

package/core/persona.js

@@ -7,6 +7,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { atomicWriteFileSync } = require("./fsutil");
 
 const CONFIG_DIR = require("../config-dir");
 const PERSONA_FILE = process.env.PERSONA_FILE ? path.resolve(process.env.PERSONA_FILE) : path.join(CONFIG_DIR, "persona.md");
@@ -40,7 +41,7 @@ function savePersona(text) {
     throw new Error(`persona must be ${MIN_PERSONA_CHARS}-${MAX_PERSONA_CHARS} chars (got ${t.length})`);
   }
   fs.mkdirSync(path.dirname(PERSONA_FILE), { recursive: true, mode: 0o700 });
-  fs.writeFileSync(PERSONA_FILE, t + "\n", { mode: 0o600 });
+  atomicWriteFileSync(PERSONA_FILE, t + "\n", { mode: 0o600, backup: true });
   return PERSONA_FILE;
 }
 

package/core/process-tree.js

@@ -28,13 +28,30 @@ function descendantPids(rootPid) {
 }
 
 function killProcessTree(rootPid, signal = "SIGTERM") {
-  if (!rootPid) return;
+  if (!rootPid) return [];
   const descendants = descendantPids(rootPid);
   try { process.kill(-rootPid, signal); } catch (e) {}
   try { process.kill(rootPid, signal); } catch (e) {}
   for (const pid of descendants) {
     try { process.kill(pid, signal); } catch (e) {}
   }
+  return descendants;
 }
 
-module.exports = { descendantPids, killProcessTree };
+function pidExists(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === "EPERM"; }
+}
+
+async function waitForPidsExit(pids, timeoutMs = 1000) {
+  const pending = new Set((pids || []).map(Number).filter((pid) => Number.isSafeInteger(pid) && pid > 0));
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (pending.size) {
+    for (const pid of pending) if (!pidExists(pid)) pending.delete(pid);
+    if (!pending.size || Date.now() >= deadline) break;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  return [...pending];
+}
+
+module.exports = { descendantPids, killProcessTree, waitForPidsExit };

package/core/provider-migration.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const {
+  defaultMigrationSources,
+  ensureMigrationSnapshot,
+  requireProviderRemovalReady,
+} = require("./migration-backup");
+
+function completeProviderMigration(options = {}) {
+  const runtime = options.runtime || require("./config");
+  const configDir = options.configDir || runtime.CONFIG_DIR;
+  const sources = options.sources || defaultMigrationSources({
+    configDir,
+    stateFile: options.stateFile || runtime.STATE_FILE,
+    sessionsFile: options.sessionsFile || runtime.SESSIONS_FILE,
+    jobsFile: options.jobsFile || runtime.JOBS_FILE,
+    cronsFile: options.cronsFile || runtime.CRONS_FILE,
+  });
+  const snapshot = options.snapshot || ensureMigrationSnapshot({ configDir, sources });
+
+  // Load persistence modules only after the byte-for-byte rollback snapshot is
+  // durable. Each save owns its prepare -> atomic write -> verify -> activate
+  // cycle, so an interrupted run resumes safely on the next startup.
+  const state = options.stateApi || require("./state");
+  const jobs = options.jobsApi || require("./jobs");
+  state.saveState({ strict: true });
+  state.saveSessions(state.loadSessions(), { strict: true });
+  jobs.ensureMigrated({ strict: true });
+
+  const ready = requireProviderRemovalReady({ configDir, sources });
+  return {
+    snapshotDir: ready.snapshotDir,
+    stage: ready.journal.stage,
+    components: ready.journal.components,
+    reusedSnapshot: snapshot.reused === true,
+  };
+}
+
+module.exports = { completeProviderMigration };

package/core/provider-status.js

@@ -0,0 +1,80 @@
+"use strict";
+
+const config = require("./config");
+const defaultRegistry = require("./providers");
+
+function recoveryFor(provider, status) {
+  if (status.availability.state === "unconfigured") {
+    return `Install ${provider.label}, or configure ${provider.id === "claude" ? "CLAUDE_PATH" : "CODEX_PATH"}.`;
+  }
+  if (status.availability.state === "missing") {
+    return `Fix ${provider.id === "claude" ? "CLAUDE_PATH" : "CODEX_PATH"}, or remove it to use PATH discovery.`;
+  }
+  if (status.compatibility.state === "incompatible") {
+    return `Update ${provider.label}: ${status.compatibility.reason || "the installed CLI is incompatible"}`;
+  }
+  if (status.compatibility.state !== "compatible") {
+    return `Could not confirm ${provider.label} compatibility: ${status.compatibility.reason || "local probe failed"}`;
+  }
+  if (status.auth.state === "unauthenticated") return provider.authHelp();
+  if (status.auth.state === "unknown") {
+    return `Could not confirm ${provider.label} authentication: ${status.auth.reason || "local status probe failed"}`;
+  }
+  return null;
+}
+
+function inspectProviderConfiguration(options = {}) {
+  const registry = options.registry || defaultRegistry;
+  const preferred = options.defaultProvider === undefined
+    ? config.DEFAULT_PROVIDER
+    : options.defaultProvider;
+  const executableStatus = options.executableStatus || ((providerId) => (
+    config.providerExecutableStatus(providerId, options.env || process.env)
+  ));
+  const probeAuth = options.probeAuth !== false;
+  const providers = registry.listProviders().map((provider) => {
+    const executable = executableStatus(provider.id);
+    if (executable.state !== "available") {
+      const status = {
+        id: provider.id,
+        label: provider.label,
+        configured: executable.configured === true,
+        availability: {
+          state: executable.state,
+          executable: null,
+          reason: executable.reason,
+        },
+        compatibility: { state: "not_checked", version: null, reason: "Provider executable is unavailable" },
+        auth: { state: "not_checked", reason: "Provider executable is unavailable" },
+      };
+      return { ...status, recovery: recoveryFor(provider, status) };
+    }
+    const registryStatus = registry.providerStatus(provider.id, { probeAuth });
+    const status = {
+      ...registryStatus,
+      configured: executable.configured === true,
+      availability: {
+        ...registryStatus.availability,
+        executable: executable.executable || registryStatus.availability.executable,
+      },
+    };
+    return { ...status, recovery: recoveryFor(provider, status) };
+  });
+  const selected = registry.selectDefaultProvider(preferred);
+  const selectedProvider = selected.providerId
+    ? providers.find((provider) => provider.id === selected.providerId)
+    : null;
+  return {
+    providers,
+    defaultProvider: {
+      ...selected,
+      label: selectedProvider?.label || null,
+      configuredValue: preferred || null,
+    },
+  };
+}
+
+module.exports = {
+  inspectProviderConfiguration,
+  recoveryFor,
+};