@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -16,26 +16,58 @@
  * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
  * for what counts as a hidden-instruction vector).
  *
- * WHERE IT ACTUALLY RUNS — measured end-to-end, not asserted. Keep this list
- * honest: an earlier version of this header named surfaces by intent, and the
- * legacy-envelope gap below went unnoticed for exactly that reason. Every
- * claim here is backed by a probe row in
- * `agents/evidence/reports/sanitize-floor-wiring.md`:
+ * WHERE IT ACTUALLY RUNS — read the table, which is GENERATED:
  *
- *   - `retrieve_v1()`     — yes (`memory_lookup.ts` calls `sanitize_entry`)
- *   - `memory_get_v1()`   — yes (same)
- *   - MCP `memory_lookup` / `memory_get` tools — inherited from the two above
- *   - `retrieve()` / `retrieve_with_meta()` — yes, since the S0.0 wiring fix;
- *     before it they emitted every vector intact, and so did the CLI default
- *     (`--envelope legacy`), which is the path the rules document
- *   - inter-agent channels (`ai_team` / `ai_council` model replies) — the
- *     inbound parse choke point only; the subagent boundary itself is a HOST
- *     primitive this package cannot reach (see the report, § S0.0b)
+ *     docs/contracts/retrieval-read-surfaces.md
  *
- * Anything not on that list is uncovered. Do not widen the list without a
- * probe row to back it.
+ * This header used to carry that list inline, and the list was wrong in BOTH
+ * directions: a path that reaches the outside world and IS sanitized was
+ * absent from it, and two paths carrying fetched bytes toward a model-facing
+ * surface were neither listed nor covered. An earlier version had already
+ * failed the same way — it named surfaces by intent, and the legacy-envelope
+ * gap went unnoticed for exactly that reason. Twice is a property of the
+ * mechanism, not of the entries, which is why the list is now derived from the
+ * import graph by `check_read_surface_coverage` and this header points at it
+ * instead of copying it. A divergence between the two FAILS that gate; two
+ * copies is how it went stale.
+ *
+ * Anything absent from the table is uncovered, and a module the generator
+ * cannot classify appears there as an `unclassified` ROW rather than being
+ * omitted — a missing row would read as no surface at all.
+ *
+ * One boundary the table cannot move: the subagent boundary itself is a HOST
+ * primitive this package cannot reach, so the inter-agent channels are covered
+ * at the inbound parse choke point and nowhere else.
+ *
+ * loss_class: ephemeral-lossy
+ *
+ * `sanitize_text` drops hidden-instruction codepoints, control-char noise and
+ * invisible fillers, and caps the result at MAX_FIELD_CHARS. None of that is
+ * reconstructible from the output, and for the dropped vectors the
+ * unrecoverability IS the guarantee — a retrieval path that could hand back
+ * the vector it stripped would not be a floor. So the class is
+ * `ephemeral-lossy` for the module, even though `sanitize_markup` below
+ * returns structured removals for the layer it composes: a class names what a
+ * caller can recover from the output, and `sanitize_text` returns a string.
+ *
+ * THE STRUCTURAL LAYER IS A SEPARATE MODULE. Everything below is a CODEPOINT
+ * floor. Fetched markup also hides content STRUCTURALLY — an HTML comment, a
+ * `<template>` block, a `style="display:none"` span — which no codepoint
+ * predicate can see. That class is covered by `_lib/structural_hiding.ts`,
+ * composed with this floor by `sanitize_markup` below, and it is covered for
+ * fetched MARKUP only: a caller holding plain text needs nothing from it.
+ *
+ * WHAT THAT LAYER STILL DOES NOT SEE is a register in its own file —
+ * `STRUCTURAL_HIDING_GAPS` — and every surface claiming the coverage cites the
+ * register alongside the claim, because a detector cited without its gaps is
+ * how the claim becomes a false green. No recall or coverage percentage is
+ * published for it anywhere; a rate needs a frozen corpus and none exists.
+ * `aria-hidden` is deliberately NOT one of its channels
+ * (`STRUCTURAL_HIDING_NON_CHANNELS` says why).
  */
 import { _classify } from '../lint_hidden_unicode.js';
+import { strip_structural_hiding } from './structural_hiding.js';
+import type { StructuralRemoval } from './structural_hiding.js';
 import { TOKEN_RE, classifyToken } from './confusables.js';
 
 /** Hard per-field length cap — bounds a runaway/adversarial body. */
@@ -85,6 +117,35 @@ export function sanitize_text(s: string): string {
     return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
 }
 
