@event4u/agent-config 16.1.0 → 16.2.0

package/src/scripts/_lib/llm_proposer_transport.ts

@@ -37,6 +37,7 @@
  */
 
 import { load_anthropic_key } from '../ai_council/clients.js';
+import { sanitize_text } from './retrieval_sanitize.js';
 import type {
     GenerationRequest,
     GenerationResult,
@@ -140,10 +141,19 @@ export function anthropicGenerator(keyPath: string | null = null): TextGenerator
             );
         }
         const data = (await resp.json()) as AnthropicResponse;
-        const text = (data.content ?? [])
-            .filter((b) => b.type === 'text')
-            .map((b) => b.text ?? '')
-            .join('');
+        // Sanitize AT THE TRANSPORT, which is the choke point and one call site.
+        // A flag every caller has to remember is the instruction-only
+        // enforcement this package diagnoses in itself, and a partially
+        // sanitized world — some callers filtered, some not — is worse than
+        // either end state. The floor is a no-op on ordinary text, so what
+        // changes here is only a response that carries a hidden-instruction
+        // vector; see `docs/contracts/retrieval-read-surfaces.md`.
+        const text = sanitize_text(
+            (data.content ?? [])
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join(''),
+        );
         // An empty body is returned AS an empty body rather than repaired here.
         // The arm's own output contract refuses it and classifies the refusal;
         // repairing it in the transport would move a decision into the layer

package/src/scripts/_lib/obligations.ts

@@ -44,7 +44,9 @@ import {
     session_state_file,
     update_json_under_lock,
 } from '../hooks/state_io.js';
+import { manifest_path } from './installed_tools.js';
 import { type EnforcementClass, is_enforcement_class } from './obligation_frequency.js';
+import { hasSentinel } from './repo_root.js';
 
 /**
  * Directory holding one ledger file per session.
@@ -61,6 +63,77 @@ export function statePathFor(session_id: string): string {
     return session_state_file(OBLIGATION_STATE_DIR, session_id);
 }
 
+/**
+ * WHICH KIND OF TREE WROTE A ROW — the whole vocabulary, and nothing else.
+ *
+ * `obligation-settle-shadow-bar` is read off `agents/runtime/state/obligations/`,
+ * which is one machine's gitignored runtime state. That scope bound lives in the
+ * claim's prose and in a roadmap paragraph, and in nothing a reader of the rows
+ * can compute. A reading that clears the pre-registered floor would therefore be
+ * quotable as evidence about a population nobody separated. This field makes the
+ * separation a property of the DATA, so the split is computable from the ledger
+ * alone rather than asserted beside it.
+ *
+ * THREE VALUES, CLOSED, AND A UNION OF LITERALS ON PURPOSE. The record gains one
+ * enumerated field and no `payload`, `notes` or `extra` slot, so the privacy
+ * property is the SHAPE and not a scrubber somebody has to keep correct — the
+ * same by-construction posture `artifact-engagement-recording` states for the
+ * telemetry event. A type that cannot hold a path cannot leak one.
+ *
+ * WHAT IT DELIBERATELY IS NOT. Not a path, not a username, not a hostname, not a
+ * machine id, not a git remote. The obvious implementation of "which tree wrote
+ * this" is the resolved root's filesystem path, which on a developer machine
+ * carries an account name — and because the bar is read by QUOTING rows, one such
+ * field would make every row already written unquotable rather than scrubbable.
+ * So the field carries a ROLE: what kind of tree this is, never which one.
+ */
+export type WriterRole =
+    /** The tree carries this package's own `package.json` sentinel — a maintainer checkout. */
+    | 'package'
+    /** Not the package, but an install manifest is present — a consumer project. */
+    | 'consumer'
+    /** Neither marker resolved. An honest absence, never a default. */
+    | 'unknown';
+
+/** The closed set, in one place, so a reader and a writer cannot disagree. */
+export const WRITER_ROLES: readonly WriterRole[] = ['package', 'consumer', 'unknown'];
+
+/** Narrowing guard for a value read back off disk. */
+export function isWriterRole(value: unknown): value is WriterRole {
+    return typeof value === 'string' && (WRITER_ROLES as readonly string[]).includes(value);
+}
+
+/**
+ * Classify the root this ledger lives under.
+ *
+ * ORDER IS THE CONTRACT. `package` is tested FIRST, because a maintainer checkout
+ * routinely also carries the install artifacts a consumer has — this repository
+ * installs itself — and a consumer-first test would label the maintainer tree
+ * `consumer` on exactly the machine the bar is being read from. The sentinel is
+ * `hasSentinel` from `repo_root.ts` rather than a second `package.json` reader:
+ * the sentinel name lives in one place or it drifts.
+ *
+ * `consumer` keys on the INSTALL MANIFEST (`agents/installed-tools.lock`, via the
+ * canonical `manifest_path` so the `AGENT_CONFIG_INSTALLED_TOOLS` override is
+ * honoured) and not on `.agent-settings.yml`. The settings file is something a
+ * human writes by hand; the lock is written by the installer and by nothing else.
+ * A weaker marker would buy coverage by guessing, which is the one thing this
+ * field may not do.
+ *
+ * NEVER THROWS. A probe that cannot stat returns `unknown`, which is a real
+ * answer — the ledger's contract is that an instrument missing a reading is
+ * cheaper than a refused turn, and a classifier is no exception.
+ */
+export function resolveWriterRole(root: string): WriterRole {
+    try {
+        if (hasSentinel(root)) return 'package';
+        if (fs.existsSync(manifest_path(root))) return 'consumer';
+    } catch {
+        return 'unknown';
+    }
+    return 'unknown';
+}
+
 /**
  * One rule delivered into this session, with the class its frontmatter declares.
  *
@@ -75,8 +148,21 @@ export interface DeliveredRow {
     readonly cls: EnforcementClass;
     /** ISO-8601, second precision. */
     readonly at: string;
