ennodia 0.4.1 → 0.5.1

package/CONTRIBUTING.md

@@ -122,6 +122,12 @@ the root install. `bun run release:check` enforces these rules.
 The workflow passes it to npm as `NODE_AUTH_TOKEN`. JSR uses GitHub Actions
 OpenID Connect (OIDC) without a JSR token.
 
+Both npm packages publish with `--provenance` from the GitHub-hosted runner.
+The existing `id-token: write` permission lets npm attach a signed record of
+the source and build. This requires a public repository matching each
+package's `repository.url`. Previously published versions keep their
+original metadata. Provenance takes effect on the next new version.
+
 Link scope `@cherninlab`, package `ennodia`, to
 `cherninlab/ennodia` in JSR package settings. The workflow's `id-token: write`
 permission enables that authentication. To reconfigure npm, ensure the token

package/README.md

@@ -57,7 +57,7 @@ For manual setup, add this Model Context Protocol (MCP) server to your client:
 }
 ```
 
-Ennodia loads six core tools by default: about 10,000 characters of tool definitions in each session.
+Ennodia loads eight core tools by default: about 13,000 characters of tool definitions in each session.
 Add `"--tools", "all"` to `args` for the [full tool set](https://ennodia.cherninlab.com/docs/reference/mcp-tools/#tool-sets).
 
 Requirements: Bun `1.3.14` or newer, a compatible MCP client, and a supported agent with working provider access.
@@ -69,18 +69,23 @@ Requirements: Bun `1.3.14` or newer, a compatible MCP client, and a supported ag
 ## How a handoff works
 
 1. Your agent calls `ennodia_run` with the task, the agent or model to use, and a time limit.
-2. Ennodia starts that agent's own command-line tool in a fresh session, with its own tools and your account for it.
+2. Ennodia checks the selected route, then starts that agent's own command-line tool in a fresh session, with its own tools and your account for it.
 3. The answer comes back to your conversation, with its status and a receipt saved on your computer.
 
 Your conversation history stays in your agent.
 For two or more answers, Compare maps agreements, contradictions, and gaps.
 When one answer is complete as it stands, Compare can choose it, and `ennodia_run` returns it unchanged.
 
+Include relevant constraints and prior decisions in your task prompt under **Keep in mind**.
+Ennodia asks workers and Compare to return useful reminders with reasons and evidence.
+Your agent verifies them before carrying them into the next task.
+See [how to read these notes](https://ennodia.cherninlab.com/docs/guides/understand-results/#keep-in-mind).
+
 ## Supported agents
 
 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 finds executable commands. It does not verify authentication or model access.
+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.
 Codex workers use a read-only sandbox by default.
 
 Ennodia discovers native Agent Skills and can request them for specific tasks.
@@ -131,3 +136,26 @@ bun run verify
 [Pragmatic mode](docs/guides/pragmatic-mode.md) runs independent model attempts, tailored plans, and skill trials, then compares the evidence.
 It keeps bulky evidence outside the main conversation and returns findings for your agent to verify.
 Savings are not yet validated.
+
+## Login recovery and updates
+
+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.
+
+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.
+Other hosts, such as Codex and Claude Code, show the Markdown panel.
+
+Run that action in an interactive terminal, then call `ennodia_check_harnesses` with the same harness and model and `refresh: true, verify: true`.
+Run receipts keep missing reviewer coverage visible, including in compact responses.
+
+Supported harness upgrades run once per day on use while Ennodia has no active tasks.
+Set `ENNODIA_AUTO_UPDATE=false` to disable them.
+Use `ennodia_check_harnesses` with `upgrade: true` to update and recheck immediately.
+
+Ennodia also checks its own installation automatically. Run results report the loaded code location, version, runtime, and installation scope. The report checks required files, bundled skills, and storage access. The recheck tool refreshes this report. MCP startup instructions carry only installation problems.
+
+Mention installation limitations when they affect the request. Cache installs can change on a future unpinned launch. These local checks do not verify the latest registry version or provider access.
+See [recovery and updates](https://ennodia.cherninlab.com/docs/reference/supported-harnesses/#recovery-and-updates).

package/bin/ennodia

@@ -5,19 +5,30 @@ import { fileURLToPath } from "node:url";
 
 const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src", "cli.ts");
 
-const bunCheck = spawnSync("bun", ["--version"], { stdio: "ignore" });
+const bunCheck = spawnSync("bun", ["--version"], { encoding: "utf8", timeout: 5_000 });
 
-if (bunCheck.error) {
+if (bunCheck.error || bunCheck.status !== 0) {
   process.stderr.write(
-    "Ennodia requires Bun (1.3.14 or newer) to run, but it wasn't found on your PATH.\n" +
+    "Ennodia requires Bun (1.3.14 or newer). Bun wasn't available on PATH or failed its version check.\n" +
       "Install Bun from https://bun.sh, then try again:\n" +
       "  curl -fsSL https://bun.sh/install | bash\n",
   );
   process.exit(1);
 }
 
+const bunVersion = bunCheck.stdout.trim();
+const minimum = [1, 3, 14];
+const parsed = /^([0-9]+)\.([0-9]+)\.([0-9]+)(?:[-+].*)?$/.exec(bunVersion);
+const parts = parsed?.slice(1, 4).map(Number);
+const firstDifference = parts?.findIndex((part, index) => part !== minimum[index]);
+if (!parts || (firstDifference !== -1 && parts[firstDifference] < minimum[firstDifference]) || (firstDifference === -1 && bunVersion.split("+")[0].includes("-"))) {
+  process.stderr.write(`Ennodia requires Bun >=1.3.14; found ${bunVersion}. Upgrade Bun with bun upgrade, then restart Ennodia.\n`);
+  process.exit(1);
+}
+
 const result = spawnSync("bun", ["run", cliPath, ...process.argv.slice(2)], {
   stdio: "inherit",
+  env: { ...process.env, ENNODIA_LAUNCHER_PATH: fileURLToPath(import.meta.url) },
 });
 
 process.exit(result.status ?? 1);

package/docs/getting-started.md

@@ -31,8 +31,20 @@ Bring the findings back to this conversation.
 ```
 
 Start with one worker and a small set of files.
