@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/_lib/production_reach.ts

@@ -0,0 +1,194 @@
+/**
+ * Which `src/` symbols a production entry reaches (road-to-a-tick-the-shipped-path-earns 3.1).
+ *
+ * Static and name-level, the same reading as `dispatch_import_closure`: relative specifiers only,
+ * dynamic `import()` not followed. A symbol counts as reached when some module
+ * in the closure imports it BY NAME from its defining module (or imports that
+ * module whole), or when the defining module is itself an entry. Reaching the
+ * module is not enough — `egress_normalize.ts` is in the closure for one regex
+ * while `detectNormalized` has no production importer, and that is the case
+ * this exists to see.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const ENTRIES_CONFIG_REL = 'src/config/production-entries.json';
+
+export interface ReachTree {
+    list(): readonly string[];
+    read(rel: string): string | null;
+}
+
+/** The checkout under `root`: tracked plus untracked-not-ignored files. */
+export function worktreeOf(root: string): ReachTree {
+    let files: string[] | null = null;
+    return {
+        list() {
+            if (files === null) {
+                const res = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+                    cwd: root,
+                    encoding: 'utf-8',
+                    maxBuffer: 64 * 1024 * 1024,
+                });
+                files = res.status === 0 ? res.stdout.split('\n').filter((l) => l !== '') : [];
+            }
+            return files;
+        },
+        read(rel) {
+            const abs = path.join(root, rel);
+            return fs.existsSync(abs) && fs.statSync(abs).isFile() ? fs.readFileSync(abs, 'utf-8') : null;
+        },
+    };
+}
+
+/** A commit's tree, read from objects — for replaying an old range. */
+export function commitTreeOf(root: string, ref: string): ReachTree {
+    const ls = spawnSync('git', ['ls-tree', '-r', '--name-only', ref], { cwd: root, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+    const files = ls.status === 0 ? ls.stdout.split('\n').filter((l) => l !== '') : [];
+    const present = new Set(files);
+    return {
+        list: () => files,
+        read(rel) {
+            if (!present.has(rel)) return null;
+            const res = spawnSync('git', ['show', `${ref}:${rel}`], { cwd: root, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+            return res.status === 0 ? res.stdout : null;
+        },
+    };
+}
+
+export function globToRegExp(glob: string): RegExp {
+    let re = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i] as string;
+        if (c === '*' && glob[i + 1] === '*') {
+            re += glob[i + 2] === '/' ? '(?:.*/)?' : '.*';
+            i += glob[i + 2] === '/' ? 2 : 1;
+        } else if (c === '*') re += '[^/]*';
+        else re += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+
+/** Resolve a `.js` specifier from `fromRel` to the source it names in `tree`. */
+function resolve(tree: ReachTree, fromRel: string, spec: string): string | null {
+    const base = path.posix.join(path.posix.dirname(fromRel), spec);
+    for (const c of [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, `${base}/index.ts`]) {
+        const norm = path.posix.normalize(c);
+        if (tree.read(norm) !== null) return norm;
+    }
+    return null;
+}
+
+/** `{ a, b as c }` → `['a', 'b']`; `* as ns` and a default import → `['*']`. */
+export function importedNames(clause: string): string[] {
+    const names: string[] = [];
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces) {
+        for (const part of (braces[1] as string).split(',')) {
+            const name = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0]?.trim();
+            if (name) names.push(name);
+        }
+    }
+    const outside = clause.replace(/\{[^}]*\}/, '');
+    if (/\*\s+as\s+\w+/.test(outside) || /^\s*(?:type\s+)?[A-Za-z_$][\w$]*\s*(?:,|$)/.test(outside)) names.push('*');
+    return names;
+}
+
+export interface ModuleImport {
+    readonly target: string;
+    readonly names: readonly string[];
+}
+
+/** Every relative import of `rel`, resolved, with the names it takes. */
+export function moduleImports(tree: ReachTree, rel: string): ModuleImport[] {
+    const source = (tree.read(rel) ?? '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+    const out: ModuleImport[] = [];
+    const re = /\b(import|export)\s+(?:type\s+)?((?:(?!\b(?:import|export)\b)[^;'"])*?)\bfrom\s*['"](\.{1,2}\/[^'"]+)['"]|\bimport\s*['"](\.{1,2}\/[^'"]+)['"]/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(source)) !== null) {
+        const spec = (m[3] ?? m[4]) as string;
+        const target = resolve(tree, rel, spec);
+        if (target === null) continue;
+        out.push({ target, names: m[4] !== undefined ? [] : importedNames(m[2] ?? '') });
+    }
+    return out;
+}
+
+/** Entries from the committed config: the fixed list plus every script an entry source names. */
+export function productionEntries(tree: ReachTree): string[] {
+    const raw = tree.read(ENTRIES_CONFIG_REL);
+    if (raw === null) return [];
+    const cfg = JSON.parse(raw) as { entries?: string[]; entry_sources?: string[] };
+    const entries = new Set((cfg.entries ?? []).filter((e) => tree.read(e) !== null));
+    const sources = (cfg.entry_sources ?? []).map(globToRegExp);
+    for (const file of tree.list()) {
+        if (!sources.some((re) => re.test(file))) continue;
+        for (const m of (tree.read(file) ?? '').matchAll(/(?:src\/)?scripts\/([A-Za-z0-9_/.-]+?)(?:\.ts)?(?![A-Za-z0-9_/.-])/g)) {
+            const candidate = `src/scripts/${m[1] as string}.ts`;
+            if (tree.read(candidate) !== null) entries.add(candidate);
+        }
+    }
+    return [...entries].sort();
+}
+
+/**
+ * Exports the module's own code also uses — named again after their declaration.
+ * A reached module's `main` runs its helpers without importing them, so a helper
+ * a concern calls is reached; one only its test calls is not.
+ */
+export function usedExports(source: string): string[] {
+    const code = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+    const out: string[] = [];
+    for (const m of code.matchAll(/\bexport\s+(?:declare\s+)?(?:async\s+)?(?:function\*?|const|let|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g)) {
+        const name = m[1] as string;
+        const uses = code.match(new RegExp(`(?<![\\w$.])${name.replace(/\$/g, '\\$')}(?![\\w$])`, 'g'))?.length ?? 0;
+        if (uses >= 2) out.push(name);
+    }
+    return out;
+}
+
+export interface Reach {
+    readonly entries: ReadonlySet<string>;
+    readonly modules: ReadonlySet<string>;
+    /** `<module>#<name>`; `<module>#*` when a closure module takes it whole. */
+    readonly symbols: ReadonlySet<string>;
+}
+
+export function productionReach(tree: ReachTree, extra: readonly string[] = []): Reach {
+    const entries = new Set([...productionEntries(tree), ...extra.filter((e) => tree.read(e) !== null)]);
+    const modules = new Set<string>();
+    const symbols = new Set<string>();
+    const queue = [...entries];
+    while (queue.length > 0) {
+        const rel = queue.shift() as string;
+        if (modules.has(rel)) continue;
+        modules.add(rel);
+        for (const name of usedExports(tree.read(rel) ?? '')) symbols.add(`${rel}#${name}`);
+        for (const imp of moduleImports(tree, rel)) {
+            for (const n of imp.names) symbols.add(`${imp.target}#${n}`);
+            if (!modules.has(imp.target)) queue.push(imp.target);
+        }
+    }
+    return { entries, modules, symbols };
+}
+
+/** The `src/` symbols a test takes, and whether production reaches at least one. */
+export function testReaches(tree: ReachTree, reach: Reach, testRel: string): { taken: string[]; reached: string[] } {
+    const taken: string[] = [];
+    const reached: string[] = [];
+    for (const imp of moduleImports(tree, testRel)) {
+        if (!imp.target.startsWith('src/') || /\.test\.ts$/.test(imp.target)) continue;
+        for (const n of imp.names.length ? imp.names : ['*']) {
+            const key = `${imp.target}#${n}`;
+            taken.push(key);
+            const hit =
+                reach.entries.has(imp.target) ||
+                reach.symbols.has(key) ||
+                reach.symbols.has(`${imp.target}#*`) ||
+                (n === '*' && reach.modules.has(imp.target));
+            if (hit) reached.push(key);
+        }
+    }
+    return { taken, reached };
+}

package/src/scripts/_lib/project_tree_form.ts

@@ -0,0 +1,134 @@
+/**
+ * Where the PROJECT tree's rule-layer form comes from, now that no settings key
+ * carries it.
+ *
+ * WHY THIS EXISTS. ADR-293 removed `lean_projection.*`, and the shipped
+ * settings template was the last layer of the cascade `resolveLeanProjection`
+ * read — so the project tree on the first host got its `delivery` from a key
+ * that no longer exists. Removing the key with nothing in its place would have
+ * flipped that tree to the full form: a default change for a tree whose form
+ * ADR-267 decided ON EVIDENCE (616/616 byte-equal deliveries, 101/101 labelled
+ * rules reachable, 0 of 212 near-misses fired on the frozen routing-matrix
+ * corpus), with nothing measured against it. That is not a "no worse" move, and
+ * it would also leave Phase 5 with no live arm to compare.
+ *
+ * WHY IT IS NOT THE KEY UNDER ANOTHER NAME. `src/config/project-tree-form.json`
+ * is package-owned and ships in the repository: there is no consumer-writable
+ * layer, no cascade, and no merge. `modeExplicit` stays false for it, exactly as
+ * it did for the template, so nothing here is read as a consumer's consent. And
+ * it carries its own replacement condition rather than a value alone — a row
+ * without the measurement that justifies it is REFUSED, so the file cannot
+ * become a place to write a form someone merely wants.
+ *
+ * PRECEDENCE, WHICH IS THE WHOLE SAFETY ARGUMENT. A valid OBSERVED verdict from
+ * the layer-form decision function supersedes this record for that host, in both
+ * directions — an observed `full` wins over a record saying `delivery`. The
+ * record stands only while that function can answer nothing but
+ * `delivery-unobserved`, which is its state today for every host. Without that
+ * rule this file would be a permanent bypass of the decision function rather
+ * than a stand-in for it, which is the one risk the reviewing seat named.
+ *
+ * WHY ONE SEAT WAS ENOUGH TO BUILD ON, AND NOT ENOUGH TO CLOSE. The choice was
+ * reviewed at a degraded quorum, so step 3.6 stays open and its blocker carries
+ * the confirmation. Acting on it meanwhile is bounded by what the option does:
+ * it changes no behaviour at all — it reproduces what the shipped template
+ * produced — and every alternative did. The record lives with the roadmap.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { DEFAULT_LEAN_PROJECTION_MODE, type LeanProjectionMode } from './lean_projection_mode.js';
+
+export const PROJECT_TREE_FORM_REL = path.join('src', 'config', 'project-tree-form.json');
+
+/** One host's shipped form, with the evidence that justifies it. */
+export interface ProjectTreeForm {
+    readonly form: LeanProjectionMode;
+    readonly basis: string;
+}
+
+/** The shape this module needs from a decision verdict; the full type lives in `layer_form_decision.ts`. */
+export interface FormVerdict {
+    readonly form: 'full' | 'thinned';
+    readonly reason: string;
+}
+
+const FORMS: readonly string[] = ['eager-all', 'thin', 'delivery'];
+
+/**
+ * The reason that means "the function could not look", as opposed to a verdict
+ * it actually reached. Only this one yields to the shipped record.
+ */
+export const UNOBSERVED_REASON = 'delivery-unobserved';
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Every host row the record carries. A row without a `measured` block, or with
+ * a form the projector does not have, is dropped: this file records measured
+ * forms, and a row that records neither is not evidence.
+ */
+export function readProjectTreeForms(packageRoot: string): Map<string, ProjectTreeForm> {
+    const out = new Map<string, ProjectTreeForm>();
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(packageRoot, PROJECT_TREE_FORM_REL), 'utf8'));
+    } catch {
+        return out; // absent or unreadable: every host gets the full form
+    }
+    if (!isRecord(raw) || !isRecord(raw['hosts'])) return out;
+    for (const [host, row] of Object.entries(raw['hosts'])) {
+        if (!isRecord(row)) continue;
+        const form = row['form'];
+        if (typeof form !== 'string' || !FORMS.includes(form)) continue;
+        // At least one measured figure, each a non-empty string: `{}` records no measurement.
+        const measured = row['measured'];
+        if (!isRecord(measured)) continue;
+        const figures = Object.values(measured);
+        if (figures.length === 0 || !figures.every((v) => typeof v === 'string' && v.trim() !== '')) continue;
+        out.set(host, { form: form as LeanProjectionMode, basis: typeof row['basis'] === 'string' ? row['basis'] : 'unrecorded' });
+    }
+    return out;
+}
+
+/**
+ * The form the project tree is built with for `host`.
+ *
+ * `verdict` is the layer-form decision for this host where one exists. An
+ * observed verdict — anything whose reason is not {@link UNOBSERVED_REASON} —
+ * decides, and the record is not consulted. A host with no row and no observed
+ * verdict gets the full form, which is what an absent key always meant.
+ */
+export function projectTreeForm(
+    packageRoot: string,
+    host: string,
+    verdict: FormVerdict | null,
+): LeanProjectionMode {
+    if (verdict !== null && verdict.reason !== UNOBSERVED_REASON) {
+        return verdict.form === 'full' ? DEFAULT_LEAN_PROJECTION_MODE : (readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE);
+    }
+    return readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE;
+}
+
+/**
+ * The `{ mode, hosts }` pair the projector asks for, derived from the record.
+ *
+ * The record is per host, the projector's API is one mode plus the host list it
+ * applies to, and this is the one place the two shapes meet. `mode` is the
+ * strongest form any row carries — `delivery` over `thin` over `eager-all` —
+ * and `hosts` is every row carrying exactly that form. A tree with no record,
+ * or with rows the reader refused, gets the full form and no hosts, which is
+ * what an absent key always meant.
+ */
+export function shippedProjection(packageRoot: string): { mode: LeanProjectionMode; hosts: string[] } {
+    const forms = readProjectTreeForms(packageRoot);
+    const rank: Record<string, number> = { 'eager-all': 0, thin: 1, delivery: 2 };
+    let mode: LeanProjectionMode = DEFAULT_LEAN_PROJECTION_MODE;
+    for (const row of forms.values()) {
+        if ((rank[row.form] ?? 0) > (rank[mode] ?? 0)) mode = row.form;
+    }
+    const hosts = [...forms.entries()].filter(([, row]) => row.form === mode).map(([host]) => host).sort();
+    return { mode, hosts: mode === DEFAULT_LEAN_PROJECTION_MODE ? [] : hosts };
+}

