ennodia 0.4.1 → 0.5.0

package/src/harnesses.ts

@@ -1,6 +1,9 @@
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { signalOwnedProcess } from "./process";
 import { type Skill } from "./skills";
+import type { HarnessReadiness } from "./readiness";
 
 export type HarnessKind = "cli" | "app";
 
@@ -84,6 +87,8 @@ export type HarnessAdapter = {
   /** Whether the adapter supports manager-owned native session continuation. */
   supportsSessionContinuation?: boolean;
   buildCommand?: (commandPath: string, input: HarnessRunInput) => CommandSpec;
+  /** Extract only the final answer from structured readiness-probe output. */
+  readinessAnswer?: (stdout: string) => string | undefined;
   /** Best-effort usage extraction from a finished task's captured output. */
   extractUsage?: (stdout: string, stderr: string) => HarnessUsage | undefined;
   /** Extract a native session ID from captured stdout as it arrives. */
@@ -133,6 +138,7 @@ export type HarnessDiscovery = {
   capabilities: string[];
   notes: string[];
   inputGuidance?: string[];
+  readiness?: HarnessReadiness;
 };
 
 export type DiscoverHarnessesOptions = {
@@ -357,7 +363,8 @@ export const harnessAdapters: HarnessAdapter[] = [
     id: "hermes-agent",
     name: "Hermes Agent",
     kind: "cli",
-    commandCandidates: ["hermes-agent", "hermes"],
+    // hermes-agent is the legacy single-query runner, not the chat CLI.
+    commandCandidates: ["hermes"],
     versionArgs: ["--version"],
     capabilities: ["reasoning", "code", "agents", "non-interactive-cli"],
     notes: [
@@ -418,6 +425,18 @@ export const harnessAdapters: HarnessAdapter[] = [
     notes: [
       "Runs through `cline` with auto-approval explicitly disabled.",
     ],
+    readinessAnswer: (stdout) => {
+      // Public CLI JSON contract: docs/cli/cli-reference.mdx in cline/cline.
+      for (const line of stdout.trim().split(/\r?\n/).reverse()) {
+        try {
+          const event = JSON.parse(line);
+          if (event.type === "run_result") {
+            return event.finishReason !== "aborted" && typeof event.text === "string" ? event.text : undefined;
+          }
+        } catch { /* Ignore diagnostics outside the JSON result. */ }
+      }
+      return undefined;
+    },
     buildCommand: (commandPath, input) => {
       const args = ["--auto-approve", "false", "--json"];
 
@@ -627,7 +646,13 @@ async function discoverHarness(
 ): Promise<HarnessDiscovery> {
   const commandPath = adapter.commandCandidates
     .map((candidate) => Bun.which(candidate))
-    .find((match): match is string => Boolean(match));
+    .find((match): match is string => Boolean(match))
+    // GUI/MCP launches may omit native install roots; keep every existing PATH candidate first.
+    ?? (process.platform === "darwin" ? adapter.commandCandidates
+      .map((candidate) => Bun.which(candidate, {
+        PATH: ["/opt/homebrew/bin", "/usr/local/bin", join(homedir(), ".local", "bin")].join(":"),
+      }))
+      .find((match): match is string => Boolean(match)) : undefined);
 
   const appPath = adapter.appPaths?.find((path) => existsSync(path));
   let version: string | undefined;

package/src/history.ts

@@ -58,6 +58,8 @@ export class FileHistorySink implements HistorySink {
     this.maxRuns = Math.max(1, options.maxRuns ?? DEFAULT_HISTORY_MAX_RUNS);
   }
 
+  get storageDirectory(): string { return this.dir; }
+
   async recordRun(snapshot: RunHistorySnapshot): Promise<void> {
     await mkdir(this.dir, { recursive: true, mode: 0o700 });
     // Frame each append with a leading newline so a previous truncated record

package/src/index.ts

@@ -146,6 +146,7 @@ export {
   parseJudgeAnalysis,
   type CompareAnalysis,
   type AdvisorResult,
+  type KeepInMindNote,
   type CompareCandidate,
   type CompareCandidateInput,
   type CompareEvent,
@@ -176,6 +177,8 @@ export {
   type TaskOutputPreview,
 } from "./diagnosis";
 export { ENNODIA_VERSION } from "./version";
+export { inspectInstallation, MIN_BUN_VERSION, type InstallationReport, type InstallationScope, type InstallationCheck, type InstallationOptions } from "./installation";
+export { HarnessReadinessManager, HarnessReadinessError, readinessBlocked, harnessAttention, harnessUpgradeCommand, nativeReadinessFailure, type HarnessReadiness, type HarnessReadinessOptions, type HarnessAttention, type HarnessCheckInput, type PreflightReport, type ReadinessState, type MaintenanceCommandRunner } from "./readiness";
 export {
   discoverSkills,
   discoverSkillsWithWarnings,

package/src/installation.ts

@@ -0,0 +1,143 @@
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ENNODIA_VERSION } from "./version";
+
+export const MIN_BUN_VERSION = "1.3.14";
+export type InstallationScope = "source-checkout" | "project-local" | "global" | "cache" | "unknown";
+export type InstallationCheck = { id: string; status: "pass" | "warning" | "fail"; message: string };
+export type InstallationReport = {
+  checkedAt: string;
+  status: "healthy" | "limited" | "broken";
+  version: string;
+  packageVersion?: string;
+  distribution: "source" | "compiled";
+  scope: InstallationScope;
+  evidence: string;
+  codeRoot: string;
+  serverCwd: string;
+  launcher?: string;
+  runtime: { name: "bun" | "unsupported"; version?: string; executable: string; minimumVersion: string; platform: string; arch: string };
+  checks: InstallationCheck[];
+  storage: { temporaryDirectory: string; history: { enabled: boolean; directory?: string }; harnessUpdates: { enabled: boolean; directory: string } };
+  limitations: string[];
+};
+
+export type InstallationOptions = {
+  /** Defaults to the loaded module's location, never the caller's workspace. */
+  codeRoot?: string;
+  cwd?: string;
+  home?: string;
+  temporaryDirectory?: string;
+  env?: Record<string, string | undefined>;
+  bunVersion?: string | null;
+  history?: { enabled: boolean; directory?: string };
+  autoUpgrade?: boolean;
+  upgradeStateDirectory?: string;
+};
+
+/** Local, read-only evidence. Does not inspect credentials, contact registries,
+ * create directories, or call providers. Access checks do not prove disk capacity. */
+export function inspectInstallation(options: InstallationOptions = {}): InstallationReport {
+  const env = options.env ?? process.env;
+  const home = canonical(options.home ?? homedir());
+  const codeRoot = canonical(options.codeRoot ?? fileURLToPath(new URL("..", import.meta.url)));
+  const compiled = /(?:^|\/)\$bunfs(?:\/|$)/.test(codeRoot.replaceAll("\\", "/"));
+  const serverCwd = canonical(options.cwd ?? process.cwd());
+  const bunVersion = options.bunVersion === undefined ? process.versions.bun : options.bunVersion ?? undefined;
+  const temporaryDirectory = canonical(options.temporaryDirectory ?? tmpdir());
+  const historySetting = options.history ?? { enabled: env.ENNODIA_HISTORY !== "0", directory: env.ENNODIA_HISTORY_DIR ?? join(home, ".ennodia", "history") };
+  const history = { ...historySetting, directory: historySetting.directory ? resolve(historySetting.directory) : undefined };
+  const updates = { enabled: options.autoUpgrade ?? env.ENNODIA_AUTO_UPDATE !== "false", directory: resolve(options.upgradeStateDirectory ?? join(env.XDG_STATE_HOME ?? join(home, ".local", "state"), "ennodia", "harnesses")) };
+  const checks: InstallationCheck[] = [];
+  const add = (id: string, status: InstallationCheck["status"], message: string) => checks.push({ id, status, message });
+  add("runtime", bunVersion && atLeast(bunVersion, MIN_BUN_VERSION) ? "pass" : "fail", bunVersion ? `Bun ${bunVersion}; requires >=${MIN_BUN_VERSION}.` : `Bun >=${MIN_BUN_VERSION} is required.`);
+
+  const npm = readMetadata(join(codeRoot, "package.json"));
+  const jsr = readMetadata(join(codeRoot, "jsr.json"));
+  const metadata = npm?.name === "ennodia" ? npm : jsr?.name === "@cherninlab/ennodia" ? jsr : undefined;
+  const packageVersion = typeof metadata?.version === "string" ? metadata.version : undefined;
+  add("package-version", packageVersion === ENNODIA_VERSION ? "pass" : packageVersion ? "fail" : "warning", packageVersion ? `Metadata ${packageVersion}; loaded code ${ENNODIA_VERSION}.` : "Package metadata is unavailable; only the loaded code version is known.");
+
+  // JSR does not ship the npm launcher. Development tooling is not required.
+  const declaredModules = Array.isArray(npm?.files) ? npm.files.filter((p): p is string => typeof p === "string" && /^src\/[^/*]+\.ts$/.test(p)) : [];
+  const required = [...new Set(["src/index.ts", "src/core.ts", "src/cli.ts", "src/readiness.ts", "src/installation.ts", ...declaredModules, ...(npm?.name === "ennodia" ? ["bin/ennodia"] : [])])];
+  const missing = required.filter(p => !readableFile(join(codeRoot, p)));
+  add("runtime-files", compiled || !missing.length ? "pass" : "fail", compiled ? "Loaded core code is embedded in the executable; separate source entrypoints are not required." : missing.length ? `Missing or unreadable runtime files: ${missing.join(", ")}. Reinstall this distribution.` : "Core entrypoints and declared runtime modules are readable.");
+  const skillFiles = ["pragmatic", "compositional-audit"].map(id => join(codeRoot, "skills", id, "SKILL.md"));
+  add("bundled-skills", skillFiles.every(readableFile) ? "pass" : "warning", skillFiles.every(readableFile) ? "Bundled skills are readable." : "Bundled skills are incomplete; skill discovery or installation may be limited.");
+  const dependencies = ["@modelcontextprotocol/sdk/server/mcp.js", "zod"];
+  if (compiled) add("dependencies", "warning", "Executable uses bundled dependencies; separate dependency-file integrity cannot be checked.");
+  else {
+    const require = createRequire(join(codeRoot, "src/index.ts"));
+    const unresolved = dependencies.filter(id => { try { return !readableFile(require.resolve(id)); } catch { return true; } });
+    add("dependencies", unresolved.length ? "warning" : "pass", unresolved.length ? `Dependencies cannot be resolved from the code location: ${unresolved.join(", ")}. Install dependencies for this source distribution.` : "MCP dependencies resolve from the code location.");
+  }
+
+  const { scope, evidence } = installationScope(codeRoot, home, env);
+  if (scope === "unknown") add("installation-scope", "warning", "Global versus local scope could not be established from filesystem evidence.");
+  else add("installation-scope", "pass", evidence);
+  const temporaryAccessible = writableDirectory(temporaryDirectory, false);
+  add("temporary-storage", temporaryAccessible ? "pass" : "fail", `Temporary workspace directory ${temporaryDirectory}: ${temporaryAccessible ? "filesystem access available" : "directory missing or filesystem access unavailable"}.`);
+  if (history.enabled) {
+    const accessible = history.directory && writableDirectory(history.directory) && writableExistingFile(join(history.directory, "runs.jsonl"));
+    add("history-storage", accessible ? "pass" : "warning", history.directory ? `History storage ${history.directory}: filesystem access ${accessible ? "available" : "unavailable; receipts may not persist"}.` : "Custom history sink; filesystem access cannot be checked.");
+  }
+  if (updates.enabled) {
+    const accessible = writableDirectory(updates.directory);
+    add("maintenance-storage", accessible ? "pass" : "warning", `Harness update receipts and locks ${updates.directory}: filesystem access ${accessible ? "available" : "unavailable; upgrades may fail"}.`);
+  }
+
+  const limitations = checks.filter(c => c.status !== "pass").map(c => c.message);
+  if (scope === "cache") limitations.push("This code runs from a package cache. Cache cleanup or a future unpinned launch can change the loaded version; restart after changing the install.");
+  if (!updates.enabled) limitations.push("Automatic harness upgrades are disabled.");
+  if (!history.enabled) limitations.push("Run history is disabled; receipts will not persist through restart.");
+  const launcherPath = env.ENNODIA_LAUNCHER_PATH;
+  // Ignore stale inherited launcher metadata (e.g. when a worker starts another installation).
+  const launcher = launcherPath && isAbsolute(launcherPath) && canonical(launcherPath) === canonical(join(codeRoot, "bin/ennodia")) ? launcherPath : undefined;
+  return {
+    checkedAt: new Date().toISOString(), status: checks.some(c => c.status === "fail") ? "broken" : limitations.length ? "limited" : "healthy",
+    version: ENNODIA_VERSION, packageVersion, distribution: compiled ? "compiled" : "source", scope, evidence, codeRoot, serverCwd, launcher,
+    runtime: { name: bunVersion ? "bun" : "unsupported", version: bunVersion, executable: process.execPath, minimumVersion: MIN_BUN_VERSION, platform: process.platform, arch: process.arch },
+    checks, storage: { temporaryDirectory, history, harnessUpdates: updates }, limitations,
+  };
+}
+
+function installationScope(root: string, home: string, env: Record<string, string | undefined>): { scope: InstallationScope; evidence: string } {
+  if (existsSync(join(root, ".git"))) return { scope: "source-checkout", evidence: "Loaded code root contains Git checkout metadata." };
+  const npmCache = canonical(env.npm_config_cache ?? join(home, ".npm"));
+  const bunInstall = canonical(env.BUN_INSTALL ?? join(home, ".bun"));
+  const bunxCache = [canonical(tmpdir()), canonical("/tmp")].some(temp => within(root, temp)) && /(?:^|\/)bunx-\d+-[^/]+\/(?:.*\/)?node_modules\/ennodia$/.test(root);
+  if (within(root, join(npmCache, "_npx")) || within(root, join(bunInstall, "install/cache")) || bunxCache) return { scope: "cache", evidence: "Loaded code is inside an npm exec/npx or Bun package cache." };
+  if (root === join(bunInstall, "install/global/node_modules/ennodia")) return { scope: "global", evidence: "Loaded code is inside Bun's global installation directory." };
+  const globalSuffix = `${sep}lib${sep}node_modules${sep}ennodia`;
+  if (root.endsWith(globalSuffix)) {
+    const launcher = join(root.slice(0, -globalSuffix.length), "bin", "ennodia");
+    if (existsSync(launcher) && canonical(launcher) === canonical(join(root, "bin/ennodia"))) return { scope: "global", evidence: "Global prefix bin/ennodia resolves to this lib/node_modules/ennodia installation." };
+  }
+  const dependencyParent = dirname(dirname(root));
+  if (dirname(root).endsWith(`${sep}node_modules`) && readMetadata(join(dependencyParent, "package.json"))) return { scope: "project-local", evidence: "Loaded code is a node_modules dependency beneath a project package.json." };
+  return { scope: "unknown", evidence: "Code location does not establish an installation scope." };
+}
+
+function readMetadata(path: string): Record<string, unknown> | undefined {
+  try { const value: unknown = JSON.parse(readFileSync(path, "utf8")); return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined; } catch { return undefined; }
+}
+function canonical(path: string): string { try { return realpathSync(path); } catch { return resolve(path); } }
+function readableFile(path: string): boolean { try { accessSync(path, constants.R_OK); return statSync(path).isFile(); } catch { return false; } }
+function writableExistingFile(path: string): boolean { try { accessSync(path, constants.R_OK | constants.W_OK); return statSync(path).isFile(); } catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; } }
+function writableDirectory(path: string, allowMissing = true): boolean {
+  let ancestor = resolve(path);
+  if (!allowMissing && !existsSync(ancestor)) return false;
+  while (!existsSync(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
+  try { accessSync(ancestor, constants.R_OK | constants.W_OK | constants.X_OK); return statSync(ancestor).isDirectory(); } catch { return false; }
+}
+function within(path: string, directory: string): boolean { const suffix = relative(directory, path); return suffix !== "" && suffix !== ".." && !suffix.startsWith(`..${sep}`) && !isAbsolute(suffix); }
+function atLeast(version: string, minimum: string): boolean {
+  if (!/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(version)) return false;
+  const parts = version.split(/[.+-]/).slice(0, 3).map(Number), required = minimum.split(".").map(Number);
+  for (let i = 0; i < 3; i++) { if (parts[i]! !== required[i]!) return parts[i]! > required[i]!; }
+  return !version.split("+")[0]!.includes("-");
+}

package/src/plan-advice.ts

@@ -156,11 +156,7 @@ export class PlanAdviceManager {
     this.maxAdvice = Math.max(1, options.maxAdvice ?? DEFAULT_MAX_ADVICE);
   }
 
-  start(input: PlanAdviceManagerStartInput): PlanAdviceView {
-    if (this.shuttingDown) {
-      throw new Error("PlanAdviceManager is shutting down.");
-    }
-
+  estimateBudget(input: PlanAdviceManagerStartInput): BudgetCheck {
     const advisorPrompt = buildPlanAdvisorPrompt(input.prompt, input.inventory);
     const advisorBudget = checkBudgetLimits(
       estimateTaskBatchBudget({
@@ -173,6 +169,15 @@ export class PlanAdviceManager {
       input.budget,
     );
     assertBudgetWithinLimits(advisorBudget);
+    return advisorBudget;
+  }
+
+  start(input: PlanAdviceManagerStartInput): PlanAdviceView {
+    if (this.shuttingDown) {
+      throw new Error("PlanAdviceManager is shutting down.");
+    }
+    const advisorPrompt = buildPlanAdvisorPrompt(input.prompt, input.inventory);
+    const advisorBudget = this.estimateBudget(input);
 
     // The Advisor receives the closed inventory snapshot, not the target
     // workspace. A fresh empty cwd also avoids accidentally inheriting the
@@ -286,7 +291,7 @@ export class PlanAdviceManager {
     };
   }
 
-  authorizeExecution(
+  validateExecution(
     id: string,
     expectedPlanDigest: string,
     currentInventory: AdvisorInventorySnapshot,
@@ -324,9 +329,15 @@ export class PlanAdviceManager {
       throw new Error("Advised plan changed after approval; no tasks were started.");
     }
 
-    // Keep this final state change after every caller-supplied validation. The
-    // callback is synchronous, so no second authorization can interleave.
     validate?.(structuredClone(compiled.plan));
+    return structuredClone(compiled.plan);
+  }
+
+  authorizeExecution(id: string, expectedPlanDigest: string, currentInventory: AdvisorInventorySnapshot, validate?: (plan: AdvisorExecutionPlan) => void): AdvisorExecutionPlan {
+    const plan = this.validateExecution(id, expectedPlanDigest, currentInventory, validate);
+    const record = this.require(id);
+    // Validation and consumption remain synchronous and single-use. Async
+    // readiness checks happen before this and cannot consume a blocked plan.
     record.status = "consumed";
     record.consumedAtMs = Date.now();
     record.endedAtMs = record.consumedAtMs;
@@ -335,7 +346,7 @@ export class PlanAdviceManager {
       message: "Validated plan authorized for one execution.",
     });
 
-    return structuredClone(compiled.plan);
+    return plan;
   }
 
   async shutdown(options: { deadlineMs?: number } = {}): Promise<void> {

package/src/planner.ts

@@ -1,11 +1,13 @@
 import type { HarnessDiscovery } from "./harnesses";
 import { hasMultimodalInput, MULTIMODAL_INPUT_GUIDANCE } from "./harnesses";
+import { harnessAttention, readinessBlocked, type HarnessAttention } from "./readiness";
 import {
   CATEGORY_HARNESS_PRIORITIES,
   type RouteCategory,
 } from "./priority";
 
 export type RoutePlan = {
+  actionRequired?: HarnessAttention[];
   category: RouteCategory;
   reasons: string[];
   candidates: string[];
@@ -25,7 +27,7 @@ export function planRoute(
   options: PlanRouteOptions = {},
 ): RoutePlan {
   const lower = prompt.toLowerCase();
-  const runnable = harnesses.filter((harness) => harness.runnable);
+  const runnable = harnesses.filter((harness) => harness.runnable && !readinessBlocked(harness.readiness));
   const runnableIds = new Set(runnable.map((harness) => harness.id));
   const reasons: string[] = [];
   const audioInspectionSignals = /\bnative audio\b|\baudio listening\b|\blistening comparison\b|\blisten to\b[^.!?\n]{0,80}\b(audio|recordings?|files?|samples?)\b|\b(compare|assess|judge)\b[^.!?\n]{0,60}\b(audio|recordings?|voice|sound)\b/.test(lower);
@@ -92,6 +94,7 @@ export function planRoute(
   const compareSuggested = parallelSuggested;
 
   return {
+    ...(harnessAttention(harnesses.filter(h => h.runnable)).length ? { actionRequired: harnessAttention(harnesses.filter(h => h.runnable)) } : {}),
     category,
     reasons,
     candidates,

package/src/readiness.ts

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import type { CommandSpec, HarnessAdapter, HarnessDiscovery, HarnessRunInput } from "./harnesses";
+import { signalOwnedProcess } from "./process";
+
+export type ReadinessState = "unverified" | "ready" | "login-required" | "credentials-expired" | "setup-required" | "model-unavailable" | "quota-exhausted" | "unreachable" | "updating";
+export type HarnessReadiness = {
+  state: ReadinessState;
+  checkedAt: string;
+  model?: string;
+  message: string;
+  recovery?: { command: string[]; instruction: string; recheck: { tool: "ennodia_check_harnesses"; harnessIds: string[]; model?: string; verify: boolean } };
+  upgrade?: { status: "succeeded" | "failed" | "deferred" | "unsupported"; checkedAt: string; command?: string[]; message: string };
+};
+export type HarnessAttention = { harnessId: string; harnessName: string; readiness: HarnessReadiness };
+export type HarnessCheckInput = { harnessIds?: string[]; model?: string; cwd?: string; refresh?: boolean; verify?: boolean; upgrade?: boolean };
+export type PreflightReport = { checks: HarnessAttention[]; modelProbes: number; estimatedInputTokens: number; usage: "unknown" };
+export type CommandResult = { exitCode: number | null; stdout: string; stderr: string; timedOut: boolean };
+export type MaintenanceCommandRunner = (spec: CommandSpec, timeoutMs: number) => Promise<CommandResult>;
+export type HarnessReadinessOptions = {
+  runCommand?: MaintenanceCommandRunner;
+  now?: () => number;
+  stateDir?: string;
+  autoUpgrade?: boolean;
+  isBusy?: () => boolean;
+};
+
+const BLOCKED = new Set<ReadinessState>(["login-required", "credentials-expired", "setup-required", "model-unavailable", "quota-exhausted", "unreachable", "updating"]);
+export function readinessBlocked(readiness?: HarnessReadiness): boolean { return Boolean(readiness && BLOCKED.has(readiness.state)); }
+export function harnessAttention(harnesses: HarnessDiscovery[]): HarnessAttention[] {
+  return harnesses.filter(h => readinessBlocked(h.readiness)).map(h => ({ harnessId: h.id, harnessName: h.name, readiness: h.readiness! }));
+}
+export class HarnessReadinessError extends Error {
+  constructor(readonly actionRequired: HarnessAttention[]) {
+    super(`Review not started. ${actionRequired.map(a => `${a.harnessName}: ${a.readiness.message}`).join(" ")}`);
+    this.name = "HarnessReadinessError";
+  }
+}
+
+/** Recognize native failure envelopes, never quoted prose inside an answer. */
+export function nativeReadinessFailure(stdout: string, stderr: string): ReadinessState | undefined {
+  const lines = [...stripVTControlCharacters(stderr).split(/\r?\n/), ...stripVTControlCharacters(stdout).split(/\r?\n/)];
+  for (const line of lines) {
+    let message = line.trim();
+    try {
+      const event = JSON.parse(line);
+      if (event.type === "error") message = typeof event.message === "string" ? event.message : event.error?.message ?? "";
+      else if (event.type === "turn.failed") message = event.error?.message ?? "";
+      else continue;
+    } catch { /* native text CLIs have no JSON envelope */ }
+    message = stripVTControlCharacters(message).trim();
+    if (/^(?:Error:\s*)?(?:This |The |Your )?API key (?:has expired|is expired)\b/i.test(message)) return "credentials-expired";
+    if (/^(?:(?:API )?Error:\s*)?(?:Failed to authenticate\b|OAuth session expired\b|Authentication failed\b|Not logged in\b|Unauthorized\b|401\b|Re-authentication required\b|No access token found\b|Token refresh failed\b|Failed to refresh (?:OAuth|token)\b|Your authentication token .*expired\b)/i.test(message)) return "login-required";
+    if (/^(?:Error:\s*)?(?:You've hit your usage limit\b|quota (?:exceeded|exhausted)\b|insufficient (?:credits|balance)\b|rate limit exceeded\b|Add credits to continue\b)/i.test(message)) return "quota-exhausted";
+    if (/^(?:Error:\s*)?(?:model .* (?:not found|not available|not supported)|unknown model\b|ModelNotFoundError\b)/i.test(message)) return "model-unavailable";
+    if (/^(?:Error:\s*)?(?:No (?:API key|provider|credentials)\b|Missing .*API.?KEY\b|unrecognized arguments\b|unknown (?:option|command)\b)/i.test(message)) return "setup-required";
+  }
+  return undefined;
+}
+
+function recipe(id: string): { auth?: string[]; login: string[]; update?: string[] } {
+  switch (id) {
+    case "codex": return { auth: ["login", "status"], login: ["login"] };
+    case "claude-code": return { auth: ["auth", "status", "--json"], login: ["auth", "login"], update: ["update"] };
+    case "opencode": return { auth: ["auth", "list"], login: ["auth", "login"], update: ["upgrade"] };
+    case "kilo": return { auth: ["auth", "list"], login: ["auth", "login"], update: ["upgrade"] };
+    case "hermes-agent": return { auth: ["auth", "list"], login: ["model"], update: ["update", "--yes"] };
+    case "kiro": return { auth: ["whoami", "--format", "json"], login: ["login"], update: ["update", "--non-interactive"] };
+    case "antigravity": return { login: [], update: ["update"] };
+    default: return { login: [] };
+  }
+}
+
+/** Preserve the installed distribution and channel. Never force an upgrade. */
+export function harnessUpgradeCommand(h: HarnessDiscovery): string[] | undefined {
+  if (!h.commandPath) return undefined;
+  let actual: string;
+  try { actual = realpathSync(h.commandPath); } catch { return undefined; }
+  const brew = Bun.which("brew");
+  const cask = /\/Caskroom\/([^/]+)\//.exec(actual)?.[1];
+  const formula = /\/Cellar\/([^/]+)\//.exec(actual)?.[1];
+  const distribution = cask ?? formula;
+  const distributions: Record<string, string[]> = { codex: ["codex"], "claude-code": ["claude-code", "claude-code@latest"], opencode: ["opencode"], kilo: ["kilo"], kiro: ["kiro-cli"], "hermes-agent": ["hermes", "hermes-agent"], antigravity: ["antigravity", "antigravity-cli"], cline: ["cline"] };
+  if (distribution) return brew && distributions[h.id]?.includes(distribution) ? [brew, "upgrade", ...(cask ? ["--cask", "--greedy", "--no-quit"] : []), distribution] : undefined;
+  if (h.id === "codex") {
+    const npm = Bun.which("npm");
+    return npm && /\/node_modules\/@openai\/codex\//.test(actual) ? [npm, "install", "-g", "@openai/codex@latest"] : undefined;
+  }
+  const args = recipe(h.id).update;
+  return args ? [h.commandPath, ...args] : undefined;
+}
+
+const messages: Record<ReadinessState, string> = {
+  unverified: "Model access is unverified; a small request is required before review.",
+  ready: "The selected route returned a verified response.",
+  "login-required": "Sign-in is required before review.",
+  "credentials-expired": "The configured provider API key has expired. Replace the key in the native CLI/provider settings; signing in again will not renew it.",
+  "setup-required": "Install or repair the native CLI/provider configuration before review.",
+  "model-unavailable": "The selected model is unavailable on this route.",
+  "quota-exhausted": "Provider quota or credits are exhausted; sign-in will not resolve it.",
+  unreachable: "The readiness check did not complete; inspect connectivity or native setup before retrying.",
+  updating: "An upgrade is in progress. Recheck after it completes.",
+};
+
+/** Core owns readiness, failure memory and maintenance; native CLIs own credentials. */
+export class HarnessReadinessManager {
+  private readonly cache = new Map<string, { at: number; value: HarnessReadiness }>();
+  private readonly flights = new Map<string, Promise<HarnessReadiness>>();
+  private readonly updates = new Map<string, NonNullable<HarnessReadiness["upgrade"]>>();
+  private readonly busyHarnesses = new Set<string>();
+  private readonly upgradeFlights = new Map<string, Promise<void>>();
+  private readonly abort = new AbortController();
+  private closing = false;
+  private readonly runner: MaintenanceCommandRunner;
+  private readonly now: () => number;
+  private readonly stateDir: string;
+  readonly autoUpgrade: boolean;
+  get stateDirectory(): string { return this.stateDir; }
+  constructor(private readonly options: HarnessReadinessOptions = {}) {
+    this.runner = options.runCommand ?? ((spec, timeout) => runMaintenanceCommand(spec, timeout, this.abort.signal));
+    this.now = options.now ?? Date.now;
+    this.stateDir = options.stateDir ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), "ennodia", "harnesses");
+    this.autoUpgrade = options.autoUpgrade ?? process.env.ENNODIA_AUTO_UPDATE !== "false";
+  }
+  private key(h: HarnessDiscovery, model?: string, cwd?: string): string {
+    // Environment values may be secret: hash them, never expose or persist them.
+    const environment = createHash("sha256").update(JSON.stringify(process.env)).digest("hex");
+    return JSON.stringify([h.id, h.commandPath, h.version, model, resolve(cwd ?? process.cwd()), environment]);
+  }
+  private value(h: HarnessDiscovery, state: ReadinessState, model?: string): HarnessReadiness {
+    const r = recipe(h.id);
+    const result: HarnessReadiness = { state, checkedAt: new Date(this.now()).toISOString(), model, message: messages[state], upgrade: this.updates.get(h.id) };
+    if (state !== "ready") result.recovery = {
+      command: h.commandPath ? [h.commandPath, ...(state === "login-required" || state === "credentials-expired" || state === "unverified" ? r.login : ["--help"])] : [],
+      instruction: !h.commandPath ? "Install the supported native CLI, then recheck."
+        : state === "unverified" ? "Run the targeted recheck to verify model access. Sign in only when a login blocker is reported."
+        : state === "login-required" ? "Run the native command in an interactive terminal using the intended account/provider, then recheck."
+        : state === "credentials-expired" ? "Replace the expired API key through the native credential flow for the intended provider, then recheck the same route. Signing in again will not renew the key."
+        : state === "quota-exhausted" ? "Restore credits or quota through the intended provider, then recheck the same route. Do not repeat sign-in or switch to a different model silently."
+        : "Inspect the reported blocker through the native CLI; then recheck the same route. Do not change account, provider or model silently.",
+      recheck: { tool: "ennodia_check_harnesses", harnessIds: [h.id], ...(model ? { model } : {}), verify: true },
+    };
+    return result;
+  }
+  describe(h: HarnessDiscovery, state: ReadinessState, model?: string): HarnessReadiness { return this.value(h, state, model); }
+  invalidate(id: string): void {
+    for (const [key] of this.cache) if (JSON.parse(key)[0] === id) this.cache.delete(key);
+  }
+  private installationState(h: HarnessDiscovery): { stamp: string; lock: string } {
+    const identity = createHash("sha256").update(h.commandPath ?? h.id).digest("hex").slice(0, 20);
+    return { stamp: join(this.stateDir, `${identity}.json`), lock: join(this.stateDir, `${identity}.lock`) };
+  }
+  private clearDeadLease(lock: string): void {
+    if (!existsSync(lock)) return;
+    let owner: number;
+    try { owner = JSON.parse(readFileSync(join(lock, "owner.json"), "utf8")).pid; }
+    catch {
+      // A process can die between mkdir and recording its ownership.
+      try { if (this.now() - lstatSync(lock).mtimeMs > 120_000) rmSync(lock, { recursive: true, force: true }); } catch { /* raced with release */ }
+      return;
+    }
+    if (!Number.isInteger(owner) || owner < 1) return;
+    try { process.kill(owner, 0); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") rmSync(lock, { recursive: true, force: true }); }
+  }
+  async check(h: HarnessDiscovery, adapter?: HarnessAdapter, input: HarnessCheckInput = {}): Promise<HarnessReadiness> {
+    if (this.closing) throw new Error("Harness maintenance is shutting down.");
+    const { lock } = this.installationState(h);
+    this.clearDeadLease(lock);
+    if (this.busyHarnesses.has(h.id) || existsSync(lock)) return this.value(h, "updating", input.model);
+    const key = this.key(h, input.model, input.cwd);
+    const existing = this.cache.get(key);
+    if (!input.refresh && existing && (!input.verify || existing.value.state !== "unverified") && this.now() - existing.at < (existing.value.state === "ready" ? 300_000 : 30_000)) return existing.value;
+    const flightKey = `${key}:${Boolean(input.verify)}`;
+    const flight = this.flights.get(flightKey);
+    if (flight) return flight;
+    const pending = this.performCheck(h, adapter, input).catch(() => this.value(h, "unreachable", input.model)).then(value => {
+      this.cache.set(key, { at: this.now(), value });
+      return value;
+    }).finally(() => this.flights.delete(flightKey));
+    this.flights.set(flightKey, pending);
+    return pending;
+  }
+  private async performCheck(h: HarnessDiscovery, adapter: HarnessAdapter | undefined, input: HarnessCheckInput): Promise<HarnessReadiness> {
+    if (!h.runnable || !h.commandPath || !adapter?.buildCommand) return this.value(h, "setup-required", input.model);
+    const { lock } = this.installationState(h);
+    this.clearDeadLease(lock);
+    if (this.busyHarnesses.has(h.id) || existsSync(lock)) return this.value(h, "updating", input.model);
+    const auth = recipe(h.id).auth;
+    if (auth) {
+      const result = await this.runner({ command: h.commandPath, args: auth }, 5_000);
+      const state = nativeReadinessFailure(result.stdout, result.stderr);
+      if (state) return this.value(h, state, input.model);
+      if (h.id === "claude-code") {
+        try { if (JSON.parse(result.stdout).loggedIn === false) return this.value(h, "login-required", input.model); } catch { /* verification below */ }
+      }
+      if (result.timedOut) return this.value(h, "unreachable", input.model);
+      if (result.exitCode !== 0) return this.value(h, ["codex", "claude-code", "kiro"].includes(h.id) ? "login-required" : "setup-required", input.model);
+    }
+    if (!input.verify) return this.value(h, "unverified", input.model);
+    const dir = mkdtempSync(join(tmpdir(), "ennodia-readiness-"));
+    const nonce = `ENNODIA_READY_${randomUUID().replaceAll("-", "")}`;
+    try {
+      const spec = adapter.buildCommand(h.commandPath, { prompt: `Reply with exactly ${nonce}. Do not use tools, read files, or perform any other work.`, cwd: dir, model: input.model, timeoutMs: 20_000, finalMessagePath: join(dir, "answer.txt"), nativeSandbox: adapter.supportsNativeSandbox ? "read-only" : undefined });
+      const result = await this.runner(spec, 25_000);
+      const failure = nativeReadinessFailure(result.stdout, result.stderr);
+      if (failure) return this.value(h, failure, input.model);
+      if (result.timedOut || result.exitCode !== 0 || adapter.failureReason?.(result.stdout, result.stderr)) return this.value(h, "unreachable", input.model);
+      let answer = adapter.readinessAnswer ? adapter.readinessAnswer(result.stdout) ?? "" : result.stdout;
+      try { answer = readFileSync(join(dir, "answer.txt"), "utf8"); } catch { /* native text output */ }
+      // An echoed prompt is not success. Require a standalone returned nonce.
+      if (!stripVTControlCharacters(answer).split(/\r?\n/).some(line => line.trim() === nonce)) return this.value(h, "setup-required", input.model);
+      return this.value(h, "ready", input.model);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  observe(h: HarnessDiscovery, input: Pick<HarnessRunInput, "model" | "cwd">, result: { status: string; stdout: string; stderr: string; timedOut: boolean; hasOutput?: boolean }): void {
+    if (this.closing) return;
+    if (result.status === "cancelled" || result.timedOut) return;
+    const failure = result.status === "failed" ? nativeReadinessFailure(result.stdout, result.stderr) : undefined;
+    if (failure) this.invalidate(h.id);
+    if (failure || (result.status === "succeeded" && result.hasOutput)) {
+      this.cache.set(this.key(h, input.model, input.cwd), { at: this.now(), value: this.value(h, failure ?? "ready", input.model) });
+    }
+  }
+  /** Upgrade at most daily across server restarts; use an exclusive per-install lease. */
+  async upgrade(h: HarnessDiscovery, force = false): Promise<void> {
+    if (this.closing) throw new Error("Harness maintenance is shutting down.");
+    const existing = this.upgradeFlights.get(h.id);
+    if (existing) return existing;
+    const pending = this.performUpgrade(h, force).finally(() => this.upgradeFlights.delete(h.id));
+    this.upgradeFlights.set(h.id, pending);
+    return pending;
+  }
+  private async performUpgrade(h: HarnessDiscovery, force: boolean): Promise<void> {
+    const command = harnessUpgradeCommand(h);
+    const checkedAt = new Date(this.now()).toISOString();
+    const save = (status: NonNullable<HarnessReadiness["upgrade"]>["status"], message: string) => {
+      this.updates.set(h.id, { status, checkedAt, command, message }); this.invalidate(h.id);
+    };
+    if (!command) { save("unsupported", "No supported updater was found for this installation. Use its original installer."); return; }
+    if (this.options.isBusy?.() || this.flights.size > 0) { save("deferred", "Upgrade deferred while Ennodia work is active."); return; }
+    const { stamp, lock } = this.installationState(h);
+    try {
+      mkdirSync(this.stateDir, { recursive: true, mode: 0o700 });
+      if (!force) {
+        try {
+          const previous = JSON.parse(readFileSync(stamp, "utf8"));
+          if (this.now() - previous.at < 86_400_000) {
+            if (previous.result) this.updates.set(h.id, previous.result);
+            return;
+          }
+        } catch { /* first check */ }
+      }
+      this.clearDeadLease(lock);
+      try { mkdirSync(lock); writeFileSync(join(lock, "owner.json"), JSON.stringify({ pid: process.pid }), { mode: 0o600 }); } catch {
+        save("deferred", "Another maintenance process holds the installation lock. Recheck later."); return;
+      }
+    } catch { save("failed", "Maintenance state could not be written; no upgrade was attempted."); return; }
+    this.busyHarnesses.add(h.id);
+    try {
+      writeFileSync(stamp, JSON.stringify({ at: this.now() }), { mode: 0o600 });
+      const result = await this.runner({ command: command[0]!, args: command.slice(1) }, 120_000);
+      save(result.exitCode === 0 && !result.timedOut ? "succeeded" : "failed", result.exitCode === 0 && !result.timedOut ? "Native updater completed; version and readiness must be rechecked." : "Native updater did not complete successfully. Run the displayed update command interactively; no force flags were used.");
+      writeFileSync(stamp, JSON.stringify({ at: this.now(), result: this.updates.get(h.id) }), { mode: 0o600 });
+    } catch { save("failed", "Native updater failed to start. Run the displayed command interactively."); }
+    finally { this.busyHarnesses.delete(h.id); rmSync(lock, { recursive: true, force: true }); }
+  }
+  async shutdown(): Promise<void> {
+    this.closing = true;
+    this.abort.abort();
+    await Promise.allSettled([...this.flights.values(), ...this.upgradeFlights.values()]);
+  }
+}
+
+export async function runMaintenanceCommand(spec: CommandSpec, timeoutMs: number, signal?: AbortSignal): Promise<CommandResult> {
+  if (signal?.aborted) throw new Error("Harness maintenance was cancelled.");
+  const child = Bun.spawn([spec.command, ...spec.args], { cwd: spec.cwd, env: { ...process.env, ...spec.env }, stdin: spec.stdin ? "pipe" : "ignore", stdout: "pipe", stderr: "pipe", detached: process.platform !== "win32" });
+  if (spec.stdin && child.stdin) { child.stdin.write(spec.stdin); child.stdin.end(); }
+  let timedOut = false;
+  const readers = [child.stdout.getReader(), child.stderr.getReader()];
+  const chunks = ["", ""];
+  const kill = () => {
+    signalOwnedProcess(child, "SIGKILL", process.platform !== "win32");
+    for (const reader of readers) void reader.cancel().catch(() => {});
+  };
+  const timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+  signal?.addEventListener("abort", kill, { once: true });
+  try {
+    await Promise.all(readers.map(async (reader, index) => {
+      const decoder = new TextDecoder();
+      try { for (;;) { const { done, value } = await reader.read(); if (done) break; chunks[index] = (chunks[index] + decoder.decode(value, { stream: true })).slice(-32_000); } } finally { reader.releaseLock(); }
+    }));
+    return { exitCode: await child.exited, stdout: chunks[0]!, stderr: chunks[1]!, timedOut };
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", kill); signalOwnedProcess(child, "SIGKILL", process.platform !== "win32"); }
+}