@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/_cli/cmd_memory_get.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config memory:get` — CLI twin of the `memory_get` MCP tool
+ * (`src/scripts/mcp_server/tools.ts` `_memoryGetHandler`, road-to-memory-
+ * retrieval-economy Phase 1).
+ *
+ * Batch-fetches FULL memory entries by id — the second half of the
+ * index-first retrieval workflow: `memory:lookup --detail index` returns
+ * compact priced rows, this fetches ONLY the bodies actually needed, in one
+ * call. Reuses the exact same shared function the MCP tool calls
+ * (`memory_get_v1` in `../memory_lookup.js`) — no duplicated lookup logic.
+ *
+ * Unlike the MCP handler (which `chdir`s into the consumer root before
+ * calling), this CLI relies on `agent-config`'s existing invariant that the
+ * dispatcher never changes CWD — `memory_get_v1` resolves `agents/memory`
+ * relative to `process.cwd()`, which is already the consumer's repo root.
+ *
+ * Usage: memory:get <id> [<id> ...] [--format text|json]
+ * Exit codes:
+ *   0 — every requested id was found.
+ *   1 — at least one requested id was not found (unknown id).
+ *   2 — usage error (no ids given, unrecognized flag, missing flag value).
+ */
+import process from 'node:process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { memory_get_v1 } from '../memory_lookup.js';
+
+const PROG = 'agent-config memory:get';
+const USAGE = `usage: ${PROG} <id> [<id> ...] [--format text|json]\n`;
+
+/** argparse-style usage / help exit (code 2 / 0). Caught at the CLI entry. */
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`argparse-exit-${code}`);
+    }
+}
+
+interface Opts {
+    ids: string[];
+    format: 'text' | 'json';
+}
+
+function _argError(msg: string): never {
+    process.stderr.write(USAGE);
+    process.stderr.write(`${PROG}: error: ${msg}\n`);
+    throw new ArgparseExit(2);
+}
+
+function _parse(argv: string[]): Opts {
+    const opts: Opts = { ids: [], format: 'text' };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                `${USAGE}\n` +
+                    'Batch-fetch FULL memory entries by id — the second half of the\n' +
+                    "index-first retrieval workflow (`memory:lookup --detail index`\n" +
+                    'first, then `memory:get` the ids that justify the fetch).\n\n' +
+                    'options:\n' +
+                    '  --format text|json   output format (default: text)\n' +
+                    '  -h, --help           show this help and exit\n\n' +
+                    'exit codes:\n' +
+                    '  0  every requested id was found\n' +
+                    '  1  at least one requested id was not found\n' +
+                    '  2  usage error\n',
+            );
+            throw new ArgparseExit(0);
+        } else if (a === '--format') {
+            const val = argv[i + 1];
+            if (val === undefined) _argError('argument --format: expected one argument');
+            if (val !== 'text' && val !== 'json') {
+                _argError(`argument --format: invalid choice: '${val}' (choose from 'text', 'json')`);
+            }
+            opts.format = val;
+            i += 2;
+        } else if (a.startsWith('--format=')) {
+            const val = a.slice('--format='.length);
+            if (val !== 'text' && val !== 'json') {
+                _argError(`argument --format: invalid choice: '${val}' (choose from 'text', 'json')`);
+            }
+            opts.format = val;
+            i += 1;
+        } else if (a.startsWith('--')) {
+            _argError(`unrecognized arguments: ${a}`);
+        } else {
+            opts.ids.push(a);
+            i += 1;
+        }
+    }
+    if (opts.ids.length === 0) {
+        _argError('at least one <id> is required');
+    }
+    return opts;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Render one fetched entry as an indented `key: value` block. */
+function _renderEntryText(entry: Record<string, unknown>): string {
+    const lines: string[] = [];
+    const id = typeof entry['id'] === 'string' ? entry['id'] : '(unknown id)';
+    const type = typeof entry['type'] === 'string' ? entry['type'] : '(unknown type)';
+    lines.push(`[${id}] ${type}`);
+    const body = entry['body'];
+    if (isPlainObject(body)) {
+        for (const key of Object.keys(body).sort()) {
+            lines.push(`  ${key}: ${_renderValue(body[key])}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Render one body value for text output. `memory_lookup.ts` wraps YAML
+ * date scalars in a `PyTimestamp`-shaped object (`{ pyStr: string }`, not
+ * exported) to mirror Python's `yaml.safe_load` date parsing — duck-type
+ * that shape rather than importing the private class.
+ */
+function _renderValue(value: unknown): string {
+    if (typeof value === 'string') return value;
+    if (isPlainObject(value) && typeof value['pyStr'] === 'string' && Object.keys(value).length === 1) {
+        return value['pyStr'];
+    }
+    return JSON.stringify(value);
+}
+
+export function main(argv: string[] | null = null): number {
+    const opts = _parse(argv ?? process.argv.slice(2));
+    const envelope = memory_get_v1(opts.ids);
+    const entries = Array.isArray(envelope['entries']) ? (envelope['entries'] as Record<string, unknown>[]) : [];
+    const idStatus = isPlainObject(envelope['ids']) ? (envelope['ids'] as Record<string, string>) : {};
+    const unknown = opts.ids.filter((id) => idStatus[id] === 'unknown');
+
+    if (opts.format === 'json') {
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    } else {
+        if (entries.length === 0) {
+            process.stdout.write('  (no entries found)\n');
+        } else {
+            for (const entry of entries) {
+                process.stdout.write(`${_renderEntryText(entry)}\n`);
+            }
+        }
+        for (const id of unknown) {
+            process.stderr.write(`${PROG}: unknown id: ${id}\n`);
+        }
+    }
+
+    return unknown.length > 0 ? 1 : 0;
+}
+
+// --- CLI entry ---
+
+const _HERE = fileURLToPath(import.meta.url);
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exitCode = main(process.argv.slice(2));
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) {
+            process.exitCode = exc.code;
+        } else {
+            throw exc;
+        }
+    }
+}
+
+export { ArgparseExit };
+export type { Opts };

