@event4u/agent-config 14.22.0 → 14.23.0

package/src/scripts/_lib/session_index_trust.ts

@@ -0,0 +1,346 @@
+/**
+ * The trust contract for the session-start memory index.
+ *
+ * WHY THIS EXISTS, AND WHOSE RULING IT IMPLEMENTS.
+ *
+ * The `memory.session_index` block injects curated memory at `session_start`.
+ * Restored memory is UNTRUSTED CONTEXT arriving on an injection surface, and an
+ * AI council (2026-09-07, ruling D3, recorded in
+ * `road-to-continuity-writer-activation` step 3.1) required six properties —
+ * repository and worktree identity, path canonicalization, freshness, ordering,
+ * duplicate invocation and size limits — each with a test, BEFORE the restore
+ * moves off the `hot-context` concern. Five of the six did not exist: measured
+ * at HEAD, `session_memory_index.ts` implemented size limits only. This module
+ * is those six in one place, so the relocation has something to move.
+ *
+ * THE THREAT, STATED CONCRETELY RATHER THAN AS A CATEGORY.
+ *
+ * `MEMORY_ROOT` in `memory_lookup.ts` is the RELATIVE path `agents/memory`, so
+ * it resolves against the process cwd. The hook therefore chdirs to a workspace
+ * root it received from a host payload and reads memory from wherever that
+ * landed. Nothing checked that the root was the workspace the session belongs
+ * to, nothing resolved symlinks before trusting it, and nothing stopped a second
+ * `session_start` in one session from injecting the block twice. So the
+ * attacker this module answers is not an intruder: it is a wrong or stale root —
+ * a sibling checkout, a worktree pointed at another tree, a leftover directory,
+ * a symlink out of the workspace — serving another repository's curated memory
+ * into this session as though it were this repository's.
+ *
+ * WHAT IT DOES NOT CLAIM.
+ *
+ * It does not authenticate the memory's CONTENT. A curated entry that is wrong,
+ * or hostile, and sits at the correct path inside the correct workspace passes
+ * every property here — that is the review boundary of `agents/memory/`, not a
+ * check's. Nor does it make the index trustworthy in the sense that a model may
+ * act on it: the block stays spotlighted as DATA, per `untrusted-input-defense`,
+ * and this module bounds only WHICH bytes reach that block.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** P6 — the row cap. Owned here so all six properties read from one place. */
+export const SESSION_INDEX_ROW_CAP = 30;
+
+/**
+ * P3 — the abandonment bound, in days.
+ *
+ * A STATED DEFAULT, NOT A MEASURED OPTIMUM, said plainly because a number that
+ * looks derived and is not is worse than an admitted guess. Curated memory is
+ * deliberately long-lived — a stable `product-rules.yml` is not stale at 90
+ * days — so the bound is set well beyond any legitimate quiet period and exists
+ * to catch an ABANDONED root, not an inactive one. The two conditions that
+ * would falsify it are recorded in `road-to-continuity-writer-activation`
+ * step 3.1 rather than here.
+ */
+export const MAX_ROOT_AGE_DAYS = 400;
+
+/**
+ * Curated sources, matching the layouts `memory_lookup._iter_curated_entries`
+ * actually reads: `<root>/<type>.yml` AND `<root>/<type>/**\/*.yml`, plus the
+ * agent-written `intake/*.jsonl`. Reading only the first of those is what made
+ * P3 silently no-op on two of the three layouts — R2 finding 4.
+ */
+const CURATED_SUFFIXES = ['.yml', '.yaml', '.jsonl'] as const;
+
+/** Depth bound on the walk. A memory root is shallow; a cycle is not. */
+const MAX_WALK_DEPTH = 8;
+
+export type TrustRefusalCode =
+    | 'workspace-root-unresolvable'
+    | 'memory-root-absent'
+    | 'memory-root-escapes-workspace'
+    | 'curated-source-escapes-workspace'
+    | 'source-mtime-in-future'
+    | 'memory-root-abandoned'
+    | 'already-injected-this-session';
+
+export interface TrustRefusal {
+    readonly ok: false;
+    readonly code: TrustRefusalCode;
+    readonly detail: string;
+}
+
+export interface TrustGrant {
+    readonly ok: true;
+    /** Canonical, containment-checked absolute path to the memory root. */
+    readonly memoryRoot: string;
+    /** Canonical absolute path to the workspace the root was checked against. */
+    readonly workspaceRoot: string;
+    /** P3 — mtime of the newest curated source read, epoch ms; 0 when none. */
+    readonly newestSourceMs: number;
+}
+
+export type TrustVerdict = TrustGrant | TrustRefusal;
+
+function refuse(code: TrustRefusalCode, detail: string): TrustRefusal {
+    return { ok: false, code, detail };
+}
+
+/**
+ * P2 — canonicalize, then compare by SEGMENTS.
+ *
+ * A string prefix test says `/a/bc` is inside `/a/b`, which is how a
+ * containment check passes something it should refuse. Splitting on the
+ * separator makes the comparison mean what it says.
+ */
+export function isContained(child: string, parent: string): boolean {
+    const rel = path.relative(parent, child);
+    if (rel === '') return true;
+    if (path.isAbsolute(rel)) return false;
+    return !rel.split(path.sep).includes('..');
+}
+
+/** Canonicalize a path, following symlinks. `null` when it does not resolve. */
+export function canonical(p: string): string | null {
+    try {
+        return fs.realpathSync(p);
+    } catch {
+        return null;
+    }
+}
+
+export interface SourceWalk {
+    /** Newest mtime across every curated source read, epoch ms; 0 when none. */
+    readonly newestMs: number;
+    /** Sources whose canonical path lies outside the workspace. P1's other half. */
+    readonly escaped: readonly string[];
+    /** How many sources the walk actually read — 0 means "nothing to judge". */
+    readonly count: number;
+}
+
+/**
+ * One recursive walk serving P1's file half and P3's reading, because R2 found
+ * both defects in the same omission: the previous version read only `*.yml`
+ * directly at the root, which is one of the three layouts
+ * `memory_lookup._iter_curated_entries` supports. So freshness silently
+ * no-opped on a type-directory corpus (a 3-year-old one was served past the
+ * 400-day bound), and containment was never checked below the root at all.
+ *
+ * The containment half is the sharper of the two. Canonicalizing the ROOT does
+ * not stop a symlinked FILE inside it from resolving into another tree, and
+ * that is the exact threat this module's docblock names — proven by the
+ * reviewer, who read a donor workspace's entry out of a victim session.
+ *
+ * Per-entry timestamps do not exist (a curated entry is `{id, key, body}`), so
+ * freshness stays a property of the source files rather than something invented
+ * per row.
+ */
+export function walkCuratedSources(memoryRoot: string, workspaceRoot: string): SourceWalk {
+    let newestMs = 0;
+    let count = 0;
+    const escaped: string[] = [];
+
+    const visit = (dir: string, depth: number): void => {
+        if (depth > MAX_WALK_DEPTH) return;
+        let names: fs.Dirent[];
+        try {
+            names = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of names) {
+            const full = path.join(dir, ent.name);
+            // `withFileTypes` reports a symlink as a symlink, so a directory
+            // reached through one is followed only after it canonicalizes
+            // inside the workspace — which is the containment check itself.
+            const resolved = canonical(full);
+            if (resolved === null) continue;
+            if (!isContained(resolved, workspaceRoot)) {
+                escaped.push(full);
+                continue;
+            }
+            let st: fs.Stats;
+            try {
+                st = fs.statSync(resolved);
+            } catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                visit(resolved, depth + 1);
+                continue;
+            }
+            if (!CURATED_SUFFIXES.some((sfx) => ent.name.endsWith(sfx))) continue;
+            count += 1;
+            if (st.mtimeMs > newestMs) newestMs = st.mtimeMs;
+        }
+    };
+
+    visit(memoryRoot, 0);
+    return { newestMs, escaped, count };
+}
+
+export interface TrustInput {
+    /** The workspace root the session belongs to, as the host reported it. */
+    readonly workspaceRoot: string;
+    /** Relative memory root, matching `memory_lookup.MEMORY_ROOT`. */
+    readonly relativeMemoryRoot?: string;
+    /** Injected for tests; defaults to now. */
+    readonly now?: Date;
+}
+
+/**
+ * P1 + P2 + P3 — decide whether a memory root may be read at all.
+ *
+ * Ordered cheapest-first, and each refusal names itself: a caller that logs the
+ * code can tell "this workspace has no memory" from "this root pointed
+ * somewhere else", which is the distinction the whole module exists for.
+ */
+export function verifyMemoryRoot(input: TrustInput): TrustVerdict {
+    const now = input.now ?? new Date();
+    const rel = input.relativeMemoryRoot ?? path.join('agents', 'memory');
+
+    // P2 — the workspace root is canonicalized FIRST. Everything downstream
+    // compares against the resolved form, never the reported one.
+    const workspaceRoot = canonical(input.workspaceRoot);
+    if (workspaceRoot === null) {
+        return refuse('workspace-root-unresolvable', `workspace root does not resolve: ${input.workspaceRoot}`);
+    }
+
+    // P1 — identity, checked LEXICALLY first and on the canonical path second.
+    // The order is load-bearing and a test found it: a `..` root whose target
+    // does not exist would otherwise be reported as merely absent, which reads
+    // as "this workspace has no memory" when the truth is "this root pointed
+    // outside the tree". The escape is the more important fact, so it is the
+    // one reported, whether or not the target happens to exist.
+    const lexical = path.resolve(workspaceRoot, rel);
+    if (!isContained(lexical, workspaceRoot)) {
+        return refuse(
+            'memory-root-escapes-workspace',
+            `${lexical} is not inside ${workspaceRoot} — refusing to serve another tree's memory`,
+        );
+    }
+
+    const memoryRoot = canonical(lexical);
+    if (memoryRoot === null) {
+        return refuse('memory-root-absent', `no memory root at ${path.join(input.workspaceRoot, rel)}`);
+    }
+
+    // The second half of P1, and the half a lexical check cannot see: the path
+    // is inside the tree and the SYMLINK it resolves through is not.
+    if (!isContained(memoryRoot, workspaceRoot)) {
+        return refuse(
+            'memory-root-escapes-workspace',
+            `${memoryRoot} is not inside ${workspaceRoot} — refusing to serve another tree's memory`,
+        );
+    }
+
+    // P1's file half + P3, from one walk. R2 findings 3 and 4.
+    const walk = walkCuratedSources(memoryRoot, workspaceRoot);
+    if (walk.escaped.length > 0) {
+        return refuse(
+            'curated-source-escapes-workspace',
+            `${walk.escaped.length} curated source(s) resolve outside ${workspaceRoot}, first ${walk.escaped[0]} — refusing to serve another tree's memory`,
+        );
+    }
+
+    // P3 — freshness, in the two directions it can fail.
+    const newestSourceMs = walk.newestMs;
+    if (newestSourceMs > now.getTime() + 60_000) {
+        return refuse(
+            'source-mtime-in-future',
+            `newest curated source is dated in the future (${new Date(newestSourceMs).toISOString()}) — clock skew or tampering`,
+        );
+    }
+    if (newestSourceMs > 0) {
+        const ageDays = (now.getTime() - newestSourceMs) / 86_400_000;
+        if (ageDays > MAX_ROOT_AGE_DAYS) {
+            return refuse(
+                'memory-root-abandoned',
+                `newest curated source is ${ageDays.toFixed(0)}d old, past the ${MAX_ROOT_AGE_DAYS}d abandonment bound`,
+            );
+        }
+    }
+
+    return { ok: true, memoryRoot, workspaceRoot, newestSourceMs };
+}
+
+export interface OrderableRow {
+    readonly id: string;
+    readonly title: string;
+    readonly tokens_estimate: number;
+}
+
+/**
+ * P4 — the declared total order.
+ *
+ * Ordering is a trust property because the CAP truncates: without a declared
+ * order, which 30 of 200 entries reach the model is whatever the filesystem
+ * happened to yield, and two runs over the same tree can advertise different
+ * corpora. Cheapest row first (`tokens_estimate` ascending) so a fixed cap
+ * carries the most entries it can, with `id` ascending as the tie-break that
+ * makes the order TOTAL rather than merely defined — a comparator with ties is
+ * not deterministic under an unstable sort.
+ */
+export function orderRows<T extends OrderableRow>(rows: readonly T[]): T[] {
+    return [...rows].sort((a, b) => {
+        if (a.tokens_estimate !== b.tokens_estimate) return a.tokens_estimate - b.tokens_estimate;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+}
+
+/** P6 — apply the cap after ordering, never before. */
+export function capRows<T>(rows: readonly T[], cap: number = SESSION_INDEX_ROW_CAP): T[] {
+    const limit = Number.isFinite(cap) && cap > 0 ? Math.min(cap, SESSION_INDEX_ROW_CAP) : SESSION_INDEX_ROW_CAP;
+    return rows.slice(0, limit);
+}
+
+/** Where the P5 latch lives. Gitignored runtime state, one file per session. */
+export function latchPath(workspaceRoot: string, sessionId: string): string {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/gu, '_').slice(0, 128);
+    return path.join(workspaceRoot, 'agents', 'runtime', 'state', 'session-index-latch', `${safe}.json`);
+}
+
+/**
+ * P5 — duplicate invocation.
+ *
+ * `session_start` can fire more than once for one session (a resume, a
+ * host-side reconnect, a compaction boundary on some hosts). Two injections
+ * double the fixed cost and can present two different corpora as the same
+ * session's memory. The latch is create-exclusive (`wx`), so the FIRST caller
+ * wins and every later one refuses — an ordering that matters, because
+ * check-then-write would let two concurrent starts both pass.
+ *
+ * Fails OPEN on an unwritable state directory: a hook that cannot latch must
+ * still be able to serve the index once, and refusing there would make a
+ * read-only workspace lose the feature entirely. That is a deliberate trade and
+ * it is the reason this property is a latch rather than a gate.
+ */
+export function claimSessionOnce(workspaceRoot: string, sessionId: string): TrustVerdict | { ok: true } {
+    if (sessionId.length === 0) {
+        // No session id to key on — cannot latch, so do not pretend to.
+        return { ok: true };
+    }
+    const target = latchPath(workspaceRoot, sessionId);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, JSON.stringify({ claimed_at: new Date().toISOString() }), { flag: 'wx' });
+        return { ok: true };
+    } catch (exc) {
+        const code = (exc as { code?: string }).code;
+        if (code === 'EEXIST') {
+            return refuse('already-injected-this-session', `session ${sessionId} already received the index`);
+        }
+        // fail-open — see the docblock
+        return { ok: true };
+    }
+}