package/src/scripts/_lib/projection_key_migration.ts

@@ -0,0 +1,122 @@
+/**
+ * The one-release-window read of the projection keys ADR-293 removed.
+ *
+ * WHAT A REMOVED KEY MAY STILL DO, AND WHAT IT MAY NOT. A consumer who wrote
+ * `lean_projection.mode: eager-all` or `projection.mode: legacy-all` asked for
+ * one thing — keep the full rule layer — and the package can still honour that
+ * intent without the key: it is exactly what the install receipt's `user_pin`
+ * expresses. So for one window those two values are read once and converted
+ * into the pin. Every OTHER prior value is dropped, because every other value
+ * asked for a form the package now decides for itself from machine evidence,
+ * and applying it would reinstate the key under another name.
+ *
+ * BOTH DISPOSITIONS ARE PRINTED. A value silently honoured and a value silently
+ * dropped are indistinguishable to the consumer who wrote it, and the dropped
+ * case is the one that changes what their machine does. {@link migrationLines}
+ * emits one line per leftover key whichever way it went.
+ *
+ * THE WINDOW IS NAMED IN THE OUTPUT, NOT ONLY IN A COMMENT. After it closes
+ * this module goes and `REMOVED_KEYS` is what remains: a leftover key is then
+ * named as ignored by the loader's own deprecation line, with no conversion.
+ * That is a deliberate narrowing — the conversion exists to carry an intent
+ * across one upgrade, not to become a second settings reader with a longer
+ * life than the key it replaced.
+ *
+ * Pure: it takes a merged settings tree and returns a verdict. It reads no
+ * file, writes none, and never throws on a malformed branch — a settings layer
+ * nothing can parse must not fail an install.
+ */
+
+type SettingsDict = Record<string, unknown>;
+
+/**
+ * The release window this conversion is open for, as it appears in every line
+ * the module prints. Delete this module when the window closes; the tombstones
+ * in `REMOVED_KEYS` carry the keys from then on.
+ */
+export const MIGRATION_WINDOW = 'one release window after the 2026-10 key removal';
+
+/**
+ * Per removed key, the ONE prior value that meant "keep the full layer". Both
+ * are the value an absent key already resolved to, which is why they are the
+ * only two that survive: honouring them changes nothing about the machine, and
+ * dropping them would silently thin a consumer who had asked not to be.
+ */
+export const LEGACY_FULL_VALUE: Readonly<Record<string, string>> = Object.freeze({
+    'lean_projection.mode': 'eager-all',
+    'projection.mode': 'legacy-all',
+});
+
+export type Disposition = 'pin' | 'dropped';
+
+export interface LegacyRow {
+    readonly key: string;
+    /** The value as written, trimmed; never normalised onto a known enum. */
+    readonly value: string;
+    readonly disposition: Disposition;
+}
+
+export interface LegacyProjectionIntent {
+    /** The receipt pin this upgrade should write, if any leftover asked for the full form. */
+    readonly pin: boolean;
+    /** One row per leftover key found, in the order of {@link LEGACY_FULL_VALUE}. */
+    readonly rows: readonly LegacyRow[];
+}
+
+/** One dotted path out of a merged settings tree; `undefined` when absent or unreachable. */
+function readDotted(root: SettingsDict, dotted: string): unknown {
+    let node: unknown = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) return undefined;
+        node = (node as SettingsDict)[part];
+    }
+    return node;
+}
+
+/**
+ * What the leftover projection keys in `merged` ask for, and what is done about
+ * it. A key whose value is not a string is not a value this package ever wrote,
+ * so it yields no row rather than a guess.
+ */
+export function readLegacyProjectionIntent(merged: SettingsDict): LegacyProjectionIntent {
+    const rows: LegacyRow[] = [];
+    let pin = false;
+    for (const [key, full] of Object.entries(LEGACY_FULL_VALUE)) {
+        const raw = readDotted(merged, key);
+        if (typeof raw !== 'string') continue;
+        const value = raw.trim();
+        if (value === '') continue;
+        const disposition: Disposition = value.toLowerCase() === full ? 'pin' : 'dropped';
+        if (disposition === 'pin') pin = true;
+        rows.push({ key, value, disposition });
+    }
+    return { pin, rows };
+}
+
+/** One line per leftover key, naming what was done with it and for how long this happens. */
+export function migrationLines(intent: LegacyProjectionIntent): string[] {
+    return intent.rows.map((row) =>
+        row.disposition === 'pin'
+            ? `${row.key}: "${row.value}" was removed (ADR-293); read once as a request to keep the rule layer full, ` +
+              `and kept as the install receipt's pin — ${MIGRATION_WINDOW}.`
+            : `${row.key}: "${row.value}" was removed (ADR-293); ignored — the package decides the layer form from ` +
+              `machine evidence, and \`doctor --check layer-form\` says which form it chose and why — ${MIGRATION_WINDOW}.`,
+    );
+}
+
+/**
+ * The installer's whole use of this module: read the leftover keys out of the
+ * machine's own settings, print what was done with each, and say whether the
+ * receipt pin should be written. Returns `false` on any unreadable layer — a
+ * settings file nothing can parse states no preference, and the absence of a
+ * preference is the full form either way.
+ */
+export function legacyProjectionPin(
+    merged: SettingsDict | null,
+    emit: (line: string) => void,
+): boolean {
+    if (merged === null) return false;
+    const intent = readLegacyProjectionIntent(merged);
+    for (const line of migrationLines(intent)) emit(line);
+    return intent.pin;
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -79,7 +79,8 @@
  * slot (the git-authorization ledger, the suggestion latch) while this one
  * guards the language pin. As of this change both know `<task-notification>`,
  * `<system-reminder>` and `<agent-message`; only this one knows
- * `[SYSTEM NOTIFICATION` and `<local-command-caveat>`. That asymmetry is NOT
+ * `[SYSTEM NOTIFICATION`, `<local-command-caveat>` and the host's framed
+ * agent-message delivery (`AGENT_MESSAGE_FRAME`). That asymmetry is NOT
  * obviously a defect and was deliberately left: mistaking a real turn for a
  * machine one costs a mis-pinned reply here and a RETAINED AUTHORIZATION
  * there, so the two sides do not want the same error budget — and
@@ -95,10 +96,20 @@ export function isSyntheticPrompt(prompt: string): boolean {
     head.startsWith("<local-command-caveat>") ||
     head.startsWith("<agent-message") ||
     head.startsWith("Your claude.ai usage limit has reset") ||
-    /^\[SYSTEM NOTIFICATION\b/.test(head)
+    /^\[SYSTEM NOTIFICATION\b/.test(head) ||
+    AGENT_MESSAGE_FRAME.test(head)
   );
 }
 
+/**
+ * How Claude Code actually delivers a subagent hand-back or a cross-session
+ * message to `user_prompt_submit`: one fixed host sentence, then the wrapper
+ * tag, which the bare `<agent-message` case above never matched. Both halves
+ * are required so a human quoting the sentence keeps their turn.
+ */
+const AGENT_MESSAGE_FRAME =
+  /^Another Claude session sent a message:\s*\n\s*<(?:agent-message|cross-session-message)\b/;
+
 /**
  * A line that starts pasted DOCUMENT content rather than typed instruction.
  *