@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/arrival_record.ts

@@ -0,0 +1,217 @@
+/**
+ * The per-session arrival record: which instruction files the host loaded, and
+ * why, built from the `InstructionsLoaded` observer's lines.
+ *
+ * It is the observable predicate of the activation ladder's `visible` rung for
+ * standing rules — no new state vocabulary. A record is `visible` only when
+ * every line of its session reads cleanly; any anomaly makes the whole record
+ * `unknown`, which the layer-form decision reads as "no arrival record", so a
+ * doubtful session can only ever keep a machine full.
+ *
+ * Anomalies, each of which yields `unknown` rather than an arrival:
+ *   · no line for the session — the host did not send the event;
+ *   · a line the observer could not classify — a malformed payload;
+ *   · the same file loaded twice for the same reason — a duplicate call;
+ *   · no `session_start` load at all — the start-up events were lost;
+ *   · more than one host version within one session.
+ *
+ * ORDER IS NOT EVIDENCE, IN EITHER DIRECTION. The host runs these hooks
+ * asynchronously and in parallel, so the order lines reach disk is the
+ * scheduler's, not the host's. The record is therefore built as a set: a
+ * reordered sequence yields exactly the record the ordered one does, and no
+ * ordering can create an arrival the set does not contain.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { ActivationReceipt } from './activation_ladder.js';
+import type { ArrivalEvidence } from './layer_form_decision.js';
+import { isSessionFile, type CaptureLine } from './instructions_loaded_event.js';
+import {
+    LOAD_REASONS,
+    classifyCapture,
+    type LoadReason,
+    type LoadedLine,
+    type ObserverLine,
+} from './instructions_loaded_classify.js';
+
+export type ArrivalUnknownReason =
+    | 'event-unavailable'
+    | 'malformed'
+    | 'duplicate-events'
+    | 'no-session-start'
+    | 'host-version-mixed';
+
+export interface ArrivalFile {
+    readonly file: string;
+    readonly kind: LoadedLine['kind'];
+    readonly scope: LoadedLine['scope'];
+    readonly reason: LoadReason;
+}
+
+export interface ArrivalRecord {
+    readonly v: 1;
+    readonly session: string;
+    readonly host_version: string | null;
+    readonly launch: string | null;
+    /** Every line was written by a concern the dispatcher ran, so any line means it was reached. */
+    readonly dispatcher_reached: boolean;
+    readonly status: 'visible' | 'unknown';
+    readonly unknown_reason: ArrivalUnknownReason | null;
+    readonly files: readonly ArrivalFile[];
+    readonly counts: { readonly loaded: number; readonly unknown: number; readonly duplicates: number };
+}
+
+/** Parse every session file under the observer directory; lines that are not observer lines are dropped. */
+export function readObserverLines(dir: string): ObserverLine[] {
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).filter(isSessionFile);
+    } catch {
+        return [];
+    }
+    const out: ObserverLine[] = [];
+    for (const f of names) {
+        let text = '';
+        try {
+            text = fs.readFileSync(path.join(dir, f), 'utf8');
+        } catch {
+            // Pruned between the listing and the read; the other sessions still count.
+            continue;
+        }
+        for (const raw of text.split('\n')) {
+            if (!raw.trim()) continue;
+            try {
+                const o = JSON.parse(raw) as CaptureLine;
+                if (o && o.v === 2) out.push(classifyCapture(o));
+            } catch {
+                // A torn line is skipped; it carries no session to attribute it to.
+            }
+        }
+    }
+    return out;
+}
+
+/** Build one session's record. `lines` may hold every session; only `session`'s are read. */
+export function buildArrivalRecord(lines: readonly ObserverLine[], session: string): ArrivalRecord {
+    const mine = lines.filter((l) => l.session === session);
+    const loaded = mine.filter((l): l is LoadedLine => l.event === 'loaded');
+    const unknownCount = mine.length - loaded.length;
+    const seen = new Set<string>();
+    let duplicates = 0;
+    const files: ArrivalFile[] = [];
+    for (const l of loaded) {
+        const key = `${l.scope}:${l.file}:${l.reason}`;
+        if (seen.has(key)) {
+            duplicates += 1;
+            continue;
+        }
+        seen.add(key);
+        files.push({ file: l.file, kind: l.kind, scope: l.scope, reason: l.reason });
+    }
+    const versions = new Set(mine.map((l) => l.host_version));
+    let reason: ArrivalUnknownReason | null = null;
+    if (mine.length === 0) reason = 'event-unavailable';
+    else if (unknownCount > 0) reason = 'malformed';
+    else if (duplicates > 0) reason = 'duplicate-events';
+    else if (versions.size > 1) reason = 'host-version-mixed';
+    else if (!loaded.some((l) => l.reason === 'session_start')) reason = 'no-session-start';
+    return {
+        v: 1,
+        session,
+        host_version: mine[0]?.host_version ?? null,
+        launch: mine[0]?.launch ?? null,
+        dispatcher_reached: mine.length > 0,
+        status: reason === null ? 'visible' : 'unknown',
+        unknown_reason: reason,
+        files,
+        counts: { loaded: loaded.length, unknown: unknownCount, duplicates },
+    };
+}
+
+/** The record of the most recent session in the file, or `null` when the file holds none. */
+export function latestArrivalRecord(lines: readonly ObserverLine[]): ArrivalRecord | null {
+    let latest: ObserverLine | null = null;
+    for (const l of lines) {
+        if (l.session === null) continue;
+        if (latest === null || l.ts >= latest.ts) latest = l;
+    }
+    return latest?.session ? buildArrivalRecord(lines, latest.session) : null;
+}
+
+const RECORD_KEYS = ['v', 'session', 'host_version', 'launch', 'dispatcher_reached', 'status', 'unknown_reason', 'files', 'counts'];
+const FILE_KEYS = ['file', 'kind', 'scope', 'reason'];
+const COUNT_KEYS = ['loaded', 'unknown', 'duplicates'];
+const NAME_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+function extraKeys(o: Record<string, unknown>, allowed: readonly string[], at: string): string[] {
+    return Object.keys(o).filter((k) => !allowed.includes(k)).map((k) => `${at}: field \`${k}\` is not part of the record`);
+}
+
+/**
+ * Validate a record against its closed shape. A field the shape does not name —
+ * a body, a prompt, a path — is an error, because the record exists to carry
+ * names, counts and enums and nothing a host could fill with content.
+ */
+export function validateArrivalRecord(value: unknown): string[] {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return ['record is not an object'];
+    const o = value as Record<string, unknown>;
+    const errs = extraKeys(o, RECORD_KEYS, 'record');
+    if (o['v'] !== 1) errs.push('record: `v` must be 1');
+    if (typeof o['session'] !== 'string' || !NAME_RE.test(o['session'])) errs.push('record: `session` must be an id');
+    if (o['status'] !== 'visible' && o['status'] !== 'unknown') errs.push('record: `status` must be visible or unknown');
+    if (!Array.isArray(o['files'])) errs.push('record: `files` must be an array');
+    else {
+        for (const [i, f] of (o['files'] as unknown[]).entries()) {
+            if (typeof f !== 'object' || f === null) {
+                errs.push(`files[${String(i)}]: not an object`);
+                continue;
+            }
+            const fo = f as Record<string, unknown>;
+            errs.push(...extraKeys(fo, FILE_KEYS, `files[${String(i)}]`));
+            if (typeof fo['file'] !== 'string' || !NAME_RE.test(fo['file'])) errs.push(`files[${String(i)}]: \`file\` must be a basename`);
+            if (!(LOAD_REASONS as readonly unknown[]).includes(fo['reason'])) errs.push(`files[${String(i)}]: unknown \`reason\``);
+        }
+    }
+    const c = o['counts'];
+    if (typeof c !== 'object' || c === null) errs.push('record: `counts` must be an object');
+    else errs.push(...extraKeys(c as Record<string, unknown>, COUNT_KEYS, 'counts'));
+    return errs;
+}
+
+/** User-scope rule files loaded at session start, by rule id. */
+function startupRuleIds(record: ArrivalRecord): Set<string> {
+    return new Set(
+        record.files
+            .filter((f) => f.kind === 'rule' && f.scope === 'user' && f.reason === 'session_start')
+            .map((f) => f.file.replace(/\.md$/, '')),
+    );
+}
+
+/**
+ * What the layer-form decision needs from a record, or `null` when the record
+ * cannot serve as evidence. `standingLaws` is the rule-id set that must have
+ * loaded at session start — the consequence class.
+ */
+export function arrivalEvidence(record: ArrivalRecord | null, standingLaws: ReadonlySet<string>): ArrivalEvidence | null {
+    if (record === null || record.status !== 'visible' || record.host_version === null) return null;
+    const loaded = startupRuleIds(record);
+    return {
+        hostVersion: record.host_version,
+        stubsLoaded: loaded.size > 0,
+        standingLawsLoaded: [...standingLaws].every((id) => loaded.has(id)),
+    };
+}
+
+/** Map a record onto the ladder's `visible` rung, one receipt per expected rule. */
+export function arrivalReceipts(record: ArrivalRecord, expected: readonly string[]): ActivationReceipt[] {
+    const loaded = startupRuleIds(record);
+    return expected.map((id) => ({
+        artefact: id,
+        rungs: record.status === 'visible' ? { visible: loaded.has(id) ? 'reached' : 'not-reached' } : {},
+    }));
+}
+
+export function arrivalsDirUnder(runtimeRoot: string): string {
+    return path.join(runtimeRoot, 'arrivals');
+}