package/src/scripts/_lib/standing_bound_ratchet.ts

@@ -0,0 +1,154 @@
+/**
+ * The standing-payload bounds are shrink-only, checked against the base ref.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `src/config/preamble-payload-budget.json` says of its grace ceiling: *"It may
+ * never move UP."* `grace_ceiling_history` in the same file records it moving up
+ * twice — 138,212 → 138,273 on 2026-09-02 and 138,273 → 138,490 on 2026-09-08 —
+ * each with a careful prose justification. ADR-264 resolved that contradiction
+ * against the practice: the sentence stands, the two raises are violations caused
+ * by contradictory wording, and standing-rule growth needs a compensating
+ * reduction elsewhere.
+ *
+ * That decision then had no enforcement. A sentence in a JSON string is not a
+ * gate, and the file's own history is the evidence: nothing objected either time.
+ * This module is the enforcement — and it is the ONLY thing
+ * `road-to-a-standing-budget-with-headroom` step 1.3 ships, because the 128-token
+ * Iron Law reserve that step designed was refused by an AI council 2/2 on
+ * 2026-09-08. See ADR-265.
+ *
+ * WHAT IT CANNOT DO, STATED PLAINLY
+ * ---------------------------------
+ * The change under review can edit this file. Both council seats named that as
+ * the defect fatal to the reserve — "the checker, its imports, token census,
+ * workflow, and status context are all part of the trusted computing base", so a
+ * protected record read by an unprotected verifier grants nothing. It is fatal to
+ * a mechanism that GRANTS budget and it is not fatal to one that only REFUSES,
+ * which is the whole reason the reserve stayed unshipped and this ratchet did
+ * not: disabling this check requires visibly editing it, and every gate in this
+ * repository already rests on that same review. A ratchet whose only failure mode
+ * is "someone deleted the ratchet" is strictly better than the sentence it
+ * replaces, which had no failure mode because it did nothing.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Repo-relative path of the budget config the bound lives in. */
+export const BUDGET_CONFIG_PATH = 'src/config/preamble-payload-budget.json';
+
+/** Injection seam: run git, capture output, never throw on a non-zero exit. */
+export type GitRunner = (args: readonly string[], cwd: string) => {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+
+export const realGit: GitRunner = (args, cwd) => {
+    const r = spawnSync('git', [...args], { cwd, encoding: 'utf-8' });
+    return { ok: r.status === 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+
+export interface BoundsRatchetVerdict {
+    ok: boolean;
+    violations: string[];
+    /** The bound read at the base ref, or `null` when it could not be read. */
+    baseGraceCeiling: number | null;
+    /** The ref compared against, or `null` when none resolved. */
+    baseRef: string | null;
+    /** Why the comparison was skipped, when it was. Printed, never silent. */
+    note: string | null;
+}
+
+function showAtRef(git: GitRunner, repoRoot: string, ref: string, relPath: string): string | null {
+    const r = git(['show', `${ref}:${relPath}`], repoRoot);
+    return r.ok ? r.stdout : null;
+}
+
+/**
+ * Compare the grace ceiling in this tree against the one at the base ref.
+ *
+ * SKIPS rather than fails when the base ref or the base config cannot be read.
+ * That is the opposite of the fail-closed posture the same council demanded for
+ * the reserve, and the asymmetry is deliberate: an unreadable base there would
+ * have GRANTED budget on an infrastructure failure, whereas here it would REFUSE
+ * a change on one. A shallow clone, a first commit and a detached build all
+ * legitimately have no base, and a gate that reds on them gets switched off —
+ * which is how a repository loses the enforcement it just built. The skip is
+ * reported in both the human and JSON output so it cannot pass for a check.
+ */
+export function assertBoundsDidNotRise(opts: {
+    repoRoot: string;
+    baseRef: string | null;
+    git?: GitRunner;
+    /**
+     * The ceiling this run actually compares the payload against.
+     *
+     * The CI step passes `--ceiling <grace_ceiling>`, so the effective bound can
+     * be raised either by editing the config or by passing a bigger number. Both
+     * arrive here as one value, which closes the second path without a second
+     * check.
+     */
+    headGraceCeiling: number;
+}): BoundsRatchetVerdict {
+    const git = opts.git ?? realGit;
+    if (opts.baseRef === null || opts.baseRef.trim() === '') {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: null,
+            note: 'no base ref resolved, so the shrink-only bound was NOT verified in this run',
+        };
+    }
+    const cfg = showAtRef(git, opts.repoRoot, opts.baseRef, BUDGET_CONFIG_PATH);
+    if (cfg === null) {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `${BUDGET_CONFIG_PATH} could not be read at ${opts.baseRef}, so the shrink-only bound was NOT verified`,
+        };
+    }
+    let baseGrace: number | null = null;
+    try {
+        const parsed = JSON.parse(cfg) as Record<string, unknown>;
+        const delivery = (parsed['ci_delivery'] ?? {}) as Record<string, unknown>;
+        const n = Number(delivery['grace_ceiling']);
+        baseGrace = Number.isFinite(n) ? n : null;
+    } catch {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `${BUDGET_CONFIG_PATH} at ${opts.baseRef} is not parseable, so the shrink-only bound was NOT verified`,
+        };
+    }
+    if (baseGrace === null) {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `no ci_delivery.grace_ceiling at ${opts.baseRef}, so there is no earlier bound to ratchet against`,
+        };
+    }
+    if (opts.headGraceCeiling > baseGrace) {
+        return {
+            ok: false,
+            baseGraceCeiling: baseGrace,
+            baseRef: opts.baseRef,
+            note: null,
+            violations: [
+                `the standing-payload grace ceiling rose from ${String(baseGrace)} to ` +
+                    `${String(opts.headGraceCeiling)} against ${opts.baseRef}. ` +
+                    `${BUDGET_CONFIG_PATH} says it may not move upward and ADR-264 decided that ` +
+                    'the sentence stands: standing-rule growth needs a compensating reduction ' +
+                    'elsewhere, not a bigger ceiling. Lower the addition, migrate the prose out of ' +
+                    'the standing rule, or reduce another standing asset by the same amount.',
+            ],
+        };
+    }
+    return { ok: true, violations: [], baseGraceCeiling: baseGrace, baseRef: opts.baseRef, note: null };
+}