crewhaus 0.2.1 → 0.2.2

package/dist/advise-rules.d.ts

@@ -15,6 +15,7 @@
  * context slice for each missing kind and simply produce no findings — the
  * rules only fire where the data now exists.
  */
+import type { ArmStats } from "@crewhaus/routing-store";
 import type { Spec } from "@crewhaus/spec";
 import { type SpecPatch } from "@crewhaus/spec-patch";
 export type AdviceSeverity = "info" | "warn";
@@ -108,6 +109,13 @@ export type AdviceContext = {
     readonly totalToolBytes: number;
     /** `.crewhaus/audit` record kinds → counts (report context + future rules). */
     readonly auditKindCounts: ReadonlyMap<string, number>;
+    /**
+     * Adaptive model routing — the `model_pool` reward scoreboard arms from
+     * `.crewhaus/routing/arms.jsonl` (empty when the harness has never routed a
+     * pool). The routing rules mine these into pool-POLICY suggestions; the
+     * candidate roster itself stays human-owned.
+     */
+    readonly routingArms: ReadonlyArray<ArmStats>;
 };
 export type SessionEvents = {
     readonly sessionId: string;
@@ -140,7 +148,7 @@ export declare function payloadOf(obj: unknown, kind: string): Record<string, un
  * old-vintage logs (no advisor kinds) and future kinds both pass through
  * cleanly.
  */
-export declare function buildAdviceContext(sessions: ReadonlyArray<SessionEvents>, auditObjects?: ReadonlyArray<unknown>): AdviceContext;
+export declare function buildAdviceContext(sessions: ReadonlyArray<SessionEvents>, auditObjects?: ReadonlyArray<unknown>, routingArms?: ReadonlyArray<ArmStats>): AdviceContext;
 export type AdviceThresholds = {
     /** Minimum calls before a tool's error rate is judged at all. */
     toolFailureMinCalls: number;
@@ -171,6 +179,13 @@ export type AdviceThresholds = {
     /** Item 21 — minimum total tool bytes before dominance is judged at all
      *  (a handful of tiny calls shouldn't trip a restructure). */
     toolByteMinTotal: number;
+    /** Adaptive routing — samples an arm needs before the routing rules judge
+     *  it, when the spec doesn't set `model_pool.learning.minSamplesPerArm`.
+     *  Mirrors the PolicyRouter's own default floor. */
+    poolMinSamples: number;
+    /** Adaptive routing — mean-reward gap below the band best at/above which a
+     *  candidate is called consistently losing (demotion advice). */
+    poolDemotionGap: number;
 };
 /**
  * Canonical rule thresholds. runtime-core's in-run digest
@@ -187,6 +202,16 @@ export type RuleOptions = {
     /** The cwd spec, when one exists — enables patch suggestions. */
     readonly spec?: Spec;
     readonly thresholds?: Partial<AdviceThresholds>;
+    /**
+     * Whether the RAW spec YAML textually carries a key at `path` (the driver
+     * builds this from `specHasPath` in `@crewhaus/spec-patch`). Zod-defaulted
+     * fields are always present on the parsed `spec`, but `applySpecPatch`
+     * requires `add` for absent keys and `replace` for present ones — a rule
+     * proposing a patch on a defaultable field needs this to pick the op.
+     * Absent → such rules assume the key is absent (the common case for
+     * defaulted fields) and emit `add`.
+     */
+    readonly specHasPath?: (path: ReadonlyArray<string>) => boolean;
 };
 export type AdviceRule = (ctx: AdviceContext, opts?: RuleOptions) => AdviceFinding[];
 /**
@@ -315,6 +340,35 @@ export declare function subAgentFragment(toolName: string): string;
  * rule stays silent, since there's nowhere to paste it.
  */
 export declare const ruleSubAgentSplit: AdviceRule;
+/**
+ * Pool policy upgrade: the spec declares a `model_pool` that is NOT yet
+ * `learned`, and the reward scoreboard already has full-coverage data (every
+ * candidate past the sample floor in ≥1 difficulty band) — the harness has
+ * earned the right to exploit what it measured. Proposes flipping
+ * `model_pool.policy` to `learned` (whitelisted; `optimize --from-advice`
+ * eval-gates the flip). The candidate ROSTER is never touched.
+ */
+export declare const rulePoolPolicyUpgrade: AdviceRule;
+/**
+ * Pool candidate demotion: a candidate that is past the sample floor and
+ * loses to the band best by ≥ `poolDemotionGap` mean reward in EVERY band
+ * with full coverage is consistently wasted spend. ADVICE-ONLY by design:
+ * the candidate roster is human-owned (mirroring the `["agent","model"]`
+ * OPTIMIZABLE_PATHS exclusion), so this never emits a patch — it names the
+ * loser and lets a human edit `model_pool.candidates`.
+ */
+export declare const rulePoolCandidateDemotion: AdviceRule;
+/**
+ * Stale exploitation: a `learned` pool whose scoreboard has full coverage but
+ * whose config never explores again — `explorationRate` unset/0 and the
+ * bandit is not `thompson` (which self-explores via posterior sampling). Once
+ * every arm clears the floor, such a pool hard-commits to the argmax forever
+ * and can never notice model drift or a candidate that improved. Proposes a
+ * small ε (0.05) via a whole-`learning`-block replace that PRESERVES the
+ * spec's other learning fields (whitelisted path; `optimize --from-advice`
+ * eval-gates it).
+ */
+export declare const rulePoolStaleExploitation: AdviceRule;
 export declare const ADVICE_RULES: ReadonlyArray<AdviceRule>;
 /**
  * Run every rule and rank the findings: warn before info, then by the

package/dist/advise-rules.js

@@ -64,7 +64,7 @@ export function payloadOf(obj, kind) {
  * old-vintage logs (no advisor kinds) and future kinds both pass through
  * cleanly.
  */
-export function buildAdviceContext(sessions, auditObjects = []) {
+export function buildAdviceContext(sessions, auditObjects = [], routingArms = []) {
     const toolStats = new Map();
     const recoveriesByAction = new Map();
     const recoveriesByErrorName = new Map();
@@ -197,6 +197,7 @@ export function buildAdviceContext(sessions, auditObjects = []) {
         perToolBytes,
         totalToolBytes,
         auditKindCounts,
+        routingArms,
     };
 }
 /**
@@ -218,6 +219,8 @@ export const DEFAULT_ADVICE_THRESHOLDS = {
     chronicCompactionSessions: 2,
     toolByteDominance: 0.6,
     toolByteMinTotal: 50_000,
+    poolMinSamples: 25,
+    poolDemotionGap: 0.3,
 };
 /** Stop reasons that are part of healthy operation; everything else
  *  (max_tokens, refusal, pause_turn, …) counts as anomalous. Mirrored by
@@ -798,6 +801,164 @@ export const ruleSubAgentSplit = (ctx, opts) => {
         },
     ];
 };
+function agentModelPool(spec) {
+    const agent = specField(spec, "agent");
+    const pool = agent?.["model_pool"];
+    if (pool === undefined || pool === null || typeof pool !== "object")
+        return undefined;
+    return pool;
+}
+/** The bands (routeKeys) where EVERY pool candidate has ≥ `floor` samples. */
+function bandsWithFullCoverage(arms, candidates, floor) {
+    const bands = [...new Set(arms.map((a) => a.routeKey))];
+    return bands.filter((band) => candidates.every((c) => arms.some((a) => a.routeKey === band && a.model === c.model && a.n >= floor)));
+}
+/**
+ * Pool policy upgrade: the spec declares a `model_pool` that is NOT yet
+ * `learned`, and the reward scoreboard already has full-coverage data (every
+ * candidate past the sample floor in ≥1 difficulty band) — the harness has
+ * earned the right to exploit what it measured. Proposes flipping
+ * `model_pool.policy` to `learned` (whitelisted; `optimize --from-advice`
+ * eval-gates the flip). The candidate ROSTER is never touched.
+ */
+export const rulePoolPolicyUpgrade = (ctx, opts) => {
+    const t = resolveThresholds(opts);
+    const spec = opts?.spec;
+    const pool = agentModelPool(spec);
+    if (pool === undefined || pool.policy === "learned")
+        return [];
+    if (ctx.routingArms.length === 0 || pool.candidates.length < 2)
+        return [];
+    const floor = pool.learning?.minSamplesPerArm ?? t.poolMinSamples;
+    const ready = bandsWithFullCoverage(ctx.routingArms, pool.candidates, floor);
+    if (ready.length === 0)
+        return [];
+    const totalSamples = ctx.routingArms.reduce((acc, a) => acc + a.n, 0);
+    const adviceText = `The model_pool reward scoreboard has ≥${floor} samples for every candidate in band(s) ${ready.join(", ")} — set model_pool.policy: learned so routing exploits the measured per-band winners instead of the fixed heuristic.`;
+    const policyKeyPresent = opts?.specHasPath?.(["agent", "model_pool", "policy"]) ?? false;
+    const patch = {
+        target: spec?.target ?? "cli",
+        path: ["agent", "model_pool", "policy"],
+        op: policyKeyPresent ? "replace" : "add",
+        value: "learned",
+        rationale: `advise: scoreboard full coverage (every candidate ≥${floor} samples) in band(s) ${ready.join(", ")} across ${totalSamples} routed decisions`,
+    };
+    return [
+        {
+            id: "pool-policy-upgrade",
+            severity: "info",
+            summary: "model_pool scoreboard is ready — flip policy to learned",
+            evidence: [
+                `bands with every candidate ≥${floor} samples: ${ready.join(", ")}`,
+                `${totalSamples} routed decisions recorded across ${ctx.routingArms.length} arm(s)`,
+                `current policy: ${pool.policy}`,
+            ],
+            counts: { readyBands: ready.length, totalSamples },
+            suggestion: patchOrAdvice(spec, patch, adviceText),
+        },
+    ];
+};
+/**
+ * Pool candidate demotion: a candidate that is past the sample floor and
+ * loses to the band best by ≥ `poolDemotionGap` mean reward in EVERY band
+ * with full coverage is consistently wasted spend. ADVICE-ONLY by design:
+ * the candidate roster is human-owned (mirroring the `["agent","model"]`
+ * OPTIMIZABLE_PATHS exclusion), so this never emits a patch — it names the
+ * loser and lets a human edit `model_pool.candidates`.
+ */
+export const rulePoolCandidateDemotion = (ctx, opts) => {
+    const t = resolveThresholds(opts);
+    const pool = agentModelPool(opts?.spec);
+    if (pool === undefined || ctx.routingArms.length === 0 || pool.candidates.length < 3) {
+        // With only 2 candidates, "demote the loser" would collapse the pool —
+        // routing a 1-model pool is meaningless; leave that call entirely human.
+        return [];
+    }
+    const floor = pool.learning?.minSamplesPerArm ?? t.poolMinSamples;
+    const fullBands = bandsWithFullCoverage(ctx.routingArms, pool.candidates, floor);
+    if (fullBands.length === 0)
+        return [];
+    const losers = pool.candidates.filter((c) => fullBands.every((band) => {
+        const bandArms = ctx.routingArms.filter((a) => a.routeKey === band);
+        const best = Math.max(...bandArms.map((a) => a.meanReward));
+        const own = bandArms.find((a) => a.model === c.model);
+        return own !== undefined && own.meanReward <= best - t.poolDemotionGap;
+    }));
+    return losers.map((loser) => {
+        const detail = fullBands
+            .map((band) => {
+            const bandArms = ctx.routingArms.filter((a) => a.routeKey === band);
+            const best = Math.max(...bandArms.map((a) => a.meanReward));
+            const own = bandArms.find((a) => a.model === loser.model);
+            return `${band}: ${own?.meanReward.toFixed(3)} vs best ${best.toFixed(3)}`;
+        })
+            .join("; ");
+        return {
+            id: `pool-candidate-demotion:${loser.model}`,
+            severity: "info",
+            summary: `model_pool candidate ${loser.model} consistently loses`,
+            evidence: [
+                `mean reward trails the band best by ≥${t.poolDemotionGap} in every full-coverage band (${detail})`,
+                "the candidate roster is human-owned — remove it from model_pool.candidates by hand if the trend holds",
+            ],
+            counts: { fullBands: fullBands.length },
+            suggestion: {
+                kind: "advice",
+                text: `Candidate ${loser.model} has enough samples and still trails the best arm by ≥${t.poolDemotionGap} mean reward in every measured band (${detail}). Consider removing it from model_pool.candidates — fewer arms also means less exploration spend. This is a roster change, so it is never auto-applied.`,
+            },
+        };
+    });
+};
+/**
+ * Stale exploitation: a `learned` pool whose scoreboard has full coverage but
+ * whose config never explores again — `explorationRate` unset/0 and the
+ * bandit is not `thompson` (which self-explores via posterior sampling). Once
+ * every arm clears the floor, such a pool hard-commits to the argmax forever
+ * and can never notice model drift or a candidate that improved. Proposes a
+ * small ε (0.05) via a whole-`learning`-block replace that PRESERVES the
+ * spec's other learning fields (whitelisted path; `optimize --from-advice`
+ * eval-gates it).
+ */
+export const rulePoolStaleExploitation = (ctx, opts) => {
+    const t = resolveThresholds(opts);
+    const spec = opts?.spec;
+    const pool = agentModelPool(spec);
+    if (pool === undefined || pool.policy !== "learned")
+        return [];
+    if (ctx.routingArms.length === 0 || pool.candidates.length < 2)
+        return [];
+    const learning = pool.learning ?? {};
+    // Already exploring (ε > 0) or self-exploring (thompson) → healthy.
+    if ((learning.explorationRate ?? 0) > 0 || learning.bandit === "thompson")
+        return [];
+    const floor = learning.minSamplesPerArm ?? t.poolMinSamples;
+    const ready = bandsWithFullCoverage(ctx.routingArms, pool.candidates, floor);
+    if (ready.length === 0)
+        return []; // still warming up — the floor explores for it
+    const proposedLearning = { ...learning, explorationRate: 0.05 };
+    const learningKeyPresent = opts?.specHasPath?.(["agent", "model_pool", "learning"]) ?? false;
+    const adviceText = "This learned model_pool has cleared its sample floor in every measured band and now exploits the argmax forever — it can no longer notice model drift or an improved candidate. Set model_pool.learning.explorationRate (e.g. 0.05) to keep sampling occasionally, or switch learning.bandit to thompson, which self-balances exploration.";
+    const patch = {
+        target: spec?.target ?? "cli",
+        path: ["agent", "model_pool", "learning"],
+        op: learningKeyPresent ? "replace" : "add",
+        value: proposedLearning,
+        rationale: `advise: learned pool converged (full coverage in band(s) ${ready.join(", ")}) with explorationRate 0 and a non-thompson bandit — pure exploitation goes stale`,
+    };
+    return [
+        {
+            id: "pool-stale-exploitation",
+            severity: "info",
+            summary: "converged learned model_pool never explores — add explorationRate",
+            evidence: [
+                `full-coverage band(s) at floor ${floor}: ${ready.join(", ")}`,
+                `learning.explorationRate is ${learning.explorationRate ?? "unset"} and bandit is ${learning.bandit ?? "epsilon-greedy"}`,
+            ],
+            counts: { readyBands: ready.length },
+            suggestion: patchOrAdvice(spec, patch, adviceText),
+        },
+    ];
+};
 export const ADVICE_RULES = [
     ruleRepeatedToolFailures,
     ruleTruncationPressure,
@@ -807,6 +968,9 @@ export const ADVICE_RULES = [
     ruleFailureTaxonomy,
     ruleLoopBreak,
     ruleSubAgentSplit,
+    rulePoolPolicyUpgrade,
+    rulePoolCandidateDemotion,
+    rulePoolStaleExploitation,
 ];
 /**
  * Run every rule and rank the findings: warn before info, then by the

package/dist/index.js

@@ -23,11 +23,16 @@ import { createLogger } from "@crewhaus/logging";
 import { McpHost } from "@crewhaus/mcp-host";
 import { captureFacts, createMemoryStore, deriveMemoryDecision, summarizeDurableFacts, } from "@crewhaus/memory-store";
 import { BUILTIN_DEFAULT_RULES, PermissionConfigError, parsePermissionsConfig, tagRules, } from "@crewhaus/permission-engine";
+// Adaptive model routing — `crewhaus route status|reset` inspects/clears the
+// per-(routeKey, model) reward scoreboard behind `agent.model_pool`; advise
+// mines the same scoreboard into pool-policy suggestions.
+import { openScoreboard } from "@crewhaus/routing-store";
 import { runChatLoop } from "@crewhaus/runtime-core";
 import { createSessionStore, evictExpiredSessions } from "@crewhaus/session-store";
 import { createSkillTool, discoverSkills } from "@crewhaus/skills-registry";
 import { loadCommands } from "@crewhaus/slash-commands";
 import { parseSpec } from "@crewhaus/spec";
+import { specHasPath } from "@crewhaus/spec-patch";
 import { spawnSubAgent } from "@crewhaus/sub-agent-spawner";
 import { ToolCatalog } from "@crewhaus/tool-catalog";
 import { registerMcpServer } from "@crewhaus/tool-mcp";
@@ -260,8 +265,6 @@ import { RetireError, buildRetirementPlan, formatPlan, formatRetirementResult, r
 // Item 25 — model right-sizing downshift search core (pure enumeration + cost
 // projection + $/score ranking); side-effect-free so it is unit-testable.
 import { buildRightSizeReport, enumerateSlotCandidates, } from "./right-size";
-// Adaptive model routing — `crewhaus route status|reset` inspects/clears the
-// per-(routeKey, model) reward scoreboard behind `agent.model_pool`.
 import { runRoute } from "./route";
 // Item 13 — `crewhaus scaffold-evals` + `init --with-evals`: day-one eval
 // assets generated from the spec (deterministic template / one-shot model
@@ -1425,6 +1428,7 @@ function usageText() {
         "       [--factory-root <p>] [--docs-root <p>] [--demos-root <p>]",
         "  cost-summary --session <id>          summarize cost_accrual events for a session",
         "  route status [--dir <root>]          show the adaptive model_pool reward scoreboard",
+        "  route explain <session> [--dir <r>]  replay a run's per-turn model_route decisions",
         "  route reset  [--dir <root>]          wipe the scoreboard (default root .crewhaus)",
         "  advise [--session <id> | --all]      mine session logs for spec advice (item 14)",
         "       [--json] [-o <dir>]             writes suggestions.json + report.html (default .crewhaus/advice)",
@@ -3442,6 +3446,16 @@ async function runRunCli(args, ir, specPath) {
                 ir.agent.modelTiers !== undefined
                 ? { modelTiers: ir.agent.modelTiers }
                 : {}),
+            // Adaptive model routing — thread `agent.model_pool` so `crewhaus run`
+            // routes (and learns) exactly like the compiled cli bundle, not just the
+            // single primary. Mutually exclusive with tiers/fallbacks in the spec;
+            // a `--model` override forces a single model, so the pool applies only
+            // without an override.
+            ...(ir.target === "cli" &&
+                typeof modelOverride !== "string" &&
+                ir.agent.modelPool !== undefined
+                ? { modelPool: ir.agent.modelPool }
+                : {}),
             // Section 55 / item 23 — thread the spec's failure_taxonomy so
             // recovery-engine consults the user's named error classes (including
             // the `switch-model` verdict) before its built-in flow.
@@ -7668,11 +7682,13 @@ async function runAdvise(args) {
     if (args.flags["help"]) {
         process.stdout.write("usage: crewhaus advise [--session <id> | --all] [--json] [-o <dir>]\n" +
             "\n" +
-            "mines .crewhaus/sessions (+ .crewhaus/audit) for spec advice:\n" +
+            "mines .crewhaus/sessions (+ .crewhaus/audit + .crewhaus/routing) for spec advice:\n" +
             "  repeated tool failures, max_tokens truncation pressure, compaction\n" +
             "  thrash, permission-ask churn, stop-reason anomalies, learned\n" +
             "  failure_taxonomy + loop-break rules, sub-agent splits under\n" +
-            "  chronic context pressure\n" +
+            "  chronic context pressure, and model_pool scoreboard mining\n" +
+            "  (flip policy to learned once every candidate has enough samples;\n" +
+            "  name consistently-losing candidates — roster edits stay human)\n" +
             "\n" +
             "  --session <id>  mine one session (default: all sessions)\n" +
             "  --json          print machine-readable findings to stdout\n" +
@@ -7722,17 +7738,34 @@ async function runAdvise(args) {
     // The cwd spec enables patch suggestions; without one (or with a broken
     // one) rules fall back to advice text — mining must not block on it.
     let spec;
+    let specText;
     const specPath = join(process.cwd(), "crewhaus.yaml");
     if (existsSync(specPath)) {
         try {
-            spec = parseSpec(readFileSync(specPath, "utf-8"));
+            specText = readFileSync(specPath, "utf-8");
+            spec = parseSpec(specText);
         }
         catch (err) {
             process.stderr.write(`[advise] crewhaus.yaml did not parse (${err.message}) — patch suggestions downgraded to advice\n`);
         }
     }
-    const ctx = buildAdviceContext(sessions, auditObjects);
-    const findings = runAdviceRules(ctx, spec !== undefined ? { spec } : {});
+    // Adaptive model routing — the pool reward scoreboard, when the harness has
+    // one. A missing/empty store simply produces no routing findings.
+    let routingArms = [];
+    try {
+        routingArms = openScoreboard(join(process.cwd(), ".crewhaus")).snapshot();
+    }
+    catch {
+        // Corrupt store must not block mining the sessions.
+    }
+    const ctx = buildAdviceContext(sessions, auditObjects, routingArms);
+    const specTextForOps = specText;
+    const findings = runAdviceRules(ctx, {
+        ...(spec !== undefined ? { spec } : {}),
+        ...(spec !== undefined && specTextForOps !== undefined
+            ? { specHasPath: (path) => specHasPath(specTextForOps, path) }
+            : {}),
+    });
     const generatedAt = new Date().toISOString();
     const suggestions = buildSuggestionsFile(findings, ctx.sessionIds, generatedAt);
     const outDir = strFlag(args, "out") ?? join(process.cwd(), ".crewhaus", "advice");

package/dist/route.d.ts

@@ -1,9 +1,11 @@
 import { type ArmStats } from "@crewhaus/routing-store";
 export type RouteArgs = {
-    readonly sub: "status" | "reset";
+    readonly sub: "status" | "reset" | "explain";
     readonly dir: string;
+    /** Session id — required for `explain`. */
+    readonly session?: string;
 };
-/** Parse `route <sub> [--dir <root>]` argv (everything after `route`). */
+/** Parse `route <sub> [<session>] [--dir <root>]` argv (everything after `route`). */
 export declare function parseRouteArgs(argv: readonly string[]): RouteArgs;
 /** Snapshot the scoreboard arms (sorted routeKey then model). */
 export declare function loadArms(rootDir: string): ArmStats[];
@@ -15,5 +17,23 @@ export declare function loadArms(rootDir: string): ArmStats[];
 export declare function formatRouteStatus(arms: readonly ArmStats[]): string;
 /** Wipe the whole scoreboard. Returns the number of arms removed. */
 export declare function resetRouting(rootDir: string): number;
+/** One persisted `model_route` decision from a session log. */
+export type RouteDecision = {
+    readonly turnNumber?: number;
+    readonly routeKey: string;
+    readonly model: string;
+    readonly policy: string;
+    readonly reason: string;
+    readonly explored?: boolean;
+    readonly policyVersion?: string;
+};
+/**
+ * Read the `model_route` decisions persisted in a session's event log at
+ * `<rootDir>/sessions/<sessionId>.jsonl`, in turn order. A missing log yields
+ * `[]`; a malformed line is skipped (the log is best-effort observability).
+ */
+export declare function readRouteDecisions(rootDir: string, sessionId: string): RouteDecision[];
+/** Render a run's per-turn routing decisions as a table (turn order). */
+export declare function formatRouteExplain(sessionId: string, decisions: readonly RouteDecision[]): string;
 /** Run `crewhaus route …`, returning the text to print. */
 export declare function runRoute(argv: readonly string[]): string;

package/dist/route.js

@@ -1,25 +1,30 @@
 /**
- * `crewhaus route` — inspect and reset the adaptive-model-routing scoreboard
- * (the durable per-`(routeKey, model)` reward store behind `agent.model_pool`).
+ * `crewhaus route` — inspect, explain, and reset adaptive model routing
+ * (the `agent.model_pool` reward scoreboard + per-turn routing decisions).
  *
- *   route status [--dir <root>]   show the learned arms, best-per-bucket first
- *   route reset  [--dir <root>]   wipe the scoreboard (kill switch)
+ *   route status  [--dir <root>]        show the learned arms, best-per-bucket first
+ *   route explain <session> [--dir …]   replay a run's per-turn model_route decisions
+ *   route reset   [--dir <root>]         wipe the scoreboard (kill switch)
  *
- * `--dir` points at the `.crewhaus` root (default `.crewhaus`); the store lives
- * at `<root>/routing/arms.jsonl`. Live per-turn `model_route` decisions are
- * already visible in a run's structured trace; this command surfaces the
- * ACCUMULATED learning that a `learned` policy exploits.
+ * `--dir` points at the `.crewhaus` root (default `.crewhaus`); the scoreboard
+ * lives at `<root>/routing/arms.jsonl` and session logs at
+ * `<root>/sessions/<id>.jsonl`. `status` surfaces the ACCUMULATED learning a
+ * `learned` policy exploits; `explain` shows WHY each turn of one run picked
+ * the model it did (including ε-greedy exploration draws).
  */
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { openScoreboard } from "@crewhaus/routing-store";
 const DEFAULT_ROOT = ".crewhaus";
-/** Parse `route <sub> [--dir <root>]` argv (everything after `route`). */
+/** Parse `route <sub> [<session>] [--dir <root>]` argv (everything after `route`). */
 export function parseRouteArgs(argv) {
     let dir = DEFAULT_ROOT;
     let sub;
+    let session;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
+        if (a === undefined)
+            continue;
         if (a === "--dir") {
             const v = argv[i + 1];
             if (v === undefined)
@@ -27,16 +32,26 @@ export function parseRouteArgs(argv) {
             dir = v;
             i++;
         }
-        else if (a === "status" || a === "reset") {
+        else if (sub === undefined && (a === "status" || a === "reset" || a === "explain")) {
+            // A subcommand keyword is only the subcommand when it comes FIRST; after
+            // that the same word is a plain positional (so `route explain status`
+            // explains a session literally named "status", not runs `status`).
             sub = a;
         }
+        else if (sub === "explain" && session === undefined && !a.startsWith("--")) {
+            session = a; // the session id positional (only `explain` takes one)
+        }
         else {
-            throw new Error(`route: unknown argument "${a}" (expected: status | reset [--dir <root>])`);
+            throw new Error(`route: unknown argument "${a}" (expected: status | reset | explain <session> [--dir <root>])`);
         }
     }
-    if (sub === undefined)
-        throw new Error("route: expected a subcommand (status | reset)");
-    return { sub, dir };
+    if (sub === undefined) {
+        throw new Error("route: expected a subcommand (status | explain <session> | reset)");
+    }
+    if (sub === "explain" && session === undefined) {
+        throw new Error("route explain: a <session> id is required");
+    }
+    return { sub, dir, ...(session !== undefined ? { session } : {}) };
 }
 /** Snapshot the scoreboard arms (sorted routeKey then model). */
 export function loadArms(rootDir) {
@@ -80,11 +95,74 @@ export function resetRouting(rootDir) {
         rmSync(path, { force: true });
     return removed;
 }
+/**
+ * Read the `model_route` decisions persisted in a session's event log at
+ * `<rootDir>/sessions/<sessionId>.jsonl`, in turn order. A missing log yields
+ * `[]`; a malformed line is skipped (the log is best-effort observability).
+ */
+export function readRouteDecisions(rootDir, sessionId) {
+    // Guard against a hostile session id escaping the sessions dir (e.g.
+    // `../../etc/passwd`). Real ids are `sess_<hex>`; anything with a path
+    // separator or `..` is rejected outright.
+    if (/[/\\]/.test(sessionId) || sessionId.includes("..") || sessionId.length === 0) {
+        throw new Error(`route explain: invalid session id "${sessionId}"`);
+    }
+    const path = join(rootDir, "sessions", `${sessionId}.jsonl`);
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (rec.kind !== "model_route" || typeof rec.payload !== "object" || rec.payload === null) {
+            continue;
+        }
+        const p = rec.payload;
+        if (typeof p["routeKey"] !== "string" || typeof p["model"] !== "string")
+            continue;
+        out.push({
+            ...(typeof p["turnNumber"] === "number" ? { turnNumber: p["turnNumber"] } : {}),
+            routeKey: p["routeKey"],
+            model: p["model"],
+            policy: typeof p["policy"] === "string" ? p["policy"] : "?",
+            reason: typeof p["reason"] === "string" ? p["reason"] : "",
+            ...(typeof p["explored"] === "boolean" ? { explored: p["explored"] } : {}),
+            ...(typeof p["policyVersion"] === "string" ? { policyVersion: p["policyVersion"] } : {}),
+        });
+    }
+    return out;
+}
+/** Render a run's per-turn routing decisions as a table (turn order). */
+export function formatRouteExplain(sessionId, decisions) {
+    if (decisions.length === 0) {
+        return `No model_route decisions recorded for session ${sessionId}. (Only runs whose spec declares \`agent.model_pool\` persist routing decisions.)`;
+    }
+    const lines = [`session ${sessionId} — ${decisions.length} routing decision(s):`, ""];
+    lines.push(`${"turn".padStart(4)} ${"band".padEnd(5)} ${"model".padEnd(28)} ${"policy".padEnd(10)} ${"pick".padEnd(9)} reason`);
+    for (const d of decisions) {
+        const turn = d.turnNumber !== undefined ? String(d.turnNumber) : "-";
+        const pick = d.explored ? "explore" : "exploit";
+        lines.push(`${turn.padStart(4)} ${d.routeKey.padEnd(5)} ${d.model.padEnd(28)} ${d.policy.padEnd(10)} ${pick.padEnd(9)} ${d.reason}`);
+    }
+    return lines.join("\n");
+}
 /** Run `crewhaus route …`, returning the text to print. */
 export function runRoute(argv) {
     const args = parseRouteArgs(argv);
     if (args.sub === "status")
         return formatRouteStatus(loadArms(args.dir));
+    if (args.sub === "explain") {
+        const session = args.session; // parseRouteArgs guarantees it for explain
+        return formatRouteExplain(session, readRouteDecisions(args.dir, session));
+    }
     const removed = resetRouting(args.dir);
     return `Reset routing scoreboard at ${join(args.dir, "routing", "arms.jsonl")} (${removed} arm${removed === 1 ? "" : "s"} removed).`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewhaus",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "CrewHaus — the meta-harness compiler for AI agents. Compile one crewhaus.yaml spec into a CLI agent, channel bot, RAG pipeline, multi-agent crew, eval harness, voice or browser agent, and more.",
   "keywords": [
@@ -31,94 +31,94 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/adapter-anthropic": "0.2.1",
-    "@crewhaus/agent-context-isolation": "0.2.1",
-    "@crewhaus/audit-log": "0.2.1",
-    "@crewhaus/eval-optimizer-orchestrator": "0.2.1",
-    "@crewhaus/prompt-optimizer": "0.2.1",
-    "@crewhaus/prompt-optimizer-claude": "0.2.1",
-    "@crewhaus/justification-judge-claude": "0.2.1",
-    "@crewhaus/spec-patch": "0.2.1",
-    "@crewhaus/canary-controller": "0.2.1",
-    "@crewhaus/compiler": "0.2.1",
-    "@crewhaus/computer-use-driver": "0.2.1",
-    "@crewhaus/context-bundle": "0.2.1",
-    "@crewhaus/cost-tracker": "0.2.1",
-    "@crewhaus/data-retention-engine": "0.2.1",
-    "@crewhaus/dataset-registry": "0.2.1",
-    "@crewhaus/deployment-controller": "0.2.1",
-    "@crewhaus/egress-classifier": "0.2.1",
-    "@crewhaus/egress-matcher-semantic": "0.2.1",
-    "@crewhaus/embedder": "0.2.1",
-    "@crewhaus/errors": "0.2.1",
-    "@crewhaus/eval-dataset": "0.2.1",
-    "@crewhaus/eval-grader": "0.2.1",
-    "@crewhaus/eval-judge": "0.2.1",
-    "@crewhaus/eval-report": "0.2.1",
-    "@crewhaus/eval-runner": "0.2.1",
-    "@crewhaus/event-log": "0.2.1",
-    "@crewhaus/gateway-server": "0.2.1",
-    "@crewhaus/grader-safety-classifiers": "0.2.1",
-    "@crewhaus/hooks-engine": "0.2.1",
-    "@crewhaus/infra-utils": "0.2.1",
-    "@crewhaus/ir": "0.2.1",
-    "@crewhaus/ir-passes": "0.2.1",
-    "@crewhaus/logging": "0.2.1",
-    "@crewhaus/mcp-host": "0.2.1",
-    "@crewhaus/memory-store": "0.2.1",
-    "@crewhaus/model-router": "0.2.1",
-    "@crewhaus/module-marketplace-client": "0.2.1",
-    "@crewhaus/migration-engine": "0.2.1",
-    "@crewhaus/migration-runner": "0.2.1",
-    "@crewhaus/plugin-registry": "0.2.1",
-    "@crewhaus/plugin-sdk": "0.2.1",
-    "@crewhaus/permission-engine": "0.2.1",
-    "@crewhaus/pii-redactor": "0.2.1",
-    "@crewhaus/prompt-injection-detector": "0.2.1",
-    "@crewhaus/regression-runner": "0.2.1",
-    "@crewhaus/routing-store": "0.2.1",
-    "@crewhaus/run-context": "0.2.1",
-    "@crewhaus/runtime-core": "0.2.1",
-    "@crewhaus/secrets-manager": "0.2.1",
-    "@crewhaus/session-store": "0.2.1",
-    "@crewhaus/spec-registry": "0.2.1",
-    "@crewhaus/skills-registry": "0.2.1",
-    "@crewhaus/slash-commands": "0.2.1",
-    "@crewhaus/smoke-harness": "0.2.1",
-    "@crewhaus/spec": "0.2.1",
-    "@crewhaus/sub-agent-spawner": "0.2.1",
-    "@crewhaus/template-marketplace-client": "0.2.1",
-    "@crewhaus/template-registry": "0.2.1",
-    "@crewhaus/tenancy": "0.2.1",
-    "@crewhaus/trace-event-bus": "0.2.1",
-    "@crewhaus/tool-bash": "0.2.1",
-    "@crewhaus/tool-builder": "0.2.1",
-    "@crewhaus/target-cli": "0.2.1",
-    "@crewhaus/target-eval-bundle": "0.2.1",
-    "@crewhaus/tool-catalog": "0.2.1",
-    "@crewhaus/tool-code-execution": "0.2.1",
-    "@crewhaus/tool-codegraph": "0.2.1",
-    "@crewhaus/tool-fetch": "0.2.1",
-    "@crewhaus/tool-fs": "0.2.1",
-    "@crewhaus/tool-image": "0.2.1",
-    "@crewhaus/tool-image-generation": "0.2.1",
-    "@crewhaus/tool-document-ingest": "0.2.1",
-    "@crewhaus/tool-mcp": "0.2.1",
-    "@crewhaus/tool-memory": "0.2.1",
-    "@crewhaus/tool-mouse-keyboard": "0.2.1",
-    "@crewhaus/tool-navigate": "0.2.1",
-    "@crewhaus/tool-permission-matcher": "0.2.1",
-    "@crewhaus/tool-screen-capture": "0.2.1",
-    "@crewhaus/tool-task": "0.2.1",
-    "@crewhaus/tool-todo": "0.2.1",
-    "@crewhaus/tool-vision-grounding": "0.2.1",
-    "@crewhaus/tool-web": "0.2.1",
-    "@crewhaus/docker-images": "0.2.1",
-    "@crewhaus/crewhaus-cloud": "0.2.1",
-    "@crewhaus/federation-discovery": "0.2.1",
-    "@crewhaus/sandbox": "0.2.1",
-    "@crewhaus/sandbox-image-registry": "0.2.1",
-    "@crewhaus/compliance-controls": "0.2.1",
+    "@crewhaus/adapter-anthropic": "0.2.2",
+    "@crewhaus/agent-context-isolation": "0.2.2",
+    "@crewhaus/audit-log": "0.2.2",
+    "@crewhaus/eval-optimizer-orchestrator": "0.2.2",
+    "@crewhaus/prompt-optimizer": "0.2.2",
+    "@crewhaus/prompt-optimizer-claude": "0.2.2",
+    "@crewhaus/justification-judge-claude": "0.2.2",
+    "@crewhaus/spec-patch": "0.2.2",
+    "@crewhaus/canary-controller": "0.2.2",
+    "@crewhaus/compiler": "0.2.2",
+    "@crewhaus/computer-use-driver": "0.2.2",
+    "@crewhaus/context-bundle": "0.2.2",
+    "@crewhaus/cost-tracker": "0.2.2",
+    "@crewhaus/data-retention-engine": "0.2.2",
+    "@crewhaus/dataset-registry": "0.2.2",
+    "@crewhaus/deployment-controller": "0.2.2",
+    "@crewhaus/egress-classifier": "0.2.2",
+    "@crewhaus/egress-matcher-semantic": "0.2.2",
+    "@crewhaus/embedder": "0.2.2",
+    "@crewhaus/errors": "0.2.2",
+    "@crewhaus/eval-dataset": "0.2.2",
+    "@crewhaus/eval-grader": "0.2.2",
+    "@crewhaus/eval-judge": "0.2.2",
+    "@crewhaus/eval-report": "0.2.2",
+    "@crewhaus/eval-runner": "0.2.2",
+    "@crewhaus/event-log": "0.2.2",
+    "@crewhaus/gateway-server": "0.2.2",
+    "@crewhaus/grader-safety-classifiers": "0.2.2",
+    "@crewhaus/hooks-engine": "0.2.2",
+    "@crewhaus/infra-utils": "0.2.2",
+    "@crewhaus/ir": "0.2.2",
+    "@crewhaus/ir-passes": "0.2.2",
+    "@crewhaus/logging": "0.2.2",
+    "@crewhaus/mcp-host": "0.2.2",
+    "@crewhaus/memory-store": "0.2.2",
+    "@crewhaus/model-router": "0.2.2",
+    "@crewhaus/module-marketplace-client": "0.2.2",
+    "@crewhaus/migration-engine": "0.2.2",
+    "@crewhaus/migration-runner": "0.2.2",
+    "@crewhaus/plugin-registry": "0.2.2",
+    "@crewhaus/plugin-sdk": "0.2.2",
+    "@crewhaus/permission-engine": "0.2.2",
+    "@crewhaus/pii-redactor": "0.2.2",
+    "@crewhaus/prompt-injection-detector": "0.2.2",
+    "@crewhaus/regression-runner": "0.2.2",
+    "@crewhaus/routing-store": "0.2.2",
+    "@crewhaus/run-context": "0.2.2",
+    "@crewhaus/runtime-core": "0.2.2",
+    "@crewhaus/secrets-manager": "0.2.2",
+    "@crewhaus/session-store": "0.2.2",
+    "@crewhaus/spec-registry": "0.2.2",
+    "@crewhaus/skills-registry": "0.2.2",
+    "@crewhaus/slash-commands": "0.2.2",
+    "@crewhaus/smoke-harness": "0.2.2",
+    "@crewhaus/spec": "0.2.2",
+    "@crewhaus/sub-agent-spawner": "0.2.2",
+    "@crewhaus/template-marketplace-client": "0.2.2",
+    "@crewhaus/template-registry": "0.2.2",
+    "@crewhaus/tenancy": "0.2.2",
+    "@crewhaus/trace-event-bus": "0.2.2",
+    "@crewhaus/tool-bash": "0.2.2",
+    "@crewhaus/tool-builder": "0.2.2",
+    "@crewhaus/target-cli": "0.2.2",
+    "@crewhaus/target-eval-bundle": "0.2.2",
+    "@crewhaus/tool-catalog": "0.2.2",
+    "@crewhaus/tool-code-execution": "0.2.2",
+    "@crewhaus/tool-codegraph": "0.2.2",
+    "@crewhaus/tool-fetch": "0.2.2",
+    "@crewhaus/tool-fs": "0.2.2",
+    "@crewhaus/tool-image": "0.2.2",
+    "@crewhaus/tool-image-generation": "0.2.2",
+    "@crewhaus/tool-document-ingest": "0.2.2",
+    "@crewhaus/tool-mcp": "0.2.2",
+    "@crewhaus/tool-memory": "0.2.2",
+    "@crewhaus/tool-mouse-keyboard": "0.2.2",
+    "@crewhaus/tool-navigate": "0.2.2",
+    "@crewhaus/tool-permission-matcher": "0.2.2",
+    "@crewhaus/tool-screen-capture": "0.2.2",
+    "@crewhaus/tool-task": "0.2.2",
+    "@crewhaus/tool-todo": "0.2.2",
+    "@crewhaus/tool-vision-grounding": "0.2.2",
+    "@crewhaus/tool-web": "0.2.2",
+    "@crewhaus/docker-images": "0.2.2",
+    "@crewhaus/crewhaus-cloud": "0.2.2",
+    "@crewhaus/federation-discovery": "0.2.2",
+    "@crewhaus/sandbox": "0.2.2",
+    "@crewhaus/sandbox-image-registry": "0.2.2",
+    "@crewhaus/compliance-controls": "0.2.2",
     "yaml": "^2.6.0"
   },
   "devDependencies": {