@event4u/agent-config 9.14.0 → 9.16.0

package/src/scripts/routing_doctor.ts

@@ -0,0 +1,560 @@
+#!/usr/bin/env tsx
+/**
+ * routing:doctor — read-only, live-installation routing diagnosis.
+ *
+ * Answers, against the REAL installation (not fixtures), the question the
+ * session-canary incident exposed as untestable: "why did / didn't concern X
+ * fire on session start?" — plus the freshness facts a routing complaint
+ * needs ruled out first. Composes existing single-purpose surfaces instead
+ * of duplicating them:
+ *
+ *   * `hooks_status.collect()`   — per-platform bridge presence + bindings
+ *     (the "is the dispatcher even registered in the host?" layer).
+ *   * `dispatch_hook._resolve_concerns()` — the exact session_start concern
+ *     chain the dispatcher would run for the platform.
+ *   * `concern_registry.CONCERN_REGISTRY` — in-process gate PROBES for the
+ *     read-only session_start concerns: each probe runs the concern's real
+ *     `main()` with a synthetic session_start envelope and reports
+ *     ACTIVE (context injected, with the concern's own `reason`) or
+ *     INACTIVE (clean no-op). This is the live gate evaluation, not a
+ *     simulation.
+ *   * compile_router `--check` + `condense.sh --changed` — router and
+ *     projection freshness (skippable via `--no-freshness`; auto-skipped
+ *     when the source tree is absent, i.e. in a consumer install).
+ *
+ * PROBE SAFETY. Only concerns in `PROBE_SAFE` are invoked — verified to
+ * perform zero state writes on the session_start path (session-canary,
+ * onboarding-gate, profile-staleness). Stateful concerns (chat-history,
+ * hot-context, first-run-gate, wrapper-freshness, surface-probe) are listed
+ * with status `stateful` and NOT invoked; their last outcome is visible via
+ * `hooks:doctor` (dispatcher feedback files). Deeper diagnosis of a
+ * stateful concern stays a `hooks:doctor` job — this doctor never widens
+ * the probe set silently.
+ *
+ * Read-only contract: no file is created or modified; the only child
+ * processes are the two freshness checks, both themselves read-only.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  type JsonObject,
+  type JsonValue,
+  _load_yaml,
+  _resolve_concerns,
+} from "./hooks/dispatch_hook.js";
+import { CONCERN_REGISTRY } from "./hooks/concern_registry.js";
+import {
+  clearHookStdinOverride,
+  setHookStdinOverride,
+} from "./hooks/hook_stdin.js";
+import * as hooks_status from "./hooks_status.js";
+import { load_agent_settings } from "./_lib/agent_settings.js";
+import {
+  normalizeHostManifest,
+  type HostCapabilityManifest,
+} from "./_lib/host_capability.js";
+import {
+  classifyLookup,
+  classifyTask,
+  type ActivationInputs,
+} from "./_lib/auto_dispatch.js";
+import { TIER_ORDER, readCooldowns } from "./_lib/tier_budget_routing.js";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const MANIFEST_PATH = path.join(REPO_ROOT, "src", "scripts", "hook_manifest.yaml");
+
+/**
+ * Concerns whose session_start `main()` performs zero state writes — the
+ * only ones the doctor may invoke live. Adding a concern here requires
+ * re-verifying its write-free path (grep for writeFileSync / appendFileSync /
+ * mkdirSync / renameSync on the session_start branch).
+ */
+export const PROBE_SAFE: ReadonlySet<string> = new Set([
+  "session-canary",
+  "onboarding-gate",
+  "profile-staleness",
+]);
+
+export interface GateReport {
+  concern: string;
+  script: string;
+  status: "ACTIVE" | "INACTIVE" | "ERROR" | "stateful" | "unregistered";
+  reason: string;
+  injects_context: boolean;
+}
+
+export interface FreshnessReport {
+  router: "fresh" | "stale" | "skipped" | "unavailable";
+  projection: "clean" | "stale" | "skipped" | "unavailable";
+  projection_detail: string;
+  dispatch_bundle: "built" | "absent (tsx fallback path)";
+}
+
+export interface OrchestrationReport {
+  enabled: boolean;
+  auto: string;
+  downshift: boolean;
+  budget_routing: string;
+  /** cost.budgets.per_tier ceilings + live cool-down state per tier. */
+  tier_budgets: Record<string, { ceiling_usd: number | null; cooldown_until_ms: number }>;
+  host_manifest: HostCapabilityManifest;
+  /** Verdict of the real activation gate for a canonical delegable probe. */
+  activation: { action: string; reason: string };
+  cost_budgets: Record<string, unknown>;
+  ledger_present: boolean;
+  /** Optional --classify dry-run result. */
+  sample: {
+    prompt: string;
+    lookup_route: string;
+    lookup_primitive: string | null;
+    dispatch: string;
+    mode: string | null;
+    reason: string;
+  } | null;
+  /** Budget-routing delivery evidence (external review 2026-08-03, Finding 2). */
+  delivery: {
+    eligible_dispatches: number;
+    budget_evidence_lines: number;
+    warning: string;
+  };
+}
+
+/**
+ * Adherence ≠ delivery: budget routing binds via policy prose, so the
+ * doctor checks the DELIVERY evidence — orchestration audit lines that
+ * carry a tier decision. Eligible dispatches recorded while
+ * `budget_routing != off` but ZERO tier-carrying lines → WARN with the
+ * exact reason. Read-only over agents/runtime/state/audit/*.jsonl; no
+ * new state. This closes the same blind-spot class the session-canary
+ * incident exposed (policy present, delivery silently absent).
+ */
+export function check_budget_delivery(
+  workspace_root: string,
+  budget_routing: string,
+): OrchestrationReport["delivery"] {
+  const out = { eligible_dispatches: 0, budget_evidence_lines: 0, warning: "" };
+  if (budget_routing === "off") {
+    return out;
+  }
+  const auditDir = path.join(workspace_root, "agents", "runtime", "state", "audit");
+  let files: string[] = [];
+  try {
+    files = fs.readdirSync(auditDir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return out; // no audit dir — nothing dispatched, nothing to warn about
+  }
+  for (const f of files) {
+    let text = "";
+    try {
+      text = fs.readFileSync(path.join(auditDir, f), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const rec = JSON.parse(line) as Record<string, unknown>;
+        const spawns = Number(rec["spawn_count"] ?? 0);
+        if (!Number.isFinite(spawns) || spawns < 1) continue;
+        out.eligible_dispatches += 1;
+        if (typeof rec["tier"] === "string" && rec["tier"] !== "") {
+          out.budget_evidence_lines += 1;
+        }
+      } catch {
+        // non-record line — audit files are shared JSONL surfaces
+      }
+    }
+  }
+  if (out.eligible_dispatches > 0 && out.budget_evidence_lines === 0) {
+    out.warning =
+      `budget_routing=${budget_routing} is policy-bound but shows no delivery evidence: ` +
+      `${out.eligible_dispatches} orchestration dispatch(es) recorded, 0 carry a tier decision — ` +
+      `the relation may not be running (adherence != delivery)`;
+  }
+  return out;
+}
+
+export interface DoctorReport {
+  platform: string;
+  chain: string[];
+  gates: GateReport[];
+  freshness: FreshnessReport;
+  orchestration: OrchestrationReport;
+  bridge_table: string;
+}
+
+/**
+ * Orchestration-routing state: settings gates, host capability, budget
+ * inputs, and (optionally) a dry-run classification for a sample prompt.
+ * Read-only — mirrors exactly what the delegation layer would resolve.
+ */
+export function collect_orchestration(
+  workspace_root: string,
+  sample_prompt: string | null,
+): OrchestrationReport {
+  const settings = load_agent_settings({ cwd: workspace_root });
+  const sub = (settings["subagents"] ?? {}) as Record<string, unknown>;
+  const enabled = sub["enabled"] !== false;
+  const auto = typeof sub["auto"] === "string" ? (sub["auto"] as string) : "ask";
+  const downshift = sub["downshift"] !== false;
+  const host_manifest = normalizeHostManifest(sub["host_capabilities"]);
+  const activationInputs: ActivationInputs = {
+    enabled,
+    auto: (auto === "on" || auto === "off" ? auto : "ask") as ActivationInputs["auto"],
+    subagent_spawn: host_manifest.subagent_spawn,
+  };
+  // Canonical delegable probe: the gate verdict shows which activation
+  // layer (settings / host primitive) decides on THIS installation.
+  const probe = classifyTask(
+    { size_estimate: 5, independent_slices: 3 },
+    activationInputs,
+  );
+  const cost = (settings["cost"] ?? {}) as Record<string, unknown>;
+  const cost_budgets = (cost["budgets"] ?? {}) as Record<string, unknown>;
+  const tracking_dir = path.join(workspace_root, "agents", "cost-tracking");
+  const ledger_present = fs.existsSync(path.join(tracking_dir, "sessions.jsonl"));
+  // YAML 1.1 trap: an unquoted `off` parses as boolean false — coerce it
+  // back to the enum string so the check honors the user's intent.
+  const budget_routing =
+    sub["budget_routing"] === false
+      ? "off"
+      : typeof sub["budget_routing"] === "string"
+        ? (sub["budget_routing"] as string)
+        : "ask";
+  const per_tier = (cost_budgets["per_tier"] ?? {}) as Record<string, unknown>;
+  const cooldowns = readCooldowns(tracking_dir);
+  const tier_budgets: OrchestrationReport["tier_budgets"] = {};
+  for (const t of TIER_ORDER) {
+    const v = per_tier[t];
+    tier_budgets[t] = {
+      ceiling_usd: typeof v === "number" && Number.isFinite(v) ? v : null,
+      cooldown_until_ms: cooldowns[t],
+    };
+  }
+
+  let sample: OrchestrationReport["sample"] = null;
+  if (sample_prompt) {
+    const lookup = classifyLookup(sample_prompt);
+    const cls = classifyTask({ size_estimate: 5 }, activationInputs);
+    sample = {
+      prompt: sample_prompt,
+      lookup_route: lookup.route,
+      lookup_primitive: lookup.primitive,
+      dispatch: lookup.route === "primitive" ? "primitive (no spawn)" : cls.action,
+      mode: cls.mode,
+      reason: lookup.route === "primitive" ? lookup.reason : cls.reason,
+    };
+  }
+  return {
+    enabled,
+    auto,
+    downshift,
+    budget_routing,
+    tier_budgets,
+    host_manifest,
+    activation: { action: probe.action, reason: probe.reason },
+    cost_budgets,
+    ledger_present,
+    sample,
+    delivery: check_budget_delivery(workspace_root, budget_routing),
+  };
+}
+
+/** Invoke one PROBE_SAFE concern's registered main() and observe its gate. */
+export function probe_gate(
+  name: string,
+  script: string,
+  workspace_root: string,
+): GateReport {
+  const main_fn = CONCERN_REGISTRY[script];
+  if (!main_fn) {
+    return {
+      concern: name,
+      script,
+      status: "unregistered",
+      reason: "no CONCERN_REGISTRY entry — dispatcher would use the slow tsx spawn path",
+      injects_context: false,
+    };
+  }
+  const envelope: JsonObject = {
+    event: "session_start",
+    workspace_root,
+    platform: "routing-doctor-probe",
+  };
+  let out = "";
+  const prevWrite = process.stdout.write;
+  type WriteFn = typeof process.stdout.write;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const capture: WriteFn = ((chunk: any, enc?: any, cb?: any): boolean => {
+    out += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8");
+    const callback = typeof enc === "function" ? enc : cb;
+    if (typeof callback === "function") callback();
+    return true;
+  }) as WriteFn;
+
+  let rc = 0;
+  setHookStdinOverride(JSON.stringify(envelope));
+  process.stdout.write = capture;
+  try {
+    const result = main_fn([]);
+    rc = typeof result === "number" ? result : 0;
+  } catch (exc) {
+    rc = 3;
+    out = "";
+    process.stdout.write = prevWrite;
+    return {
+      concern: name,
+      script,
+      status: "ERROR",
+      reason: exc instanceof Error ? exc.message : String(exc),
+      injects_context: false,
+    };
+  } finally {
+    process.stdout.write = prevWrite;
+    clearHookStdinOverride();
+  }
+
+  if (rc !== 0) {
+    return {
+      concern: name,
+      script,
+      status: "ERROR",
+      reason: `probe exited rc=${rc}`,
+      injects_context: false,
+    };
+  }
+  const text = out.trim();
+  if (text === "") {
+    return {
+      concern: name,
+      script,
+      status: "INACTIVE",
+      reason: "gate closed — concern emitted nothing (clean no-op)",
+      injects_context: false,
+    };
+  }
+  let reason = "gate open";
+  let injects = false;
+  try {
+    const parsed = JSON.parse(text) as JsonObject;
+    if (typeof parsed["reason"] === "string" && parsed["reason"] !== "") {
+      reason = parsed["reason"] as string;
+    }
+    injects = typeof parsed["context"] === "string" && parsed["context"] !== "";
+  } catch {
+    reason = "gate open (non-JSON stdout)";
+  }
+  return { concern: name, script, status: "ACTIVE", reason, injects_context: injects };
+}
+
+/** session_start chain for the platform, from the real manifest. */
+export function resolve_chain(
+  manifest: JsonObject,
+  platform: string,
+): Array<{ name: string; script: string }> {
+  const concerns = _resolve_concerns(manifest, platform, "session_start");
+  return concerns.map((c) => ({
+    name: String((c as JsonObject)["name"] ?? "unknown"),
+    script: String((c as JsonObject)["script"] ?? ""),
+  }));
+}
+
+function _freshness(no_freshness: boolean): FreshnessReport {
+  const bundle = fs.existsSync(path.join(REPO_ROOT, "dist", "hooks", "dispatch.js"))
+    ? ("built" as const)
+    : ("absent (tsx fallback path)" as const);
+  if (no_freshness) {
+    return { router: "skipped", projection: "skipped", projection_detail: "", dispatch_bundle: bundle };
+  }
+  const compiler = path.join(REPO_ROOT, "src", "scripts", "compile_router.ts");
+  let router: FreshnessReport["router"] = "unavailable";
+  if (fs.existsSync(compiler)) {
+    const r = spawnSync("npx", ["tsx", compiler, "--check"], {
+      cwd: REPO_ROOT,
+      encoding: "utf-8",
+      timeout: 120_000,
+    });
+    router = r.status === 0 ? "fresh" : "stale";
+  }
+  const condense = path.join(REPO_ROOT, "src", "scripts", "condense.sh");
+  let projection: FreshnessReport["projection"] = "unavailable";
+  let detail = "";
+  if (fs.existsSync(condense)) {
+    const r = spawnSync("bash", [condense, "--changed"], {
+      cwd: REPO_ROOT,
+      encoding: "utf-8",
+      timeout: 300_000,
+    });
+    const outText = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+    if (outText.includes("Every .md projection matches")) {
+      projection = "clean";
+    } else {
+      projection = "stale";
+      detail = outText
+        .split("\n")
+        .filter((l) => l.trim().startsWith("rules/") || l.trim().startsWith("skills/") || l.trim().startsWith("commands/"))
+        .slice(0, 10)
+        .join("; ");
+    }
+  }
+  return { router, projection, projection_detail: detail, dispatch_bundle: bundle };
+}
+
+export function collect_report(options: {
+  platform: string;
+  workspace_root: string;
+  no_freshness: boolean;
+  classify?: string | null;
+}): DoctorReport {
+  const manifest = _load_yaml(MANIFEST_PATH);
+  const chain = resolve_chain(manifest, options.platform);
+  const gates: GateReport[] = chain.map(({ name, script }) => {
+    if (!PROBE_SAFE.has(name)) {
+      return {
+        concern: name,
+        script,
+        status: "stateful" as const,
+        reason: "not probed (writes state) — see hooks:doctor last-feedback",
+        injects_context: false,
+      };
+    }
+    return probe_gate(name, script, options.workspace_root);
+  });
+  let bridge_table = "";
+  try {
+    const matrix = hooks_status.collect(options.workspace_root, manifest);
+    bridge_table = hooks_status._render_table(matrix);
+  } catch (exc) {
+    bridge_table = `bridge status unavailable: ${exc instanceof Error ? exc.message : String(exc)}`;
+  }
+  return {
+    platform: options.platform,
+    chain: chain.map((c) => c.name),
+    gates,
+    freshness: _freshness(options.no_freshness),
+    orchestration: collect_orchestration(options.workspace_root, options.classify ?? null),
+    bridge_table,
+  };
+}
+
+function _render(report: DoctorReport): string {
+  const lines: string[] = [];
+  lines.push(`routing:doctor · platform=${report.platform} · event=session_start`);
+  lines.push("");
+  lines.push("Gate status (live probes, read-only):");
+  for (const g of report.gates) {
+    const marker =
+      g.status === "ACTIVE" ? "✅" : g.status === "ERROR" ? "❌" : g.status === "INACTIVE" ? "⚠️" : "·";
+    const ctx = g.injects_context ? " [injects context]" : "";
+    lines.push(`  ${marker} ${g.concern.padEnd(20)} ${g.status.padEnd(10)} ${g.reason}${ctx}`);
+  }
+  lines.push("");
+  lines.push(
+    `Freshness: router=${report.freshness.router} · projection=${report.freshness.projection}` +
+      (report.freshness.projection_detail ? ` (${report.freshness.projection_detail})` : "") +
+      ` · dispatch bundle=${report.freshness.dispatch_bundle}`,
+  );
+  lines.push("");
+  const o = report.orchestration;
+  lines.push(
+    `Orchestration: enabled=${o.enabled} · auto=${o.auto} · downshift=${o.downshift} · ` +
+      `budget_routing=${o.budget_routing} · subagent_spawn=${o.host_manifest.subagent_spawn} · ` +
+      `ledger=${o.ledger_present ? "present" : "absent"}`,
+  );
+  const tierBits = Object.entries(o.tier_budgets).map(([t, s]) => {
+    const cap = s.ceiling_usd === null ? "no cap" : `$${s.ceiling_usd}`;
+    const cool = s.cooldown_until_ms > 0 ? " COOLING" : "";
+    return `${t}=${cap}${cool}`;
+  });
+  lines.push(`  tier budgets (rolling-24h): ${tierBits.join(" · ")}`);
+  if (o.delivery.warning) {
+    lines.push(`  ⚠️ ${o.delivery.warning}`);
+  } else if (o.delivery.eligible_dispatches > 0) {
+    lines.push(
+      `  delivery evidence: ${o.delivery.budget_evidence_lines}/${o.delivery.eligible_dispatches} dispatches carry a tier decision`,
+    );
+  }
+  lines.push(`  activation probe: ${o.activation.action} — ${o.activation.reason}`);
+  if (o.sample) {
+    lines.push(
+      `  dry-run "${o.sample.prompt.slice(0, 60)}": ${o.sample.dispatch}` +
+        (o.sample.mode ? ` (${o.sample.mode})` : "") +
+        (o.sample.lookup_primitive ? ` via ${o.sample.lookup_primitive}` : "") +
+        ` — ${o.sample.reason}`,
+    );
+  }
+  lines.push("");
+  lines.push("Host bridge / bindings:");
+  lines.push(report.bridge_table);
+  return lines.join("\n");
+}
+
+export function main(argv?: string[]): number {
+  const args = argv ?? process.argv.slice(2);
+  let platform = "claude";
+  let workspace_root = process.cwd();
+  let json = false;
+  let strict = false;
+  let no_freshness = false;
+  let classify: string | null = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "--platform" && args[i + 1]) {
+      platform = String(args[(i += 1)]);
+    } else if (a === "--workspace" && args[i + 1]) {
+      workspace_root = path.resolve(String(args[(i += 1)]));
+    } else if (a === "--classify" && args[i + 1]) {
+      classify = String(args[(i += 1)]);
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "--strict") {
+      strict = true;
+    } else if (a === "--no-freshness") {
+      no_freshness = true;
+    }
+  }
+  const report = collect_report({ platform, workspace_root, no_freshness, classify });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report as unknown as JsonValue, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${_render(report)}\n`);
+  }
+  const red =
+    report.gates.some((g) => g.status === "ERROR" || g.status === "unregistered") ||
+    report.freshness.router === "stale" ||
+    report.freshness.projection === "stale";
+  return strict && red ? 1 : 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== "undefined" && __AGENT_CONFIG_BUNDLE__) {
+    return false;
+  }
+  if (process.argv[1] === undefined) {
+    return false;
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv1;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}