ennodia 0.4.0 → 0.5.0

package/src/server.ts

@@ -10,7 +10,10 @@ import {
 import { renderPlanMermaid } from "./planner";
 import { formatHarnessPriorityList } from "./priority";
 import { ENNODIA_VERSION } from "./version";
-import { REASONING_EFFORTS } from "./harnesses";
+import { REASONING_EFFORTS, type HarnessDiscovery } from "./harnesses";
+import { HarnessReadinessError, harnessAttention, type HarnessAttention } from "./readiness";
+import type { InstallationReport } from "./installation";
+import { ACCESS_TEXT, HARNESS_GUIDE_URL, INSTALL_GUIDE_URL, MCP_APP_MIME_TYPE, SETUP_APP_HTML, SETUP_APP_TOOL_META, SETUP_APP_URI, accessRank, type AccessKey } from "./setup-app";
 
 const defaultCore = createDefaultEnnodiaCore();
 const comparePriorityText = formatHarnessPriorityList();
@@ -60,6 +63,8 @@ export const CORE_TOOL_NAMES: readonly string[] = [
   "ennodia_get_run",
   "ennodia_cancel_run",
   "ennodia_list_harnesses",
+  "ennodia_setup",
+  "ennodia_check_harnesses",
   "ennodia_list_skills",
   "ennodia_history",
 ];
@@ -69,7 +74,7 @@ export const CORE_TOOL_NAMES: readonly string[] = [
  * model providers, and their workers can change files when the caller allows
  * it, so they claim neither read-only nor harmless. */
 export function toolAnnotations(name: string): { readOnlyHint: boolean; openWorldHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean } {
-  if (/^ennodia_(?:list_|get_|history$|plan$|estimate_)/.test(name)) return { readOnlyHint: true, openWorldHint: false };
+  if (/^ennodia_(?:list_|get_|history$|plan$|estimate_|setup$)/.test(name)) return { readOnlyHint: true, openWorldHint: false };
   if (name.startsWith("ennodia_cancel_")) return { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
   if (name === "ennodia_install_skills") return { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
   return { readOnlyHint: false, openWorldHint: true };
@@ -90,13 +95,24 @@ export function createEnnodiaServer(
   const server = new McpServer({
     name: "ennodia",
     version: ENNODIA_VERSION,
-  });
+  }, { instructions: serverInstructions(core.getInstallation?.()) });
 
   // Keep each registration, so the core set can drop the others below, and
   // add the annotations that tell clients which calls only read.
   const registered = new Map<string, RegisteredTool>();
   const registerTool = server.registerTool.bind(server) as (name: string, config: { annotations?: object }, ...rest: unknown[]) => RegisteredTool;
   server.registerTool = ((name: string, config: { annotations?: object }, ...rest: unknown[]) => {
+    const handler = rest[rest.length - 1] as (...args: unknown[]) => Promise<unknown>;
+    rest[rest.length - 1] = async (...args: unknown[]) => {
+      try { return await handler(...args); }
+      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 };
+        }
+        throw error;
+      }
+    };
     const tool = registerTool(name, { ...config, annotations: { ...toolAnnotations(name), ...config.annotations } }, ...rest);
     registered.set(name, tool);
     return tool;
@@ -107,7 +123,7 @@ export function createEnnodiaServer(
     {
       title: "List Ennodia harnesses",
       description:
-        "Discover local harnesses, availability, versions, capabilities, adapter notes, and inputGuidance. Before audio/image/video work, read inputGuidance: model capabilities do not guarantee native input through a harness. Use first when setup or routing fails.",
+        "Discover supported agents and cached readiness for routing. Do not summarize it for the user; for setup or status requests call ennodia_setup. Read inputGuidance before media work.",
       inputSchema: {
         refresh: z
           .boolean()
@@ -120,6 +136,42 @@ export function createEnnodiaServer(
     async ({ refresh }) => jsonResult(await core.listHarnesses({ refresh })),
   );
 
+  // Read-only, so clients such as Codex show setup without an approval prompt.
+  server.registerTool("ennodia_setup", {
+    title: "Show Ennodia setup",
+    description: "Show the user Ennodia's agents: each agent's status and the exact fix for blocked ones. Refreshes native sign-in status without model requests. Hosts that render MCP Apps show a card with check buttons; others get a Markdown panel to show the user.",
+    _meta: SETUP_APP_TOOL_META,
+  }, async () => {
+    const harnesses = await core.listHarnesses({ refresh: true });
+    const installation = core.getInstallation?.(true);
+    return setupResult({ installation, harnesses, actionRequired: harnessAttention(harnesses) }, harnesses, installation);
+  });
+
+  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,
+    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."),
+      cwd: z.string().optional().describe("Workspace identity for the readiness receipt; probes run in an empty temporary directory."),
+      refresh: z.boolean().default(true).describe("Invalidate cached readiness and recheck native status."),
+      verify: z.boolean().default(false).describe("Verify each selected route with a bounded real model request. Uses provider capacity."),
+      upgrade: z.boolean().default(false).describe("Run supported updaters now, then rediscover and recheck. Deferred while Ennodia tasks are active."),
+    },
+  }, async input => {
+    const result = await core.checkHarnesses(input);
+    return setupResult(result, result.harnesses, result.installation);
+  });
+
+  // Hosts that render MCP Apps show this card for the two tools above.
+  // Other hosts ignore the resource and keep the Markdown panel.
+  server.registerResource("ennodia-setup", SETUP_APP_URI, {
+    title: "Ennodia setup",
+    description: "Setup card for hosts that render MCP Apps.",
+    mimeType: MCP_APP_MIME_TYPE,
+  }, async () => ({ contents: [{ uri: SETUP_APP_URI, mimeType: MCP_APP_MIME_TYPE, text: SETUP_APP_HTML, _meta: { ui: { prefersBorder: true, permissions: { clipboardWrite: {} } } } }] }));
+
   server.registerTool(
     "ennodia_list_skills",
     {
@@ -690,7 +742,7 @@ export function createEnnodiaServer(
         prompt: z
           .string()
           .min(1)
-          .describe("The user task to route to local AI harnesses. For native media, first read ennodia_list_harnesses inputGuidance, specify local paths and a harness/model, then verify one small sample with mode single and compare false. Ennodia sends text, not media attachments."),
+          .describe("The user task to route to local AI harnesses. Include relevant Keep in mind constraints, evidence, and unresolved assumptions in this prompt. For native media, first read ennodia_list_harnesses inputGuidance, specify local paths and a harness/model, then verify one small sample with mode single and compare false. Ennodia sends text, not media attachments."),
         category: categorySchema.optional(),
         harnessId: z
           .string()
@@ -850,7 +902,7 @@ export function createEnnodiaServer(
     {
       title: "Get Ennodia run",
       description:
-        "Inspect a run or wait up to waitMs for completion. Prefer waitMs: 30000, compact: true and includeEvents: false while awaiting results. A nonterminal response means work continues; do not claim its findings were consumed.",
+        "Inspect a run or wait up to waitMs for completion, including task-specific keepInMind notes when Compare returns them. Prefer waitMs: 30000, compact: true and includeEvents: false while awaiting results. A nonterminal response means work continues; do not claim its findings were consumed.",
       inputSchema: {
         runId: z.string().min(1).describe("Run ID returned by ennodia_run."),
         compact: z.boolean().default(false).describe("Omit repeated routing, budget, prompt preview and skill metadata. Preserve status, timing, task IDs, answers and errors. Answer and event limits still apply. Use false for full diagnostics."),
@@ -1141,7 +1193,7 @@ export function createEnnodiaServer(
     {
       title: "Get Ennodia Judge + Result Advisor comparison",
       description:
-        "Inspect comparison status, candidate inputs, Judge analysis, Result Advisor answer, child task IDs, degradation state, and ETA.",
+        "Inspect comparison status, candidate inputs, Judge analysis, Result Advisor answer and keepInMind notes with evidence and uncertainty, child task IDs, degradation state, and ETA.",
       inputSchema: {
         compareId: z
           .string()
@@ -1280,6 +1332,53 @@ export async function shutdownEnnodia(
   await defaultCore.shutdown(options);
 }
 
+/** Startup instructions load into every session that has Ennodia configured,
+ * so they stay short and keep Ennodia quiet until there is something to fix. */
+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 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.",
+  ];
+  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(" ")}`);
+  return lines.join("\n");
+}
+
+function accessKey(route: HarnessDiscovery | HarnessAttention): AccessKey {
+  return "id" in route && !route.runnable ? "missing" : route.readiness?.state ?? "unverified";
+}
+
+/** Keep the JSON text contract intact for clients that parse tool text, and
+ * add the panel an agent shows when the host has no card: each agent's status
+ * in plain words, then the exact sign-in commands. */
+function setupResult(value: unknown, routes: (HarnessDiscovery | HarnessAttention)[], installation?: InstallationReport) {
+  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.`);
+  }
+  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 ?? [] : [] };
+  }).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;
+    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.
+  for (const row of rows.filter(row => row.command.length)) {
+    const command = row.command.map(arg => /^[A-Za-z0-9_./:@=+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+    const fence = "`".repeat(Math.max(3, ...[...command.matchAll(/`+/g)].map(match => match[0].length + 1)));
+    lines.push("", `Sign in to ${row.name} in a terminal:`, "", `${fence}sh\n${command}\n${fence}`);
+  }
+  if (rows.some(row => accessRank(row.key) === 0)) lines.push("", "Keep sign-in and API keys in each agent's own CLI, never in this chat.");
+  return { content: [...jsonResult(value).content, { type: "resource" as const, resource: { uri: "ennodia://setup", mimeType: "text/markdown", text: lines.join("\n") } }] };
+}
+
 function jsonResult(value: unknown) {
   return {
     content: [

package/src/setup-app.ts

@@ -0,0 +1,338 @@
+import type { ReadinessState } from "./readiness";
+import { ENNODIA_VERSION } from "./version";
+
+/** MCP Apps (`io.modelcontextprotocol/ui`, stable 2026-01-26) lets a host show
+ * a server's HTML view inside the conversation. Ennodia uses one view: a card
+ * of agents and their fixes. Other hosts show the Markdown panel instead.
+ * The card calls only `ennodia_check_harnesses` and never collects credentials. */
+export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+export const SETUP_APP_URI = "ui://ennodia/setup.html";
+
+/** The flat key serves hosts that predate the nested `ui.resourceUri` form. */
+export const SETUP_APP_TOOL_META = { ui: { resourceUri: SETUP_APP_URI }, "ui/resourceUri": SETUP_APP_URI };
+
+export type AccessKey = ReadinessState | "missing";
+
+/** Plain words for each agent state, shared by the Markdown panel and the card. */
+export const ACCESS_TEXT: Record<AccessKey, { label: string; next: string }> = {
+  "login-required": { label: "Needs sign-in", next: "Sign in with the command below, then check again." },
+  "credentials-expired": { label: "API key expired", next: "Replace the key in the agent's own settings, then check again. Signing in does not renew it." },
+  "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." },
+  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." },
+  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;
+}
+
+export const HARNESS_GUIDE_URL = "https://ennodia.cherninlab.com/docs/reference/supported-harnesses/";
+export const INSTALL_GUIDE_URL = "https://ennodia.cherninlab.com/docs/install/";
+
+/** Plain ES5 so it runs in any host webview without a build step. */
+const SETUP_APP_SCRIPT = String.raw`
+(function () {
+  "use strict";
+  var ACCESS = __ACCESS__, RANK = __RANK__;
+  var state = { agents: [], installation: null, input: {}, host: {}, busy: {}, notes: {}, newlyReady: {}, error: "", loaded: false };
+  var nextId = 1, pending = {}, lastHeight = 0;
+
+  function post(message) { window.parent.postMessage(message, "*"); }
+  function request(method, params) {
+    var id = nextId++;
+    post({ jsonrpc: "2.0", id: id, method: method, params: params || {} });
+    return new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });
+  }
+  function notify(method, params) { post({ jsonrpc: "2.0", method: method, params: params || {} }); }
+  function reply(id, result) { post({ jsonrpc: "2.0", id: id, result: result }); }
+
+  window.addEventListener("message", function (event) {
+    if (event.source !== window.parent) return;
+    var m = event.data;
+    if (!m || m.jsonrpc !== "2.0") return;
+    if (m.method === undefined) {
+      var waiting = pending[m.id];
+      if (!waiting) return;
+      delete pending[m.id];
+      if (m.error) waiting.reject(new Error(m.error.message || "The host rejected the request."));
+      else waiting.resolve(m.result);
+      return;
+    }
+    switch (m.method) {
+      case "ui/notifications/tool-input": state.input = (m.params && m.params.arguments) || {}; break;
+      case "ui/notifications/tool-result": showResult(m.params); break;
+      case "ui/notifications/tool-cancelled": state.loaded = true; state.error = "The check was cancelled."; render(); break;
+      case "ui/notifications/host-context-changed": applyContext(m.params); break;
+      case "ui/resource-teardown": case "ping": if (m.id !== undefined) reply(m.id, {}); break;
+      default: if (m.id !== undefined) post({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "Method not found" } });
+    }
+  });
+
+  function parse(result) {
+    var blocks = (result && result.content) || [];
+    for (var i = 0; i < blocks.length; i++) {
+      if (blocks[i].type !== "text") continue;
+      try { return JSON.parse(blocks[i].text); } catch (error) { return { error: blocks[i].text }; }
+    }
+    return { error: "Ennodia returned no agent data." };
+  }
+  function failed(result, data) { return Boolean(result && result.isError || data.error); }
+
+  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,
+      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; }
+  function merge(list) {
+    (list || []).forEach(function (h) {
+      var agent = normalize(h), current = find(agent.id);
+      if (current) state.agents[state.agents.indexOf(current)] = agent; else state.agents.push(agent);
+    });
+  }
+
+  function showResult(result) {
+    var data = parse(result);
+    state.loaded = true;
+    state.error = failed(result, data) ? (data.error || "Ennodia reported an error.") : "";
+    if (data.installation) state.installation = data.installation;
+    merge(data.harnesses);
+    // Sort once: rows keep their place after a check, so nothing moves under the pointer.
+    state.agents.sort(function (a, b) { return RANK[a.key] - RANK[b.key]; });
+    render();
+  }
+
+  function check(agent) {
+    var args = { harnessIds: [agent.id], refresh: true, verify: true };
+    var model = agent.model || state.input.model;
+    if (model) args.model = model;
+    if (state.input.cwd) args.cwd = state.input.cwd;
+    var before = agent.key;
+    state.busy[agent.id] = true;
+    state.notes[agent.id] = "Checking…";
+    render();
+    request("tools/call", { name: "ennodia_check_harnesses", arguments: args }).then(function (result) {
+      var data = parse(result);
+      if (failed(result, data)) { state.notes[agent.id] = data.error || "The check failed."; return; }
+      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." : "";
+      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(); });
+  }
+
+  function tellAgent(agent, node) {
+    node.disabled = true;
+    var text = agent.name + (agent.model ? " (" + agent.model + ")" : "") + " is ready in Ennodia now.";
+    request("ui/message", { role: "user", content: [{ type: "text", text: text }] }).then(function () {
+      delete state.newlyReady[agent.id]; state.notes[agent.id] = "Sent to the chat."; render();
+    }, function () { node.disabled = false; state.notes[agent.id] = "The host did not accept the message."; render(); });
+  }
+
+  function openLink(url) {
+    if (state.host.openLinks) request("ui/open-link", { url: url }).catch(function () { window.open(url, "_blank", "noopener"); });
+    else window.open(url, "_blank", "noopener");
+  }
+
+  function shellQuote(args) {
+    return args.map(function (arg) { return /^[A-Za-z0-9_.\/:@=+-]+$/.test(arg) ? arg : "'" + arg.replace(/'/g, "'\\''") + "'"; }).join(" ");
+  }
+
+  function copy(text, node, code) {
+    var reset = function () { setTimeout(function () { node.textContent = "Copy"; }, 1600); };
+    var selected = function () {
+      var range = document.createRange(); range.selectNodeContents(code);
+      var selection = window.getSelection(); selection.removeAllRanges(); selection.addRange(range);
+      node.textContent = "Selected"; reset();
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(function () { node.textContent = "Copied"; reset(); }, selected);
+    else selected();
+  }
+
+  function el(tag, className, text) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+  function button(label, className, onClick) {
+    var node = el("button", className, label);
+    node.type = "button";
+    node.addEventListener("click", function () { onClick(node); });
+    return node;
+  }
+
+  function renderAgent(agent) {
+    var needsUser = RANK[agent.key] === 0;
+    var item = el("li", "agent " + (needsUser ? "action" : agent.key === "missing" ? "unavailable" : agent.key));
+    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));
+    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));
+    if (agent.command.length) {
+      var row = el("div", "command");
+      var code = el("code", "", shellQuote(agent.command));
+      row.appendChild(code);
+      row.appendChild(button("Copy", "ghost", function (node) { copy(code.textContent, node, code); }));
+      item.appendChild(row);
+    }
+    if (state.notes[agent.id]) item.appendChild(el("p", "note", state.notes[agent.id]));
+    var actions = el("div", "actions");
+    if (state.host.serverTools && agent.key !== "ready" && agent.key !== "missing") {
+      var checkButton = button(agent.key === "unverified" ? "Verify" : "Check again", needsUser ? "primary" : "", function () { check(agent); });
+      checkButton.disabled = Boolean(state.busy[agent.id]);
+      actions.appendChild(checkButton);
+    }
+    if (agent.key === "missing") actions.appendChild(button("Install guide", "", function () { openLink(__GUIDE__); }));
+    if (state.newlyReady[agent.id] && state.host.message) actions.appendChild(button("Tell the agent", "primary", function (node) { tellAgent(agent, node); }));
+    if (actions.childNodes.length) item.appendChild(actions);
+    return item;
+  }
+
+  function render() {
+    document.getElementById("loading").hidden = state.loaded;
+    var list = document.getElementById("agents");
+    list.textContent = "";
+    state.agents.forEach(function (a) { list.appendChild(renderAgent(a)); });
+    if (state.loaded && !state.agents.length && !state.error) list.appendChild(el("li", "agent", "No supported agents were found on this machine."));
+    var error = document.getElementById("error");
+    error.textContent = state.error; error.hidden = !state.error;
+    var install = document.getElementById("install"), report = state.installation;
+    install.textContent = "";
+    install.hidden = !report || report.status === "healthy";
+    if (!install.hidden) {
+      install.appendChild(el("p", "", "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__); }));
+    }
+    document.getElementById("cost").hidden = !state.host.serverTools || !state.agents.some(function (a) { return a.key !== "ready" && a.key !== "missing"; });
+    resize();
+  }
+
+  function resize() {
+    var height = Math.ceil(document.documentElement.getBoundingClientRect().height);
+    if (height === lastHeight) return;
+    lastHeight = height;
+    notify("ui/notifications/size-changed", { height: height });
+  }
+
+  function applyContext(context) {
+    if (!context) return;
+    var root = document.documentElement;
+    if (context.theme === "light" || context.theme === "dark") { root.setAttribute("data-theme", context.theme); root.style.colorScheme = context.theme; }
+    var variables = context.styles && context.styles.variables;
+    if (variables) Object.keys(variables).forEach(function (key) { if (variables[key]) root.style.setProperty(key, variables[key]); });
+    var fonts = context.styles && context.styles.css && context.styles.css.fonts;
+    if (fonts && !document.getElementById("host-fonts")) { var style = el("style", "", fonts); style.id = "host-fonts"; document.head.appendChild(style); }
+  }
+
+  if (window.ResizeObserver) new ResizeObserver(resize).observe(document.documentElement);
+  render();
+  request("ui/initialize", { appInfo: { name: "ennodia-setup", version: __VERSION__ }, appCapabilities: { availableDisplayModes: ["inline"] }, protocolVersion: "2026-01-26" })
+    .then(function (result) {
+      state.host = (result && result.hostCapabilities) || {};
+      applyContext(result && result.hostContext);
+      notify("ui/notifications/initialized", {});
+      render();
+    }, function () { state.loaded = true; state.error = "This host did not start the Ennodia card."; render(); });
+})();
+`;
+
+const SETUP_APP_STYLE = `
+:root {
+  color-scheme: light dark;
+  --fb-bg: #ffffff; --fb-soft: #f4f4f2; --fb-text: #1c1b19; --fb-muted: #5f5d58; --fb-border: #e4e2dc;
+  --fb-ok: #1f7a3d; --fb-warn: #a65b00; --fb-bad: #b42318;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --fb-bg: #1b1b1a; --fb-soft: #262624; --fb-text: #f2f1ee; --fb-muted: #a9a69f; --fb-border: #3a3936; --fb-ok: #5fd08a; --fb-warn: #f0b04d; --fb-bad: #ff8a7a; }
+}
+:root[data-theme="dark"] { --fb-bg: #1b1b1a; --fb-soft: #262624; --fb-text: #f2f1ee; --fb-muted: #a9a69f; --fb-border: #3a3936; --fb-ok: #5fd08a; --fb-warn: #f0b04d; --fb-bad: #ff8a7a; }
+* { box-sizing: border-box; }
+html, body { margin: 0; }
+body {
+  background: var(--color-background-primary, var(--fb-bg)); color: var(--color-text-primary, var(--fb-text));
+  font: var(--font-text-sm-size, 14px)/var(--font-text-sm-line-height, 1.45) var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif);
+}
+main { padding: 14px 16px 12px; }
+h1 { font-size: var(--font-heading-xs-size, 15px); font-weight: var(--font-weight-semibold, 600); margin: 0; }
+ul { list-style: none; margin: 0; padding: 0; }
+#agents { margin-top: 10px; border-top: 1px solid var(--color-border-primary, var(--fb-border)); }
+.agent { padding: 10px 0; border-bottom: 1px solid var(--color-border-primary, var(--fb-border)); }
+.head { display: flex; align-items: center; gap: 8px; }
+.dot { width: 8px; height: 8px; border-radius: 50%; flex: none; background: var(--color-text-tertiary, var(--fb-muted)); }
+.ready .dot { background: var(--color-text-success, var(--fb-ok)); }
+.action .dot { background: var(--color-text-warning, var(--fb-warn)); }
+.unavailable .dot { background: transparent; border: 1px solid var(--color-text-tertiary, var(--fb-muted)); }
+.name { font-weight: var(--font-weight-medium, 500); min-width: 0; overflow-wrap: anywhere; }
+.model { margin-left: 6px; font-weight: var(--font-weight-normal, 400); color: var(--color-text-secondary, var(--fb-muted)); font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.92em; }
+.status { margin-left: auto; white-space: nowrap; color: var(--color-text-secondary, var(--fb-muted)); }
+.ready .status { color: var(--color-text-success, var(--fb-ok)); }
+.action .status { color: var(--color-text-warning, var(--fb-warn)); }
+.next, .note { margin: 4px 0 0 16px; color: var(--color-text-secondary, var(--fb-muted)); }
+.note { color: var(--color-text-primary, var(--fb-text)); }
+.command { display: flex; align-items: center; gap: 8px; margin: 8px 0 0 16px; padding: 6px 6px 6px 10px; border-radius: var(--border-radius-md, 8px); background: var(--color-background-secondary, var(--fb-soft)); }
+.command code { flex: 1 1 auto; min-width: 0; overflow-x: auto; white-space: nowrap; font: 0.92em/1.4 var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); }
+.actions { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 8px 0 0 16px; }
+button {
+  font: inherit; color: inherit; cursor: pointer; padding: 4px 10px; border-radius: var(--border-radius-sm, 6px);
+  border: 1px solid var(--color-border-primary, var(--fb-border)); background: var(--color-background-primary, var(--fb-bg));
+}
+button:hover { background: var(--color-background-secondary, var(--fb-soft)); }
+button:focus-visible { outline: 2px solid var(--color-ring-primary, var(--fb-text)); outline-offset: 1px; }
+button:disabled { cursor: default; opacity: 0.55; }
+button.primary { background: var(--color-background-inverse, var(--fb-text)); color: var(--color-text-inverse, var(--fb-bg)); border-color: transparent; }
+button.ghost { border-color: transparent; background: transparent; padding: 2px 8px; }
+#install { margin-top: 10px; padding: 8px 10px; border-radius: var(--border-radius-md, 8px); background: var(--color-background-secondary, var(--fb-soft)); }
+#install p { margin: 0 0 4px; font-weight: var(--font-weight-medium, 500); }
+#install ul { margin: 0 0 8px 16px; list-style: disc; color: var(--color-text-secondary, var(--fb-muted)); }
+#loading, .cost { margin: 10px 0 0; color: var(--color-text-secondary, var(--fb-muted)); }
+.cost { font-size: 0.92em; }
+.error { margin: 10px 0 0; color: var(--color-text-danger, var(--fb-bad)); }
+`;
+
+const ACCESS_KEYS = Object.keys(ACCESS_TEXT) as AccessKey[];
+
+export const SETUP_APP_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ennodia agents</title>
+<style>${SETUP_APP_STYLE}</style>
+</head>
+<body>
+<main>
+<h1>Ennodia agents</h1>
+<p id="loading">Checking agents…</p>
+<p id="error" class="error" role="alert" hidden></p>
+<ul id="agents" aria-live="polite"></ul>
+<section id="install" hidden></section>
+<p id="cost" class="cost" hidden>A check sends at most one small model request.</p>
+</main>
+<script>${SETUP_APP_SCRIPT
+  .replace("__ACCESS__", () => JSON.stringify(ACCESS_TEXT))
+  .replace("__RANK__", () => JSON.stringify(Object.fromEntries(ACCESS_KEYS.map(key => [key, accessRank(key)]))))
+  .replace("__GUIDE__", () => JSON.stringify(HARNESS_GUIDE_URL))
+  .replace("__INSTALL__", () => JSON.stringify(INSTALL_GUIDE_URL))
+  .replace("__VERSION__", () => JSON.stringify(ENNODIA_VERSION))}</script>
+</body>
+</html>
+`;

package/src/tasks.ts

@@ -13,6 +13,7 @@ import type {
 import { assertHarnessSettingsSupported, DEFAULT_TASK_TIMEOUT_MS, inputGuidanceNotes, withInputGuidance } from "./harnesses";
 import { preview, tailItems } from "./internal";
 import { signalOwnedProcess } from "./process";
+import { HarnessReadinessError, readinessBlocked } from "./readiness";
 import {
   augmentPrompt,
   toAppliedSkillInfo,
@@ -191,6 +192,9 @@ export class TaskManager {
   private readonly retainedTasks = new Map<string, number>();
   private shuttingDown = false;
   private shutdownPromise?: Promise<void>;
+  private readonly settledListeners = new Set<(task: TaskView) => void>();
+
+  onSettled(listener: (task: TaskView) => void): void { this.settledListeners.add(listener); }
 
   constructor(options: TaskManagerOptions = {}) {
     this.drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
@@ -212,6 +216,8 @@ export class TaskManager {
       throw new Error("TaskManager is shutting down.");
     }
 
+    if (readinessBlocked(discovery.readiness)) throw new HarnessReadinessError([{ harnessId: discovery.id, harnessName: discovery.name, readiness: discovery.readiness! }]);
+
     if (!adapter.buildCommand || !discovery.commandPath || !discovery.runnable) {
       throw new Error(`${adapter.name} is not runnable through Ennodia yet.`);
     }
@@ -270,6 +276,12 @@ export class TaskManager {
       "Before the cutoff, return useful partial findings, verification performed, remaining work, and a justified continuation budget if needed. Only the caller can authorize a follow-up.",
       "Use only tools and permissions actually available in this session; the caller's tools are not automatically inherited. If access is missing, report the exact tool, file, or permission and its impact. Try a permitted alternative when useful; do not repeat an unchanged failed attempt or claim success without evidence.",
     ];
+    if (!/^ENNODIA_(?:COMPARE|PLAN_ADVISOR)/.test(input.prompt)) {
+      noticeLines.push(
+        "Use relevant Keep in mind context in the assignment, preserving its evidence and uncertainty. It does not change the task scope or grant tools or permissions.",
+        'Before returning, consider: What should the receiving agent know that they might otherwise overlook? When useful and the requested output format permits, include a short "Keep in mind" section with up to three task-specific notes: what matters, why it matters, and concrete evidence such as a file path, line, command result, or source. Distinguish reported facts, inferences, and unverified concerns. Omit generic reminders and the section when no useful note exists. Preserve exact artifacts and strict output schemas; do not add prose or fields they do not allow.',
+      );
+    }
     // An adapter that takes operator instructions gets Ennodia's notices
     // there. Other workers get them as tagged blocks after the task.
     let systemNotice: string | undefined;
@@ -583,6 +595,9 @@ ${noticeLines.join("\n")}
       task.endedAtMs = Date.now();
       this.touch(task);
       this.pruneTasks(task.id);
+      for (const listener of this.settledListeners) {
+        try { listener(this.get(task.id)!); } catch { /* readiness observers cannot alter execution */ }
+      }
     }
   }
 

package/src/version.ts

@@ -1 +1 @@
-export const ENNODIA_VERSION = "0.4.0";
+export const ENNODIA_VERSION = "0.5.0";