+    /** Which kind of tree wrote this. Stamped here, never supplied — see {@link WriterInput}. */
+    readonly writer: WriterRole;
 }
 
+/**
+ * What a CALLER offers, for every row type: the stored shape minus its writer.
+ *
+ * The writer is stamped by the append functions from the `root` they were
+ * already given, and is deliberately not part of any caller's input. A caller
+ * that could supply it could supply the wrong one — and a provenance field a
+ * caller can set is a provenance field, not provenance. Making it unsettable is
+ * cheaper than any check that it was set correctly.
+ */
+export type WriterInput<T> = Omit<T, 'writer'>;
+
 /**
  * One obligation discharged this session.
  *
@@ -92,6 +178,8 @@ export interface DischargeRow {
     /** What observed it — a concern name, so a reader can go and check. */
     readonly by: string;
     readonly at: string;
+    /** Which kind of tree wrote this. Stamped, never supplied. */
+    readonly writer: WriterRole;
 }
 
 /**
@@ -109,6 +197,14 @@ export interface ShadowRow {
     readonly attempt: number;
     /** Always true today: a row is only written when the detector would refuse. */
     readonly would_refuse: boolean;
+    /**
+     * Which kind of tree wrote this. Stamped, never supplied.
+     *
+     * The shadow array is the one the pre-registered bar actually counts, so
+     * this is the field that turns "the corpus is one machine" from a sentence
+     * in a claim into something a reader can compute off the rows.
+     */
+    readonly writer: WriterRole;
 }
 
 /** The on-disk shape of one session's ledger. */