-Discovery checks installed commands, not authentication, model access, or provider quota.
-A live task establishes which configuration works in your environment.
+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.
+
+For setup or recovery, give your agent this request:
+
+```text
+Show Ennodia setup in this session. Help me fix the agent I choose.
+After I complete native sign-in or configuration, recheck that agent and continue my task.
+```
+
+Your agent calls `ennodia_setup` and shows you each agent's status, with the exact fix for blocked agents.
+Hosts that render MCP Apps can show it as a card with check buttons. A check sends at most one small model request.
+
+Complete sign-in and credential changes in the native tool. Keep credentials out of chat.
 
 Your agent can call `ennodia_list_harnesses`, then `ennodia_run` with a selected `harnessId`, `mode: "single"`, and `compare: false`.
 Poll `ennodia_get_run` with the returned run identifier (ID).
@@ -111,7 +123,7 @@ For a local checkout, use the source file:
 
 Replace `/absolute/path/to/ennodia` with your local repository path.
 
-Ennodia loads six core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
+Ennodia loads eight core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
 
 Use your client's supported configuration method.
 Preserve existing server entries.

package/docs/guides/understand-results.md

@@ -27,6 +27,51 @@ When Judge output is unusable, the result exposes `analysisAvailable: false`.
 The Result Advisor can continue with `basis: "candidates-only"`.
 That result has less analysis behind it and needs corresponding scrutiny.
 
