@event4u/agent-config 8.8.0 → 8.9.0

package/src/scripts/_lib/lexical_index.ts

@@ -0,0 +1,155 @@
+/**
+ * Hand-rolled, dependency-free lexical index for memory/knowledge retrieval
+ * (road-to-retrieval-substrate-hardening B2).
+ *
+ * The current `memory_lookup._score` gives every keyword match the SAME coarse
+ * bucket (0.8 glob / 0.6 substring), so several entries tie at the top and
+ * retrieval "recalls but does not rank" (the mean-tie-set 3.3 finding from
+ * road-to-second-brain-retrieval-precision). This module replaces that bucket
+ * with a continuous BM25 score over an IDF-weighted term index, plus a
+ * character-trigram candidate prefilter so it stays cheap at corpus scale.
+ *
+ * It is the BM25 core ADR-061 already sanctions — pure Node stdlib, NO engine
+ * fork, NO minisearch-class dependency. `_score` stays as the below-tripwire
+ * mini-corpus fallback; this index activates at the `lint_knowledge_scale`
+ * tripwire. Deterministic: identical docs + query → identical scores + order.
+ */
+
+/** BM25 term-frequency saturation. */
+export const BM25_K1 = 1.5;
+/** BM25 length-normalisation strength. */
+export const BM25_B = 0.75;
+/** Minimum token length kept (drops single chars / punctuation noise). */
+export const MIN_TOKEN_LEN = 2;
+
+export interface IndexDoc {
+    id: string;
+    /** All searchable text of the entry, already concatenated. */
+    text: string;
+}
+
+interface DocStats {
+    id: string;
+    len: number; // token count
+    tf: Map<string, number>; // term → frequency in this doc
+    trigrams: Set<string>;
+}
+
+/** Lowercase, split on non-alphanumeric, keep tokens ≥ MIN_TOKEN_LEN. */
+export function tokenize(s: string): string[] {
+    const out: string[] = [];
+    for (const raw of s.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length >= MIN_TOKEN_LEN) out.push(raw);
+    }
+    return out;
+}
+
+/** Character trigrams of a normalised string (alphanumerics + single spaces). */
+export function trigrams(s: string): Set<string> {
+    const norm = s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    const out = new Set<string>();
+    if (norm.length < 3) {
+        if (norm.length > 0) out.add(norm);
+        return out;
+    }
+    for (let i = 0; i + 3 <= norm.length; i++) {
+        out.add(norm.slice(i, i + 3));
+    }
+    return out;
+}
+
+/**
+ * An in-memory BM25 index over a fixed document set. Built once, queried many
+ * times. Stateless after construction — `rank()` / `score()` never mutate it,
+ * so a cached instance is safe to reuse until the underlying corpus changes.
+ */
+export class LexicalIndex {
+    private readonly docs: Map<string, DocStats> = new Map();
+    private readonly df: Map<string, number> = new Map();
+    private readonly n: number;
+    private readonly avgdl: number;
+
+    constructor(documents: readonly IndexDoc[]) {
+        let totalLen = 0;
+        for (const d of documents) {
+            const tokens = tokenize(d.text);
+            const tf = new Map<string, number>();
+            for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+            for (const t of tf.keys()) this.df.set(t, (this.df.get(t) ?? 0) + 1);
+            this.docs.set(d.id, { id: d.id, len: tokens.length, tf, trigrams: trigrams(d.text) });
+            totalLen += tokens.length;
+        }
+        this.n = documents.length;
+        this.avgdl = this.n > 0 ? totalLen / this.n : 0;
+    }
+
+    /** Robertson–Spärck-Jones IDF, floored at 0 so common terms never subtract. */
+    private idf(term: string): number {
+        const df = this.df.get(term) ?? 0;
+        if (df === 0) return 0;
+        return Math.max(0, Math.log(1 + (this.n - df + 0.5) / (df + 0.5)));
+    }
+
+    /** BM25 score of one document against the tokenised query terms. */
+    score(queryTerms: readonly string[], docId: string): number {
+        const doc = this.docs.get(docId);
+        if (doc === undefined || doc.len === 0) return 0;
+        let s = 0;
+        for (const term of queryTerms) {
+            const tf = doc.tf.get(term);
+            if (tf === undefined) continue;
+            const idf = this.idf(term);
+            if (idf === 0) continue;
+            const denom = tf + BM25_K1 * (1 - BM25_B + (BM25_B * doc.len) / (this.avgdl || 1));
+            s += (idf * (tf * (BM25_K1 + 1))) / denom;
+        }
+        return s;
+    }
+
+    /**
+     * Rank documents for a set of query keys (phrases are tokenised). A
+     * character-trigram prefilter selects candidates cheaply; the guard keeps
+     * any doc sharing a query TOKEN even when no trigram overlaps, so the
+     * prefilter never drops a genuine lexical match. Ties break by id for a
+     * stable, deterministic order.
+     */
+    rank(queryKeys: readonly string[]): Array<{ id: string; score: number }> {
+        const queryText = queryKeys.join(' ');
+        const qTerms = tokenize(queryText);
+        const qTermSet = new Set(qTerms);
+        const qTrigrams = trigrams(queryText);
+
+        const candidates: string[] = [];
+        for (const [id, doc] of this.docs) {
+            let hit = false;
+            for (const t of qTrigrams) {
+                if (doc.trigrams.has(t)) {
+                    hit = true;
+                    break;
+                }
+            }
+            if (!hit) {
+                // Guard: keep a doc that shares an exact query token even with
+                // no trigram overlap (short tokens / edge normalisation).
+                for (const t of qTermSet) {
+                    if (doc.tf.has(t)) {
+                        hit = true;
+                        break;
+                    }
+                }
+            }
+            if (hit) candidates.push(id);
+        }
+
+        const scored = candidates
+            .map((id) => ({ id, score: this.score(qTerms, id) }))
+            .filter((r) => r.score > 0);
+        scored.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return scored;
+    }
+
+    /** Document count — for the caller's tripwire / diagnostics. */
+    get size(): number {
+        return this.n;
+    }
+}

