ennodia 0.5.1 → 0.5.3

package/README.md

@@ -85,7 +85,7 @@ See [how to read these notes](https://ennodia.cherninlab.com/docs/guides/underst
 
 Codex CLI, Claude Code, OpenCode, Kilo Code, Kiro CLI, Cline, Hermes Agent, and Antigravity.
 Model availability and tool permissions depend on the installed agent and its provider configuration.
-Discovery reports native login checks and recovery actions. Before execution, Ennodia verifies each selected model route with a small request when recent success is unavailable.
+Discovery reports native login checks and confirmed recovery actions. The requested task verifies model access without a separate model call first.
 Codex workers use a read-only sandbox by default.
 
 Ennodia discovers native Agent Skills and can request them for specific tasks.
@@ -142,7 +142,7 @@ Savings are not yet validated.
 Ennodia checks selected workers, Judge, and Advisor routes before execution.
 Blocked routes return a native recovery action before reviewers start.
 Ennodia says nothing about its own status unless an agent you asked for is blocked.
-Rechecks, setup, and blocked starts include a setup panel with the exact fix.
+Rechecks and blocked starts return compact diagnostics. The full setup panel appears only for an explicit setup request.
 
 Your agent calls `ennodia_setup` to show each agent's status and fix in your current session.
 Hosts that render MCP Apps, such as Claude Desktop and Visual Studio Code, can show it as a card with check buttons.

package/docs/getting-started.md

@@ -34,6 +34,9 @@ Start with one worker and a small set of files.
 Ennodia checks each selected agent before execution. Your agent hears nothing about Ennodia's status unless an agent you requested is blocked.
 A blocked agent comes with its exact fix, such as a sign-in command.
 
+The requested task verifies model access. Ennodia does not add a separate model call before it.
+An optional verification timeout leaves access unverified and does not prevent a task from starting.
+
 For setup or recovery, give your agent this request:
 
 ```text

package/docs/install.md

@@ -81,7 +81,9 @@ Tell the user which step is needed before trying to call Ennodia.
 
 Ennodia includes an installation self-check in run results and rechecks. Its MCP startup instructions carry only installation problems. It uses the loaded code location to identify a source checkout, project-local dependency, global installation, package cache, or unknown scope. It checks the Bun version, package version, core files, bundled skills, and filesystem access for temporary workspaces, history, and harness update receipts. Development files are not required for a packaged install. The npm launcher stops before startup if Bun is too old.
 
-Tell the user about reported installation problems before the first run. Call `ennodia_check_harnesses` with `refresh: true` to refresh the installation report and native harness status after a repair. Filesystem access checks do not prove free disk space or future writes. They do not verify provider access or the latest published package version. A global install gives no extra permissions. The user's normal permissions still apply.
+Report confirmed installation blockers briefly. A running process using an older version needs a reconnect. This does not mean the installation is broken. Do not repeat unchanged warnings.
+
+Call `ennodia_check_harnesses` with `refresh: true` to refresh the installation report and native harness status after a repair. Filesystem access checks do not prove free disk space or future writes. They do not verify provider access or the latest published package version. A global install gives no extra permissions. The user's normal permissions still apply.
 
 The report also identifies compiled code. A compiled executable does not need separate source entrypoints. Missing bundled skills remain a reported limitation. Compilation is currently an experimental build path.
 

package/docs/reference/mcp-tools.md

@@ -733,7 +733,7 @@ pass that task ID as `continueTaskId` in the next run. The follow-up keeps the
 harness and directory. It inherits the model and reasoning effort unless you
 supply new values. Each follow-up has a new task ID and execution allowance.
 
-Readiness checks use the inherited or explicitly supplied model before the follow-up starts.
+Native status checks use the inherited or explicitly supplied model before the follow-up starts.
 An earlier turn cannot be used once a follow-up has started.
 
 Continuation requires a task still held by the same running Ennodia server.
@@ -813,7 +813,7 @@ Sign-in and credential changes stay in each agent's own CLI.
 
 #### Setup card
 
-`ennodia_setup` and `ennodia_check_harnesses` name the `ui://ennodia/setup.html` resource in `_meta.ui.resourceUri`.
+Only `ennodia_setup` names the `ui://ennodia/setup.html` resource in `_meta.ui.resourceUri`.
 The resource uses the MCP Apps type `text/html;profile=mcp-app`.
 Hosts that render MCP Apps show the card inside the conversation. Other hosts ignore it and keep the Markdown panel.
 
@@ -837,15 +837,25 @@ The result includes `installation`, a local self-check of Ennodia's loaded code
 It accepts `harnessIds`, `model`, `cwd`, `refresh`, `verify`, and `upgrade`.
 Native status checks are the default. `verify: true` makes a bounded real model request.
 
-`unverified` means unchecked. `ennodia_run` verifies its selected routes automatically.
+`unverified` means model access is unknown. Normal runs use native status checks and let the task verify model access.
+An inconclusive check does not block the task or mark the agent as needing setup.
 Use targeted `harnessIds` for recovery checks. Unrelated blockers do not prevent work on usable requested routes.
 
-Rechecks, `ennodia_setup`, and blocked preflight responses include an embedded `ennodia://setup` resource with `text/markdown` content.
+Only `ennodia_setup` includes the embedded `ennodia://setup` resource with `text/markdown` content.
+Rechecks and blocked preflight responses return compact JSON diagnostics without creating another setup card.
 The JSON text response keeps its existing shape.
 
 The panel is a table of agents, with agents that need the user first. Each row gives the status in plain words and the next step.
 Sign-in commands follow the table, for login blockers only. Key expiry and quota blockers name their own recovery.
-Show the panel when the host displays no setup card. Recheck the same harness and model after recovery, then resume the original task.
+
+Show the full panel only for an explicit setup or status request.
+For a blocked task, report its cause and native recovery action briefly.
+Do not repeat unchanged warnings or automatically retry checks.
+Recheck the same harness and model after recovery, then resume the original task.
+
+When the installed package differs from the running process, `installation.restartRequired` is true.
+This is a reload notice, not a broken installation. Reconnect the MCP connection to load the installed version.
+Missing runtime files or an unsupported runtime still report a broken installation.
 
 `upgrade: true` runs supported updaters before rediscovery and recheck.
 This tool can change installed software and call providers, so it does not declare `readOnlyHint`.

package/docs/reference/supported-harnesses.md

@@ -45,12 +45,14 @@ It does not guarantee media support, authentication, or access to a requested mo
 Plan Advisor receives this guidance in its harness inventory.
 
 Discovery checks installation and native login status through supported commands.
-Model access remains unverified until a small real request or a recent successful task returns an answer.
-A stalled check stops at its deadline and reports a blocker.
+Model access remains unverified until an explicit verification request or a successful task returns an answer.
+A stalled check stops at its deadline and leaves access unverified.
 Ennodia checks selected worker, Judge, and Advisor routes before execution.
 Known blockers prevent requested work from starting.
 Automatic routing excludes blocked routes and reports missing coverage.
 
+Normal runs check native status without making a separate model request.
+
 ## Media inputs
 
 Ennodia sends a text prompt through the selected CLI. Include local file paths and requested ranges in that prompt.
@@ -138,7 +140,7 @@ Call `ennodia_check_harnesses` after sign-in:
 ```
 
 Pass the same `model` and `cwd` when rechecking an explicit route.
-The check returns `actionRequired` for login, setup, model, capacity, and connectivity blockers.
+The check returns `actionRequired` for confirmed login, setup, model, and capacity blockers.
 A missing CLI requires installation. A capacity failure requires capacity recovery.
 Neither is fixed by repeated sign-in.
 
@@ -157,8 +159,8 @@ Native checks cache for 30 seconds. Verified routes cache for five minutes.
 A native authentication failure invalidates the route immediately.
 Concurrent checks of the same route share one request.
 
-`unverified` means unchecked. It does not mean a failed harness.
-`ennodia_run` verifies its selected routes before launching workers.
+`unverified` means model access is unknown. It does not mean a failed harness.
+`ennodia_run` lets the requested task verify model access after native status checks.
 Checking every supported harness is not a prerequisite for a run.
 
 Unrelated harness blockers do not prevent work on a usable requested route.
@@ -169,9 +171,9 @@ Ennodia does not require an additional approval step.
 Model probes run in an empty temporary directory with normal native permissions.
 A temporary directory is not a security sandbox.
 
-Probes use provider capacity and reserve 256 input tokens per route for budget checks.
-The reserve is an estimate, not a measurement of provider usage.
-Probe calls count toward `maxChildTasks`. Usage remains unknown when the provider reports no measurement.
+Explicit verification uses provider capacity independently of a run's budget.
+Normal runs add no model probe calls or input-token reserves.
+A verification timeout after 25 seconds does not block the requested task or imply a setup problem.
 
 Before ordinary execution, Ennodia attempts supported upgrades once per day while no Ennodia task is active.
 Homebrew installations use their installed formula or cask.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ennodia",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "mcpName": "io.github.cherninlab/ennodia",
   "description": "Connects the AI agents you use: your agent hands a task to another and gets the answer back",
   "license": "MIT",

package/src/core.ts

@@ -416,7 +416,7 @@ export class EnnodiaCore {
       for (const h of harnesses) { const fresh = refreshed.find(f => f.id === h.id); if (fresh) Object.assign(h, fresh); }
     }
     const unique = [...new Map(routes.map(r => [JSON.stringify(r), r])).values()];
-    // Check every native login before any model probe or reviewer launch.
+    // Native checks catch known blockers; the requested task verifies model access.
     const checked = await Promise.all(unique.map(async route => {
       const h = harnesses.find(h => h.id === route.harnessId);
       if (!h) throw new Error(`Unknown harness: ${route.harnessId}`);
@@ -425,23 +425,10 @@ export class EnnodiaCore {
     const initialBlocked = checked.filter(c => readinessBlocked(c.readiness)).map(c => ({ harnessId: c.h.id, harnessName: c.h.name, readiness: c.readiness }));
     if (initialBlocked.length) throw new HarnessReadinessError(initialBlocked);
     for (const { h, readiness } of checked) {
-      if (readiness.state !== "ready") {
-        // Probes are real provider calls. Reserve them before starting, and
-        // expose their estimate separately rather than implying free checks.
-        report.modelProbes++; report.estimatedInputTokens += 256;
-      }
       report.checks.push({ harnessId: h.id, harnessName: h.name, readiness });
-      if (budget?.maxChildTasks !== undefined && routes.length + report.modelProbes > budget.maxChildTasks) throw new Error("Budget limit exceeded: readiness probes also count as child calls. Verify the routes separately or increase maxChildTasks.");
-      if (budget?.maxEstimatedInputTokens !== undefined && report.estimatedInputTokens > budget.maxEstimatedInputTokens) throw new Error("Budget limit exceeded: readiness probe input reserve.");
-    }
-    const verified = await Promise.all(report.checks.map(async c => ({ ...c, readiness: await this.readinessManager!.check(harnesses.find(h => h.id === c.harnessId)!, this.findHarnessAdapter(c.harnessId), { model: c.readiness.model, cwd, verify: true }) })));
-    report.checks = verified;
-    const blocked = verified.filter(c => readinessBlocked(c.readiness));
-    if (blocked.length) throw new HarnessReadinessError(blocked);
-    for (const check of verified) {
-      const h = harnesses.find(h => h.id === check.harnessId);
-      if (h) h.readiness = check.readiness;
+      h.readiness = readiness;
     }
+    if (budget?.maxChildTasks !== undefined && routes.length > budget.maxChildTasks) throw new Error("Budget limit exceeded: selected routes exceed maxChildTasks.");
     return report;
   }
 

package/src/diagnosis.ts

@@ -1,5 +1,6 @@
 import type { TaskView } from "./tasks";
 import { truncate } from "./internal";
+import { openCodeQuotaError } from "./harnesses";
 
 export type TaskOutputPreview = {
   harnessId: string;
@@ -150,7 +151,8 @@ export function hasCodexQuotaError(stdout: string): boolean {
 }
 
 function hasQuotaError(task: TaskView): boolean {
-  return task.harnessId === "codex" && (hasCodexQuotaError(task.stdout) || hasCodexQuotaError(task.stderr));
+  return task.harnessId === "opencode" ? Boolean(openCodeQuotaError(task.stderr))
+    : task.harnessId === "codex" && (hasCodexQuotaError(task.stdout) || hasCodexQuotaError(task.stderr));
 }
 
 function hasAuthenticationError(task: TaskView): boolean {

package/src/harnesses.ts

@@ -95,6 +95,8 @@ export type HarnessAdapter = {
   extractSessionId?: (stdout: string) => string | undefined;
   /** Some public CLIs report a semantic failure with exit code zero. */
   failureReason?: (stdout: string, stderr: string) => string | undefined;
+  /** A confirmed native failure that must stop a still-running CLI. */
+  streamFailureReason?: (stdout: string, stderr: string) => string | undefined;
   /** The CLI accepts operator instructions separately from the prompt. A
    * worker then reads Ennodia's limits as its session's own, not as text
    * inside the task, which a careful model can distrust. */
@@ -312,8 +314,10 @@ export const harnessAdapters: HarnessAdapter[] = [
     notes: ["Runs through `opencode run` without permission-bypass flags."],
     // Concurrent starts can fail while another instance holds its database.
     startupConflict: /database is locked/i,
+    streamFailureReason: (_stdout, stderr) => openCodeQuotaError(stderr),
     buildCommand: (commandPath, input) => {
-      const args = ["run"];
+      // Retryable provider errors otherwise stay in OpenCode's private log.
+      const args = ["run", "--print-logs", "--log-level", "ERROR"];
 
       if (input.cwd) {
         args.push("--dir", input.cwd);
@@ -501,6 +505,24 @@ export const harnessAdapters: HarnessAdapter[] = [
   },
 ];
 
+/** OpenCode's public --print-logs stderr; never inspect worker stdout here. */
+export function openCodeQuotaError(stderr: string): string | undefined {
+  for (const line of stderr.split(/\r?\n/)) {
+    if (!/^timestamp=\S+ level=ERROR /.test(line) ||
+        !/ message="stream error" /.test(line) ||
+        !/ small=false /.test(line) || !/ mode=primary /.test(line)) continue;
+    // Ignore small/title requests: they can fail while the main agent works.
+    const encoded = / error\.error=("(?:[^"\\]|\\.)*")(?= |$)/.exec(line)?.[1];
+    if (!encoded) continue;
+    let message: string;
+    try { message = JSON.parse(encoded); } catch { continue; }
+    if (/^AI_APICallError:\s*(?:OpenCode )?Go usage limit (?:reached|exceeded)\b/i.test(message)) {
+      return message.replace(/^AI_APICallError:\s*/i, "");
+    }
+  }
+  return undefined;
+}
+
 function extractCodexSessionId(stdout: string): string | undefined {
   for (const line of stdout.split(/\r?\n/)) {
     const event = parseJsonObject(line);

package/src/installation.ts

@@ -13,6 +13,7 @@ export type InstallationReport = {
   status: "healthy" | "limited" | "broken";
   version: string;
   packageVersion?: string;
+  restartRequired?: boolean;
   distribution: "source" | "compiled";
   scope: InstallationScope;
   evidence: string;
@@ -59,7 +60,8 @@ export function inspectInstallation(options: InstallationOptions = {}): Installa
   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.");
+  const restartRequired = Boolean(packageVersion && packageVersion !== ENNODIA_VERSION);
+  add("package-version", packageVersion === ENNODIA_VERSION ? "pass" : "warning", restartRequired ? `Installed ${packageVersion}; running ${ENNODIA_VERSION}. Reconnect the Ennodia MCP connection to load the installed version.` : 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)) : [];
@@ -99,7 +101,7 @@ export function inspectInstallation(options: InstallationOptions = {}): Installa
   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,
+    version: ENNODIA_VERSION, packageVersion, ...(restartRequired ? { restartRequired } : {}), 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,
   };

package/src/readiness.ts

@@ -4,6 +4,7 @@ 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 { openCodeQuotaError } from "./harnesses";
 import { signalOwnedProcess } from "./process";
 
 export type ReadinessState = "unverified" | "ready" | "login-required" | "credentials-expired" | "setup-required" | "model-unavailable" | "quota-exhausted" | "unreachable" | "updating";
@@ -28,7 +29,7 @@ export type HarnessReadinessOptions = {
   isBusy?: () => boolean;
 };
 
-const BLOCKED = new Set<ReadinessState>(["login-required", "credentials-expired", "setup-required", "model-unavailable", "quota-exhausted", "unreachable", "updating"]);
+const BLOCKED = new Set<ReadinessState>(["login-required", "credentials-expired", "setup-required", "model-unavailable", "quota-exhausted", "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! }));
@@ -42,6 +43,7 @@ export class HarnessReadinessError extends Error {
 
 /** Recognize native failure envelopes, never quoted prose inside an answer. */
 export function nativeReadinessFailure(stdout: string, stderr: string, allowPlainStdout = false): ReadinessState | undefined {
+  if (openCodeQuotaError(stderr)) return "quota-exhausted";
   const stderrLines = stripVTControlCharacters(stderr).split(/\r?\n/);
   const lines = [...stderrLines, ...stripVTControlCharacters(stdout).split(/\r?\n/)];
   for (const [index, line] of lines.entries()) {
@@ -58,7 +60,7 @@ export function nativeReadinessFailure(stdout: string, stderr: string, allowPlai
     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*)?(?:You've hit your (?:usage|\d+[ -]hour|weekly) 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";
   }
@@ -98,7 +100,7 @@ export function harnessUpgradeCommand(h: HarnessDiscovery): string[] | undefined
 }
 
 const messages: Record<ReadinessState, string> = {
-  unverified: "Model access is unverified; a small request is required before review.",
+  unverified: "Model access is unverified. A task can run without a separate model check.",
   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.",
@@ -137,10 +139,9 @@ export class HarnessReadinessManager {
   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"])] : [],
+    if (state !== "ready" && state !== "unverified") result.recovery = {
+      command: h.commandPath ? [h.commandPath, ...(state === "login-required" || state === "credentials-expired" ? 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."
@@ -181,7 +182,7 @@ export class HarnessReadinessManager {
     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 => {
+    const pending = this.performCheck(h, adapter, input).catch(() => ({ ...this.value(h, "unverified", input.model), message: "The native check could not complete. Model access remains unverified; a task can still run." })).then(value => {
       this.cache.set(key, { at: this.now(), value });
       return value;
     }).finally(() => this.flights.delete(flightKey));
@@ -201,8 +202,8 @@ export class HarnessReadinessManager {
       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 (result.timedOut) return { ...this.value(h, "unverified", input.model), message: "The native sign-in check timed out. No sign-in or setup failure was confirmed." };
+      if (result.exitCode !== 0) return { ...this.value(h, "unverified", input.model), message: "The native check exited without a recognized blocker. A task can still run." };
     }
     if (!input.verify) return this.value(h, "unverified", input.model);
     const dir = mkdtempSync(join(tmpdir(), "ennodia-readiness-"));
@@ -212,11 +213,12 @@ export class HarnessReadinessManager {
       const result = await this.runner(spec, 25_000);
       const failure = nativeReadinessFailure(result.stdout, result.stderr, true);
       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);
+      if (result.timedOut) return { ...this.value(h, "unverified", input.model), message: "Model verification timed out after 25 seconds. A task can still run with its own time limit." };
+      if (result.exitCode !== 0 || adapter.failureReason?.(result.stdout, result.stderr)) return { ...this.value(h, "unverified", input.model), message: "Model verification did not complete. A task can still run." };
       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);
+      if (!stripVTControlCharacters(answer).split(/\r?\n/).some(line => line.trim() === nonce)) return { ...this.value(h, "unverified", input.model), message: "Model verification did not return the expected response. A task can still run." };
       return this.value(h, "ready", input.model);
     } finally { rmSync(dir, { recursive: true, force: true }); }
   }
@@ -242,7 +244,8 @@ export class HarnessReadinessManager {
     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);
+      this.updates.set(h.id, { status, checkedAt, command, message });
+      if (status === "succeeded" || status === "failed") 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; }

package/src/server.ts

@@ -108,7 +108,7 @@ export function createEnnodiaServer(
       catch (error) {
         if (error instanceof HarnessReadinessError) {
           const installation = core.getInstallation?.();
-          return { ...setupResult({ error: error.message, installation, actionRequired: error.actionRequired, coverage: { started: 0 } }, error.actionRequired, installation), isError: true };
+          return { ...jsonResult({ error: error.message, installation, actionRequired: error.actionRequired, coverage: { started: 0 } }), isError: true };
         }
         throw error;
       }
@@ -149,8 +149,7 @@ export function createEnnodiaServer(
 
   server.registerTool("ennodia_check_harnesses", {
     title: "Recheck or upgrade Ennodia harnesses",
-    description: "Recheck Ennodia's installation and recover affected harnesses. Return installation scope, runtime/package/storage limitations, native recovery commands and actionRequired. Target affected harnessIds; unrelated blockers do not prevent authorized work on usable routes. verify makes a small real model call; upgrade runs supported updaters before rechecking. Never switch account/provider/model silently.",
-    _meta: SETUP_APP_TOOL_META,
+    description: "Recheck selected harnesses and return compact diagnostics. Target affected harnessIds; unrelated blockers do not prevent work. verify makes an optional real model call; a timeout leaves access unverified and does not block tasks. upgrade runs supported updaters before rechecking. Never switch account/provider/model silently. Show a brief changed result; use ennodia_setup only when the user asks for the full setup view.",
     inputSchema: {
       harnessIds: z.array(z.string().min(1)).min(1).optional().describe("Harnesses to recheck. Omit for all installed harnesses."),
       model: z.string().min(1).optional().describe("Exact model to verify on the selected route."),
@@ -161,7 +160,7 @@ export function createEnnodiaServer(
     },
   }, async input => {
     const result = await core.checkHarnesses(input);
-    return setupResult(result, result.harnesses, result.installation);
+    return jsonResult(result);
   });
 
   // Hosts that render MCP Apps show this card for the two tools above.
@@ -1337,9 +1336,9 @@ export async function shutdownEnnodia(
 export function serverInstructions(installation?: InstallationReport): string {
   const lines = [
     "Ennodia hands work to the user's other local agents. Do not open with Ennodia's status or list agents the user did not ask about: ennodia_run checks the agents it selects before starting.",
-    "If a requested agent is blocked, the result carries an ennodia://setup panel: show the user its fix as written. After the user fixes it, recheck that agent and model with ennodia_check_harnesses (verify: true), then continue the task. If a run skipped agents (actionRequired), say so in one line. Unrelated blockers must not hold up work on usable agents.",
+    "For a confirmed blocker on a requested agent, state its cause and native recovery action in one short line. Do not repeat unchanged warnings or automatically retry checks. After recovery, recheck that harness and model. If agents were skipped (actionRequired), say so in one line. Unrelated blockers must not hold up usable agents.",
     "For setup or status requests, call ennodia_setup and show its panel. Hosts that render MCP Apps show it as a card; then add one line at most.",
-    "Unverified means not checked yet, not failed. A verified default model does not prove access to other models. Never collect credentials in chat, never switch account, provider or model silently, and never claim a check ran when it did not. Follow the user's existing authorization and the host's approval policy; add no approval step of your own.",
+    "Unverified means model access is unknown, not failed; the requested task can verify it. Use a separate model probe only when needed. A reload notice after an update is not a broken installation; mention it once when relevant. Never collect credentials in chat, switch account/provider/model silently, or claim a check ran when it did not. Follow existing authorization; add no approval step of your own.",
   ];
   if (installation?.status === "broken") lines.push(`Ennodia's installation is broken: ${installation.limitations.join(" ")} Tell the user before starting work and link ${INSTALL_GUIDE_URL}.`);
   else if (installation?.status === "limited") lines.push(`Installation notes, to mention only when they affect the request: ${installation.limitations.join(" ")}`);
@@ -1357,16 +1356,17 @@ function setupResult(value: unknown, routes: (HarnessDiscovery | HarnessAttentio
   const cell = (text: string) => text.replaceAll("|", "\\|").replace(/[\r\n]+/g, " ");
   const lines = ["## Ennodia agents"];
   if (installation && installation.status !== "healthy") {
-    lines.push("", `Installation ${installation.status}:`, ...installation.limitations.map(limit => `- ${limit}`), "", `Repair it with the [installation guide](${INSTALL_GUIDE_URL}), then restart the MCP connection.`);
+    lines.push("", installation.status !== "broken" && installation.restartRequired ? "Ennodia update ready:" : `Installation ${installation.status}:`, ...installation.limitations.map(limit => `- ${limit}`));
+    if (!installation.restartRequired || installation.status === "broken") lines.push("", `[Installation guide](${INSTALL_GUIDE_URL})`);
   }
   const rows = routes.map(route => {
     const key = accessKey(route);
-    return { name: "id" in route ? route.name : route.harnessName, model: route.readiness?.model, key, command: key === "login-required" ? route.readiness?.recovery?.command ?? [] : [] };
+    return { name: "id" in route ? route.name : route.harnessName, model: route.readiness?.model, message: route.readiness?.message, key, command: key === "login-required" ? route.readiness?.recovery?.command ?? [] : [] };
   }).sort((a, b) => accessRank(a.key) - accessRank(b.key));
   if (rows.length) lines.push("", "| Agent | Status | Next step |", "| --- | --- | --- |");
   else lines.push("", `No supported agents were found. Install one with the [harness guide](${HARNESS_GUIDE_URL}).`);
   for (const row of rows) {
-    const next = row.key === "missing" ? `${ACCESS_TEXT.missing.next} [Install guide](${HARNESS_GUIDE_URL})` : ACCESS_TEXT[row.key].next;
+    const next = row.key === "missing" ? `${ACCESS_TEXT.missing.next} [Install guide](${HARNESS_GUIDE_URL})` : row.key === "unverified" && row.message ? row.message : ACCESS_TEXT[row.key].next;
     lines.push(`| ${cell(row.name + (row.model ? ` · ${row.model}` : ""))} | ${ACCESS_TEXT[row.key].label} | ${cell(next)} |`);
   }
   // Only a login blocker calls for a command. Other blockers need credits or a new key.

package/src/setup-app.ts

@@ -21,16 +21,16 @@ export const ACCESS_TEXT: Record<AccessKey, { label: string; next: string }> = {
   "quota-exhausted": { label: "Out of quota", next: "Restore credits or quota with the provider, then check again. Signing in does not help." },
   "model-unavailable": { label: "Model unavailable", next: "This agent cannot use this model. Pick another from its model list." },
   "setup-required": { label: "Needs setup", next: "Finish the agent's own setup, then check again." },
-  unreachable: { label: "Check failed", next: "The check did not finish. Look at the connection or the agent's setup, then check again." },
+  unreachable: { label: "Could not verify", next: "Model access is unknown. This does not confirm a sign-in or setup problem." },
   updating: { label: "Updating", next: "An update is running. Check again when it finishes." },
-  unverified: { label: "Not checked yet", next: "Ennodia checks it on first use." },
+  unverified: { label: "Not verified", next: "A task can run without a separate model check." },
   ready: { label: "Ready", next: "" },
   missing: { label: "Not available", next: "Not installed, or it cannot run without a terminal." },
 };
 
 /** Agents that need the user come first, unavailable ones last. */
 export function accessRank(key: AccessKey): number {
-  return key === "unverified" ? 1 : key === "ready" ? 2 : key === "missing" ? 3 : 0;
+  return key === "unverified" || key === "unreachable" ? 1 : key === "ready" ? 2 : key === "missing" ? 3 : 0;
 }
 
 export const HARNESS_GUIDE_URL = "https://ennodia.cherninlab.com/docs/reference/supported-harnesses/";
@@ -88,7 +88,7 @@ const SETUP_APP_SCRIPT = String.raw`
   function normalize(h) {
     var r = h.readiness || {};
     var key = h.runnable === false ? "missing" : (ACCESS[r.state] ? r.state : "unverified");
-    return { id: h.id, name: h.name || h.id, model: r.model || "", key: key,
+    return { id: h.id, name: h.name || h.id, model: r.model || "", message: r.message || "", key: key,
       command: key === "login-required" && r.recovery && Array.isArray(r.recovery.command) ? r.recovery.command : [] };
   }
   function find(id) { for (var i = 0; i < state.agents.length; i++) if (state.agents[i].id === id) return state.agents[i]; return null; }
@@ -125,7 +125,7 @@ const SETUP_APP_SCRIPT = String.raw`
       if (data.installation) state.installation = data.installation;
       merge(data.harnesses);
       var now = find(agent.id);
-      state.notes[agent.id] = now && now.key === "ready" ? "Ready now." : now && now.key === before ? "No change yet." : "";
+      state.notes[agent.id] = now && now.key === "ready" ? "Ready now." : "";
       if (now && now.key === "ready" && before !== "ready") state.newlyReady[agent.id] = true;
     }, function (error) { state.notes[agent.id] = error.message || "The check failed."; })
       .then(function () { delete state.busy[agent.id]; render(); });
@@ -178,12 +178,12 @@ const SETUP_APP_SCRIPT = String.raw`
     var head = el("div", "head");
     head.appendChild(el("span", "dot"));
     var name = el("span", "name", agent.name);
-    if (agent.model) name.appendChild(el("span", "model", agent.model));
+    if (agent.model) name.appendChild(el("span", "model", " · " + agent.model));
     head.appendChild(name);
     head.appendChild(el("span", "status", ACCESS[agent.key].label));
     item.appendChild(head);
-    // An unchecked agent needs nothing from the user; its button is enough.
-    if (ACCESS[agent.key].next && agent.key !== "unverified") item.appendChild(el("p", "next", ACCESS[agent.key].next));
+    var next = agent.key === "unverified" && agent.message ? agent.message : ACCESS[agent.key].next;
+    if (next) item.appendChild(el("p", "next", next));
     if (agent.command.length) {
       var row = el("div", "command");
       var code = el("code", "", shellQuote(agent.command));
@@ -216,11 +216,11 @@ const SETUP_APP_SCRIPT = String.raw`
     install.textContent = "";
     install.hidden = !report || report.status === "healthy";
     if (!install.hidden) {
-      install.appendChild(el("p", "", "Ennodia installation: " + report.status + "."));
+      install.appendChild(el("p", "", report.status !== "broken" && report.restartRequired ? "Ennodia update ready." : "Ennodia installation: " + report.status + "."));
       var notes = el("ul");
       (report.limitations || []).forEach(function (text) { notes.appendChild(el("li", "", text)); });
       install.appendChild(notes);
-      install.appendChild(button("Installation guide", "", function () { openLink(__INSTALL__); }));
+      if (!report.restartRequired || report.status === "broken") install.appendChild(button("Installation guide", "", function () { openLink(__INSTALL__); }));
     }
     document.getElementById("cost").hidden = !state.host.serverTools || !state.agents.some(function (a) { return a.key !== "ready" && a.key !== "missing"; });
     resize();

package/src/tasks.ts

@@ -145,6 +145,8 @@ type InternalTask = Omit<
   isolatedCwd?: string;
   extractUsage?: HarnessAdapter["extractUsage"];
   failureReason?: HarnessAdapter["failureReason"];
+  streamFailureReason?: HarnessAdapter["streamFailureReason"];
+  streamFailure?: string;
   /** The exact spawn, kept so a start that met a startup conflict can run again. */
   spawnInput: TaskSpawnInput;
   stdinText?: string;
@@ -379,6 +381,7 @@ ${noticeLines.join("\n")}
       isolatedCwd,
       extractUsage: adapter.extractUsage,
       failureReason: adapter.failureReason,
+      streamFailureReason: adapter.streamFailureReason,
       spawnInput,
       stdinText: commandSpec.stdin,
       startupConflict: adapter.startupConflict,
@@ -407,7 +410,7 @@ ${noticeLines.join("\n")}
     ]).then(() => undefined);
 
     task.timeout = setTimeout(() => {
-      if (task.cancelRequested) {
+      if (task.cancelRequested || task.streamFailure) {
         return;
       }
 
@@ -549,7 +552,7 @@ ${noticeLines.join("\n")}
         terminalStatus = "cancelled";
       } else {
         terminalStatus =
-          exitCode === 0 && !task.timedOut && !task.drainTimedOut
+          exitCode === 0 && !task.timedOut && !task.drainTimedOut && !task.streamFailure
             ? "succeeded"
             : "failed";
       }
@@ -628,7 +631,7 @@ ${noticeLines.join("\n")}
   private metStartupConflict(task: InternalTask): boolean {
     return Boolean(task.startupConflict?.test(task.stderr)) &&
       !task.stdout.trim() &&
-      !task.cancelRequested && !task.timedOut && !task.drainTimedOut && !this.shuttingDown &&
+      !task.cancelRequested && !task.timedOut && !task.drainTimedOut && !task.streamFailure && !this.shuttingDown &&
       (task.startupRestarts ?? 0) < MAX_STARTUP_RESTARTS &&
       Date.now() - task.attemptStartedAtMs < STARTUP_CONFLICT_WINDOW_MS;
   }
@@ -903,6 +906,7 @@ ${noticeLines.join("\n")}
         }
         task.streamCaptureTruncated ||= task[streamName].length + chunk.length > MAX_CAPTURE_CHARS;
         task[streamName] = appendLimited(task[streamName], chunk);
+        this.checkStreamFailure(task);
         task.lastOutputAtMs = Date.now();
         this.pushEvent(task, { type: streamName, message: chunk });
         this.touch(task);
@@ -912,6 +916,7 @@ ${noticeLines.join("\n")}
       if (finalChunk) {
         task.streamCaptureTruncated ||= task[streamName].length + finalChunk.length > MAX_CAPTURE_CHARS;
         task[streamName] = appendLimited(task[streamName], finalChunk);
+        this.checkStreamFailure(task);
         task.lastOutputAtMs = Date.now();
         this.pushEvent(task, { type: streamName, message: finalChunk });
         this.touch(task);
@@ -922,6 +927,20 @@ ${noticeLines.join("\n")}
     }
   }
 
+  private checkStreamFailure(task: InternalTask): void {
+    if (!task.streamFailureReason || task.streamFailure || task.cancelRequested || task.timedOut) return;
+    try {
+      const reason = task.streamFailureReason(task.stdout, task.stderr);
+      if (!reason) return;
+      task.streamFailure = reason;
+      this.pushEvent(task, { type: "error", message: reason });
+      this.terminate(task);
+    } catch (error) {
+      task.streamFailureReason = undefined;
+      this.pushEvent(task, { type: "error", message: `Adapter stream check failed: ${String(error)}` });
+    }
+  }
+
   private toView(task: InternalTask, options: TaskViewOptions = {}): TaskView {
     const now = Date.now();
     const end = task.endedAtMs ?? now;

package/src/version.ts

@@ -1 +1 @@
-export const ENNODIA_VERSION = "0.5.1";
+export const ENNODIA_VERSION = "0.5.3";