+/**
+ * The fetched-markup floor: structural pre-pass, then the codepoint floor.
+ *
+ * ORDER IS LOAD-BEARING. The structural pass runs FIRST, because a codepoint
+ * floor applied first would sanitize text that is about to be discarded and,
+ * worse, would leave a hidden subtree looking clean. Running it second means
+ * every byte that survives the structural pass still clears the codepoint
+ * floor — including the text that was only reachable once markup was removed.
+ *
+ * Use this for fetched MARKUP. For plain text `sanitize_text` is the whole
+ * floor and this adds nothing but a parse.
+ *
+ * The removals are RETURNED, not logged and not swallowed: a caller debugging
+ * a corrupted result needs to know what went and where it was. See the removal
+ * policy in `structural_hiding.ts`.
+ */
+export function sanitize_markup(markup: string): {
+    text: string;
+    removals: readonly StructuralRemoval[];
+    truncated: boolean;
+} {
+    const stripped = strip_structural_hiding(markup);
+    return {
+        text: sanitize_text(stripped.text),
+        removals: stripped.removals,
+        truncated: stripped.truncated,
+    };
+}
+
 /**
  * Report the INVISIBLE layer without removing it.
  *

package/src/scripts/_lib/rides_along.ts

@@ -0,0 +1,102 @@
+/**
+ * What rides along during a mission — `road-to-adversarial-verification-and-long-runs`
+ * 6.1.
+ *
+ * `active-remediation`'s ladder is fix-now / note+ask / follow-up PR, and its
+ * middle rung is unavailable inside an autonomous mission: there is nobody to
+ * ask. Without a replacement the rung collapses in one of two bad directions —
+ * every spotted issue becomes a fix (scope creep, which `minimal-safe-diff`
+ * exists to stop) or every one becomes silence (which `active-remediation`
+ * exists to stop). So under a mission the middle rung becomes **emit a follow-up
+ * artefact**, and this module decides which rung a candidate lands on.
+ *
+ * **Six criteria, ALL of which must hold.** They are `AND`-ed rather than scored
+ * because a scored version lets a large change buy its way in with four cheap
+ * yeses, which is the shape that turns a boy-scout rule into a refactor licence.
+ *
+ * Pure: the caller characterises the change, this decides. The characterisation
+ * is a judgement and stays the agent's; the DECISION is mechanical so it is the
+ * same for the same inputs.
+ */
+
+/** What the agent observed about a candidate improvement. */
+export interface Candidate {
+    /** What it is. Used only in the rendered line. */
+    readonly what: string;
+    /** In the same request path / module the mission is already touching. */
+    readonly local: boolean;
+    /** Small: roughly a handful of lines in one production file. */
+    readonly small: boolean;
+    /** Low blast radius — nothing outside this module observes the change. */
+    readonly lowBlastRadius: boolean;
+    /** Clearly correct: a reviewer would not need to be persuaded. */
+    readonly clearlyCorrect: boolean;
+    /** Testable, and the test ships in the same commit. */
+    readonly testable: boolean;
+    /** Carries NO new product decision — nothing about what the thing should do. */
+    readonly noProductDecision: boolean;
+}
+
+/** The kinds of improvement a mission may take at all. */
+export const RIDE_ALONG_KINDS: readonly string[] = [
+    'characterization-test',
+    'regression-test',
+    'small-adjacent-bug',
+    'naming',
+    'types',
+    'robustness',
+    'local-dead-code',
+    'simplify-touched-code',
+    'testability',
+] as const;
+
+export type Disposition = 'ride-along' | 'follow-up-artefact';
+
+export interface Verdict {
+    readonly disposition: Disposition;
+    /** Every criterion that failed, in declaration order. Empty on ride-along. */
+    readonly failed: readonly string[];
+}
+
+const CRITERIA: readonly (readonly [keyof Candidate, string])[] = [
+    ['local', 'not local to the path this mission is already touching'],
+    ['small', 'not small — more than a handful of lines in one file'],
+    ['lowBlastRadius', 'blast radius reaches beyond this module'],
+    ['clearlyCorrect', 'not clearly correct — a reviewer would need persuading'],
+    ['testable', 'not testable in the same commit'],
+    ['noProductDecision', 'carries a new product decision'],
+];
+
+/**
+ * Which rung this candidate lands on.
+ *
+ * Returns EVERY failed criterion rather than the first, because the follow-up
+ * artefact has to say why the change was deferred, and "it failed one of six"
+ * is not a reason a later reader can act on.
+ */
+export function disposition(c: Candidate): Verdict {
+    const failed = CRITERIA.filter(([k]) => c[k] !== true).map(([, why]) => why);
+    return {
+        disposition: failed.length === 0 ? 'ride-along' : 'follow-up-artefact',
+        failed,
+    };
+}
+
+/**
+ * The follow-up artefact's body — what was seen, and why it did not ride along.
+ *
+ * A deferral with no reason is the note-and-forget `active-remediation` already
+ * forbids, one layer out: the artefact exists so the issue is still owed, and an
+ * artefact that does not say why it was deferred cannot be triaged later.
+ */
+export function followUpBody(c: Candidate, v: Verdict): string {
+    if (v.disposition === 'ride-along') return '';
+    return [
+        `Deferred adjacent improvement: ${c.what}`,
+        '',
+        'Did not ride along because:',
+        ...v.failed.map((f) => `  - ${f}`),
+        '',
+        'Spotted during a mission; the code was left alone deliberately.',
+    ].join('\n');
+}