package/src/scripts/_lib/orchestration_record.ts

@@ -0,0 +1,170 @@
+/**
+ * Orchestration telemetry record builder (pure, no-I/O).
+ *
+ * Builds ONE validated audit-log-v1 line carrying an `orchestration`
+ * sub-object, from the counts the orchestrating agent already has after an
+ * auto-dispatch. This is the agent-behavioral capture path decided 2026-06-30
+ * (maintainer decision: no hook/daemon — the agent writes directly), made
+ * reliable + one-command here instead of hand-authored JSON.
+ *
+ * Contracts:
+ * - `docs/contracts/audit-log-v1.md` (the envelope)
+ * - `src/agent-src/contexts/execution/orchestration-telemetry.md` (the object)
+ *
+ * PRIVACY BY CONSTRUCTION: every field is a count, enum, or id — there is NO
+ * field capable of holding free-form content, prompt text, or a body. Do not
+ * add one. (Mirrors `domain-safety-pii` § Surface 2 / artifact-engagement.)
+ */
+
+export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
+export type VerifyMode = 'deterministic' | 'judge' | 'none';
+export type Provenance = 'measured' | 'estimated';
+export type TierChosen = 'lite' | 'medium' | 'high';
+export type TierSource = 'static' | 'inferred' | 'inherit';
+export type Band = 'low' | 'medium' | 'high';
+export type LinePhase = 'refine' | 'memory' | 'analyze' | 'plan' | 'implement' | 'test' | 'verify' | 'report';
+export type LineOutcome = 'success' | 'blocked' | 'skipped' | 'error';
+
+/** Inputs the agent supplies about one auto-dispatch. */
+export interface RecordInput {
+    // Orchestration object
+    spawn_count: number;
+    token_delta: number;
+    // Optionals accept explicit `undefined` (CLI parsing yields it); the
+    // builder defaults every one. Compatible with exactOptionalPropertyTypes.
+    token_delta_provenance?: Provenance | undefined;
+    tiers?: string[] | undefined;
+    tier_chosen?: TierChosen | null | undefined;
+    tier_source?: TierSource | null | undefined;
+    task_class?: string | null | undefined;
+    task_size_estimate?: number | undefined;
+    wall_clock_ms?: number | undefined;
+    /** Absolute measured tokens the dispatched slice consumed (feeds the modeled cost-%). */
+    dispatch_tokens?: number | null | undefined;
+    /** The orchestrator's own tier — the baseline the downshift cost-% measures against. */
+    session_tier?: string | null | undefined;
+    dispatch_outcome?: DispatchOutcome | undefined;
+    verify_mode?: VerifyMode | undefined;
+    // Audit-log envelope (sensible defaults for a dispatch record)
+    phase?: LinePhase | undefined;
+    outcome?: LineOutcome | undefined;
+    confidence_band?: Band | undefined;
+    risk_class?: Band | undefined;
+    persona?: string | null | undefined;
+    work_id?: string | undefined;
+    /** ISO-8601 UTC timestamp; caller supplies (keeps this fn pure/deterministic). */
+    ts: string;
+    /** Stable id (ULID or content hash); caller supplies. */
+    id: string;
+}
+
+export interface BuiltLine {
+    line: Record<string, unknown> | null;
+    errors: string[];
+}
+
+const DISPATCH_OUTCOMES: readonly DispatchOutcome[] = ['DONE', 'DONE_WITH_CONCERNS', 'NEEDS_CONTEXT', 'BLOCKED', 'killed'];
+const VERIFY_MODES: readonly VerifyMode[] = ['deterministic', 'judge', 'none'];
+const PROVENANCES: readonly Provenance[] = ['measured', 'estimated'];
+const TIERS_CHOSEN: readonly TierChosen[] = ['lite', 'medium', 'high'];
+const TIER_SOURCES: readonly TierSource[] = ['static', 'inferred', 'inherit'];
+const BANDS: readonly Band[] = ['low', 'medium', 'high'];
+const PHASES: readonly LinePhase[] = ['refine', 'memory', 'analyze', 'plan', 'implement', 'test', 'verify', 'report'];
+
+/** Map a dispatch outcome to the audit-log envelope outcome enum. */
+function envelopeOutcome(d: DispatchOutcome): LineOutcome {
+    if (d === 'BLOCKED') return 'blocked';
+    if (d === 'NEEDS_CONTEXT') return 'skipped';
+    if (d === 'killed') return 'error';
+    return 'success'; // DONE / DONE_WITH_CONCERNS
+}
+
+function isInt(n: unknown): n is number {
+    return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n);
+}
+
+/**
+ * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
+ * `errors` is non-empty, `line` is null and the caller must NOT write.
+ */
+export function buildOrchestrationLine(input: RecordInput): BuiltLine {
+    const errors: string[] = [];
+
+    if (!isInt(input.spawn_count) || input.spawn_count < 1) {
+        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record)');
+    }
+    if (!isInt(input.token_delta)) errors.push('token_delta must be an integer (negative = net saved vs the in-session baseline)');
+    if (input.task_size_estimate !== undefined && (!isInt(input.task_size_estimate) || input.task_size_estimate < 0)) {
+        errors.push('task_size_estimate must be a non-negative integer');
+    }
+    if (input.wall_clock_ms !== undefined && (!isInt(input.wall_clock_ms) || input.wall_clock_ms < 0)) {
+        errors.push('wall_clock_ms must be a non-negative integer');
+    }
+    if (input.dispatch_tokens != null && (!isInt(input.dispatch_tokens) || input.dispatch_tokens < 0)) {
+        errors.push('dispatch_tokens must be a non-negative integer (absolute tokens the dispatched slice consumed)');
+    }
+
+    const prov: Provenance = input.token_delta_provenance ?? 'estimated';
+    if (!PROVENANCES.includes(prov)) errors.push(`token_delta_provenance must be one of ${PROVENANCES.join(' | ')}`);
+
+    const dOutcome: DispatchOutcome = input.dispatch_outcome ?? 'DONE';
+    if (!DISPATCH_OUTCOMES.includes(dOutcome)) errors.push(`dispatch_outcome must be one of ${DISPATCH_OUTCOMES.join(' | ')}`);
+
+    const vMode: VerifyMode = input.verify_mode ?? 'deterministic';
+    if (!VERIFY_MODES.includes(vMode)) errors.push(`verify_mode must be one of ${VERIFY_MODES.join(' | ')}`);
+
+    if (input.tier_chosen != null && !TIERS_CHOSEN.includes(input.tier_chosen)) {
+        errors.push(`tier_chosen must be one of ${TIERS_CHOSEN.join(' | ')} (or omitted)`);
+    }
+    if (input.tier_source != null && !TIER_SOURCES.includes(input.tier_source)) {
+        errors.push(`tier_source must be one of ${TIER_SOURCES.join(' | ')} (or omitted)`);
+    }
+
+    const band = input.confidence_band ?? 'medium';
+    if (!BANDS.includes(band)) errors.push(`confidence_band must be one of ${BANDS.join(' | ')}`);
+    const risk = input.risk_class ?? 'low';
+    if (!BANDS.includes(risk)) errors.push(`risk_class must be one of ${BANDS.join(' | ')}`);
+    const phase = input.phase ?? 'implement';
+    if (!PHASES.includes(phase)) errors.push(`phase must be one of ${PHASES.join(' | ')}`);
+
+    if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
+    if (!input.id) errors.push('id (ULID or content hash) is required');
+
+    if (errors.length) return { line: null, errors };
+
+    const orchestration: Record<string, unknown> = {
+        task_size_estimate: input.task_size_estimate ?? 0,
+        spawn_count: input.spawn_count,
+        tiers: input.tiers ?? [],
+        token_delta: input.token_delta,
+        token_delta_provenance: prov,
+        wall_clock_ms: input.wall_clock_ms ?? 0,
+        outcome: dOutcome,
+        verify_mode: vMode,
+        task_class: input.task_class ?? null,
+        tier_chosen: input.tier_chosen ?? null,
+        tier_source: input.tier_source ?? null,
+        dispatch_tokens: input.dispatch_tokens ?? null,
+        session_tier: input.session_tier ?? null,
+    };
+
+    const line: Record<string, unknown> = {
+        schema_version: 1,
+        id: input.id,
+        ts: input.ts,
+        work_id: input.work_id ?? `orchestration-${input.ts}`,
+        phase,
+        outcome: input.outcome ?? envelopeOutcome(dOutcome),
+        confidence_band: band,
+        risk_class: risk,
+        memory: { asks: 0, hits: 0 },
+        verify: { claims: 0, first_try_passes: 0 },
+        rules_applied: ['delegation-policy'],
+        persona: input.persona ?? null,
+        input_kind: 'orchestration',
+        type: 'phase',
+        orchestration,
+    };
+
+    return { line, errors: [] };
+}