package/src/scripts/_lib/asset_render_record.ts

@@ -0,0 +1,247 @@
+/**
+ * The asset render, as a `post_tool_use` hook SAW it finish.
+ *
+ * WHY A RECORD, AND NOT A BETTER READING OF THE TRANSCRIPT. The turn-end gate
+ * used to accept a digest-matching manifest when a render naming the file ran
+ * after the edit, and voided the manifests when a recognised write touched the
+ * render directory. "Recognised" was a command pattern list, so any write route
+ * the list did not know — an unlisted interpreter, a script file, indirection
+ * through a variable — forged a manifest unseen. A transcript cannot close that,
+ * because it never sees what a command did.
+ *
+ * A `post_tool_use` hook sees the finished call and its exit status. So this
+ * module records, at the moment a standalone asset render finished, which file
+ * it read and the exact bytes of the manifest it left. The gate then accepts a
+ * manifest only when its CURRENT bytes still hash to that recorded digest. A
+ * manifest written by any other route — before the render, after it, or instead
+ * of it — either has no record or no longer matches one, whatever the route was.
+ *
+ * WHAT IS STILL TRUSTED, stated rather than implied. The command must be a
+ * standalone render (`isPureRender`) — a positive shape that fails closed, not a
+ * list of forbidden writes — so a chained `&& echo > manifest.json` records
+ * nothing. What is not enforced is that the `agent-config` the shell resolved is
+ * this package's binary: a PATH shim that exits 0 and writes a manifest would be
+ * recorded as a render. That is a forgery of the tool itself rather than of its
+ * output, and no hook reading the tool's result could tell the two apart. Nor is
+ * the recorder's own state file guarded: an agent that writes a forged
+ * `asset_renders` entry there with an edit tool has forged the hook, not the
+ * render, and that file is as trusted as every other record the gate reads.
+ *
+ * THE PATH MUST BE THE RENDER'S, NOT A GUESS AT IT. The record binds the
+ * manifest at the path this module computes, so a computed path that differs
+ * from the one the shell gave the CLI would bind a manifest the render never
+ * wrote (completion review, finding 1). Every argument must therefore be a
+ * plain word the shell cannot expand — no `$`, `~`, glob, escape or embedded
+ * space — and the manifest must name the same target and slug; anything else
+ * records nothing, which leaves the obligation open rather than discharged.
+ * One window stays open: the manifest is hashed when the render's
+ * `post_tool_use` event fires, not at the instant the render wrote it, so on a
+ * host that runs Bash calls in parallel a second call could rewrite the file in
+ * between and have its bytes recorded. That needs a concurrent write aimed at
+ * the moment of one specific render, and is stated rather than closed.
+ * The working directory comes from the host's `cwd` where the payload carries
+ * one (finding 2).
+ *
+ * Shared by the producer (`before_complete_hook.ts`) and the consumer
+ * (`hooks/svg_obligation.ts`), and by `ui:render` itself for the two facts the
+ * reader must agree with it on: where the manifest lands and which exit means
+ * "no renderer".
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { isAssetRenderCommand } from './verification_command.js';
+
+/** Where `ui:render` writes, relative to its project root. */
+export const RENDER_REL = path.join('agents', 'runtime', 'state', 'render');
+
+/**
+ * `--profile asset` with no renderer. Distinct from 1, which `ui:render` uses
+ * for an internal error, because "nothing rendered here" is a consumer's
+ * ordinary state and its manifest still carries the static witness.
+ */
+export const EXIT_RENDERER_ABSENT = 3;
+
+/**
+ * The exits that leave a manifest describing the file. 1 is excluded: a render
+ * that ran and failed, or was called wrong, is evidence of nothing.
+ */
+const RECORDED_EXITS: ReadonlySet<number> = new Set([0, EXIT_RENDERER_ABSENT]);
+
+/** The output directory name `ui:render` derives from its target. */
+export function renderSlug(target: string): string {
+    return (
+        target
+            .replace(/^https?:\/\//, '')
+            .replace(/[^a-z0-9]+/gi, '-')
+            .replace(/^-+|-+$/g, '')
+            .toLowerCase()
+            .slice(0, 60) || 'render'
+    );
+}
+
+/**
+ * A render call standing alone — no second command chained to it and no
+ * redirect — so its text cannot also carry a write. A leading `cd <dir> &&`,
+ * piping its output to a read-only filter, and folding stderr into stdout are
+ * allowed.
+ */
+export function isPureRender(command: string): boolean {
+    if (!isAssetRenderCommand(command)) return false;
+    const [head, ...pipes] = command.replace(/^\s*cd\s+[^;&|<>`$\n]+&&\s*/, '').replace(/\s\d?>&\d\b/g, ' ').replace(/\s2>\s*\/dev\/null\b/g, ' ').split('|');
+    if (/[;&<>`\n]|\$\(/.test(head ?? '')) return false;
+    return pipes.every((p) => /^\s*(tail|head|grep|jq|cat|less|wc)\b[^;&<>`|]*$/.test(p) && !/\$\(/.test(p));
+}
+
+export interface AssetRenderRecord {
+    /** The rendered file, relative to the recorder's root, forward slashes. */
+    readonly file: string;
+    readonly file_digest: string;
+    /** The manifest the render left, relative to the recorder's root. */
+    readonly manifest: string;
+    /** sha256 of the manifest's bytes as the render left them. */
+    readonly manifest_digest: string;
+    readonly exit_code: number;
+}
+
+/**
+ * A render the hook saw finish without a readable exit status. Not evidence
+ * either way: its presence sends the gate back to the transcript rule, the
+ * same instrument-gap reading the turn-end gate's other detectors apply.
+ */
+export interface AssetRenderGap {
+    readonly instrument_gap: true;
+    readonly command: string;
+}
+
+/** Does a state value carry a render the host reported no exit for? */
+export function hasInstrumentGap(raw: readonly unknown[]): boolean {
+    return raw.some((r) => typeof r === 'object' && r !== null && (r as Record<string, unknown>)['instrument_gap'] === true);
+}
+
+/** `ui:render` options that take a value, so their value is not the target. */
+const VALUE_OPTIONS = new Set([
+    '--project-root',
+    '--slug',
+    '--profile',
+    '--class',
+    '--delivery',
+    '--thresholds',
+    '--icon-set',
+    '--compare',
+    '--registration',
+]);
+
+const sha256 = (bytes: Buffer): string => crypto.createHash('sha256').update(bytes).digest('hex');
+const unquote = (t: string): string => t.replace(/^['"]|['"]$/g, '');
+/** A word the shell passes through unchanged, optionally in matching quotes. */
+const PLAIN_WORD = /^(['"]?)[A-Za-z0-9._/:=@+,%-]+\1$/;
+const slashed = (p: string): string => p.split(path.sep).join('/');
+
+/**
+ * The render a finished Bash call performed, or `null`.
+ *
+ * Reproduces the CLI's own resolution — target against `--project-root` (else
+ * the call's working directory), slug from `--slug` (else the target) — so the
+ * manifest read is the one that render wrote, not one found by search.
+ * `shellCwd` is the host's report of the call's working directory, when it
+ * sends one; without it the call is assumed to start at `root`.
+ */
+export function observeAssetRender(
+    root: string,
+    command: string,
+    exitCode: number | null,
+    shellCwd: string = root,
+): AssetRenderRecord | AssetRenderGap | null {
+    if (!isPureRender(command)) return null;
+    if (exitCode === null) return { instrument_gap: true, command: command.slice(0, 512) };
+    if (!RECORDED_EXITS.has(exitCode)) return null;
+    const cd = /^\s*cd\s+([^;&|<>`$\n]+?)\s*&&/.exec(command);
+    if (cd && !PLAIN_WORD.test(cd[1]!.trim())) return null;
+    const cwd = path.resolve(shellCwd, cd ? unquote(cd[1]!.trim()) : '.');
+    const head =
+        command
+            .replace(/^\s*cd\s+[^;&|<>`$\n]+&&\s*/, '')
+            .replace(/\s\d?>&\d\b/g, ' ')
+            .replace(/\s2>\s*\/dev\/null\b/g, ' ')
+            .split('|')[0] ?? '';
+    const words = head.trim().split(/\s+/);
+    // One word the shell could rewrite and the computed path is a guess.
+    if (!words.every((w) => PLAIN_WORD.test(w))) return null;
+    const tokens = words.map(unquote);
+    const at = tokens.findIndex((t) => t === 'ui:render');
+    if (at === -1) return null;
+
+    const opts = new Map<string, string>();
+    let target: string | undefined;
+    for (let i = at + 1; i < tokens.length; i += 1) {
+        const t = tokens[i]!;
+        const eq = t.indexOf('=');
+        if (t.startsWith('--') && eq !== -1) {
+            opts.set(t.slice(0, eq), t.slice(eq + 1));
+        } else if (VALUE_OPTIONS.has(t)) {
+            opts.set(t, tokens[i + 1] ?? '');
+            i += 1;
+        } else if (!t.startsWith('-') && target === undefined) {
+            target = t;
+        }
+    }
+    if (target === undefined) return null;
+
+    const projectRoot = path.resolve(cwd, opts.get('--project-root') ?? '.');
+    const fileAbs = path.resolve(projectRoot, target);
+    const slug = opts.get('--slug') ?? renderSlug(target);
+    const manifestAbs = path.join(projectRoot, RENDER_REL, slug, 'manifest.json');
+    try {
+        const manifestBytes = fs.readFileSync(manifestAbs);
+        const m = JSON.parse(manifestBytes.toString('utf8')) as { target?: unknown; slug?: unknown };
+        // The manifest must describe THIS call — a leftover from another
+        // target or slug at the same path is not its output.
+        if (m.target !== target || m.slug !== slug) return null;
+        return {
+            file: slashed(path.relative(root, fileAbs)),
+            file_digest: sha256(fs.readFileSync(fileAbs)),
+            manifest: slashed(path.relative(root, manifestAbs)),
+            manifest_digest: sha256(manifestBytes),
+            exit_code: exitCode,
+        };
+    } catch {
+        // No file or no manifest: the render left nothing to bind, so nothing
+        // is recorded — the same verdict as a render that never ran.
+        return null;
+    }
+}
+
+/** The well-formed records in a state value, dropping anything else. */
+export function readAssetRenderRecords(raw: readonly unknown[]): AssetRenderRecord[] {
+    return raw.filter((r): r is AssetRenderRecord => {
+        if (typeof r !== 'object' || r === null) return false;
+        const o = r as Record<string, unknown>;
+        return ['file', 'file_digest', 'manifest', 'manifest_digest'].every((k) => typeof o[k] === 'string');
+    });
+}
+
+/**
+ * The manifest a record vouches for, parsed, or a reason it no longer does.
+ *
+ * `changed` is the forgery case this module exists for: the manifest's bytes
+ * moved after the render the hook saw finish.
+ */
+export function recordedManifest(
+    root: string,
+    record: AssetRenderRecord,
+): { manifest: unknown } | { changed: true } | null {
+    let bytes: Buffer;
+    try {
+        bytes = fs.readFileSync(path.resolve(root, record.manifest));
+    } catch {
+        return null;
+    }
+    if (sha256(bytes) !== record.manifest_digest) return { changed: true };
+    try {
+        return { manifest: JSON.parse(bytes.toString('utf8')) as unknown };
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/billing_grant.ts

@@ -15,7 +15,8 @@
  * produces: the git-guard grant expired after 30 minutes, so a drain outliving
  * its own grant re-asked mid-run — which is the interruption this whole
  * mechanism exists to remove. So the TTL here is the RUN, and `revoke` is
- * called from the path that already clears run-continuation state. A wall
+ * called from the path that cleared run-continuation state while that concern
+ * existed. A wall
  * clock appears only as a backstop for a run that died without cleaning up.
  *
  * Transport is an env var (`AC_BILLING_GRANT`) plus a file under
@@ -121,7 +122,8 @@ export function hasBillingGrant(
 /**
  * Remove the grant for `runId`. Safe to call when none exists.
  *
- * Called from `run_continuation_hook.clearRunState` — the one place a run is
+ * Called from `run_continuation_hook.clearRunState` until that concern was
+ * withdrawn (road-to-what-was-built-and-never-ran Phase 4); it was the one place a run was
  * declared over, and therefore the grant's real TTL. `clearRunState` is
  * exported for that reason: reaching it through the concern chain would mean
  * standing up the whole dispatch harness to assert one unlink.