@@ -125,10 +221,11 @@ interface SerialisedRow {
     rule: string;
     class: string;
     at: string;
+    writer: WriterRole;
 }
 
 function serialise(row: DeliveredRow): SerialisedRow {
-    return { rule: row.rule, class: row.cls, at: row.at };
+    return { rule: row.rule, class: row.cls, at: row.at, writer: row.writer };
 }
 
 /**
@@ -139,6 +236,16 @@ function serialise(row: DeliveredRow): SerialisedRow {
  * whose class is outside the closed set must not enter the ledger wearing a
  * value the vocabulary denies — `is_enforcement_class` is the gate, so a
  * future widening of the schema cannot leak in through the state file.
+ *
+ * THE WRITER IS TREATED THE OTHER WAY ROUND, and the asymmetry is deliberate. A
+ * row whose CLASS is outside the vocabulary is dropped, because the class is the
+ * row's subject matter and a row wearing a denied class is a false statement
+ * about what was delivered. A row whose WRITER is absent or unrecognised is KEPT
+ * and reads `unknown`, because the writer is provenance ABOUT a delivery that
+ * genuinely happened — dropping the row would destroy a real record to punish a
+ * missing label, and every row written before this field existed is exactly that
+ * case. `unknown` is the honest reading of both, which is why one value covers
+ * absent and unresolvable alike.
  */
 export function parseRows(loaded: unknown): DeliveredRow[] {
     if (typeof loaded !== 'object' || loaded === null) return [];
@@ -154,7 +261,8 @@ export function parseRows(loaded: unknown): DeliveredRow[] {
         if (typeof rule !== 'string' || rule === '') continue;
         if (typeof at !== 'string' || at === '') continue;
         if (!is_enforcement_class(cls)) continue;
-        out.push({ rule, cls, at });
+        const writer = e['writer'];
+        out.push({ rule, cls, at, writer: isWriterRole(writer) ? writer : 'unknown' });
     }
     return out;
 }
