@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/_lib/neighbour_contradictions.ts

@@ -0,0 +1,236 @@
+/**
+ * Contradiction review between a project's instructions and its neighbours'
+ * (road-to-neighbours-that-pull-their-weight step 2.2).
+ *
+ * REPORT-ONLY. Nothing here edits, gates or suppresses an instruction — the
+ * output is a table a human reads. `neighbour-precedence` (step 2.1) is the
+ * rubric: the "which wins" column is its source order applied to the two
+ * sources, computed here, and the verdict column is one council seat's reading
+ * of whether the pair actually disagrees.
+ *
+ * NO STATIC DETECTOR DECIDES ANYTHING. A static contradiction detector was
+ * measured at 67 % false positives (`docs/contracts/rule-interactions.md`), so
+ * this module only FORMS candidate pairs, and only from strong signals: a
+ * shared subject word with opposite modality, or a skill name collision the
+ * census already found. Whether a candidate is a contradiction is the seat's
+ * call, never this file's.
+ *
+ * A neighbour body the shape scan refused (step 1.3) is never read here: the
+ * caller passes only scanned sources, and a refused body contributes no line.
+ */
+import * as fs from 'node:fs';
+
+/** Rank in `neighbour-precedence`'s source order — lower wins. */
+export const RANK_PROJECT = 3;
+export const RANK_SUITE = 4;
+export const RANK_NEIGHBOUR_ALWAYS_ON = 6;
+export const RANK_NEIGHBOUR_SKILL = 7;
+
+const RANK_LABEL: Record<number, string> = {
+    [RANK_PROJECT]: 'project instruction file',
+    [RANK_SUITE]: "this suite's routed guidance",
+    [RANK_NEIGHBOUR_ALWAYS_ON]: "neighbour's always-on text",
+    [RANK_NEIGHBOUR_SKILL]: 'neighbour skill body (discoverable)',
+};
+
+export interface InstructionSource {
+    /** Where the text came from, as printed. */
+    label: string;
+    file: string;
+    rank: number;
+}
+
+export interface InstructionLine {
+    source: InstructionSource;
+    line: number;
+    text: string;
+    negative: boolean;
+    stems: Set<string>;
+}
+
+export interface CandidatePair {
+    kind: 'opposite-modality' | 'name-collision';
+    a: { label: string; rank: number; text: string };
+    b: { label: string; rank: number; text: string };
+    /** The shared subject word, or the colliding name. */
+    subject: string;
+}
+
+export type Verdict = 'contradiction' | 'compatible' | 'unclear';
+
+const NEGATION = /\b(never|don't|do not|must not|mustn't|should not|shouldn't|avoid|stop)\b/iu;
+const DIRECTIVE_WORD = /\b(always|must|should|never|don't|do not|avoid)\b/iu;
+const NON_IMPERATIVE_START = new Set([
+    'the', 'a', 'an', 'this', 'that', 'these', 'those', 'it', 'its', 'we', 'you', 'i', 'our',
+    'they', 'there', 'when', 'if', 'see', 'for', 'in', 'on', 'as', 'by', 'with', 'from',
+]);
+const STOP = new Set([
+    'always', 'never', 'must', 'should', 'avoid', 'stop', 'don', 'with', 'without', 'that', 'this',
+    'they', 'them', 'then', 'than', 'into', 'from', 'your', 'when', 'what', 'will', 'each', 'every',
+    'only', 'also', 'here', 'there', 'have', 'been', 'more', 'some', 'such', 'like', 'just',
+]);
+
+/** A crude stem — enough to meet `wait` and `waiting`, never a lemmatiser. */
+export function stem(word: string): string {
+    let w = word.toLowerCase().replace(/[^a-z]/gu, '');
+    for (const suffix of ['ing', 'ed', 'es', 's']) {
+        if (w.length > suffix.length + 3 && w.endsWith(suffix)) {
+            w = w.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return w;
+}
+
+/** Is this line phrased as an instruction at all? */
+export function isDirective(text: string): boolean {
+    if (DIRECTIVE_WORD.test(text)) return true;
+    const first = (text.split(/\s+/u)[0] ?? '').toLowerCase().replace(/[^a-z']/gu, '');
+    return first.length > 0 && !NON_IMPERATIVE_START.has(first);
+}
+
+/** Directive lines of one markdown source, outside fences and frontmatter. */
+export function extractInstructions(source: InstructionSource, body?: string): InstructionLine[] {
+    let text: string;
+    try {
+        text = body ?? fs.readFileSync(source.file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: InstructionLine[] = [];
+    let fenced = false;
+    let frontmatter = false;
+    text.split('\n').forEach((raw, i) => {
+        const line = raw.trim();
+        if (i === 0 && line === '---') {
+            frontmatter = true;
+            return;
+        }
+        if (frontmatter) {
+            if (line === '---') frontmatter = false;
+            return;
+        }
+        if (line.startsWith('```') || line.startsWith('~~~')) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced || line === '' || line.startsWith('#') || line.startsWith('|') || line.startsWith('>')) return;
+        const clean = line.replace(/^([-*+]|\d+\.)\s+/u, '').replace(/[*_`]/gu, '');
+        if (clean.split(/\s+/u).length < 3 || !isDirective(clean)) return;
+        const stems = new Set(
+            clean
+                .split(/\s+/u)
+                .map(stem)
+                .filter((s) => s.length >= 4 && !STOP.has(s)),
+        );
+        out.push({ source, line: i + 1, text: clean, negative: NEGATION.test(clean), stems });
+    });
+    return out;
+}
+
+function where(l: InstructionLine): string {
+    return `${l.source.label}:${l.line}`;
+}
+
+/**
+ * Candidate pairs from opposite modality over a shared subject word.
+ *
+ * Only ACROSS ranks — two lines of one source rank are one author's
+ * contradiction, which is not what this review is for — and only where one
+ * side is negative and the other is not. One pair per line pair, naming the
+ * first shared stem in sorted order so the output is stable.
+ */
+export function modalityPairs(lines: readonly InstructionLine[], cap = 20): CandidatePair[] {
+    const out: CandidatePair[] = [];
+    for (let i = 0; i < lines.length && out.length < cap; i += 1) {
+        for (let j = i + 1; j < lines.length && out.length < cap; j += 1) {
+            const x = lines[i] as InstructionLine;
+            const y = lines[j] as InstructionLine;
+            if (x.source.rank === y.source.rank || x.negative === y.negative) continue;
+            const shared = [...x.stems].filter((s) => y.stems.has(s)).sort();
+            if (shared.length === 0) continue;
+            const [hi, lo] = x.source.rank <= y.source.rank ? [x, y] : [y, x];
+            out.push({
+                kind: 'opposite-modality',
+                a: { label: where(hi), rank: hi.source.rank, text: hi.text },
+                b: { label: where(lo), rank: lo.source.rank, text: lo.text },
+                subject: shared[0] as string,
+            });
+        }
+    }
+    return out;
+}
+
+/** A neighbour skill that shares a name with one of ours — the census's `shadowed`. */
+export function collisionPair(neighbourQualified: string, ourName: string): CandidatePair {
+    return {
+        kind: 'name-collision',
+        a: { label: `suite:${ourName}`, rank: RANK_SUITE, text: `this suite's skill \`${ourName}\`` },
+        b: {
+            label: neighbourQualified,
+            rank: RANK_NEIGHBOUR_SKILL,
+            text: `neighbour skill \`${neighbourQualified}\``,
+        },
+        subject: ourName,
+    };
+}
+
+/** "Which wins by 2.1" — the lower rank, named. */
+export function winnerBy21(p: CandidatePair): string {
+    const w = p.a.rank <= p.b.rank ? p.a : p.b;
+    return `${w.label} (rank ${w.rank}, ${RANK_LABEL[w.rank] ?? 'unranked'})`;
+}
+
+/** The single-seat prompt. States no expected verdict (evaluator-independence). */
+export function seatPrompt(pairs: readonly CandidatePair[], rubric: string): string {
+    const rows = pairs.map(
+        (p, i) => `PAIR ${i + 1} (${p.kind}, subject "${p.subject}")\n  A [${p.a.label}]: ${p.a.text}\n  B [${p.b.label}]: ${p.b.text}`,
+    );
+    return [
+        '# Neighbour contradiction review',
+        '',
+        'For each pair, decide whether A and B give an agent instructions that cannot both be followed.',
+        'Answer one line per pair, exactly `PAIR <n>: contradiction`, `PAIR <n>: compatible` or `PAIR <n>: unclear`,',
+        'then at most one sentence of reason on the same line. The rubric for which source wins is below; you do not',
+        'need to restate it.',
+        '',
+        '## Rubric — neighbour-precedence',
+        '',
+        rubric.trim(),
+        '',
+        '## Pairs',
+        '',
+        ...rows,
+        '',
+    ].join('\n');
+}
+
+/** Read `PAIR <n>: <verdict>` lines; a pair the seat did not answer is `unclear`. */
+export function parseVerdicts(text: string, count: number): Verdict[] {
+    const out: Verdict[] = Array.from({ length: count }, () => 'unclear');
+    for (const m of text.matchAll(/PAIR\s+(\d+)\s*:\s*(contradiction|compatible|unclear)/giu)) {
+        const n = Number(m[1]) - 1;
+        if (n >= 0 && n < count) out[n] = (m[2] ?? 'unclear').toLowerCase() as Verdict;
+    }
+    return out;
+}
+
+export interface ReviewRow {
+    pair: string;
+    verdict: Verdict;
+    wins: string;
+}
+
+/** The table, from pairs and a seat's verdicts. */
+export function reviewRows(pairs: readonly CandidatePair[], verdicts: readonly Verdict[]): ReviewRow[] {
+    return pairs.map((p, i) => ({
+        pair: `${p.a.label} "${p.a.text}" × ${p.b.label} "${p.b.text}"`,
+        verdict: verdicts[i] ?? 'unclear',
+        wins: winnerBy21(p),
+    }));
+}
+
+export function renderReview(rows: readonly ReviewRow[]): string[] {
+    if (rows.length === 0) return ['  no candidate pairs — nothing to review'];
+    return ['  pair | verdict | which wins by 2.1', ...rows.map((r) => `  ${r.pair} | ${r.verdict} | ${r.wins}`)];
+}

package/src/scripts/_lib/neighbour_scan.ts

@@ -0,0 +1,122 @@
+/**
+ * The shape scan a neighbour skill body passes before any of it may be indexed.
+ *
+ * SCAN BEFORE INJECT. A foreign `SKILL.md` is a file another package put on
+ * disk, and the ranker reaches it through the catalogue union. Nothing about
+ * being in `~/.claude/skills` makes its prose safe to fold into a term index
+ * whose output names skills to a model — the body is untrusted content in the
+ * sense `untrusted-input-defense` means it, and the floor here is the same one
+ * that rule states: it is data until something has looked at it.
+ *
+ * THE SHAPES ARE THE ONES THIS SUITE ALREADY SCANS ITS OWN CORPUS WITH. Four
+ * `security_lint` checks, reused as functions rather than re-implemented
+ * (decision D3 of the lane): instruction smuggling, hidden Unicode, mixed-script
+ * confusables and dangerous frontmatter. Re-declaring their patterns here would
+ * create a second copy to drift against the first, and the first is the one CI
+ * keeps honest.
+ *
+ * ANY FINDING REFUSES THE BODY — severity is NOT the discriminator. In the
+ * corpus linters, `HIGH` fails a build and `MED` warns, because the corpus is
+ * this package's own prose and a warning there is a maintainer's to weigh. A
+ * neighbour body is nobody's to weigh at rank time, and the cost of refusing is
+ * known and small: the skill still RANKS, by its name, with the finding kind
+ * printed. Risk-register row 4 is exactly this trade and resolves the same way —
+ * a shell snippet can be an installer skill's whole point, so the skill is never
+ * hidden, only un-indexed.
+ *
+ * WHY THIS IS NOT IMPORTED BY THE RANKER. It pulls four linter modules and,
+ * through one of them, `node:child_process`. The ranker runs inside the shared
+ * hook bundle on `user_prompt_submit`, where every byte is paid by every concern
+ * on every dispatch and `check_hook_bundle_composition` holds the ceiling. So
+ * the scan runs in the census CLI and its verdict reaches the ranker as a cached
+ * record — see `neighbour_census.scanVerdict`, where a missing record is a
+ * refusal rather than a pass.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as sl from './security_lint.js';
+import { fileDigest, type ScanCache, type ScanRecord } from './skill_origin.js';
+import { _scan as scanSmuggling } from '../lint_instruction_smuggling.js';
+import { _scan as scanHiddenUnicode } from '../lint_hidden_unicode.js';
+import { _scan as scanConfusables } from '../lint_confusables.js';
+import { _scan as scanFrontmatter } from '../lint_skill_frontmatter_safety.js';
+
+/** The shape checks, in the order their findings are reported. */
+const SHAPES: ReadonlyArray<readonly [string, (sf: sl.ScannedFile) => sl.Finding[]]> = [
+    ['instruction-smuggling', scanSmuggling],
+    ['dangerous-frontmatter', scanFrontmatter],
+    ['hidden-unicode', scanHiddenUnicode],
+    ['mixed-script-confusable', scanConfusables],
+];
+
+export interface ScanResult {
+    /** `null` when every shape passed; otherwise the first finding's check id. */
+    kind: string | null;
+    /** Every finding, for a report that wants more than the first kind. */
+    findings: sl.Finding[];
+}
+
+/**
+ * Scan one `SKILL.md`.
+ *
+ * An unreadable file is a refusal, not a pass (`unreadable`): a body nobody
+ * could open is in exactly the state this gate exists to keep out of the index,
+ * and returning `kind: null` for it would make an IO error look like a clean
+ * scan. A THROWING check is reported under its own id rather than swallowed, for
+ * the same reason.
+ */
+export function scanNeighbourBody(skillMdPath: string): ScanResult {
+    let sf: sl.ScannedFile;
+    try {
+        sf = sl.scan_file(skillMdPath);
+    } catch {
+        return { kind: 'unreadable', findings: [] };
+    }
+    const findings: sl.Finding[] = [];
+    for (const [id, scan] of SHAPES) {
+        try {
+            findings.push(...scan(sf));
+        } catch {
+            findings.push(
+                new sl.Finding(sf.rel, 0, id, 'HIGH', 'shape check threw on this body', 1.0),
+            );
+        }
+    }
+    return { kind: findings.length === 0 ? null : (findings[0] as sl.Finding).check, findings };
+}
+
+/**
+ * Record what the scan found, for the ranker to read on the hook path.
+ *
+ * The digest is the FILE's, not the finding's: the ranker re-digests the body it
+ * is about to index and compares, so a body edited after its scan reads as
+ * `digest-changed` and goes back to name-only ranking until the census runs
+ * again. That compare is the whole mechanism behind "a changed digest rescans
+ * first" — without it a one-time pass would keep clearing a file forever.
+ *
+ * A write failure is reported to the caller rather than thrown: the scan is
+ * correct either way, and a read-only report directory must not fail a census.
+ */
+export function writeScanCache(file: string, entries: readonly ScanRecord[]): boolean {
+    const payload: ScanCache = {
+        schema_version: 1,
+        entries: [...entries].sort((a, b) => (a.qualified < b.qualified ? -1 : 1)),
+    };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** A `ScanRecord` for one file, digest included. */
+export function scanRecordFor(qualified: string, skillMdPath: string): ScanRecord {
+    return {
+        qualified,
+        digest: fileDigest(skillMdPath) ?? '',
+        unscanned: scanNeighbourBody(skillMdPath).kind,
+    };
+}

package/src/scripts/_lib/neighbour_tool_use.ts

@@ -0,0 +1,187 @@
+/**
+ * The foreign-MCP-tool-name store: one writer on the post-tool hook path, one
+ * reader in the neighbour census.
+ *
+ * WHY A MODULE OF ITS OWN, AND NOT A CONSTANT IN EITHER SIDE. The writer lives
+ * in `hooks/mcp_usage_observation_hook.ts`, which is inlined into the shared hook
+ * bundle `check_hook_bundle_composition` caps; the reader lives in
+ * `_lib/neighbour_census.ts`, which is not. Putting the pair here lets esbuild
+ * tree-shake {@link toolsUsedByServer} out of the hook bundle while both sides
+ * still name one path — a constant copied into two files is a store that
+ * silently splits in two the first time one copy is edited.
+ *
+ * WHAT IS RECORDED, AND WHAT IS NOT. One map of `mcp__<server>__<tool>` to the
+ * ISO date it was last seen. No arguments, no responses, no session id, no
+ * project path beyond the file's own location. The names recorded are names the
+ * consumer's own `.mcp.json` already lists, and the file is written under
+ * `agents/runtime/`, which is gitignored and local-only — nothing here is sent
+ * anywhere, and no transport reads it.
+ *
+ * NOT GATED ON THE TELEMETRY OPT-IN, DELIBERATELY. `telemetry_usage_hook`'s
+ * Class-A capture is default-off because it feeds an outbound spool. This store
+ * feeds `doctor neighbours`, a local report the consumer runs on their own tree.
+ * Gating it on an org telemetry switch would make the census print `0` on every
+ * install that never enabled one — a number that looks like a measurement and is
+ * an instrumentation artifact, which is the exact failure the usage hook's own
+ * header records from the collector it replaced.
+ *
+ * GROWTH, DECLARED (scale-discipline R-A7). The store is a map keyed by tool
+ * NAME, not an append log: one entry per distinct `mcp__…` name the consumer
+ * has ever called, each rewritten in place at most once per day. The bound is
+ * therefore the size of the neighbour's tool surface — tens of entries, not a
+ * series — so it needs no TTL job. The reader applies the window; entries older
+ * than it stay on disk and stop counting, which is why a stale entry is inert
+ * rather than wrong.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Host-side prefix of every MCP tool name: `mcp__<server>__<tool>`. */
+export const MCP_TOOL_PREFIX = 'mcp__';
+
+/**
+ * The store, relative to the project root. Gitignored; see the header.
+ *
+ * A literal with forward slashes rather than `path.join`, and the reason is
+ * measured rather than stylistic: `path.join` here is a top-level call, so the
+ * `node:path` namespace import survives into the hook bundle even though every
+ * function in this module that needs it is tree-shaken out of that bundle.
+ * `path.join(root, REL)` at each call site normalises the separator on Windows,
+ * so the only thing lost is the authoring convention.
+ */
+export const FOREIGN_TOOL_USE_REL = 'agents/runtime/neighbour-tool-use.json';
+
+/** The census window. 30 days, matching the step that asked for the number. */
+export const TOOL_USE_WINDOW_DAYS = 30;
+
+/** The filename the writer's root is the directory of. */
+const SETTINGS_FILENAME = '.agent-settings.yml';
+
+/** `YYYY-MM-DD` in UTC — the granularity the store keys on. */
+export function usageDay(now: Date): string {
+    return now.toISOString().slice(0, 10);
+}
+
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/u;
+
+/**
+ * Is this store value a day the window comparison can be trusted on?
+ *
+ * The comparison is lexicographic, which is exactly right for `YYYY-MM-DD` and
+ * quietly wrong for anything else: `'TODO'`, `'unknown'` and `'hand edited'`
+ * all sort ABOVE a real cutoff, so without this check a hand-edited or
+ * half-written store inflates the count instead of being ignored. The reader's
+ * promise is that a malformed store yields nothing, and a malformed VALUE is
+ * the likelier half of that.
+ */
+export function isUsageDay(value: unknown): value is string {
+    return typeof value === 'string' && DAY_RE.test(value);
+}
+
+/**
+ * The `.mcp.json` key as it appears inside a tool name.
+ *
+ * Hosts sanitise the key before embedding it — a server registered as
+ * `claude.ai Claude Docs` arrives as `mcp__claude_ai_Claude_Docs__…`. Normalising
+ * BOTH sides the same way is what keeps a matched count from quietly being a
+ * zero: an exact-key match would report `0` for every server whose name carries
+ * a dot or a space, which reads as "never used" rather than as "never matched".
+ */
+export function serverSegment(key: string): string {
+    return key.replace(/[^A-Za-z0-9_-]/gu, '_');
+}
+
+/**
+ * Does `tool` belong to the server whose sanitised key is `segment`?
+ *
+ * Driven by the KNOWN segment rather than by parsing the tool name, and that
+ * direction is the whole correctness argument. Parsing — split at the first
+ * `__` after the prefix — is ambiguous exactly where {@link serverSegment} is
+ * lossy: `Acme Inc. Tools` sanitises to `Acme_Inc__Tools`, whose own name
+ * contains the separator, so a parser reads the server as `Acme_Inc` and the
+ * census reports `0` for a server in daily use. That is the same never-matched
+ * zero `serverSegment` exists to prevent, reintroduced one layer down. Matching
+ * against the keys `.mcp.json` actually lists cannot be ambiguous, because the
+ * candidate set is finite and known.
+ */
+export function toolBelongsTo(tool: string, segment: string): boolean {
+    if (!tool.startsWith(MCP_TOOL_PREFIX)) return false;
+    const rest = tool.slice(MCP_TOOL_PREFIX.length);
+    return rest === segment || rest.startsWith(`${segment}__`);
+}
+
+/**
+ * The directory the store lives under, from any directory inside the project.
+ *
+ * Both the writer and the reader call this one function, so the store is
+ * rooted at the directory holding `.agent-settings.yml` on both sides: a
+ * session started in a subdirectory would otherwise scatter one store per
+ * directory, and a monorepo with settings at the repo root and `.mcp.json`
+ * under `packages/web` would read `0` for a server in daily use. A fixture
+ * still pins the two sides equal end to end.
+ *
+ * No settings file on any ancestor → `start`.
+ */
+export function resolveStoreRoot(start: string): string {
+    let dir = path.resolve(start);
+    for (;;) {
+        try {
+            if (fs.statSync(path.join(dir, SETTINGS_FILENAME)).isFile()) return dir;
+        } catch {
+            // Not here — keep walking.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.resolve(start);
+        dir = parent;
+    }
+}
+
+/**
+ * Distinct tools seen per server inside the window, keyed by server segment.
+ *
+ * `segments` is the closed candidate set — the sanitised `.mcp.json` keys. Every
+ * one of them appears in the result, so a server with no sightings reads `0`
+ * rather than being absent. Longest segment wins where one is a prefix of
+ * another, so a tool is counted once.
+ *
+ * A missing, unreadable or malformed store yields all-zero — true of what was
+ * observed. It does not mean the server was unused, and the census says so next
+ * to the number.
+ */
+export function toolsUsedByServer(
+    projectRoot: string,
+    now: Date,
+    segments: Iterable<string>,
+): Map<string, number> {
+    const known = [...new Set(segments)].sort((a, b) => b.length - a.length);
+    const counts = new Map<string, number>(known.map((s) => [s, 0]));
+    if (known.length === 0) return counts;
+
+    let decoded: unknown;
+    try {
+        const root = resolveStoreRoot(projectRoot);
+        decoded = JSON.parse(fs.readFileSync(path.join(root, FOREIGN_TOOL_USE_REL), 'utf-8'));
+    } catch {
+        return counts;
+    }
+    if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) return counts;
+
+    const today = usageDay(now);
+    // Inclusive of both ends, so the span is WINDOW days and not WINDOW+1: a
+    // floor computed at `now - 30d` would count 31 distinct days under a field
+    // named `tools_used_30d`.
+    const floor = usageDay(new Date(now.getTime() - (TOOL_USE_WINDOW_DAYS - 1) * 86_400_000));
+
+    for (const [tool, seen] of Object.entries(decoded as Record<string, unknown>)) {
+        // A future date is as much a sign of a bad write as a malformed one,
+        // and without the upper bound a single `9999-01-01` counts forever.
+        if (!isUsageDay(seen) || seen < floor || seen > today) continue;
+        for (const segment of known) {
+            if (toolBelongsTo(tool, segment)) {
+                counts.set(segment, (counts.get(segment) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    return counts;
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -41,6 +41,50 @@
  * over-filtering would silently stop pinning real prompts, which is worse.
  * Measured across 1 540 user-role entries: 509 open at character zero with a
  * marker, and in 0 of them does human text survive wrapper removal.
+ *
+ * `<agent-message` added 2026-10-03, by the same under-filtering it warns
+ * about: a subagent hand-back reaches this slot as `<agent-message from="…">`,
+ * and 12 of the 153 hook-sourced user records in this project's capture open
+ * with it. It pinned a German session to `en`, after which the turn-end gate
+ * refused each German reply — a reply language derived from a frame nobody
+ * typed. Its literal stops before the `>` because the element carries an
+ * attribute; the anchor at character zero is unchanged.
+ *
+ * **The fourth shape has NO envelope tag, and it is the exception this file's
+ * own "structural, not linguistic" rule has to name rather than quietly break.**
+ * The host resumes a rate-limited session with a plain sentence —
+ * `Your claude.ai usage limit has reset. Continue the task you were working
+ * on…` — carrying no element, no bracket and no stamp. 5 of the 153
+ * hook-sourced user records in this project's capture open with it. Measured
+ * 2026-10-03: it pinned a German session to `en` with `prompt_chars: 148`,
+ * which is that sentence's exact length, and every German reply for the rest
+ * of the run was then refused by the turn-end gate as wrong-language.
+ *
+ * Matching prose is what the paragraph above warns against, so what makes this
+ * one admissible is stated rather than assumed: it is a FIXED host string, not
+ * a linguistic pattern, and the character-zero anchor does the same work a tag
+ * would — a human asking *why did I get "Your claude.ai usage limit has
+ * reset"* does not open with it. A test pins that direction. If the host ever
+ * reworded the sentence this guard would silently stop matching, which is the
+ * honest failure mode: it under-filters back to today's behaviour rather than
+ * misfiring on a real turn.
+ *
+ * It is deliberately NOT added to `machine_wake.ts`. There the same
+ * misclassification retains an authorization instead of mis-pinning a reply,
+ * and a prose match is too weak a warrant for that consequence — see the
+ * asymmetry note below, which this is the first real test of.
+ *
+ * **A SECOND VOCABULARY ANSWERS THIS SAME QUESTION AND THE TWO HAVE DRIFTED.**
+ * `_lib/machine_wake.ts`'s `humanTypedThisTurn` guards per-turn STATE on this
+ * 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
+ * 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
+ * `<local-command-caveat>` in particular precedes a real typed prompt. Unify
+ * them only with that asymmetry answered, never as tidying.
  */
 export function isSyntheticPrompt(prompt: string): boolean {
   const head = prompt.trimStart().slice(0, 400);
@@ -49,6 +93,8 @@ export function isSyntheticPrompt(prompt: string): boolean {
     head.startsWith("<task-notification>") ||
     head.startsWith("<system-reminder>") ||
     head.startsWith("<local-command-caveat>") ||
+    head.startsWith("<agent-message") ||
+    head.startsWith("Your claude.ai usage limit has reset") ||
     /^\[SYSTEM NOTIFICATION\b/.test(head)
   );
 }