@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/routing_doctor.ts

@@ -53,7 +53,7 @@ import {
 import * as hooks_status from "./hooks_status.js";
 import { load_agent_settings } from "./_lib/agent_settings.js";
 import {
-  normalizeHostManifest,
+  resolveHostCapabilities,
   type HostCapabilityManifest,
 } from "./_lib/host_capability.js";
 import {
@@ -106,6 +106,19 @@ export interface OrchestrationReport {
   /** 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;
+  /**
+   * The host identifier the capability registry was keyed on, and whether it
+   * was OBSERVED (given via `--platform`) or merely ASSUMED (the CLI default).
+   *
+   * The doctor has no host detection: `main()` defaults to `claude`. Once
+   * capability resolution keys on that string, an assumed platform produces a
+   * confident-looking `subagent_spawn` for a host the user may not be on —
+   * so the assumption is reported next to the value it decided, and a reader
+   * can falsify it. Without this pair the misdiagnosis is invisible in the
+   * output, which is worse than the pre-registry bug it replaced.
+   */
+  host_platform: string;
+  host_platform_assumed: boolean;
   /** Verdict of the real activation gate for a canonical delegable probe. */
   activation: { action: string; reason: string };
   cost_budgets: Record<string, unknown>;
@@ -194,18 +207,40 @@ export interface DoctorReport {
 /**
  * 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.
+ * Read-only — it mirrors what the delegation layer resolves FOR `platform`.
+ * That qualifier is load-bearing: the hook reads its platform off a real
+ * envelope, this function is told one, and the two agree only when the
+ * caller was told the truth (see `platform_assumed`).
+ *
+ * `platform` is the host identifier the committed capability registry is
+ * keyed on — the same string a hook envelope's `platform` field carries.
+ * It is REQUIRED, not optional: resolving through `normalizeHostManifest`
+ * alone (as this function did until the registry landed) skips the registry
+ * row entirely, so on a fresh clone with no `subagents.host_capabilities`
+ * override the doctor reported `subagent_spawn: false` while
+ * `delegation_nudge_hook` — which does call `resolveHostCapabilities` —
+ * reported `true`. Two readers of one fact disagreeing is worse than either
+ * answer, and the diagnostic is the one a user runs precisely to check the
+ * other. A required parameter makes that regression uncompilable; an
+ * optional one only discourages it in a comment, and a comment has never
+ * failed a build.
+ *
+ * `platform_assumed` says whether the caller OBSERVED the host or guessed
+ * it. It is not decoration: keying the registry on a guessed host is how
+ * this function would trade the bug it fixed for a mirrored one.
  */
 export function collect_orchestration(
   workspace_root: string,
   sample_prompt: string | null,
+  platform: string,
+  platform_assumed: boolean,
 ): 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 host_manifest = resolveHostCapabilities(platform, sub["host_capabilities"]);
   const activationInputs: ActivationInputs = {
     enabled,
     auto: (auto === "on" || auto === "off" ? auto : "ask") as ActivationInputs["auto"],
@@ -260,6 +295,8 @@ export function collect_orchestration(
     budget_routing,
     tier_budgets,
     host_manifest,
+    host_platform: platform,
+    host_platform_assumed: platform_assumed,
     activation: { action: probe.action, reason: probe.reason },
     cost_budgets,
     ledger_present,
@@ -410,6 +447,15 @@ function _freshness(no_freshness: boolean): FreshnessReport {
 
 export function collect_report(options: {
   platform: string;
+  /**
+   * True when `platform` is the CLI's fallback rather than a value the caller
+   * observed or passed. Optional so existing callers keep compiling, and
+   * defaulting to `true` on purpose: a caller that did not say where the
+   * platform came from has not established that it observed one, and the
+   * conservative reading is the one that shows the caveat rather than the one
+   * that hides it.
+   */
+  platform_assumed?: boolean;
   workspace_root: string;
   no_freshness: boolean;
   classify?: string | null;
@@ -440,7 +486,12 @@ export function collect_report(options: {
     chain: chain.map((c) => c.name),
     gates,
     freshness: _freshness(options.no_freshness),
-    orchestration: collect_orchestration(options.workspace_root, options.classify ?? null),
+    orchestration: collect_orchestration(
+      options.workspace_root,
+      options.classify ?? null,
+      options.platform,
+      options.platform_assumed ?? true,
+    ),
     bridge_table,
   };
 }
@@ -466,9 +517,18 @@ function _render(report: DoctorReport): string {
   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} · ` +
+      `budget_routing=${o.budget_routing} · subagent_spawn=${o.host_manifest.subagent_spawn} ` +
+      `(host=${o.host_platform}${o.host_platform_assumed ? ", ASSUMED" : ", observed"}) · ` +
       `ledger=${o.ledger_present ? "present" : "absent"}`,
   );
+  if (o.host_platform_assumed) {
+    // Without this line the reader cannot tell a measured capability from one
+    // the registry produced for a host nobody checked they were on.
+    lines.push(
+      `  ⚠️ host not detected — '${o.host_platform}' is this command's default, ` +
+        `and the capability registry is keyed on it. Pass --platform <host> to check another.`,
+    );
+  }
   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" : "";
@@ -499,7 +559,11 @@ function _render(report: DoctorReport): string {
 
 export function main(argv?: string[]): number {
   const args = argv ?? process.argv.slice(2);
+  // The default is a guess, and since the capability registry is keyed on it
+  // the guess now decides `subagent_spawn`. Track where the value came from so
+  // the report can say so — there is no host detection here to replace it with.
   let platform = "claude";
+  let platform_assumed = true;
   let workspace_root = process.cwd();
   let json = false;
   let strict = false;
@@ -509,6 +573,7 @@ export function main(argv?: string[]): number {
     const a = args[i];
     if (a === "--platform" && args[i + 1]) {
       platform = String(args[(i += 1)]);
+      platform_assumed = false;
     } else if (a === "--workspace" && args[i + 1]) {
       workspace_root = path.resolve(String(args[(i += 1)]));
     } else if (a === "--classify" && args[i + 1]) {
@@ -521,7 +586,13 @@ export function main(argv?: string[]): number {
       no_freshness = true;
     }
   }
-  const report = collect_report({ platform, workspace_root, no_freshness, classify });
+  const report = collect_report({
+    platform,
+    platform_assumed,
+    workspace_root,
+    no_freshness,
+    classify,
+  });
   if (json) {
     process.stdout.write(`${JSON.stringify(report as unknown as JsonValue, null, 2)}\n`);
   } else {

package/src/scripts/schemas/rule.schema.json

@@ -154,6 +154,11 @@
       },
       "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `none` is legal and counted — an honest gap beats a false claim. Resolved, not trusted, by check_enforcement_coverage.ts."
     },
+    "obligation_frequency": {
+      "type": "string",
+      "enum": ["per-edit", "per-turn", "per-task", "per-session", "per-event", "per-commit", "per-file-write", "none"],
+      "description": "How often this rule's obligation comes due — the question `enforced_by` does not answer. `enforced_by` asks *does something carry this*; a carrier can be wired, reachable and firing and still fire in the wrong slot (session-canary: a per-task obligation carried by a session_start hook, measured dropped on ~13 of 15 task starts while counting as enforced). Joined against the carrier's per-slot-and-platform firing frequency by check_enforcement_coverage.ts. The value set is a FOREST, not a chain — three roots that never cover one another: lifecycle (`per-turn` > `per-task` > `per-session`), repository-write (`per-commit`, `per-file-write`), and external-event (`per-event`). `per-edit` is a fourth, incomparable-to-`per-turn` case: pre/post_tool_use fire per tool call, so a conversational turn with no tool call fires them zero times. `none` = no recurring obligation (a pointer or reference rule). Required on every non-kernel rule by validate_frontmatter.ts; the nine kernel rules are exempt because block_kernel_rule_writes.ts denies agent writes to them, and that exemption is derived from _lib/kernel_rules.ts so it closes itself the moment a rule leaves the kernel."
+    },
     "trust": {
       "type": "object",
       "additionalProperties": false,

package/src/scripts/self_repair_cli.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * Self-repair CLI — the queue reader and the single gated outward step.
+ *
+ *   self-repair:status                 list open records
+ *   self-repair:release <fp> [--dry-run] [--repo <owner/name>]
+ *
+ * `release` is the ONE keystroke the loop is designed around: everything up to
+ * it — detection, dedup, analysis, the authored fix, the commit — happens
+ * without the user. Publishing does not, because a push and a PR/issue are
+ * both Hard-Floor actions under `non-destructive-by-default`, and no standing
+ * instruction lifts that floor. Running this command IS the user's word.
+ *
+ * Route selection follows the spec exactly: a pull request when the fix can be
+ * authored and pushed, an issue when it cannot, and a local record when nothing
+ * can leave the machine. `--dry-run` prints the resolved route and the rendered
+ * body and touches no network — that is the path the tests drive.
+ *
+ * Fail-closed on privacy: the record's own text goes through the audited
+ * privacy floor before anything leaves the machine, and a refusal downgrades
+ * the record to local-only rather than scrubbing it into publishable shape.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    chooseEgressRoute,
+    type DefectRecord,
+    type EgressCapability,
+    type EgressRoute,
+    egressBlockedReason,
+    renderReport,
+} from './_lib/self_repair.js';
+import { listRecords, markReleased, openRecords, readRecord } from './_lib/self_repair_store.js';
+
+export const UPSTREAM_REPO = 'event4u-app/agent-config';
+
+const EXIT_OK = 0;
+const EXIT_FAIL = 1;
+
+/** Probe result for one machine — injectable so tests never shell out. */
+export interface Probe {
+    agentConfigCheckout: string | null;
+    ghAuthenticated: boolean;
+    canPush: boolean;
+}
+
+function run(cmd: string, args: string[], cwd?: string): { ok: boolean; out: string } {
+    const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8' });
+    return { ok: r.status === 0, out: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+}
+
+/**
+ * Where the fix can be authored. `AGENT_CONFIG_SOURCE` wins; otherwise the CWD
+ * when it IS the package checkout. A consumer project has neither — that is the
+ * normal case, and the reason the issue fallback exists.
+ */
+export function findAgentConfigCheckout(env: NodeJS.ProcessEnv, cwd: string): string | null {
+    const explicit = env['AGENT_CONFIG_SOURCE'];
+    if (explicit && fs.existsSync(path.join(explicit, 'src', 'rules'))) {
+        return explicit;
+    }
+    if (
+        fs.existsSync(path.join(cwd, 'src', 'rules')) &&
+        fs.existsSync(path.join(cwd, 'src', 'scripts', 'hook_manifest.yaml'))
+    ) {
+        return cwd;
+    }
+    return null;
+}
+
+export function probeMachine(env: NodeJS.ProcessEnv, cwd: string): Probe {
+    const checkout = findAgentConfigCheckout(env, cwd);
+    const gh = run('gh', ['auth', 'status']);
+    const canPush = checkout !== null && run('git', ['remote'], checkout).out.trim().length > 0;
+    return { agentConfigCheckout: checkout, ghAuthenticated: gh.ok, canPush };
+}
+
+export function capabilityOf(probe: Probe): EgressCapability {
+    return {
+        hasAgentConfigCheckout: probe.agentConfigCheckout !== null,
+        ghAuthenticated: probe.ghAuthenticated,
+        canPush: probe.canPush,
+    };
+}
+
+/** Title line for the PR / issue — one per defect class, stable across reruns. */
+export function titleFor(record: DefectRecord): string {
+    return `fix(self-repair): ${record.defect_class} — ${record.occurrences}x observed`;
+}
+
+export interface ReleasePlan {
+    route: EgressRoute;
+    blocked: string | null;
+    title: string;
+    body: string;
+}
+
+/** Pure: everything `release` decides before it touches the network. */
+export function planRelease(record: DefectRecord, probe: Probe, repoRoot: string): ReleasePlan {
+    const blocked = egressBlockedReason(record, repoRoot);
+    const route: EgressRoute =
+        blocked !== null ? 'local-only' : chooseEgressRoute(capabilityOf(probe));
+    return { route, blocked, title: titleFor(record), body: renderReport(record, route) };
+}
+
+function statusCmd(root: string): number {
+    const open = openRecords(root);
+    const all = listRecords(root);
+    if (all.length === 0) {
+        process.stdout.write('self-repair: no records.\n');
+        return EXIT_OK;
+    }
+    process.stdout.write(`self-repair: ${open.length} open of ${all.length} record(s)\n\n`);
+    for (const r of all) {
+        const mark = r.status === 'open' ? 'o' : '.';
+        process.stdout.write(
+            `  ${mark} ${r.fingerprint}  ${r.defect_class}  ${r.occurrences}x  ${r.last_seen}\n` +
+                `      ${r.evidence}\n`,
+        );
+    }
+    process.stdout.write('\nRelease one: agent-config self-repair:release <fingerprint>\n');
+    return EXIT_OK;
+}
+
+function releaseCmd(root: string, argv: string[]): number {
+    const fp = argv.find((a) => !a.startsWith('-'));
+    if (!fp) {
+        process.stderr.write('self-repair:release needs a fingerprint (see self-repair:status).\n');
+        return EXIT_FAIL;
+    }
+    const record = readRecord(root, fp);
+    if (record === null) {
+        process.stderr.write(`self-repair:release: no record ${fp}.\n`);
+        return EXIT_FAIL;
+    }
+    const dryRun = argv.includes('--dry-run');
+    const repoArg = argv.indexOf('--repo');
+    const repo = repoArg >= 0 ? (argv[repoArg + 1] ?? UPSTREAM_REPO) : UPSTREAM_REPO;
+    const probe = probeMachine(process.env, process.cwd());
+    const plan = planRelease(record, probe, root);
+
+    process.stdout.write(`self-repair:release ${fp} -> route=${plan.route}\n`);
+    if (plan.blocked !== null) {
+        process.stdout.write(`  WARN  ${plan.blocked}\n`);
+    }
+    if (dryRun) {
+        process.stdout.write(`\n--- ${plan.title} ---\n${plan.body}\n`);
+        return EXIT_OK;
+    }
+    if (plan.route === 'local-only') {
+        process.stdout.write(
+            '  Nothing published. The record stays in agents/runtime/self-repair/.\n',
+        );
+        return EXIT_OK;
+    }
+    if (plan.route === 'issue') {
+        const r = run('gh', [
+            'issue',
+            'create',
+            '--repo',
+            repo,
+            '--title',
+            plan.title,
+            '--body',
+            plan.body,
+        ]);
+        process.stdout.write(`${r.out}\n`);
+        if (!r.ok) {
+            return EXIT_FAIL;
+        }
+    } else {
+        const checkout = probe.agentConfigCheckout!;
+        const branch = run('git', ['branch', '--show-current'], checkout).out.trim();
+        if (!branch || branch === 'main') {
+            process.stderr.write(
+                '  The fix must sit on its own branch in the agent-config checkout ' +
+                    `(currently: ${branch || 'detached'}).\n`,
+            );
+            return EXIT_FAIL;
+        }
+        const pushed = run('git', ['push', '-u', 'origin', branch], checkout);
+        if (!pushed.ok) {
+            process.stderr.write(`${pushed.out}\n`);
+            return EXIT_FAIL;
+        }
+        const pr = run(
+            'gh',
+            ['pr', 'create', '--repo', repo, '--title', plan.title, '--body', plan.body],
+            checkout,
+        );
+        process.stdout.write(`${pr.out}\n`);
+        if (!pr.ok) {
+            return EXIT_FAIL;
+        }
+    }
+    markReleased(root, fp, new Date().toISOString());
+    return EXIT_OK;
+}
+
+export function main(argv: readonly string[]): number {
+    const root = process.cwd();
+    const sub = argv[0] ?? 'status';
+    if (sub === 'status') {
+        return statusCmd(root);
+    }
+    if (sub === 'release') {
+        return releaseCmd(root, [...argv.slice(1)]);
+    }
+    process.stderr.write(`self-repair: unknown subcommand '${sub}' (status | release).\n`);
+    return EXIT_FAIL;
+}
+
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/self_repair_hook.ts

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * Self-repair hook — turns an observed agent defect into a queued, fixable
+ * record without the user having to file anything.
+ *
+ * Three slots, one record shape:
+ *
+ *   - `user_prompt_submit` — the user states the agent worked wrongly. Opens a
+ *     `user-reported` record and injects the open-queue line so the agent picks
+ *     the work up in the same turn.
+ *   - `stop` — the finished turn is run past the deterministic detectors. A hit
+ *     opens a `self-detected` record. Nothing is injected here: a reminder that
+ *     fires after the reply cannot shape it, and the queue line at the next
+ *     prompt reaches the same agent one turn later at a fraction of the tokens.
+ *   - every other slot — clean no-op.
+ *
+ * ADVISORY BY CONSTRUCTION (`fail_closed: false`, always exit 0). Blocking a
+ * turn-end on a heuristic is the failure mode the enforcement-projection and
+ * recursive-verification nulls both warn about; this hook records, it does not
+ * gate. The one outward step (push + PR, or an issue) stays behind the
+ * `non-destructive-by-default` Hard Floor and lives in `self_repair_cli.ts`.
+ *
+ * Honest scope: the detector set is small and deterministic on purpose. It
+ * covers the two defect classes the conformance audits actually measured, plus
+ * the user-report path. It does NOT "check all rules were followed" — most
+ * obligations are model-carried and unobservable from a transcript, and a
+ * detector that guessed at them would manufacture defects and flood the queue.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    type DefectFinding,
+    detectUserReport,
+    runDetectors,
+    type TurnSnapshot,
+} from './_lib/self_repair.js';
+import { openRecords, upsertFinding } from './_lib/self_repair_store.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function str(v: JsonValue | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+
+function workspaceRoot(env: JsonObject): string {
+    const v = env['workspace_root'];
+    return typeof v === 'string' && v ? v : process.cwd();
+}
+
+/**
+ * Last assistant reply + the tool commands of the turn, read from the host's
+ * JSONL transcript. Absent or unreadable transcript → an empty snapshot, which
+ * every detector declines.
+ */
+export function readTurn(transcriptPath: string, pinned: 'de' | 'en' | null): TurnSnapshot {
+    const empty: TurnSnapshot = { prompt: '', reply: '', toolCommands: [], pinnedLanguage: pinned };
+    if (!transcriptPath) {
+        return empty;
+    }
+    let lines: string[];
+    try {
+        lines = fs.readFileSync(transcriptPath, 'utf-8').split('\n');
+    } catch {
+        return empty;
+    }
+    let reply = '';
+    let prompt = '';
+    const toolCommands: string[] = [];
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line) {
+            continue;
+        }
+        let obj: unknown;
+        try {
+            obj = JSON.parse(line);
+        } catch {
+            continue;
+        }
+        if (!isObject(obj)) {
+            continue;
+        }
+        const msg = obj['message'];
+        if (!isObject(msg)) {
+            continue;
+        }
+        const content = msg['content'];
+        if (obj['type'] === 'user' && typeof content === 'string') {
+            prompt = content;
+        }
+        if (obj['type'] !== 'assistant') {
+            continue;
+        }
+        if (typeof content === 'string') {
+            reply = content;
+            continue;
+        }
+        if (!Array.isArray(content)) {
+            continue;
+        }
+        const parts: string[] = [];
+        for (const blk of content) {
+            if (!isObject(blk)) {
+                continue;
+            }
+            if (blk['type'] === 'text' && typeof blk['text'] === 'string') {
+                parts.push(blk['text']);
+            }
+            if (blk['type'] === 'tool_use') {
+                const input = blk['input'];
+                const name = str(blk['name']);
+                const cmd = isObject(input) ? str(input['command']) : '';
+                toolCommands.push(`${name} ${cmd}`.trim());
+            }
+        }
+        if (parts.length > 0) {
+            reply = parts.join('\n');
+        }
+    }
+    return { prompt, reply, toolCommands, pinnedLanguage: pinned };
+}
+
+/** The queue line injected at prompt time when records are waiting. */
+export function buildQueueLine(count: number, newest: string): string {
+    return (
+        `<self-repair-queue>${count} open agent-config defect record(s) ` +
+        `(newest: ${newest}). These are defects in the AGENT CONFIG, not in this ` +
+        `project. Per the self-repair rule: analyse the newest record, author the ` +
+        `fix against agent-config, and prepare the release — the outward step ` +
+        `(push + PR, or an issue) still needs the user's word this turn. ` +
+        `Records: agents/runtime/self-repair/</self-repair-queue>`
+    );
+}
+
+function pinnedLanguage(env: JsonObject): 'de' | 'en' | null {
+    const v = str(env['reply_language'] ?? env['language']).toLowerCase();
+    if (v.startsWith('de')) {
+        return 'de';
+    }
+    if (v.startsWith('en')) {
+        return 'en';
+    }
+    return null;
+}
+
+export function main(): number {
+    let env: JsonObject = {};
+    try {
+        const raw = readHookStdin();
+        const parsed: unknown = raw.trim() ? JSON.parse(raw) : {};
+        env = isObject(parsed) ? parsed : {};
+    } catch {
+        // malformed stdin — never block, just no-op below
+    }
+
+    const slot = str(env['event']) || 'session_start';
+    if (slot !== 'user_prompt_submit' && slot !== 'stop') {
+        return EXIT_ALLOW;
+    }
+
+    const root = workspaceRoot(env);
+    const now = new Date().toISOString();
+    const findings: DefectFinding[] = [];
+
+    if (slot === 'user_prompt_submit') {
+        const prompt = str(env['prompt'] ?? env['user_prompt'] ?? env['text']);
+        const f = detectUserReport(prompt);
+        if (f !== null) {
+            findings.push(f);
+        }
+    } else {
+        const tp = str(env['transcript_path'] ?? env['transcriptPath']);
+        findings.push(...runDetectors(readTurn(tp, pinnedLanguage(env))));
+    }
+
+    for (const f of findings) {
+        try {
+            upsertFinding(root, f, now);
+        } catch {
+            // an unwritable store must never cost the user their turn
+        }
+    }
+
+    // Injection happens at prompt time only — see the header note on `stop`.
+    if (slot !== 'user_prompt_submit') {
+        return EXIT_ALLOW;
+    }
+    let open: ReturnType<typeof openRecords>;
+    try {
+        open = openRecords(root);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (open.length === 0) {
+        return EXIT_ALLOW;
+    }
+    process.stdout.write(
+        `${JSON.stringify({
+            decision: 'allow',
+            reason: `self-repair: ${open.length} open record(s)`,
+            context: buildQueueLine(open.length, open[0]!.defect_class),
+        })}\n`,
+    );
+    return EXIT_ALLOW;
+}
+
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}