@@ -185,13 +293,14 @@ export function stamp(now: Date = new Date()): string {
 export function appendDelivered(
     root: string,
     session_id: string,
-    rows: readonly DeliveredRow[],
+    rows: readonly WriterInput<DeliveredRow>[],
 ): number {
     if (rows.length === 0) return 0;
     if (is_replay_mode()) return 0;
     if (session_id.trim() === '') return 0;
 
     const target = path.join(root, statePathFor(session_id));
+    const writer = resolveWriterRole(root);
     let added = 0;
     try {
         update_json_under_lock<LedgerFile>(target, (loaded) => {
@@ -201,7 +310,7 @@ export function appendDelivered(
             for (const row of rows) {
                 if (seen.has(row.rule)) continue;
                 seen.add(row.rule);
-                merged.push(serialise(row));
+                merged.push(serialise({ ...row, writer }));
                 added += 1;
             }
             if (added === 0) return null; // deliberate no-write
@@ -245,24 +354,25 @@ function carryOver(loaded: Partial<LedgerFile>): Pick<LedgerFile, 'discharged' |
 export function appendDischarge(
     root: string,
     session_id: string,
-    rows: readonly DischargeRow[],
+    rows: readonly WriterInput<DischargeRow>[],
 ): number {
     if (rows.length === 0) return 0;
     if (is_replay_mode()) return 0;
     if (session_id.trim() === '') return 0;
 
     const target = path.join(root, statePathFor(session_id));
+    const writer = resolveWriterRole(root);
     let added = 0;
     try {
         update_json_under_lock<LedgerFile>(target, (loaded) => {
             const existing = Array.isArray(loaded.discharged) ? loaded.discharged : [];
-            const key = (r: DischargeRow): string => `${r.rule}::${r.by}`;
+            const key = (r: WriterInput<DischargeRow>): string => `${r.rule}::${r.by}`;
             const seen = new Set(existing.map(key));
             const merged = [...existing];
             for (const row of rows) {
                 if (seen.has(key(row))) continue;
                 seen.add(key(row));
-                merged.push(row);
+                merged.push({ ...row, writer });
                 added += 1;
             }
             if (added === 0) return null;
@@ -320,6 +430,7 @@ export function appendShadow(
 
     const fingerprint = [...missing].sort().join('::');
     const target = path.join(root, statePathFor(session_id));
+    const writer = resolveWriterRole(root);
     let attempt = 0;
     try {
         update_json_under_lock<LedgerFile>(target, (loaded) => {
@@ -334,7 +445,7 @@ export function appendShadow(
                 discharged: Array.isArray(loaded.discharged) ? loaded.discharged : [],
                 shadow: [
                     ...existing,
-                    { at: now, missing: [...missing], attempt, would_refuse: true },
+                    { at: now, missing: [...missing], attempt, would_refuse: true, writer },
                 ],
             };
         });

package/src/scripts/_lib/probe_inputs.ts

@@ -0,0 +1,271 @@
+/**
+ * `probe_inputs` — what the UI-conformance probe read, in a form its reader can
+ * re-check without starting a browser.
+ *
+ * `ui-conformance.json` recorded `generated_at` and nothing about its inputs, so
+ * a probe run before the last UI edit was indistinguishable from one run after
+ * it. This module is the shared vocabulary that closes that: the probe writes an
+ * `inputs` block with a content digest per input, and the design-pass reader
+ * recomputes those digests and compares. ONE definition, imported by both sides,
+ * because a producer and a consumer with separate copies of a hash rule agree
+ * only until one of them is edited.
+ *
+ * DIGESTS, NOT MTIMES, AND THAT IS THE WHOLE DECISION (D1). The reader already
+ * applies an mtime rule to the ui-audit artefact, and reusing it here was the
+ * obvious move. It answers the wrong question: an mtime moves on a checkout, a
+ * `cp -p`-less copy, or a bare `touch`, so it would report movement on turns
+ * where no byte changed — and a reader who learns to ignore a false stale has
+ * learned to ignore a real one. A content digest reports exactly what is being
+ * asked: are the bytes the probe saw still the bytes on disk?
+ *
+ * THE TARGET DIGEST IS A TREE DIGEST, and this is the one place the roadmap's
+ * own text needed correcting. A UI surface is an entry document plus the styles
+ * and scripts beside it; a digest of `index.html` alone would be blind to a CSS
+ * edit, which is the single most common UI change there is — and the roadmap's
+ * own verify line for step 1.1 names exactly that case. So the record covers the
+ * directory the entry document sits in. It costs a small recursive read the
+ * probe does not otherwise perform (the browser, not Node, opens `styles.css`),
+ * which is a real cost the roadmap's Risk 3 mitigation did not anticipate. It is
+ * bounded: a few small text files against a run that launches Chromium and
+ * reloads the page dozens of times per node.
+ *
+ * NO BROWSER IS REACHABLE FROM HERE. This module imports `node:crypto`,
+ * `node:fs` and `node:path` and nothing else, which is what lets the hook decide
+ * staleness on a host with no browser binaries installed.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Schema of the `inputs` block. A reader that does not know it says unknown. */
+export const INPUTS_SCHEMA = 'ui-conformance-inputs/v1';
+
+/**
+ * The probe build that wrote the block. Bumped when a change to the probe makes
+ * an older artefact's findings incomparable with a newer run's; a reader seeing
+ * a value it does not know reports unknown rather than guessing.
+ */
+export const PROBE_VERSION = 'ui-conformance-probe/v1';
+
+/** The sibling file the probe reads for declared, approved deviations. */
+export const DECLARATIONS_BASENAME = 'conformance.declared.json';
+
+/**
+ * Bound on a tree digest. A surface directory is a handful of files; anything
+ * past this is a checkout root someone pointed the probe at by mistake, and
+ * hashing it would cost more than the probe run. Exceeding it is recorded as
+ * absent with a reason — never silently truncated, which would produce a digest
+ * that looks authoritative and covers an arbitrary subset.
+ */
+export const MAX_TREE_FILES = 2000;
+
+/** Directories never worth digesting, and ruinous to walk. */
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+export const INPUT_KEYS = ['target', 'reference', 'declarations'] as const;
+export type InputKey = (typeof INPUT_KEYS)[number];
+
+export interface InputRecord {
+    /**
+     * What was digested — a directory for `tree`, a file for `file`. `null` only
+     * when no path was supplied at all, which is itself recorded rather than
+     * omitted.
+     */
+    path: string | null;
+    kind: 'tree' | 'file';
+    /** `absent` carries a reason and a null digest. Never an omitted key. */
+    state: 'read' | 'absent';
+    /** `sha256:<hex>` when read, `null` when absent. */
+    digest: string | null;
+    /** Files folded into a tree digest. Absent on a `file` record. */
+    files?: number;
+    reason?: string;
+}
+
+export interface ProbeInputs {
+    schema: string;
+    probe: string;
+    target: InputRecord;
+    reference: InputRecord;
+    declarations: InputRecord;
+}
+
+const sha256 = (data: Buffer | string): string => `sha256:${createHash('sha256').update(data).digest('hex')}`;
+
+const why = (err: unknown): string => {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    return code ? String(code) : String(err);
+};
+
+/**
+ * The ONE definition of where a target's declarations file lives. The probe's
+ * CLI computed this inline; a second copy here would be a rule that agrees with
+ * the probe only until one of the two is edited.
+ */
+export function declarationsPathFor(targetEntryFile: string): string {
+    return path.join(path.dirname(targetEntryFile), DECLARATIONS_BASENAME);
+}
+
+/** Digest one file. Never throws — an unreadable input is a recorded fact. */
+export function digestFile(file: string | null, whenNull = 'no path was supplied'): InputRecord {
+    if (!file) return { path: null, kind: 'file', state: 'absent', digest: null, reason: whenNull };
+    try {
+        return { path: file, kind: 'file', state: 'read', digest: sha256(fs.readFileSync(file)) };
+    } catch (err) {
+        return { path: file, kind: 'file', state: 'absent', digest: null, reason: `unreadable: ${why(err)}` };
+    }
+}
+
+/**
+ * Digest a directory as one value: every file under it, sorted by relative path,
+ * folded path-and-content into a single hash. Sorted because a directory listing
+ * order is a filesystem detail, and a digest that moved with it would report
+ * movement nobody made.
+ *
+ * `exclude` drops names recorded as inputs in their own right — the declarations
+ * file — so an edit to it moves exactly one digest rather than two.
+ */
+export function digestTree(
+    dir: string | null,
+    exclude: readonly string[] = [],
+    whenNull = 'no path was supplied',
+): InputRecord {
+    if (!dir) return { path: null, kind: 'tree', state: 'absent', digest: null, reason: whenNull };
+    const skip = new Set(exclude);
+    const found: string[] = [];
+
+    const walk = (rel: string): string | null => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true });
+        } catch (err) {
+            return `unreadable: ${why(err)}`;
+        }
+        for (const e of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+            const child = rel ? `${rel}/${e.name}` : e.name;
+            if (rel === '' && skip.has(e.name)) continue;
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name)) continue;
+                const failed = walk(child);
+                if (failed) return failed;
+                continue;
+            }
+            if (!e.isFile()) continue;
+            found.push(child);
+            if (found.length > MAX_TREE_FILES) {
+                return `directory holds more than ${MAX_TREE_FILES} files — too large to digest`;
+            }
+        }
+        return null;
+    };
+
+    const failure = walk('');
+    if (failure) return { path: dir, kind: 'tree', state: 'absent', digest: null, reason: failure };
+
+    const h = createHash('sha256');
+    for (const rel of found.sort()) {
+        let body: Buffer;
+        try {
+            body = fs.readFileSync(path.join(dir, rel));
+        } catch (err) {
+            return { path: dir, kind: 'tree', state: 'absent', digest: null, reason: `unreadable: ${why(err)}` };
+        }
+        // The path is folded in alongside the bytes, so a rename moves the digest
+        // even when the content is byte-identical.
+        h.update(rel).update('\0').update(body).update('\0');
+    }
+    return {
+        path: dir,
+        kind: 'tree',
+        state: 'read',
+        digest: `sha256:${h.digest('hex')}`,
+        files: found.length,
+    };
+}
+
+/**
+ * The block the probe writes beside `generated_at`. A target or reference is
+ * digested as the surface directory it belongs to; the declarations file is
+ * digested on its own.
+ */
+export function collectInputs(targetEntryFile: string | null, referenceEntryFile: string | null): ProbeInputs {
+    const dirOf = (f: string | null): string | null => (f ? path.dirname(f) : null);
+    return {
+        schema: INPUTS_SCHEMA,
+        probe: PROBE_VERSION,
+        target: digestTree(dirOf(targetEntryFile), [DECLARATIONS_BASENAME], 'no --target was supplied'),
+        reference: digestTree(
+            dirOf(referenceEntryFile),
+            [DECLARATIONS_BASENAME],
+            'no --reference was given; nothing was compared against',
+        ),
+        declarations: targetEntryFile
+            ? digestFile(declarationsPathFor(targetEntryFile))
+            : digestFile(null, 'no --target was supplied, so no declarations file was looked for'),
+    };
+}
+
+export type InputComparison =
+    | { verdict: 'unknown'; reason: string; moved: readonly InputKey[] }
+    | { verdict: 'unchanged'; moved: readonly InputKey[] }
+    | { verdict: 'moved'; moved: readonly InputKey[] };
+
+const isRecord = (v: unknown): v is InputRecord =>
+    typeof v === 'object' && v !== null && 'state' in (v as object) && 'kind' in (v as object);
+
+/**
+ * Re-read each recorded input and say whether it moved.
+ *
+ * THREE verdicts, and `unknown` is not a hedge. An artefact written before the
+ * `inputs` block existed has nothing to compare, and calling that `moved` would
+ * report stale for every pre-existing run on the first turn after this change —
+ * Risk 1 of the roadmap. It is a version skew, not evidence of movement, and it
+ * is equally not evidence of freshness.
+ *
+ * `resolve` maps a recorded path to this host's filesystem; the caller owns that
+ * because the probe records the path it was given and only the reader knows the
+ * root it is reading from.
+ */
+export function compareInputs(recorded: unknown, resolve: (p: string) => string): InputComparison {
+    if (typeof recorded !== 'object' || recorded === null) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: 'the artefact carries no inputs block — it predates the input digests',
+        };
+    }
+    const r = recorded as Partial<ProbeInputs>;
+    if (r.schema !== INPUTS_SCHEMA) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: `inputs schema ${String(r.schema)} is not ${INPUTS_SCHEMA} — this reader cannot compare it`,
+        };
+    }
+    if (r.probe !== PROBE_VERSION) {
+        return {
+            verdict: 'unknown',
+            moved: [],
+            reason: `written by ${String(r.probe)}, read by ${PROBE_VERSION} — findings across builds are not comparable`,
+        };
+    }
+
+    const moved: InputKey[] = [];
+    for (const key of INPUT_KEYS) {
+        const rec = r[key];
+        if (!isRecord(rec)) {
+            return {
+                verdict: 'unknown',
+                moved: [],
+                reason: `the inputs block carries no usable record for ${key}`,
+            };
+        }
+        // An input that was never supplied has nothing to move to or from.
+        if (rec.path === null) continue;
+        const here = rec.kind === 'tree'
+            ? digestTree(resolve(rec.path), [DECLARATIONS_BASENAME])
+            : digestFile(resolve(rec.path));
+        if (here.state !== rec.state || here.digest !== rec.digest) moved.push(key);
+    }
+    return moved.length ? { verdict: 'moved', moved } : { verdict: 'unchanged', moved: [] };
+}