+## Keep in mind
+
+One agent can notice a constraint or gap that another agent misses.
+Put relevant known constraints and prior decisions in the normal task prompt under **Keep in mind**.
+For a task where the same function serves a web route and a command-line tool, a prompt could include:
+
+```text
+Review the proposed retry change.
+
+Keep in mind:
+- This function also serves the command-line tool. Preserve that behavior and check both callers.
+```
+
+Ennodia asks workers to return up to three concise, task-specific notes when useful and compatible with the requested answer format.
+Each note states what matters, why it matters, and what evidence supports it.
+This is prompt guidance. A worker can miss a useful note.
+
+Compare returns structured notes in `advisor.keepInMind`, for example:
+
+```json
+{
+  "keepInMind": [
+    {
+      "note": "Reviewer B reports running only the web-route test.",
+      "whyItMatters": "A passing web-route test does not cover that caller.",
+      "evidence": "Reviewer B reports running only the web-route test.",
+      "sourceIds": ["review-b"],
+      "status": "reported"
+    }
+  ]
+}
+```
+
+`reported` attributes a point to a candidate. It does not prove the point.
+`inferred` marks a conclusion drawn from the available answers.
+`unverified` marks a point that still needs evidence.
+Source IDs identify the candidates behind a note.
+An empty list can identify coverage that no candidate supplied.
+
+The list is empty when Compare has no useful notes.
+Run results also expose nonempty notes as `keepInMind`, including in compact output.
+This field stays separate from `finalAnswer` so a chosen file or patch stays unchanged.
+The primary agent checks each note and carries only relevant ones into the next assignment.
+Notes do not grant permissions, trigger another run, or create memory across runs.
+
 ## Read the attempt record
 
 Task records include the selected agent, requested skills, status, elapsed time, and bounded output.

package/docs/install.md