package/src/scripts/_lib/settings_renamed_keys.ts

@@ -0,0 +1,82 @@
+/**
+ * Settings keys this package has RENAMED, old path -> new path.
+ *
+ * Distinct from `REMOVED_KEYS` in the one way that matters to a user: a
+ * removed key's value is DISCARDED, and a renamed key's value is CARRIED.
+ * Putting a rename in the removed map would silently return an installed
+ * `false` to the shipped default, which is the opposite of accepting the old
+ * key — so the two maps stay separate even though both warn once.
+ *
+ * An entry is dropped one minor after it lands. The new key always wins when
+ * one layer carries both: a reader who has already migrated is not overridden
+ * by a stale line they forgot to delete.
+ *
+ * Its own module rather than more lines in `agent_settings.ts`, which sits
+ * three lines under the 1500-line source ceiling — a sixty-line addition there
+ * is sixty units of ratchet, and here it is none.
+ */
+
+export type SettingsLayer = Record<string, unknown>;
+
+export const RENAMED_KEYS: ReadonlyMap<string, string> = new Map([
+    ['planning.challenge_on_create', 'planning.closure_pass'],
+]);
+
+/** Keys already warned about in THIS process — the "once per run" dedupe. */
+const _warned = new Set<string>();
+
+/** Read a dotted path out of a settings tree. `undefined` when absent. */
+function _read(tree: SettingsLayer, dotted: string): unknown {
+    let cur: unknown = tree;
+    for (const part of dotted.split('.')) {
+        if (cur === null || typeof cur !== 'object' || Array.isArray(cur)) return undefined;
+        cur = (cur as SettingsLayer)[part];
+    }
+    return cur;
+}
+
+/** Write a dotted path into a settings tree, creating the intermediate maps. */
+function _write(tree: SettingsLayer, dotted: string, value: unknown): void {
+    const parts = dotted.split('.');
+    let cur: SettingsLayer = tree;
+    for (const part of parts.slice(0, -1)) {
+        const next = cur[part];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) cur[part] = {};
+        cur = cur[part] as SettingsLayer;
+    }
+    cur[parts[parts.length - 1] as string] = value;
+}
+
+/**
+ * Carry every renamed key's value onto its new path within ONE layer, and
+ * return that layer.
+ *
+ * Per LAYER, before the merge, and that ordering is the whole contract: the
+ * shipped template already carries the new key, so a rename applied to the
+ * MERGED tree would always find the target "already set" and drop the user's
+ * value on the floor. Applied per layer, the old key becomes the new key
+ * inside the layer that wrote it, and ordinary precedence does the rest.
+ *
+ * Mutates and returns `layer` so it can wrap an existing merge call without
+ * adding a statement. Never throws: a layer that cannot be walked is a layer
+ * with nothing to migrate.
+ */
+export function applyRenamedKeys<T extends SettingsLayer>(layer: T): T {
+    for (const [oldKey, newKey] of RENAMED_KEYS) {
+        const oldValue = _read(layer, oldKey);
+        if (oldValue === undefined) continue;
+        if (_read(layer, newKey) === undefined) _write(layer, newKey, oldValue);
+        if (_warned.has(oldKey)) continue;
+        _warned.add(oldKey);
+        process.stderr.write(
+            `⚠️  settings: \`${oldKey}\` was renamed to \`${newKey}\`. The old key still ` +
+                `works for one minor; rename it in your .agent-settings.yml.\n`,
+        );
+    }
+    return layer;
+}
+
+/** Test seam — the once-per-process warning dedupe is process state. */
+export function _resetRenameWarnings(): void {
+    _warned.clear();
+}

package/src/scripts/_lib/shell_write_shapes.ts