package/src/scripts/_cli/cmd_refresh.ts

@@ -68,6 +68,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
 import * as sync_gitignore from '../sync_gitignore.js';
+import * as sync_gitattributes from '../sync_gitattributes.js';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -306,6 +307,12 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
     if (rc !== 0) {
         return rc;
     }
+
+    // Memory merge-safety attributes (road-to-reachable-code-memory Phase 5):
+    // advisory, same shape as the gitignore sync above — never fails the
+    // refresh on its own.
+    _sync_gitattributes(project_root, out, err);
+
     _print(out, '✅  refresh --project complete.');
     return 0;
 }
@@ -329,6 +336,28 @@ function _sync_gitignore(project_root: string, out: OutSink, err: OutSink): numb
     return 0;
 }
 
+/**
+ * Sync the memory-merge-safety block into the consumer's `.gitattributes`.
+ * Advisory only (mirrors `_sync_gitignore`'s failure shape) — a missing
+ * template or a write failure is reported but never fails the refresh.
+ */
+function _sync_gitattributes(project_root: string, out: OutSink, err: OutSink): number {
+    let mod: typeof sync_gitattributes;
+    try {
+        mod = sync_gitattributes;
+    } catch (exc) {
+        _print(err, `⚠️  refresh --project: gitattributes sync unavailable (${osErrorStr(exc)})`);
+        return 0;
+    }
+    const rc = mod.main(['--path', path.join(project_root, '.gitattributes')]);
+    if (rc !== 0 && rc !== null && rc !== undefined) {
+        _print(err, `⚠️  refresh --project: gitattributes sync returned ${rc}`);
+    } else {
+        _print(out, '✅  .gitattributes memory merge-safety block synced.');
+    }
+    return 0;
+}
+
 interface Args {
     is_global: boolean;
     is_project: boolean;
@@ -460,6 +489,7 @@ export {
     _is_source_repo,
     _refresh_project,
     _sync_gitignore,
+    _sync_gitattributes,
     _remove_legacy_consumer_bridge_marker,
     ArgparseExit,
 };

package/src/scripts/_dispatch.bash

@@ -76,6 +76,7 @@ TS-shell native (run via the installed `agent-config` binary):
   commands [ls|explain]      List/explain the command surface from the discovery manifest
   mcp-server                 Turnkey read-only stdio MCP server (no repo clone; ADR-085)
   doctor-shell               Probe the TS-shell environment
+  rtk:detect                 rtk (Rust Token Killer) presence + identity readout (--json)
   eval:record                Record a live trigger-eval result into a corpus manifest
 EOF
 
@@ -173,6 +174,8 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              relation-graph with a node budget. Flags: --budget N
   benchmark                  Report context-token reduction vs the full always-loaded
                              projection (from the pinned token baseline). Flags: --format
+  code-graph                 Deterministic code-graph engine (ADR-124, Class A).
+                             Usage: code-graph build|validate|detect|query|explain|affected|path [options]
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -205,13 +208,31 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              Usage: hooks:replay --platform <name> --event <event>
                                     --payload <path|event-name> [--native-event <native>]
                                     [--manifest <path>] [--json] [--dry-run]
+  reach:doctor               Health report over the reach channel registry: per channel
+                             the active backend, lifecycle, and the pinned install command
+                             for this platform when a backend is missing/broken.
+                             Read-only — no writes, no installs; NOT a router and NOT an
+                             agent-facing recommendation.
+                             Flags: --format json|table, --strict (CI), --channel <id>,
+                             --registry <path>, --deep (⚠️  opt-in NETWORK: one real
+                             read-only request per declared backend; never runs in CI,
+                             writes nothing)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
+  memory:get                 Batch-fetch full memory entries by id (CLI twin of the
+                             memory_get MCP tool). Usage: memory:get <id> [<id> ...] [--format text|json]
   linked-projects:list       List opted-in IDE-attached sibling repos (path · detected_via · large)
                              Flags: --all (show undecided too), --format json
   memory:signal              Append a provisional intake signal (memory proposal)
   memory:hash                Hash a memory entry (YAML or JSON stdin)
   memory:check               Validate memory YAML schema + staleness
   memory:check-proposal      Run the admission gate on a memory proposal
+  memory:learn               Aggregate memory intake signals into the local learning
+                             sidecar (read-only; --write to emit). Usage: memory:learn [--intake-dir DIR]
+                             [--out-dir DIR] [--now ISO] [--write] [--format text|json]
+  analytics                  Local-only workspace analytics (emit|show|prune|migrate).
+                             Usage: analytics show [--window 30d|7d|24h] · analytics prune
+  knowledge                  Global knowledge-card store (list|show|trace|forget|promote|
+                             validate|lead-check|purge). Usage: knowledge list [--json]
   proposal:check             Validate a learning/skill/rule proposal markdown
   refine-ticket:detect       Run the deterministic refine-ticket detection helper
   chat-history:hook          Platform hook entry point (read JSON from stdin)
@@ -296,8 +317,12 @@ Examples (Tier 2):
   ./agent-config hooks:install
   ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
   ./agent-config memory:lookup --types domain-invariants --key billing
+  ./agent-config memory:get a1-crosshost-subagent-degradation
   ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
   ./agent-config memory:check --path agents/memory
+  ./agent-config memory:learn --format json
+  ./agent-config code-graph detect
+  ./agent-config code-graph query <symbol>
   ./agent-config refine-ticket:detect ticket-body.txt
   ./agent-config telemetry:status
   ./agent-config telemetry:status --format json
@@ -455,6 +480,15 @@ cmd_benchmark() {
   exec_ts "$script" "$@"
 }
 
+# `agent-config code-graph` — deterministic code-graph engine (ADR-124,
+# Class A). Delegates 1:1 to the engine CLI's own subcommand dispatch
+# (build|validate|detect|query|explain|affected|path); no re-parsing here.
+cmd_code_graph() {
+  local script
+  script="$(resolve_script "src/scripts/code_graph/cli.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_mcp_check() {
   local script
   script="$(resolve_script "src/scripts/mcp_render.ts")"
@@ -471,6 +505,13 @@ cmd_mcp_setup() {
 # package (PACKAGE_ROOT/src/scripts/mcp_server/) as a TypeScript module run
 # via tsx — no Python venv / SDK install any more (the runtime is Node/tsx).
 cmd_mcp_run() {
+  # Precompiled bundle first (road-to-credible-install Phase 1 tsx sweep):
+  # one node start, no tsx in the runtime tree. tsx path is the dev-tree
+  # fallback only.
+  local server_bundle="$PACKAGE_ROOT/dist/mcp/server.mjs"
+  if [[ -f "$server_bundle" ]]; then
+    exec node "$server_bundle" "$@"
+  fi
   local server_main="$PACKAGE_ROOT/src/scripts/mcp_server/__main__.ts"
   if [[ ! -f "$server_main" ]]; then
     echo "❌  agent-config: MCP server module not found at $server_main" >&2
@@ -542,6 +583,43 @@ cmd_memory_lookup() {
   exec_ts "$script" "$@"
 }
 
+# `agent-config memory:get` — CLI twin of the `memory_get` MCP tool
+# (batch full-entry fetch by id). Package-internal handler
+# (src/scripts/_cli/cmd_memory_get.ts) reuses `memory_get_v1` from
+# src/scripts/memory_lookup.ts — no separate resolve needed, same
+# direct-PACKAGE_ROOT pattern as cmd_export / cmd_sync / cmd_validate.
+cmd_memory_get() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_memory_get.ts" "$@"
+}
+
+# `agent-config memory:learn` — aggregate the memory intake signal log
+# into the local, gitignored learning sidecar (road-to-retrieval-
+# substrate-hardening B3). Read-only by default (the sidecar's own
+# default); `--write` emits `.agent-learning.json` + `LESSONS.md`.
+cmd_memory_learn() {
+  local script
+  script="$(resolve_script "src/scripts/learning_sidecar.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
+# `agent-config analytics` — local-only workspace analytics
+# (docs/contracts/local-analytics.md). Delegates 1:1 to the module's own
+# subcommand dispatch (emit|show|prune|migrate|decrypt-all|rekey).
+cmd_analytics() {
+  local script
+  script="$(resolve_script "src/cli/python/workspace_analytics.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
+# `agent-config knowledge` — file-first global knowledge-card store
+# (ADR-100). Delegates 1:1 to the store CLI's own subcommand dispatch
+# (list|show|trace|forget|promote|validate|lead-check|purge).
+cmd_knowledge() {
+  local script
+  script="$(resolve_script "src/scripts/knowledge_global_cli.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
 cmd_linked_projects_list() {
   local script
   script="$(resolve_script "src/scripts/linked_projects_list.ts")" || return 1
@@ -621,6 +699,13 @@ cmd_context_hygiene_hook() {
 }
 
 cmd_dispatch_hook() {
+  # Hook hot path (road-to-credible-install Phase 1): prefer the precompiled
+  # single-process bundle — one node start, concerns in-process, no tsx.
+  # Fallback to the tsx path only on a stale dev tree without dist/.
+  local bundle="$PACKAGE_ROOT/dist/hooks/dispatch.js"
+  if [[ -f "$bundle" ]]; then
+    exec node "$bundle" "$@"
+  fi
   exec_hook "src/scripts/hooks/dispatch_hook" "$@"
 }
 
@@ -636,6 +721,11 @@ cmd_hooks_replay() {
   exec_hook "src/scripts/hooks/replay_hook" "$@"
 }
 
+# Read-only reach-channel health report. Never installs, never writes.
+cmd_reach_doctor() {
+  exec_hook "src/scripts/reach_doctor" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   local script
   script="$(resolve_script "src/scripts/chat_history.ts")" || return 1
@@ -1058,6 +1148,7 @@ main() {
     affected)                cmd_affected "$@" ;;
     graph-explain)           cmd_graph_explain "$@" ;;
     benchmark)               cmd_benchmark "$@" ;;
+    code-graph)              cmd_code_graph "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;
@@ -1069,11 +1160,15 @@ main() {
     implement-ticket)        cmd_implement_ticket "$@" ;;
     work)                    cmd_work "$@" ;;
     memory:lookup)           cmd_memory_lookup "$@" ;;
+    memory:get)              cmd_memory_get "$@" ;;
     linked-projects:list)    cmd_linked_projects_list "$@" ;;
     memory:signal)           cmd_memory_signal "$@" ;;
     memory:hash)             cmd_memory_hash "$@" ;;
     memory:check)            cmd_memory_check "$@" ;;
     memory:check-proposal)   cmd_memory_check_proposal "$@" ;;