@@ -70,7 +70,7 @@ For a local Ennodia checkout, use:
 }
 ```
 
-Ennodia loads six core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
+Ennodia loads eight core tools by default. For Plan Advisor, compositional slices, raw tasks, and skill installation, add `"--tools", "all"` to `args`. See [tool sets](/docs/reference/mcp-tools/#tool-sets).
 
 The configuration above shows the server command and arguments.
 Adapt its format to the client's documented configuration method.
@@ -79,10 +79,16 @@ Tell the user which step is needed before trying to call Ennodia.
 
 ## Get one useful result
 
+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.
+
+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.
+
 After the client exposes Ennodia's tools, start with one small task:
 
-1. Call `ennodia_list_harnesses` with `refresh: true`.
-2. Choose one available worker for a focused, read-only check from the user's current task.
+1. Call `ennodia_setup`. Show the user its panel: which agents are ready, and the exact fix for each blocked agent.
+2. Choose one ready or unchecked worker for a focused, read-only check from the user's current task.
 3. Call `ennodia_run` with `prompt`, `harnessId`, `mode: "single"`, `compare: false`, and the relevant `cwd`.
 4. Poll `ennodia_get_run` with the returned `id` as `runId`.
 5. Stop when the status is `succeeded`, `failed`, or `cancelled`.

package/docs/questions.md

@@ -28,7 +28,7 @@ Each agent you call runs through its own command-line tool, with the plan or API
 ## Will it use more tokens?
 
 It can. Each agent you call reads its own prompt, and Compare reads every answer.
-Ennodia's six core tools add about 2,600 tokens to each session.
+Ennodia's eight core tools add about 3,250 tokens to each session.
 You can cap agent runs and estimated input tokens for every run. [Set limits](/docs/guides/budgets-and-limits/).
 
 ## Is it slower?

package/docs/reference/mcp-tools.md

@@ -11,8 +11,8 @@ events, child task IDs, Judge + Result Advisor state, and the final answer.
 ## Tool sets
 
 An agent loads every tool definition into each session where Ennodia is configured, even when the session never calls Ennodia.
-By default, Ennodia loads six core tools, about 10,000 characters of definitions.
-They cover handing work to one agent or a team, Compare, waiting, cancelling, and run history.
+By default, Ennodia loads eight core tools, about 13,000 characters of definitions.
+They cover handing work to one agent or a team, Compare, waiting, cancelling, run history, and harness recovery.
 
 The full set adds 20 tools for raw tasks, compositional slices, Plan Advisor, budget estimates, separate Compare calls, and skill installation.
 It loads about 46,000 characters of definitions.
@@ -50,7 +50,9 @@ This setting approves Ennodia runs only. Codex's sandbox and its other tools kee
 
 | Goal | Tool sequence | Tool set |
 | --- | --- | --- |
-| Check local setup | `ennodia_list_harnesses` | core |
+| Show agent status and fixes in this session | `ennodia_setup` | core |
+| Recheck an agent after a fix | `ennodia_check_harnesses` | core |
+| List agents for routing | `ennodia_list_harnesses` | core |
 | Start a visible end-to-end run | `ennodia_run` -> `ennodia_get_run` | core |
 | Inspect terminal receipts after restart | `ennodia_history` | core |
 | Preview route and cost | `ennodia_estimate_budget` | full |
@@ -172,6 +174,9 @@ Version probes have bounded deadlines. A failed probe appears in adapter notes w
 | --- | --- | --- |
 | `refresh` | `false` | Ignore the short discovery cache and re-scan. |
 
+The result is JSON only. Agents call this tool for routing, so it carries no setup panel.
+Use `ennodia_setup` to show the user each agent's status and fix.
+
 Use this first when a client setup, command path, or adapter is not behaving as
 expected.
 
@@ -238,6 +243,8 @@ arguments, permissions, isolation, timeouts, retries, or budgets.
 Harness inventory entries preserve optional `inputGuidance: string[]` from discovery.
 Plan Advisor treats this bounded guidance as observations, not proof of native media support.
 Slices execute concurrently. For unverified native access, its instructions request a probe-only plan, followed by a new plan after the probe.
+Plan Advisor also asks each slice prompt to carry relevant constraints and prior decisions from the original task under **Keep in mind**.
+This guidance does not pass one independent candidate's findings to another.
 
 The lifecycle is deliberately two-phase: request and inspect advice first, then
 launch the exact validated plan in a separate call. Ennodia rejects invalid
@@ -419,6 +426,12 @@ It also returns the final answer when available. The important value is `id`.
 Poll it with
 `ennodia_get_run`.
 
+Include relevant constraints and prior decisions under **Keep in mind** in the normal `prompt`.
+There is no separate input field.
+Workers are asked to return up to three useful notes with reasons and evidence when the requested answer format permits.
+For compared runs, nonempty Result Advisor notes appear in `keepInMind`, separate from `finalAnswer`.
+Normal and compact run views preserve this field.
+
 ### `ennodia_get_run`
 
 Returns the current run state. Set `waitMs` to wait for completion without repeated immediate polls. A wait timeout leaves the run running.
@@ -615,6 +628,23 @@ blind spots, and risks. The Result Advisor uses that analysis plus the original
 candidates to return a typed answer, basis, confidence, and open questions.
 This is model-led comparison, not formal voting.
 
+The Result Advisor also returns `keepInMind`: up to three task-specific notes that the receiving agent could overlook.
+The field defaults to `[]` when omitted or when no useful notes are available.
+Each note has these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `note` | Constraint, connection, assumption, or gap to carry forward (at most 1000 characters). |
+| `whyItMatters` | Effect on the task or next decision (at most 1000 characters). |
+| `evidence` | Supporting observation or explicit evidence gap (at most 2000 characters). |
+| `sourceIds` | Up to 64 listed candidate IDs supporting the note. A `reported` note requires a source. Use `[]` for inferred or unverified missing coverage. |
+| `status` | `reported` for an attributed candidate report, `inferred` for a conclusion from available answers, or `unverified` for a point that needs evidence. |
+
+A `reported` note is not independent proof.
+Invalid optional notes are omitted with an `advisor-notes-ignored` event. The valid answer and candidate choice are preserved.
+The primary agent verifies notes and carries only relevant ones into later prompts.
+These notes do not change permissions, start another run, or create memory across runs.
+
 When one candidate fully answers the prompt as it stands, such as a complete
 file, the Result Advisor names it in `chosenSourceId`. A caller can then use
 that candidate's own text, not a rewrite. `ennodia_run` does this for you: its
@@ -702,6 +732,8 @@ After the worker settles, inspect its task receipt. If `canContinue` is true,
 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.
 An earlier turn cannot be used once a follow-up has started.
 
 Continuation requires a task still held by the same running Ennodia server.
@@ -768,3 +800,62 @@ Preserve full patch artifacts and verify them before application.
 A later Compare call and its Judge and Result Advisor have separate limits.
 `includeCompareEstimate` includes an estimate, not a reserved spending balance.
 Count these stages, retries and verification when reporting whole-task cost.
+
+### `ennodia_setup`
+
+Show the user each agent's status and the exact fix for blocked agents.
+The tool takes no input. It refreshes native sign-in status without a model request.
+It declares `readOnlyHint`, so clients such as Codex run it without an approval prompt.
+
+The result has the same JSON shape as `ennodia_check_harnesses`, plus the `ennodia://setup` panel.
+Hosts that render MCP Apps show the [setup card](#setup-card) in place of the panel.
+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`.
+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.
+
+The card lists agents that need the user first, with the next step for each.
+A login blocker shows its sign-in command with a copy button.
+Each check button calls `ennodia_check_harnesses` for that agent and model with `verify: true`.
+A check sends at most one small model request.
+When an agent becomes ready, the card can send a short note to the chat.
+
+The card loads no external code and makes no network requests.
+It never collects credentials.
+
+### `ennodia_check_harnesses`
+
+`ennodia_check_harnesses` is part of the default tool set.
+
+The result includes `installation`, a local self-check of Ennodia's loaded code root, version, installation scope, Bun runtime, core files, bundled skills, and storage access. MCP initialization sends only its problems to the host, and a healthy installation adds nothing. `ennodia_run` and `ennodia_get_run` include the full report even in compact results. Mention its limitations when they affect the request.
+
+`refresh: true` refreshes installation evidence as well as harness readiness. Scope remains `unknown` when filesystem evidence is insufficient. The report does not verify registry freshness, provider access, disk capacity, or future writes.
+
+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.
+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.
+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.
+
+`upgrade: true` runs supported updaters before rediscovery and recheck.
+This tool can change installed software and call providers, so it does not declare `readOnlyHint`.
+
+Present `actionRequired` immediately, including on partial success.
+Do not wait for an explicit user question about missing reviewers.
+Run preflight errors return `isError`, recovery actions, and zero started reviewers.
+Run receipts retain `preflight`, `coverage`, and `actionRequired` in compact responses.
+Use the matching native recovery action, then recheck the same route.
+
+An expired provider API key returns `credentials-expired` and requires key replacement.
+Depleted credits return `quota-exhausted` and require capacity recovery.
+See [Recovery and updates](/docs/reference/supported-harnesses/#recovery-and-updates).

package/docs/reference/supported-harnesses.md

@@ -7,6 +7,12 @@ Ennodia coordinates local agents through thin adapters. Each harness uses a
 local command-line interface (CLI). Use `ennodia_list_harnesses` to see what is
 installed and runnable on the current machine.
 
+On macOS, discovery checks the existing `PATH` first, then `/opt/homebrew/bin`,
+`/usr/local/bin`, and `~/.local/bin`. This covers restricted GUI and MCP launch
+paths without changing the selected account, model, or child process environment.
+Explicit command paths and routes with no command candidates stay unchanged.
+Restart the MCP server after updating Ennodia to load discovery changes.
+
 ## Adapter IDs
 
 | ID | Tool | Notes |
@@ -32,15 +38,18 @@ installed and runnable on the current machine.
 ```
 
 The response reports availability, runnable state, command path, version,
-capabilities, adapter notes, and optional `inputGuidance`.
+capabilities, adapter notes, optional `inputGuidance`, and `readiness`.
 
 `inputGuidance` is a bounded `string[]` of adapter observations and input advice.
 It does not guarantee media support, authentication, or access to a requested model.
 Plan Advisor receives this guidance in its harness inventory.
 
-Discovery checks installed commands, not active authentication or model access.
-A stalled version probe stops at its deadline and adds an adapter note.
-Use a small real task to check the selected agent before sending larger work.
+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.
+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.
 
 ## Media inputs
 
@@ -110,6 +119,77 @@ agy --version
 agy models
 ```
 
-If the shell cannot find `agy` at all, open Antigravity and use its supported
-CLI install or shell-integration flow first. Then restart the Model Context
+If neither `PATH` nor the native install roots contain `agy`, open Antigravity
+and use its supported CLI install or shell-integration flow first. Then restart the Model Context
 Protocol (MCP) client and call `ennodia_list_harnesses` again.
+
+## Recovery and updates
+
+Run the native command returned in `readiness.recovery` in an interactive terminal.
+Keep the intended account, provider, and model.
+Call `ennodia_check_harnesses` after sign-in:
+
+```json
+{
+  "harnessIds": ["codex"],
+  "refresh": true,
+  "verify": true
+}
+```
+
+Pass the same `model` and `cwd` when rechecking an explicit route.
+The check returns `actionRequired` for login, setup, model, capacity, and connectivity blockers.
+A missing CLI requires installation. A capacity failure requires capacity recovery.
+Neither is fixed by repeated sign-in.
+
+`credentials-expired` means the configured provider API key has expired.
+Replace the key through the native credential flow for the intended provider.
+Signing in again does not renew an expired API key.
+`quota-exhausted` includes depleted credits.
+Restore credits or quota through the intended provider before rechecking.
+
+Ennodia reads terminal-formatted native errors and returns the matching recovery action.
+A worker's plain-text answer does not trigger a sign-in or capacity recovery action.
+
+Hermes uses the full `hermes chat` CLI. The legacy `hermes-agent` executable is not compatible.
+
+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.
+Checking every supported harness is not a prerequisite for a run.
+
+Unrelated harness blockers do not prevent work on a usable requested route.
+A verified default route does not prove access to other models.
+Use the existing user authorization and the host approval policy.
+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.
+
+Before ordinary execution, Ennodia attempts supported upgrades once per day while no Ennodia task is active.
+Homebrew installations use their installed formula or cask.
+An npm Codex installation uses its supported npm update command.
+Other supported installations use native updaters.
+
+Updates preserve the installed distribution and channel and use no force flags.
+Pinned or unsupported installations and failed updates require native maintenance.
+Updater success is not proof of model readiness.
+Ennodia rediscovers the version and rechecks the route.
+
+Set `ENNODIA_AUTO_UPDATE=false` in the MCP server environment to disable automatic upgrades.
+Call `ennodia_check_harnesses` with `upgrade: true` for an immediate update attempt and recheck.
+The response includes `readiness.upgrade` with the update result and native command.
+Approved Advisor plans do not upgrade during execution, so their frozen inventory remains stable.
+Automatic updates run on use.
+Ennodia does not install a background daemon.
+
+Report `actionRequired` and reduced `coverage` to the user on the first response that contains them.
+Compact run responses retain these fields.
+MCP clients control how those responses appear in the conversation.

package/docs/releases/0.5.0.md

@@ -0,0 +1,43 @@
+---
+title: Ennodia 0.5.0
+description: Readiness, recovery, setup cards, and attributed comparison notes.
+---
+
+# Ennodia 0.5.0
+
+Release scope for 9 November 2026.
+
+## Core
+
+- Installation evidence identifies runtime, package, and storage limitations.
+- Readiness preflight checks selected routes before orchestration. Native
+  recovery distinguishes sign-in, expired keys, unavailable models, and quota.
+- `ennodia_setup` shows agent status and recovery steps. Compatible hosts show
+  a setup card. Other hosts receive the Markdown panel.
+- Comparison results and history carry attributed “Keep in mind” notes,
+  with evidence and uncertainty kept separate from the chosen answer.
+- The npm launcher rejects unsupported Bun runtimes. Packaged installation
+  checks cover the new runtime files.
+
+## Website and publishing
+
+The website includes conversation examples and refined landing-page controls.
+New npm releases include provenance. GitHub Actions use updated pinned versions.
+The Astro and Starlight major migration is tracked separately in
+[issue 24](https://github.com/cherninlab/ennodia/issues/24).
+
+## Validation and limits
+
+The release gates are `bun run release:check`, including the full verification
+suite, npm and JSR dry-runs, and real packed-package MCP handshakes through
+`bunx`, `npm exec`, and `npx`. Registry publication and website deployment must
+also succeed in their separate GitHub Actions workflows.
+
+Mobile source is included in `apps/mobile` as the separate `0.1.0+1` development
+project. Analysis and all 18 Flutter tests passed on 9 November. Native builds,
+assistant connections, and store releases remain unavailable or unverified.
+Mobile is excluded from the npm and JSR packages.
+
+Private benchmark material remains local. No new benchmark-quality or savings
+claim is part of this release. Release checks do not prove access to every
+provider account or model.

package/docs/roadmap.md

@@ -9,7 +9,8 @@ Future items are proposals, not available behavior or release dates.
 | Stage | User outcome | Product work |
 | --- | --- | --- |
 | Current | Try another agent or skill from the same conversation. | Discovery, focused tasks, explicit choices, optional team advice, Compare, and local history. |
-| Next release candidate | Trust the reported outcome and recover from failed attempts. | Process cleanup, valid comparison evidence, safer local server requests, clearer errors, and task-based guides. |
+| 0.5.0 release candidate | Find setup problems before work starts and retain useful advice. | Harness readiness, recovery, installation checks, and attributed result notes. |
+| Mobile foundation | Start using Ennodia on Android and iOS. | Flutter app, permitted discovery, setup journal, cancellation, and verified undo. Assistant connections are not available yet. |
 | Next | Avoid repeating unsuccessful attempts. | Local outcome notes with task, model, version, skill, and relevant conditions. |
 | Later | Spend less time inspecting tool configuration. | Supported version and capability checks, clearer execution settings, and useful progress checkpoints. |
 | Later | Get useful suggestions for the next attempt. | Recommendations grounded in recorded outcomes, with reasons and uncertainty. |
@@ -21,3 +22,6 @@ Recorded outcomes need a way to inspect, correct, and delete them.
 
 The [measurement plan](/docs/evidence/measurement/) covers task correctness, time, resources, and human work.
 General savings claims will need comparative evidence.
+
+Ennodia Mobile has a separate development version. The implementation and device
+validation plan live in `apps/mobile/README.md` in the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ennodia",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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",
@@ -38,7 +38,9 @@
     "src/core.ts",
     "src/diagnosis.ts",
     "src/harnesses.ts",
+    "src/readiness.ts",
     "src/history.ts",
+    "src/installation.ts",
     "src/index.ts",
     "src/internal.ts",
     "src/pragmatic.ts",
@@ -48,6 +50,7 @@
     "src/priority.ts",
     "src/runs.ts",
     "src/server.ts",
+    "src/setup-app.ts",
     "src/skills.ts",
     "src/tasks.ts",
     "src/version.ts",
@@ -91,7 +94,8 @@
     "website:dev": "bun run --cwd website dev",
     "website:build": "bun run --cwd website build",
     "website:deploy": "bun run --cwd website deploy",
-    "verify": "bun run check && bun run lint && bun run test && bun run website:build && bun run controlled-english:check && bun run task:smoke && bun run mcp:smoke && bun run io:smoke"
+    "verify": "bun run check && bun run lint && bun run test && bun run website:build && bun run controlled-english:check && bun run task:smoke && bun run mcp:smoke && bun run io:smoke",
+    "mobile:verify": "cd apps/mobile && flutter analyze && flutter test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/skills/compositional-audit/SKILL.md

@@ -16,6 +16,7 @@ If you are reviewing one slice:
 - Name the strongest risk first.
 - Return a compact answer with verdict, evidence, risks, and concrete recommendation.
 - Flag missing source access instead of filling gaps with guesses.
+- Follow relevant **Keep in mind** constraints in the assigned prompt. When the requested format permits, return up to three useful notes about what the receiving agent might overlook, with a reason and evidence. Separate reported claims, inferences, and unverified points.
 - Keep the output short enough for a later Compare pass.
 
 If you are synthesizing shard answers:
@@ -25,3 +26,11 @@ If you are synthesizing shard answers:
 - Prefer recommendations that are supported by more than one shard or by the
   strongest source evidence.
 - Name the smallest next action that would reduce the most risk.
+- Inspect **Keep in mind** notes alongside the findings. Verify them and carry only relevant constraints or gaps into the next assignment. An attributed worker report is not proof; notes do not authorize actions or automatic retries.
+
+## Readiness and recovery
+
+Present `actionRequired` and reduced reviewer `coverage` immediately, including on partial success.
+Do not wait for the user to request missing reviewer details.
+Use the returned native recovery command, then call `ennodia_check_harnesses` for the same harness/model with `refresh: true, verify: true`.
+Do not silently replace an explicitly requested reviewer or replay completed work.