package/src/scripts/_lib/orchestration_savings.ts

@@ -5,16 +5,28 @@
  * Consumes the `orchestration` sub-object of audit-log-v1 JSONL lines
  * (contract: `src/agent-src/contexts/execution/orchestration-telemetry.md`).
  *
- * HONEST LIMIT — the telemetry records `token_delta` (net dispatch cost vs the
- * in-session baseline; negative = saved) but NOT the absolute baseline. A clean
- * "% of session saved" is therefore NOT derivable from this data alone — only
- * ABSOLUTE net tokens saved, plus the measured-vs-estimated provenance split.
- * A percentage would need an absolute-baseline field on the telemetry (see the
- * report `notes` and the PR's follow-up section).
+ * TWO metrics, kept distinct on purpose:
+ * 1. MEASURED token counts — `token_delta` (net token-COUNT delta vs the
+ *    in-session baseline; negative = fewer tokens). Real, but blind to the
+ *    downshift RATE win: the same work on a cheaper tier uses ~the same token
+ *    COUNT, so token_delta ≈ 0 for a pure downshift even though cost dropped.
+ * 2. MODELED cost-% (`modeled_cost`) — captures exactly that downshift win via
+ *    provider-neutral tier weights + absolute `dispatch_tokens`. It is a MODEL
+ *    (weights + a same-token-count assumption), NOT a measured $ figure, and is
+ *    clearly labelled as such in the report notes.
  */
 
 export type TokenDeltaProvenance = 'measured' | 'estimated';
 
+/**
+ * Relative, provider-NEUTRAL cost weights per model tier — a tunable ratio, not
+ * $ prices. Default reflects the ~5×/~15× cheap-vs-frontier ratios from the
+ * cost-downshift council; override per project via the report's `--weights`.
+ * Used ONLY for the modeled cost-%, never for the measured token counts.
+ */
+export type TierWeights = Record<string, number>;
+export const DEFAULT_TIER_WEIGHTS: TierWeights = { lite: 1, medium: 5, high: 15 };
+
 /** The `orchestration` sub-object shape we read (subset — additive fields only). */
 export interface OrchestrationRecord {
     spawn_count?: number;
@@ -23,6 +35,10 @@ export interface OrchestrationRecord {
     tier_chosen?: string | null;
     task_class?: string | null;
     outcome?: string;
+    /** Absolute measured tokens the dispatched slice consumed (for the modeled cost-%). */
+    dispatch_tokens?: number | null;
+    /** The orchestrator's own tier — the baseline the downshift is measured against. */
+    session_tier?: string | null;
 }
 
 /** A parsed audit-log-v1 line (only the fields this aggregator touches). */
@@ -37,6 +53,18 @@ export interface ProvenanceStat {
     net_token_delta: number;
 }
 
+export interface ModeledCost {
+    /** Dispatches with dispatch_tokens + session_tier + tier_chosen all weight-resolvable. */
+    covered_dispatches: number;
+    /** Σ dispatch_tokens × weight(session_tier) — same tokens costed on the baseline tier. */
+    baseline_cost_units: number;
+    /** Σ dispatch_tokens × weight(tier_chosen) — modeled cost of the downshifted run. */
+    delegated_cost_units: number;
+    /** (baseline − delegated) / baseline, 0..1; null when no covered dispatches. MODELED, not measured $. */
+    cost_reduction_pct: number | null;
+    weights: TierWeights;
+}
+
 export interface SavingsReport {
     /** Lines carrying an orchestration object with spawn_count > 0. */
     dispatches: number;
@@ -54,6 +82,8 @@ export interface SavingsReport {
     by_task_class: Record<string, number>;
     /** measured dispatches / dispatches, 0..1 (0 when no dispatches). */
     measured_share: number;
+    /** Modeled downshift cost-% (tier-weight based). Distinct from the measured token counts. */
+    modeled_cost: ModeledCost;
     /** Honest caveats about what the number does and does not mean. */
     notes: string[];
 }
@@ -70,7 +100,10 @@ function emptyProvenance(): ProvenanceStat {
  * dispatch). Unknown/absent fields default safely (token_delta → 0, provenance
  * → estimated) so a pre-extension line never throws.
  */
-export function aggregateOrchestrationSavings(lines: AuditLine[]): SavingsReport {
+export function aggregateOrchestrationSavings(
+    lines: AuditLine[],
+    weights: TierWeights = DEFAULT_TIER_WEIGHTS,
+): SavingsReport {
     const report: SavingsReport = {
         dispatches: 0,
         total_spawns: 0,
@@ -81,6 +114,7 @@ export function aggregateOrchestrationSavings(lines: AuditLine[]): SavingsReport
         by_tier: {},
         by_task_class: {},
         measured_share: 0,
+        modeled_cost: { covered_dispatches: 0, baseline_cost_units: 0, delegated_cost_units: 0, cost_reduction_pct: null, weights },
         notes: [],
     };
 
@@ -109,18 +143,37 @@ export function aggregateOrchestrationSavings(lines: AuditLine[]): SavingsReport
 
         const cls = o.task_class ?? 'unclassified';
         report.by_task_class[cls] = (report.by_task_class[cls] ?? 0) + delta;
+
+        // Modeled cost — the downshift RATE win token_delta (counts) cannot see:
+        // the same dispatch_tokens on a cheaper tier cost less by the weight ratio.
+        const dt = o.dispatch_tokens ?? 0;
+        const wChosen = o.tier_chosen != null ? weights[o.tier_chosen] : undefined;
+        const wSession = o.session_tier != null ? weights[o.session_tier] : undefined;
+        if (dt > 0 && wChosen !== undefined && wSession !== undefined) {
+            report.modeled_cost.covered_dispatches += 1;
+            report.modeled_cost.baseline_cost_units += dt * wSession;
+            report.modeled_cost.delegated_cost_units += dt * wChosen;
+        }
     }
 
     report.measured_share = report.dispatches === 0 ? 0 : report.by_provenance.measured.dispatches / report.dispatches;
 
+    const mc = report.modeled_cost;
+    mc.cost_reduction_pct = mc.baseline_cost_units > 0 ? (mc.baseline_cost_units - mc.delegated_cost_units) / mc.baseline_cost_units : null;
+
     // Honest caveats — always attached so a consumer never over-reads the number.
     if (report.dispatches === 0) {
-        report.notes.push('No orchestration telemetry yet (0 dispatches). The number accrues as `subagents.auto: on` runs delegate real slices.');
+        report.notes.push('No orchestration telemetry yet (0 dispatches). Data accrues as `subagents.auto: on` delegates real slices (recorded via orchestration_record).');
     } else {
-        report.notes.push('Reports ABSOLUTE net token_delta (negative = saved). A "% of session saved" is NOT derivable — the telemetry records net delta, not the absolute baseline. A percentage needs an absolute-baseline field on the telemetry.');
+        report.notes.push('Token counts are MEASURED but blind to the downshift rate win (same tokens on a cheaper tier ≈ same count). The MODELED cost-% below captures that axis.');
         if (report.by_provenance.estimated.dispatches > 0) {
             report.notes.push(`${report.by_provenance.estimated.dispatches}/${report.dispatches} dispatch(es) use ESTIMATED token_delta (chars/4, lossy). Prefer measured (host usage metadata).`);
         }
+        if (mc.covered_dispatches > 0 && mc.cost_reduction_pct !== null) {
+            report.notes.push(`MODELED cost reduction ${(mc.cost_reduction_pct * 100).toFixed(0)}% over ${mc.covered_dispatches}/${report.dispatches} dispatch(es) that carry tier data — from provider-neutral tier weights ${JSON.stringify(mc.weights)} + a same-token-count assumption. A MODEL, NOT a measured $ figure; tune with --weights.`);
+        } else {
+            report.notes.push('MODELED cost-% unavailable: no dispatch yet carries dispatch_tokens + session_tier + tier_chosen. Record those (orchestration_record --dispatch-tokens/--session-tier/--tier-chosen) to populate it.');
+        }
     }
 
     return report;

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -0,0 +1,71 @@
+/**
+ * Sanitize floor for retrieval read-surfaces
+ * (road-to-retrieval-substrate-hardening B6).
+ *
+ * Corpus content — especially user-ingested knowledge chunks under
+ * `agents/memory/knowledge/` — flows into the agent context via `retrieve_v1`
+ * / `memory_get_v1`. An attacker (or a compromised ingested source) can embed
+ * hidden-instruction vectors (bidi controls, zero-width chars, Unicode Tag
+ * block) or control-char noise that the model may act on — the untrusted-input
+ * / lethal-trifecta injection surface. This floor strips those vectors from
+ * every string field before it is emitted, treating retrieved content as DATA.
+ *
+ * It deliberately does NOT rewrite visible text (that would corrupt legitimate
+ * rule/chunk bodies and code snippets) — the injection risk is the *invisible*
+ * layer + unbounded length; visible content is the agent's to read as data.
+ * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
+ * for what counts as a hidden-instruction vector).
+ */
+import { _classify } from '../lint_hidden_unicode.js';
+
+/** Hard per-field length cap — bounds a runaway/adversarial body. */
+export const MAX_FIELD_CHARS = 8192;
+
+/** True for a C0/C1 control char that is NOT a benign whitespace (\t, \n). */
+function _isStrippableControl(cp: number): boolean {
+    if (cp === 0x09 || cp === 0x0a) return false; // keep tab + newline
+    if (cp <= 0x1f) return true; // C0 controls (incl. CR 0x0d — normalised out)
+    if (cp === 0x7f) return true; // DEL
+    if (cp >= 0x80 && cp <= 0x9f) return true; // C1 controls
+    return false;
+}
+
+/**
+ * Strip hidden-instruction vectors (bidi / zero-width / Unicode-tag /
+ * deprecated-format, per `_classify`) and stray control chars from a string,
+ * then cap its length. Preserves all visible content + tabs/newlines.
+ */
+export function sanitize_text(s: string): string {
+    let out = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined) continue;
+        if (_classify(cp) !== null) continue; // hidden-instruction vector → drop
+        if (_isStrippableControl(cp)) continue; // control-char noise → drop
+        out += ch;
+    }
+    return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
+}
+
+/**
+ * Return a shallow copy of a retrieval entry with every string value (and
+ * one level of string-array values) sanitized. Non-string values pass through
+ * unchanged (numbers, booleans, the PyFloat marker, nested plain objects are
+ * sanitized recursively).
+ */
+export function sanitize_entry(entry: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(entry)) {
+        out[k] = _sanitize_value(v);
+    }
+    return out;
+}
+
+function _sanitize_value(v: unknown): unknown {
+    if (typeof v === 'string') return sanitize_text(v);
+    if (Array.isArray(v)) return v.map((x) => (typeof x === 'string' ? sanitize_text(x) : _sanitize_value(x)));
+    if (v && typeof v === 'object' && v.constructor === Object) {
+        return sanitize_entry(v as Record<string, unknown>);
+    }
+    return v; // numbers, booleans, null, marker classes (PyFloat/PyTimestamp) untouched
+}

package/src/scripts/_lib/security_lint.ts

@@ -52,6 +52,7 @@ export const DEFAULT_SCAN_ROOTS: readonly string[] = [
     'src/rules',
     'src/agent-src',
     'src/domains',
+    'dist/agent-src',
 ];
 
 // A path is "example/teaching" (0.25x weight) when it lives under docs/ or

package/src/scripts/_lib/stat_index.ts

@@ -0,0 +1,98 @@
+/**
+ * Stat-index — skip an expensive scan when the input tree is unchanged
+ * (road-to-retrieval-substrate-hardening B5a).
+ *
+ * The memory / knowledge / discovery scanners re-read their whole file set on
+ * every `stop` / `session_start` hook, even when nothing changed. A stat-index
+ * captures a cheap signature of the input files (size + mtime_ns) and caches
+ * the scan's result beside it; a later call with the same signature returns the
+ * cached payload without re-scanning. The cache is version-namespaced (so a
+ * tool bump invalidates cleanly, versioned-cache lint B5b) and written
+ * atomically (pid-temp + rename) so concurrent hook invocations stay
+ * idempotent (council Q3).
+ *
+ * `size + mtime_ns` is sufficient for gating rebuild decisions (the council
+ * withdrew the crypto-binding demand as a non-problem); a `--force` bypass and
+ * an explicit `clear()` cover the rare stale-mtime case (e.g. `cp -p`).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/** A deterministic signature over a file set: `<count>:<Σsize>:<maxMtimeNs>:<hashOfPaths>`. */
+export function statSignature(files: readonly string[]): string {
+    let count = 0;
+    let totalSize = 0;
+    let maxMtimeNs = 0n;
+    const sortedPaths = [...files].sort();
+    for (const f of sortedPaths) {
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(f, { bigint: true }) as unknown as fs.Stats;
+        } catch {
+            continue; // missing file → excluded from the signature
+        }
+        count += 1;
+        totalSize += Number((st as unknown as { size: bigint }).size);
+        const m = (st as unknown as { mtimeNs: bigint }).mtimeNs;
+        if (m > maxMtimeNs) maxMtimeNs = m;
+    }
+    // A stable hash of the path list so add/remove/rename shifts the signature
+    // even when count + size + mtime coincide.
+    let h = 5381;
+    for (const p of sortedPaths) {
+        for (let i = 0; i < p.length; i++) h = ((h * 33) ^ p.charCodeAt(i)) >>> 0;
+    }
+    return `${count}:${totalSize}:${maxMtimeNs.toString()}:${h.toString(16)}`;
+}
+
+interface CacheFile<T> {
+    schema_version: number;
+    signature: string;
+    payload: T;
+}
+
+/**
+ * Return the cached payload when the file-set signature is unchanged; otherwise
+ * run `compute`, persist the result under `signature`, and return it.
+ *
+ * @param cachePath  version-namespaced cache file (e.g. `…-index-v1.json`)
+ * @param files      the input file set whose stat signature gates the cache
+ * @param compute    the expensive scan, run only on a miss
+ * @param force      bypass the cache and always recompute (then persist)
+ */
+export function scanCached<T>(
+    cachePath: string,
+    files: readonly string[],
+    compute: () => T,
+    force = false,
+): T {
+    const signature = statSignature(files);
+    if (!force) {
+        try {
+            const cached = JSON.parse(fs.readFileSync(cachePath, 'utf-8')) as CacheFile<T>;
+            if (cached.signature === signature) return cached.payload;
+        } catch {
+            /* miss → recompute */
+        }
+    }
+    const payload = compute();
+    writeCacheAtomic<T>(cachePath, { schema_version: 1, signature, payload });
+    return payload;
+}
+
+function writeCacheAtomic<T>(cachePath: string, data: CacheFile<T>): void {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const tmp = `${cachePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data));
+    fs.renameSync(tmp, cachePath);
+}
+
+/** Drop a stat-index cache file (for `--force`-style resets / tests). */
+export function clear(cachePath: string): void {
+    try {
+        fs.rmSync(cachePath);
+    } catch {
+        /* already absent */
+    }
+}