+    memory:learn)            cmd_memory_learn "$@" ;;
+    analytics)               cmd_analytics "$@" ;;
+    knowledge)               cmd_knowledge "$@" ;;
     proposal:check)          cmd_proposal_check "$@" ;;
     refine-ticket:detect)    cmd_refine_ticket_detect "$@" ;;
     chat-history:hook)       cmd_chat_history_hook "$@" ;;
@@ -1085,6 +1180,7 @@ main() {
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;
+    reach:doctor)            cmd_reach_doctor "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;

package/src/scripts/_lib/auto_dispatch.corpus.test.ts

@@ -15,7 +15,13 @@
  */
 import { describe, expect, it } from 'vitest';
 
-import { classifyTask, type ActivationInputs, type TaskSignals } from './auto_dispatch.js';
+import {
+    classifyLookup,
+    classifyTask,
+    type ActivationInputs,
+    type LookupClass,
+    type TaskSignals,
+} from './auto_dispatch.js';
 
 const ON: ActivationInputs = { enabled: true, auto: 'on', subagent_spawn: true };
 
@@ -85,3 +91,60 @@ describe('parallelizable classifier — corpus recall', () => {
         }
     });
 });
+
+/**
+ * Lookup-class corpus (L0 — road-to-lean-agent-init Phase 1). The first four
+ * entries are the live-observed 2026-07-28 task shapes that burned ~1.21M
+ * subagent tokens; each must route to a primitive, never a spawn. The
+ * negative controls are non-lookup tasks that must escalate unchanged.
+ */
+const LOOKUP_CORPUS: Array<{ id: string; text: string; expect: LookupClass | null }> = [
+    // ── the four observed shapes (live evidence, 2026-07-28 session) ──
+    { id: 'lk-01', text: 'Confirming ExternalApiProviderEnum definition location', expect: 'definition' },
+    { id: 'lk-02', text: 'Confirming GWInput import call sites', expect: 'references' },
+    { id: 'lk-03', text: 'Running check_enforcement_coverage report', expect: 'report-run' },
+    { id: 'lk-04', text: 'Probing candidate strings with tsx', expect: 'string-existence' },
+    // ── generalizations of the same shapes ──
+    { id: 'lk-05', text: 'Where is classifyTask defined?', expect: 'definition' },
+    { id: 'lk-06', text: 'Who calls readOrchestrationMetrics across the repo?', expect: 'references' },
+    { id: 'lk-07', text: 'Does the string "lean-init-2026" exist anywhere in src/?', expect: 'string-existence' },
+    { id: 'lk-08', text: 'Run the roadmap:progress-check report and summarize', expect: 'report-run' },
+    { id: 'lk-09', text: 'Find all usages of InferredTier in tests', expect: 'references' },
+    { id: 'lk-10', text: 'Locate the enum that lists the dispatch actions', expect: 'definition' },
+    // ── negative controls — must escalate, never route to a primitive ──
+    { id: 'lk-n1', text: 'Refactor the auth middleware to use the new session store', expect: null },
+    { id: 'lk-n2', text: 'Fix the failing corpus test and explain the root cause', expect: null },
+    { id: 'lk-n3', text: 'Design a migration plan for the audit schema', expect: null },
+    { id: 'lk-n4', text: 'Review this diff for security issues', expect: null },
+];
+
+describe('lookup-class routing — corpus recall + FP=0 (lean-init L0)', () => {
+    for (const c of LOOKUP_CORPUS) {
+        it(`${c.id}: ${c.text}`, () => {
+            const r = classifyLookup(c.text);
+            expect(r.lookup_class).toBe(c.expect);
+            expect(r.route).toBe(c.expect === null ? 'escalate' : 'primitive');
+        });
+    }
+
+    it('recall on the four live-observed shapes is 4/4', () => {
+        const observed = LOOKUP_CORPUS.filter((c) => c.id.startsWith('lk-0') && Number(c.id.slice(3)) <= 4);
+        expect(observed).toHaveLength(4);
+        for (const c of observed) {
+            expect(classifyLookup(c.text).route).toBe('primitive');
+        }
+    });
+
+    it('false-positive rate is 0 — no negative control routes to a primitive', () => {
+        for (const c of LOOKUP_CORPUS.filter((x) => x.expect === null)) {
+            expect(classifyLookup(c.text).route).toBe('escalate');
+        }
+    });
+
+    it('unknown resolves to escalate with a non-degradation reason', () => {
+        const r = classifyLookup('Do something clever with the codebase');
+        expect(r.route).toBe('escalate');
+        expect(r.primitive).toBeNull();
+        expect(r.reason).toContain('never down-guessed');
+    });
+});

