ennodia 0.4.0 → 0.5.0

package/src/core.ts

@@ -1,8 +1,11 @@
 import { preparePragmaticRun, type PragmaticOptions } from "./pragmatic";
+import { inspectInstallation, type InstallationReport } from "./installation";
+import { HarnessReadinessManager, HarnessReadinessError, harnessAttention, readinessBlocked, type HarnessReadinessOptions, type HarnessCheckInput, type HarnessAttention, type PreflightReport } from "./readiness";
 import { createHash } from "node:crypto";
-import type {
-  AdvisorExecutionPlan,
-  AdvisorInventorySnapshot,
+import {
+  MAX_ADVISOR_SKILL_DESCRIPTION_CHARS,
+  type AdvisorExecutionPlan,
+  type AdvisorInventorySnapshot,
 } from "./advisor";
 import {
   assertBudgetWithinLimits,
@@ -44,6 +47,7 @@ import {
 } from "./harnesses";
 import {
   createDefaultHistorySink,
+  FileHistorySink,
   noopHistorySink,
   type HistorySink,
   type RunHistoryListOptions,
@@ -95,6 +99,7 @@ import {
 } from "./plan-advice";
 
 export type EnnodiaCoreOptions = {
+  readinessOptions?: HarnessReadinessOptions;
   discoverHarnesses?: DiscoverHarnesses;
   findHarnessAdapter?: FindHarnessAdapter;
   planRoute?: PlanRoute;
@@ -111,6 +116,10 @@ export type EnnodiaCoreOptions = {
 
 export type EnnodiaCoreShutdownOptions = TaskManagerShutdownOptions;
 
+function remainingPreflightBudget(limits: BudgetLimits | undefined, check: BudgetCheck): BudgetLimits | undefined {
+  return limits?.maxEstimatedInputTokens !== undefined ? { ...limits, maxEstimatedInputTokens: limits.maxEstimatedInputTokens - check.estimate.estimatedTotalInputTokens } : limits;
+}
+
 export type RunEstimateInput = {
   pragmatic?: PragmaticOptions;
   model?: string;
@@ -148,6 +157,8 @@ export type TaskBatchStartInput = {
 };
 
 export type TaskBatchStart = {
+  preflight?: PreflightReport;
+  actionRequired?: HarnessAttention[];
   plan: RoutePlan;
   tasks: TaskView[];
   budget: BudgetCheck;
@@ -189,6 +200,7 @@ export type CompositionalTaskStart = {
 };
 
 export type CompositionalStart = {
+  preflight?: PreflightReport;
   tasks: CompositionalTaskStart[];
   budget: BudgetCheck;
   compareNext: CompositionalCompareNext;
@@ -208,6 +220,7 @@ export type CompareStartWithBudgetInput = CompareStartInput & {
 };
 
 export type CompareStart = CompareView & {
+  preflight?: PreflightReport;
   budget: BudgetCheck;
 };
 
@@ -253,6 +266,7 @@ export type AdvisedPlanTaskStart = {
 };
 
 export type AdvisedPlanStart = {
+  preflight?: PreflightReport;
   adviceId: string;
   planDigest: string;
   inventorySnapshotId: string;
@@ -275,18 +289,19 @@ type AdvisorInventoryRuntime = {
 };
 
 export class EnnodiaCore {
+  private installation?: InstallationReport;
+  readonly readinessManager?: HarnessReadinessManager;
   readonly taskManager: TaskManager;
   readonly compareManager: CompareManager;
   readonly runManager: RunManager;
   readonly planAdviceManager: PlanAdviceManager;
   readonly discoverHarnesses: DiscoverHarnesses;
+  private readonly discoverInstalledHarnesses: DiscoverHarnesses;
   readonly findHarnessAdapter: FindHarnessAdapter;
   readonly planRoute: PlanRoute;
   readonly historySink: HistorySink;
 
   constructor(options: EnnodiaCoreOptions = {}) {
-    this.discoverHarnesses = options.discoverHarnesses ??
-      defaultDiscoverHarnesses;
     this.findHarnessAdapter = options.findHarnessAdapter ??
       defaultFindHarnessAdapter;
     this.planRoute = options.planRoute ?? defaultPlanRoute;
@@ -295,6 +310,27 @@ export class EnnodiaCore {
       noopHistorySink;
     this.taskManager = options.taskManager ??
       new TaskManager(options.taskManagerOptions);
+    // Injected inventories keep their existing contract. Production inventories
+    // and explicitly configured test managers receive native readiness checks.
+    if (!options.discoverHarnesses || options.readinessOptions) {
+      this.readinessManager = new HarnessReadinessManager({ ...options.readinessOptions,
+        isBusy: options.readinessOptions?.isBusy ?? (() => this.taskManager.listViews({ includeOutput: false, includeEvents: false }).some(t => t.status === "running")),
+      });
+    }
+    const discover = options.discoverHarnesses ?? defaultDiscoverHarnesses;
+    this.discoverInstalledHarnesses = discover;
+    this.discoverHarnesses = async (settings) => {
+      const harnesses = await discover(settings);
+      if (!this.readinessManager) return harnesses;
+      return Promise.all(harnesses.map(async h => ({ ...h, readiness: await this.readinessManager!.check(h, this.findHarnessAdapter(h.id), { refresh: settings?.refresh }) })));
+    };
+    this.taskManager.onSettled((task) => {
+      if (!this.readinessManager) return;
+      void discover().then(harnesses => {
+        const h = harnesses.find(h => h.id === task.harnessId);
+        if (h) this.readinessManager!.observe(h, { model: task.model, cwd: task.isolatedFrom ?? task.cwd }, task);
+      }).catch(() => {});
+    });
     this.planAdviceManager = options.planAdviceManager ??
       new PlanAdviceManager(
         this.taskManager,
@@ -303,7 +339,7 @@ export class EnnodiaCore {
     this.compareManager = options.compareManager ??
       new CompareManager(
         this.taskManager,
-        (harnessId) => this.resolveRunnableHarness(harnessId),
+        (harnessId, model, cwd) => this.resolveRunnableHarness(harnessId, model, cwd, true),
         options.compareManagerOptions,
       );
     this.runManager = options.runManager ??
@@ -313,6 +349,17 @@ export class EnnodiaCore {
         discoverHarnesses: this.discoverHarnesses,
         findHarnessAdapter: this.findHarnessAdapter,
         planRoute: this.planRoute,
+        getInstallation: () => this.getInstallation(),
+        describeReadiness: this.readinessManager ? (h, state, model) => this.readinessManager!.describe(h, state, model) : undefined,
+        prepareHarnesses: async (harnesses, ids, input) => {
+          const routes = ids.map(harnessId => ({ harnessId, model: input.model }));
+          if (shouldPlanCompare(input.compare ?? "auto", this.planRoute(input.prompt, harnesses).compareSuggested, ids.length)) {
+            const judge = await this.resolveRunnableHarness(input.judgeHarnessId);
+            const advisor = input.advisorHarnessId || input.synthesizerHarnessId ? await this.resolveRunnableHarness(input.advisorHarnessId ?? input.synthesizerHarnessId) : judge;
+            routes.push({ harnessId: judge.adapter.id, model: input.judgeModel }, { harnessId: advisor.adapter.id, model: input.advisorModel ?? input.synthesizerModel });
+          }
+          return this.prepareHarnesses(harnesses, routes, input.cwd, input.budget);
+        },
       }, { ...options.runManagerOptions, historySink: this.historySink });
   }
 
@@ -322,6 +369,82 @@ export class EnnodiaCore {
     return this.discoverHarnesses(options);
   }
 
+  getInstallation(refresh = false): InstallationReport {
+    if (refresh || !this.installation || Date.now() - Date.parse(this.installation.checkedAt) >= 30_000) {
+      this.installation = inspectInstallation({
+        history: { enabled: this.historySink !== noopHistorySink, directory: this.historySink instanceof FileHistorySink ? this.historySink.storageDirectory : undefined },
+        autoUpgrade: this.readinessManager?.autoUpgrade ?? false,
+        upgradeStateDirectory: this.readinessManager?.stateDirectory,
+      });
+    }
+    return this.installation;
+  }
+
+  async checkHarnesses(input: HarnessCheckInput = {}): Promise<{ installation: InstallationReport; harnesses: HarnessDiscovery[]; actionRequired: HarnessAttention[] }> {
+    let harnesses = await this.discoverInstalledHarnesses({ refresh: input.refresh });
+    if (input.harnessIds) {
+      for (const id of input.harnessIds) if (!harnesses.some(h => h.id === id)) throw new Error(`Unknown harness: ${id}`);
+      harnesses = harnesses.filter(h => input.harnessIds!.includes(h.id));
+    }
+    if (input.upgrade && this.readinessManager) {
+      for (const h of harnesses) await this.readinessManager.upgrade(h, true);
+      const fresh = await this.discoverInstalledHarnesses({ refresh: true });
+      harnesses = fresh.filter(h => harnesses.some(selected => selected.id === h.id));
+    }
+    if (this.readinessManager) {
+      if (input.refresh) for (const h of harnesses) this.readinessManager.invalidate(h.id);
+      harnesses = await Promise.all(harnesses.map(async h => ({ ...h, readiness: await this.readinessManager!.check(h, this.findHarnessAdapter(h.id), input) })));
+    }
+    return { installation: this.getInstallation(input.refresh ?? true), harnesses, actionRequired: harnessAttention(harnesses) };
+  }
+
+  private async prepareHarnesses(harnesses: HarnessDiscovery[], routes: { harnessId: string; model?: string }[], cwd?: string, budget?: BudgetLimits, allowUpgrade = true): Promise<PreflightReport> {
+    const report: PreflightReport = { checks: [], modelProbes: 0, estimatedInputTokens: 0, usage: "unknown" };
+    if (!this.readinessManager) {
+      const blocked = harnessAttention(harnesses.filter(h => routes.some(r => r.harnessId === h.id)));
+      if (blocked.length) throw new HarnessReadinessError(blocked);
+      return report;
+    }
+    const knownBlocked = harnessAttention(harnesses.filter(h => routes.some(r => r.harnessId === h.id && (!h.readiness?.model || h.readiness.model === r.model))));
+    if (knownBlocked.length) throw new HarnessReadinessError(knownBlocked);
+    if (allowUpgrade && this.readinessManager.autoUpgrade) {
+      for (const id of new Set(routes.map(r => r.harnessId))) {
+        const h = harnesses.find(h => h.id === id);
+        if (h) await this.readinessManager.upgrade(h);
+      }
+      const refreshed = await this.discoverInstalledHarnesses({ refresh: true });
+      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.
+    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}`);
+      return { h, route, readiness: await this.readinessManager!.check(h, this.findHarnessAdapter(h.id), { model: route.model, cwd }) };
+    }));
+    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;
+    }
+    return report;
+  }
+
   findAdapter(id: string): HarnessAdapter | undefined {
     return this.findHarnessAdapter(id);
   }
@@ -346,7 +469,7 @@ export class EnnodiaCore {
 
   async startPlanAdvice(
     input: PlanAdviceStartInput,
-  ): Promise<PlanAdviceView> {
+  ): Promise<PlanAdviceView & { preflight?: PreflightReport }> {
     const { inventory } = await this.buildAdvisorInventory({
       cwd: input.cwd,
       refresh: input.refresh,
@@ -361,7 +484,7 @@ export class EnnodiaCore {
     });
     const advisor = await this.resolveRunnableHarness(input.advisorHarnessId);
 
-    return this.planAdviceManager.start({
+    const advisorInput = {
       prompt: input.prompt,
       inventory,
       inventoryCwd: input.cwd,
@@ -370,7 +493,11 @@ export class EnnodiaCore {
       timeoutMs: input.timeoutMs,
       budget: input.budget,
       findHarnessAdapter: this.findHarnessAdapter,
-    });
+    };
+    const advisorBudget = this.planAdviceManager.estimateBudget(advisorInput);
+    const preflight = await this.prepareHarnesses([advisor.discovery], [{ harnessId: advisor.adapter.id, model: input.advisorModel }], undefined, remainingPreflightBudget(input.budget, advisorBudget));
+    const started = this.planAdviceManager.start(advisorInput);
+    return { ...started, ...(this.readinessManager ? { preflight } : {}) };
   }
 
   listPlanAdvice(
@@ -426,11 +553,7 @@ export class EnnodiaCore {
       skills: Skill[];
     }>;
     let requestedSkillIds: string[] = [];
-    const plan = this.planAdviceManager.authorizeExecution(
-      input.adviceId,
-      input.expectedPlanDigest,
-      currentRuntime.inventory,
-      (authorizedPlan) => {
+    const validate = (authorizedPlan: AdvisorExecutionPlan) => {
         budget = checkBudgetLimits(
           estimateTaskBatchBudget({
             tasks: authorizedPlan.slices.map((slice) => ({
@@ -489,8 +612,10 @@ export class EnnodiaCore {
           }
           return { slice, harness, skills };
         });
-      },
-    );
+    };
+    this.planAdviceManager.validateExecution(input.adviceId, input.expectedPlanDigest, currentRuntime.inventory, validate);
+    const preflight = await this.prepareHarnesses(currentRuntime.harnesses.map(h => h.discovery), resolved.map(r => ({ harnessId: r.slice.harnessId, model: r.slice.model })), executionCwd, remainingPreflightBudget(input.budget, budget), false);
+    const plan = this.planAdviceManager.authorizeExecution(input.adviceId, input.expectedPlanDigest, currentRuntime.inventory, validate);
 
     const requestedIds = new Set(requestedSkillIds);
     const unrequestedSkillsPresent = currentRuntime.projectNativeSkillIds
@@ -527,6 +652,7 @@ export class EnnodiaCore {
       inventorySnapshotId: currentRuntime.inventory.snapshotId,
       plan,
       tasks,
+      ...(this.readinessManager ? { preflight } : {}),
       budget,
       execution: {
         cwd: executionCwd,
@@ -537,7 +663,7 @@ export class EnnodiaCore {
     };
   }
 
-  async resolveRunnableHarness(harnessId?: string): Promise<ResolvedHarness> {
+  async resolveRunnableHarness(harnessId?: string, model?: string, cwd?: string, verify = false): Promise<ResolvedHarness> {
     const harnesses = await this.discoverHarnesses();
     const preferredIds = harnessId
       ? [harnessId]
@@ -547,7 +673,9 @@ export class EnnodiaCore {
       const adapter = this.findHarnessAdapter(id);
       const discovery = harnesses.find((harness) => harness.id === id);
 
-      if (adapter?.buildCommand && discovery?.runnable) {
+      if (discovery && harnessId && readinessBlocked(discovery.readiness)) throw new HarnessReadinessError(harnessAttention([discovery]));
+      if (adapter?.buildCommand && discovery?.runnable && !readinessBlocked(discovery.readiness)) {
+        if (verify) await this.prepareHarnesses(harnesses, [{ harnessId: id, model }], cwd, undefined, false);
         return { adapter, discovery };
       }
     }
@@ -604,6 +732,8 @@ export class EnnodiaCore {
     );
 
     if (selectedHarnessIds.length === 0) {
+      const blocked = harnessAttention(harnesses);
+      if (blocked.length) throw new HarnessReadinessError(blocked);
       throw new Error("No runnable harnesses were found.");
     }
 
@@ -630,6 +760,7 @@ export class EnnodiaCore {
       input.cwd,
     );
     const unrequestedSkillsPresent = await this.findUnrequestedSkills(input.cwd, skills);
+    const preflight = await this.prepareHarnesses(harnesses, selectedHarnessIds.map(harnessId => ({ harnessId, model: input.model })), input.cwd, remainingPreflightBudget(input.budget, budget));
     const tasks: TaskView[] = [];
     try {
       for (const harnessId of selectedHarnessIds) {
@@ -651,7 +782,7 @@ export class EnnodiaCore {
       throw error;
     }
 
-    return { plan, tasks, budget, unrequestedSkillsPresent };
+    return { plan, tasks, budget, unrequestedSkillsPresent, ...(this.readinessManager ? { preflight, actionRequired: plan.actionRequired } : {}) };
   }
 
   async estimateCompositional(
@@ -688,6 +819,7 @@ export class EnnodiaCore {
     assertBudgetWithinLimits(budget);
 
     const unrequestedSkillsPresent = await this.findUnrequestedSkills(input.cwd, requestedSkills);
+    const preflight = await this.prepareHarnesses(harnesses, resolvedSlices.map(s => ({ harnessId: s.harnessId, model: s.model })), input.cwd, remainingPreflightBudget(input.budget, budget));
     const tasks: CompositionalStart["tasks"] = [];
     try {
       for (const [index, slice] of resolvedSlices.entries()) {
@@ -715,6 +847,7 @@ export class EnnodiaCore {
     return {
       tasks,
       budget,
+      ...(this.readinessManager ? { preflight } : {}),
       compareNext: {
         prompt: input.prompt,
         taskIds: tasks.map((item) => item.task.id),
@@ -837,6 +970,7 @@ export class EnnodiaCore {
     );
     assertBudgetWithinLimits(budget);
 
+    const preflight = await this.prepareHarnesses([judgeHarness.discovery, advisorHarness.discovery], [{ harnessId: judgeHarness.adapter.id, model: compareInput.judgeModel }, { harnessId: advisorHarness.adapter.id, model: advisorModel }], compareInput.cwd, remainingPreflightBudget(budgetLimits, budget));
     const compare = await this.compareManager.start({
       ...compareInput,
       judgeHarnessId: judgeHarness.adapter.id,
@@ -844,7 +978,7 @@ export class EnnodiaCore {
       advisorModel,
     });
 
-    return { ...compare, budget };
+    return { ...compare, budget, ...(this.readinessManager ? { preflight } : {}) };
   }
 
   listCompares(options: CompareViewOptions = {}): CompareView[] {
@@ -872,6 +1006,7 @@ export class EnnodiaCore {
   }
 
   async shutdown(options: EnnodiaCoreShutdownOptions = {}): Promise<void> {
+    await this.readinessManager?.shutdown();
     await this.runManager.shutdown(options);
     await this.compareManager.shutdown(options);
     await this.planAdviceManager.shutdown(options);
@@ -963,7 +1098,7 @@ export class EnnodiaCore {
       skills: inventorySkills.map(({ skill, supportedHarnessIds }) => ({
         id: skill.id,
         name: skill.name,
-        description: skill.description,
+        description: skill.description.slice(0, MAX_ADVISOR_SKILL_DESCRIPTION_CHARS),
         harnessIds: supportedHarnessIds,
       })),
       limits,
@@ -979,6 +1114,8 @@ export class EnnodiaCore {
         id: skill.id,
         version: skill.version,
         hash: skill.hash,
+        // Summary truncation must not hide metadata drift during revalidation.
+        description: skill.description,
         native: skill.native,
         harnessIds: supportedHarnessIds,
       })),
@@ -1114,6 +1251,8 @@ export class EnnodiaCore {
       throw new Error(`Unknown harness: ${harnessId}`);
     }
 
+    if (readinessBlocked(discovery.readiness)) throw new HarnessReadinessError(harnessAttention([discovery]));
+
     if (!discovery.runnable) {
       throw new Error(`Harness is not runnable: ${harnessId}`);
     }

package/src/harnesses.ts

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

package/src/history.ts

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

package/src/index.ts

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

package/src/installation.ts

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