@@ -0,0 +1,108 @@
+/**
+ * The shell shapes that mean "this path is being WRITTEN", shared by the
+ * PreToolUse guards that refuse a write to a governed file.
+ *
+ * WHY IT IS SHARED. `block_kernel_rule_writes.ts` grew this parser after the
+ * S0.2 spike measured a real gap: a guard keyed on the TOOL NAME let
+ * `Bash sed -i … src/rules/commit-policy.md` reach the outcome the Write
+ * branch refuses, and a two-step `Write` → `Bash mv` sequence did the same with
+ * every individual step allowed. `block_plumbing_writes.ts`
+ * (road-to-a-kernel-that-guards-its-plumbing 1.2) refuses a different file set
+ * against the same shapes. Two copies of a shell-shape parser is two places a
+ * verb can be added to one and forgotten in the other, and the guard that
+ * silently stopped recognising `tee` would look exactly like the guard that
+ * never had to.
+ *
+ * DELIBERATELY NARROW (council 2026-08-02 cut, option ii, recorded on the
+ * kernel guard and inherited here unchanged): only redirection into the path,
+ * an in-place `sed`, a `tee`/`truncate`/`rm`/`shred` naming it, or a
+ * `mv`/`cp`/`install`/`rsync` whose DESTINATION it is. Reads stay allowed —
+ * `cat`, `grep`, `head`, `diff`, `git show` carry none of these shapes — and no
+ * attempt is made to understand arbitrary shell. Recognising every conceivable
+ * write verb would make this a shell sandbox, which is the failure mode the
+ * council named.
+ *
+ * KNOWN-OPEN, stated rather than implied: a write routed through an
+ * interpreter (`python -c`, a heredoc fed to `sh`) carries none of these
+ * shapes and is not detected. This is a guard, not write mediation.
+ */
+import * as path from 'node:path';
+
+/** In-place mutators that name their target as a plain argument. */
+const MUTATOR_VERBS: ReadonlySet<string> = new Set(['sed', 'tee', 'truncate', 'rm', 'shred']);
+
+/** Verbs whose LAST positional argument is the destination. */
+const DEST_LAST_VERBS: ReadonlySet<string> = new Set(['mv', 'cp', 'install', 'rsync']);
+
+/**
+ * The first governed target a command WRITES, or `null`.
+ *
+ * @param command the raw shell string off the tool envelope
+ * @param match   classifies one token: a non-null return names the governed
+ *                target that token resolves to, and is what this returns
+ */
+export function shellWriteTarget<T>(command: string, match: (token: string) => T | null): T | null {
+    const tokens = command.split(/\s+/).filter((t) => t.length > 0);
+    const stripped = tokens.map((t) => t.replace(/^['"]|['"]$/g, ''));
+
+    // Cheap reject first: no governed path in the string at all.
+    if (!stripped.some((t) => match(t) !== null)) {
+        return null;
+    }
+
+    // 1. Redirection into the path: `> p`, `>> p`, `>p`, `>>p`.
+    for (let i = 0; i < stripped.length; i += 1) {
+        const tok = stripped[i] as string;
+        const inline = /^>{1,2}(.+)$/.exec(tok);
+        if (inline) {
+            const r = match(inline[1] as string);
+            if (r !== null) {
+                return r;
+            }
+        }
+        if (tok === '>' || tok === '>>') {
+            const next = stripped[i + 1];
+            if (typeof next === 'string') {
+                const r = match(next);
+                if (r !== null) {
+                    return r;
+                }
+            }
+        }
+    }
+
+    // 2. A mutator verb anywhere in the pipeline, with the path as an argument.
+    //    `sed` only counts in its in-place form — `sed 's/x/y/' file` prints.
+    const verbs = new Set<string>();
+    let prevWasSeparator = true;
+    for (const tok of stripped) {
+        if (['&&', '||', ';', '|'].includes(tok)) {
+            prevWasSeparator = true;
+            continue;
+        }
+        if (prevWasSeparator && !tok.startsWith('-')) {
+            verbs.add(path.basename(tok));
+            prevWasSeparator = false;
+        }
+    }
+    const sedInPlace = verbs.has('sed') && stripped.some((t) => /^-i/.test(t));
+    for (const verb of verbs) {
+        if (verb === 'sed' && !sedInPlace) {
+            continue;
+        }
+        if (MUTATOR_VERBS.has(verb)) {
+            const hit = stripped.map(match).find((r) => r !== null);
+            if (hit !== undefined && hit !== null) {
+                return hit;
+            }
+        }
+        if (DEST_LAST_VERBS.has(verb)) {
+            const last = stripped[stripped.length - 1] as string;
+            const r = match(last);
+            if (r !== null) {
+                return r;
+            }
+        }
+    }
+    return null;
+}