package/src/scripts/_lib/auto_dispatch.ts

@@ -94,6 +94,82 @@ export function classifyTask(signals: TaskSignals, activation: ActivationInputs)
     return { delegable: true, action, mode, reason };
 }
 
+// ── Lookup-class routing (L0 — road-to-lean-agent-init) ──
+
+/**
+ * Lookup-class task shapes that route to a deterministic primitive INSTEAD of
+ * a subagent spawn. Contract:
+ * `auto-dispatch-classification.md § Lookup-class rung`.
+ *
+ * Live evidence (2026-07-28): four `general-purpose` subagents burned ~1.21M
+ * tokens on tasks of exactly these shapes; the primitives answer each for <1k.
+ */
+export type LookupClass =
+    | 'definition' // "where is X defined" → code_graph query
+    | 'references' // "who calls / imports X" → code_graph query
+    | 'string-existence' // "does string Y exist" → FTS one-shot / capped grep
+    | 'report-run'; // "run report Z" → script-run with rtk wrap
+
+export type LookupPrimitive = 'code-graph-query' | 'fts-or-capped-grep' | 'script-run-rtk';
+
+export interface LookupRoute {
+    /** Matched lookup class, or null when the task is not lookup-shaped. */
+    lookup_class: LookupClass | null;
+    /** `primitive` = skip the spawn; `escalate` = normal classification path. */
+    route: 'primitive' | 'escalate';
+    primitive: LookupPrimitive | null;
+    reason: string;
+}
+
+const LOOKUP_PATTERNS: Array<{ cls: LookupClass; primitive: LookupPrimitive; re: RegExp }> = [
+    {
+        cls: 'definition',
+        primitive: 'code-graph-query',
+        re: /\b(where\s+is\s+\S+\s+defined|definition\s+(location|of|site)|find\s+the\s+definition|locate\s+the\s+(class|enum|function|type|interface|symbol)|confirm\w*\s+\S+\s+definition)\b/i,
+    },
+    {
+        cls: 'references',
+        primitive: 'code-graph-query',
+        re: /\b(who\s+(calls|imports|uses|references)|call\s*sites?|import\s+(call\s*)?sites?|reverse\s+references|where\s+is\s+\S+\s+(used|imported|referenced|called)|all\s+(callers|usages|references)\s+of)\b/i,
+    },
+    {
+        cls: 'string-existence',
+        primitive: 'fts-or-capped-grep',
+        re: /\b(does\s+(the\s+)?string\s+.*\bexist|is\s+(the\s+)?string\s+.*\b(present|used)\b|prob\w+\s+(candidate\s+)?strings?|search\s+for\s+the\s+(exact\s+)?string|(grep|check)\s+(for\s+)?(the\s+)?(literal|string)\b|does\s+\S+\s+appear\s+anywhere)/i,
+    },
+    {
+        cls: 'report-run',
+        primitive: 'script-run-rtk',
+        re: /\b(run(ning)?\s+(the\s+)?\S*(report|check|lint\w*|coverage)\b|run(ning)?\s+(check|lint|report)_\w+|regenerate\s+the\s+\S+\s+report)/i,
+    },
+];
+
+/**
+ * Route a task description to a lookup-class primitive or the regular
+ * escalation path. Deterministic regex layer, no LLM call (design lock:
+ * no LLM classifier fallback — cut C3). Non-matches escalate — never a
+ * silently degraded answer; an index-miss at execution time escalates the
+ * same way (runtime concern, documented in the classification context).
+ */
+export function classifyLookup(taskText: string): LookupRoute {
+    for (const p of LOOKUP_PATTERNS) {
+        if (p.re.test(taskText)) {
+            return {
+                lookup_class: p.cls,
+                route: 'primitive',
+                primitive: p.primitive,
+                reason: `lookup-class ${p.cls} — deterministic primitive, no spawn`,
+            };
+        }
+    }
+    return {
+        lookup_class: null,
+        route: 'escalate',
+        primitive: null,
+        reason: 'not lookup-shaped — regular classification path (never down-guessed)',
+    };
+}
+
 // ── Per-slice tier inference (v1.5 — road-to-cost-aware-model-routing) ──
 
 /**