@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/brand_voice_slot.ts

@@ -0,0 +1,258 @@
+/**
+ * The `brand-voice` context-spine slot — the first slot whose frontmatter is
+ * machine-read (docs/contracts/adr-gtm-context-spine-brand-voice.md).
+ *
+ * Parses `agents/context-spine/brand-voice.md` and validates its frontmatter as
+ * DATA: a closed field set (no visual fields, so the slot cannot become a second
+ * token store), bounded lists, hidden-Unicode refusal anywhere in the file, and
+ * references restricted to repo-relative paths or URLs. Nothing here follows a
+ * sample or a reference; readers never execute slot content.
+ */
+import * as fs from 'node:fs';
+
+import { parse as parseYaml } from 'yaml';
+
+import { ALL_TELL_RULES } from '../ai_tells_rules.js';
+import { scanHiddenUnicode } from '../detect_ai_tells.js';
+
+export interface SlotIssue {
+    field: string;
+    message: string;
+}
+
+export interface AvoidEntry {
+    term: string;
+    match: 'word' | 'substring';
+    note?: string;
+}
+
+export interface ClaimEntry {
+    text: string;
+    evidence_ref: string;
+    expires?: string;
+}
+
+export interface BrandVoiceSlot {
+    version: number;
+    attributes: Array<{ is: string; is_not: string; proof: string }>;
+    tone_by_context?: Array<Record<string, unknown>>;
+    avoid?: AvoidEntry[];
+    claims?: ClaimEntry[];
+    tell_exemptions?: string[];
+    samples?: string[];
+    customer_language?: string[];
+    provenance: {
+        sources: Array<{ ref: string; tier: string }>;
+        confidence: 'low' | 'med' | 'high';
+        last_reviewed_at: string;
+    };
+    changelog?: string[];
+    open_questions?: Array<{ question: string; recommendation: string }>;
+}
+
+export const SLOT_FIELDS = [
+    'version',
+    'attributes',
+    'tone_by_context',
+    'avoid',
+    'claims',
+    'tell_exemptions',
+    'samples',
+    'customer_language',
+    'provenance',
+    'changelog',
+    'open_questions',
+] as const;
+export const SOURCE_TIERS = ['authoritative', 'operational', 'conversational', 'external-untrusted'] as const;
+export const MAX_AVOID = 32;
+export const MAX_TERM_CHARS = 64;
+export const MAX_SAMPLES = 3;
+export const MAX_SAMPLE_WORDS = 200;
+
+type Obj = Record<string, unknown>;
+
+const isObj = (v: unknown): v is Obj => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isText = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** YAML turns an unquoted 2026-10-01 into a Date; the slot stores the day. */
+function asDay(v: unknown): string | null {
+    if (v instanceof Date && !Number.isNaN(v.getTime())) return v.toISOString().slice(0, 10);
+    return typeof v === 'string' && DATE.test(v) ? v : null;
+}
+
+/** A repo-relative path or an http(s) URL — never absolute, never escaping the repository. */
+export function isSafeRef(ref: unknown): boolean {
+    if (!isText(ref)) return false;
+    if (/^https?:\/\/\S+$/.test(ref)) return true;
+    if (/^(?:[/\\~]|[A-Za-z]:)/.test(ref) || /^[a-z][a-z0-9+.-]*:/i.test(ref)) return false;
+    return !ref.split(/[/\\]/).includes('..');
+}
+
+function frontmatterOf(text: string): string | null {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    return m === null ? null : (m[1] as string);
+}
+
+/** Parse the slot's frontmatter. `data` is null when there is none or it is not a mapping. */
+export function parseBrandVoiceSlot(text: string): { data: Obj | null; issues: SlotIssue[] } {
+    const fm = frontmatterOf(text);
+    if (fm === null) return { data: null, issues: [{ field: 'frontmatter', message: 'no --- frontmatter block' }] };
+    let data: unknown;
+    try {
+        data = parseYaml(fm, { maxAliasCount: 0 });
+    } catch (exc) {
+        return { data: null, issues: [{ field: 'frontmatter', message: `not YAML: ${(exc as Error).message.split('\n')[0]}` }] };
+    }
+    if (!isObj(data)) return { data: null, issues: [{ field: 'frontmatter', message: 'not a mapping' }] };
+    return { data, issues: [] };
+}
+
+function stringList(v: unknown, field: string, issues: SlotIssue[]): void {
+    if (v === undefined) return;
+    if (!Array.isArray(v) || !v.every(isText)) issues.push({ field, message: 'must be a list of non-empty strings' });
+}
+
+/** Every schema and data-safety issue in a slot file's text. Empty means valid. */
+export function validateBrandVoiceSlotText(text: string): SlotIssue[] {
+    const issues: SlotIssue[] = [];
+    const hidden = scanHiddenUnicode(text);
+    if (hidden.length > 0) {
+        issues.push({
+            field: 'hidden-unicode',
+            message: hidden.map((h) => `${h.cls} ×${h.count} (${h.sample_codepoints.join(', ')})`).join('; '),
+        });
+    }
+    const { data, issues: parseIssues } = parseBrandVoiceSlot(text);
+    if (data === null) return [...parseIssues, ...issues];
+
+    for (const key of Object.keys(data)) {
+        if (!(SLOT_FIELDS as readonly string[]).includes(key)) {
+            issues.push({ field: key, message: `unknown field (allowed: ${SLOT_FIELDS.join(', ')})` });
+        }
+    }
+
+    if (!Number.isInteger(data['version']) || (data['version'] as number) < 1) {
+        issues.push({ field: 'version', message: 'must be a positive integer' });
+    }
+
+    const attrs = data['attributes'];
+    if (!Array.isArray(attrs) || attrs.length !== 3) {
+        issues.push({ field: 'attributes', message: 'must list exactly three {is, is_not, proof} attributes' });
+    }
+    const attrNames = new Set<string>();
+    (Array.isArray(attrs) ? attrs : []).forEach((a, i) => {
+        for (const k of ['is', 'is_not', 'proof']) {
+            if (!isObj(a) || !isText(a[k])) issues.push({ field: `attributes[${i}].${k}`, message: 'must be non-empty text' });
+        }
+        if (isObj(a) && isText(a['is'])) attrNames.add(a['is']);
+    });
+
+    const tone = data['tone_by_context'];
+    if (tone !== undefined && !Array.isArray(tone)) issues.push({ field: 'tone_by_context', message: 'must be a list' });
+    (Array.isArray(tone) ? tone : []).forEach((t, i) => {
+        for (const k of ['context', 'audience_state', 'lead_attribute']) {
+            if (!isObj(t) || !isText(t[k])) issues.push({ field: `tone_by_context[${i}].${k}`, message: 'must be non-empty text' });
+        }
+        if (isObj(t) && isText(t['lead_attribute']) && attrNames.size > 0 && !attrNames.has(t['lead_attribute'])) {
+            issues.push({ field: `tone_by_context[${i}].lead_attribute`, message: 'must name one of the attributes' });
+        }
+        if (isObj(t)) {
+            stringList(t['amplify'], `tone_by_context[${i}].amplify`, issues);
+            stringList(t['mute'], `tone_by_context[${i}].mute`, issues);
+        }
+    });
+
+    const avoid = data['avoid'];
+    if (avoid !== undefined && (!Array.isArray(avoid) || avoid.length > MAX_AVOID)) {
+        issues.push({ field: 'avoid', message: `must be a list of at most ${MAX_AVOID} entries` });
+    }
+    (Array.isArray(avoid) ? avoid : []).forEach((a, i) => {
+        const term = isObj(a) ? a['term'] : undefined;
+        if (typeof term !== 'string' || term.trim().length === 0 || [...term].length > MAX_TERM_CHARS) {
+            issues.push({ field: `avoid[${i}].term`, message: `must be 1-${MAX_TERM_CHARS} characters of literal text` });
+        }
+        if (!isObj(a) || (a['match'] !== 'word' && a['match'] !== 'substring')) {
+            issues.push({ field: `avoid[${i}].match`, message: 'must be word or substring (no regex)' });
+        }
+        if (isObj(a) && a['note'] !== undefined && typeof a['note'] !== 'string') {
+            issues.push({ field: `avoid[${i}].note`, message: 'must be text' });
+        }
+    });
+
+    const claims = data['claims'];
+    if (claims !== undefined && !Array.isArray(claims)) issues.push({ field: 'claims', message: 'must be a list' });
+    (Array.isArray(claims) ? claims : []).forEach((c, i) => {
+        if (!isObj(c) || !isText(c['text'])) issues.push({ field: `claims[${i}].text`, message: 'must be non-empty text' });
+        if (!isObj(c) || !isSafeRef(c['evidence_ref'])) {
+            issues.push({ field: `claims[${i}].evidence_ref`, message: 'must be a repo-relative path or an http(s) URL' });
+        }
+        if (isObj(c) && c['expires'] !== undefined && asDay(c['expires']) === null) {
+            issues.push({ field: `claims[${i}].expires`, message: 'must be a YYYY-MM-DD date' });
+        }
+    });
+
+    stringList(data['tell_exemptions'], 'tell_exemptions', issues);
+    const knownTells = new Set(ALL_TELL_RULES.map((r) => r.id));
+    (Array.isArray(data['tell_exemptions']) ? data['tell_exemptions'] : []).forEach((id, i) => {
+        if (typeof id === 'string' && !knownTells.has(id)) {
+            issues.push({ field: `tell_exemptions[${i}]`, message: 'not a tell id in the detector registry' });
+        }
+    });
+
+    const samples = data['samples'];
+    if (samples !== undefined && (!Array.isArray(samples) || samples.length > MAX_SAMPLES)) {
+        issues.push({ field: 'samples', message: `must be a list of at most ${MAX_SAMPLES} samples` });
+    }
+    (Array.isArray(samples) ? samples : []).forEach((s, i) => {
+        if (!isText(s)) issues.push({ field: `samples[${i}]`, message: 'must be non-empty text' });
+        else if (s.split(/\s+/).filter(Boolean).length > MAX_SAMPLE_WORDS) {
+            issues.push({ field: `samples[${i}]`, message: `must be at most ${MAX_SAMPLE_WORDS} words` });
+        }
+    });
+
+    stringList(data['customer_language'], 'customer_language', issues);
+    stringList(data['changelog'], 'changelog', issues);
+
+    const prov = data['provenance'];
+    if (!isObj(prov)) {
+        issues.push({ field: 'provenance', message: 'must be a mapping with sources, confidence, last_reviewed_at' });
+    } else {
+        const sources = prov['sources'];
+        if (!Array.isArray(sources)) issues.push({ field: 'provenance.sources', message: 'must be a list' });
+        (Array.isArray(sources) ? sources : []).forEach((s, i) => {
+            if (!isObj(s) || !isSafeRef(s['ref'])) {
+                issues.push({ field: `provenance.sources[${i}].ref`, message: 'must be a repo-relative path or an http(s) URL' });
+            }
+            if (!isObj(s) || !(SOURCE_TIERS as readonly unknown[]).includes(s['tier'])) {
+                issues.push({ field: `provenance.sources[${i}].tier`, message: `must be one of ${SOURCE_TIERS.join(', ')}` });
+            }
+        });
+        if (!['low', 'med', 'high'].includes(prov['confidence'] as string)) {
+            issues.push({ field: 'provenance.confidence', message: 'must be low, med or high' });
+        }
+        if (asDay(prov['last_reviewed_at']) === null) {
+            issues.push({ field: 'provenance.last_reviewed_at', message: 'must be a YYYY-MM-DD date' });
+        }
+    }
+
+    const questions = data['open_questions'];
+    if (questions !== undefined && !Array.isArray(questions)) issues.push({ field: 'open_questions', message: 'must be a list' });
+    (Array.isArray(questions) ? questions : []).forEach((q, i) => {
+        for (const k of ['question', 'recommendation']) {
+            if (!isObj(q) || !isText(q[k])) issues.push({ field: `open_questions[${i}].${k}`, message: 'must be non-empty text' });
+        }
+    });
+
+    return issues;
+}
+
+/** Read and validate a slot file; a missing file is the caller's question, not an issue. */
+export function validateBrandVoiceSlotFile(p: string): SlotIssue[] {
+    return validateBrandVoiceSlotText(fs.readFileSync(p, 'utf-8'));
+}
+
+/** The slot's day field, normalised (YAML may hand back a Date). */
+export function slotDay(v: unknown): string | null {
+    return asDay(v);
+}

package/src/scripts/_lib/canary_status.ts

@@ -0,0 +1,24 @@
+/**
+ * The cross-model canary's status line: present only while three or more
+ * scheduled runs in a row are red. The reader is kept apart from
+ * `canary_liveness.ts`, which shells out to `gh`, because the session-start
+ * concern that surfaces the line sits in the hook bundle.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const CANARY_RED_STREAK = 3;
+
+/** Gitignored runtime state; written by `canary_liveness.ts`. */
+export const CANARY_LIVENESS_RELPATH = path.join('agents', 'runtime', 'state', 'canary-liveness.json');
+
+/** The line, or null when the canary is not on a red streak or nothing was recorded. */
+export function readCanaryStatusLine(repoRoot: string): string | null {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(repoRoot, CANARY_LIVENESS_RELPATH), 'utf8')) as { line?: unknown };
+        return typeof raw.line === 'string' && raw.line !== '' ? raw.line : null;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/cc_transcript.ts

@@ -28,6 +28,7 @@
  * or differently-configured transcript could carry only one.
  */
 
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { homedir } from 'node:os';
@@ -470,3 +471,278 @@ export function aggregateByBucket(records: readonly TranscriptRecord[]): Record<
 
     return buckets;
 }
+
+/* -------------------------------------------------------------------------- */
+/* Tool results — what reached the model, per tool class                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One tool class's payload bytes, beside the host's hook envelope.
+ *
+ * Payload bytes are the text strings and base64 image data inside the
+ * `tool_result` block the model received. They are NOT the serialised block:
+ * `type`, `tool_use_id`, `is_error` and the JSON punctuation around them are
+ * excluded, so the figure understates the block by its structure and is not
+ * comparable byte-for-byte with the JSON-serialised envelope. A content member
+ * of any other kind is counted in `unsupported_members`, never as bytes.
+ *
+ * The two populations are never added together. The envelope is the
+ * transcript's `toolUseResult` — the same object the host hands a
+ * post_tool_use hook, which for Edit and Write carries the whole original file
+ * the model never sees.
+ */
+export interface ToolResultClass {
+    tool: string;
+    count: number;
+    payload_bytes: number;
+    /** Sum over results that carried an envelope; `null` when none did. */
+    envelope_bytes: number | null;
+    /** Results with no `toolUseResult` — not zero, not measured. */
+    envelope_missing: number;
+    /** Content members that are neither text nor base64 image — present, not measured. */
+    unsupported_members: number;
+    /** One payload byte count per result, for percentiles. */
+    payload_samples: number[];
+}
+
+export interface ToolResultScan {
+    classes: Record<string, ToolResultClass>;
+    /** Distinct tool results counted, after dedup by `tool_use_id`. */
+    results: number;
+}
+
+interface RawBlock {
+    type?: unknown;
+    id?: unknown;
+    name?: unknown;
+    tool_use_id?: unknown;
+    content?: unknown;
+    text?: unknown;
+    source?: { type?: unknown; data?: unknown };
+}
+
+function blocksOf(raw: { message?: { content?: unknown } }): RawBlock[] {
+    const c = raw.message?.content;
+    return Array.isArray(c) ? (c.filter((b) => typeof b === 'object' && b !== null) as RawBlock[]) : [];
+}
+
+interface Payload {
+    bytes: number;
+    image: boolean;
+    unsupported: number;
+}
+
+/** Payload bytes of one `tool_result` block — see {@link ToolResultClass}. */
+function payloadOf(block: RawBlock): Payload {
+    const c = block.content;
+    if (typeof c === 'string') return { bytes: Buffer.byteLength(c, 'utf8'), image: false, unsupported: 0 };
+    const out: Payload = { bytes: 0, image: false, unsupported: 0 };
+    if (!Array.isArray(c)) return out;
+    for (const item of c as unknown[]) {
+        const m = typeof item === 'object' && item !== null ? (item as RawBlock) : null;
+        if (m !== null && m.type === 'text' && typeof m.text === 'string') {
+            out.bytes += Buffer.byteLength(m.text, 'utf8');
+        } else if (m !== null && m.type === 'image' && m.source?.type === 'base64' && typeof m.source.data === 'string') {
+            out.image = true;
+            out.bytes += m.source.data.length;
+        } else {
+            out.unsupported += 1;
+        }
+    }
+    return out;
+}
+
+function readLines(file: string): string[] {
+    try {
+        return fs.readFileSync(file, 'utf-8').split('\n');
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Tool-result payload bytes per tool class, joined to the tool name by
+ * `tool_use_id`. Two passes over the file set — names first, results second —
+ * so a result whose `tool_use` sits in another file still joins. A result whose
+ * id joins nothing is counted under `unknown`, never dropped and never guessed.
+ * A Read that returned an image is its own class, `Read:image`: encoded image
+ * data dwarfs every text class and would otherwise hide them.
+ */
+export function scanToolResults(opts: ScanOptions = {}): ToolResultScan {
+    const files = listTranscriptFiles(opts);
+    const names = new Map<string, string>();
+    for (const file of files) {
+        for (const line of readLines(file)) {
+            if (!line.includes('"tool_use"')) continue;
+            const raw = parseLine(line);
+            if (!raw || raw.type !== 'assistant') continue;
+            for (const b of blocksOf(raw)) {
+                if (b.type === 'tool_use' && typeof b.id === 'string' && typeof b.name === 'string') names.set(b.id, b.name);
+            }
+        }
+    }
+
+    const classes: Record<string, ToolResultClass> = {};
+    const seen = new Set<string>();
+    for (const file of files) {
+        for (const line of readLines(file)) {
+            if (!line.includes('"tool_result"')) continue;
+            const raw = parseLine(line) as (RawAssistantRecord & { toolUseResult?: unknown }) | null;
+            if (!raw || raw.type !== 'user') continue;
+            const blocks = blocksOf(raw).filter((b) => b.type === 'tool_result' && typeof b.tool_use_id === 'string');
+            for (const block of blocks) {
+                const id = block.tool_use_id as string;
+                if (seen.has(id)) continue;
+                seen.add(id);
+                const { bytes, image, unsupported } = payloadOf(block);
+                const name = names.get(id) ?? 'unknown';
+                const tool = image ? `${name}:image` : name;
+                const cls = (classes[tool] ??= {
+                    tool,
+                    count: 0,
+                    payload_bytes: 0,
+                    envelope_bytes: null,
+                    envelope_missing: 0,
+                    unsupported_members: 0,
+                    payload_samples: [],
+                });
+                cls.count += 1;
+                cls.payload_bytes += bytes;
+                cls.unsupported_members += unsupported;
+                cls.payload_samples.push(bytes);
+                // One envelope per record: attributed only when the record holds one result.
+                const env = blocks.length === 1 ? raw.toolUseResult : undefined;
+                if (env === undefined || env === null) {
+                    cls.envelope_missing += 1;
+                } else {
+                    let envBytes: number | null = null;
+                    try {
+                        envBytes = Buffer.byteLength(typeof env === 'string' ? env : JSON.stringify(env), 'utf8');
+                    } catch {
+                        envBytes = null;
+                    }
+                    if (envBytes === null) cls.envelope_missing += 1;
+                    else cls.envelope_bytes = (cls.envelope_bytes ?? 0) + envBytes;
+                }
+            }
+        }
+    }
+    return { classes, results: seen.size };
+}
+
+/**
+ * One tool result, not a class sum: what a classifier that looks at the call
+ * needs. `command` is kept for Bash only — every other input (a Write's whole
+ * file, an Edit's strings) would cost memory no caller reads.
+ */
+export interface ToolResultRecord {
+    tool: string;
+    command: string | null;
+    bytes: number;
+    /** The result record's `timestamp`, or null when absent. */
+    timestamp: string | null;
+    /**
+     * The transcript file, relative to the scanned directory, without `.jsonl` — one
+     * model context. Never the record's `sessionId`: a subagent transcript carries
+     * its parent's, but the parent's reads were never in the subagent's context.
+     */
+    session: string;
+    /** A `Read` call's `file_path`, else null. */
+    path: string | null;
+    /** A ranged `Read` as `offset+limit` (either side may be empty), null for a full read or another tool. */
+    range: string | null;
+    /** sha256 over the result's text payload; null for an image or a result with no text. */
+    digest: string | null;
+    /** A PreToolUse hook attachment for this call carried a `reread_guard_hook` advisory line. */
+    advised: boolean;
+}
+
+/** The prefix every `reread_guard_hook` advisory line starts with (pinned by a test against its builders). */
+export const REREAD_ADVISORY = 're-read guard: ';
+
+function textOf(block: RawBlock): string | null {
+    const c = block.content;
+    if (typeof c === 'string') return c;
+    if (!Array.isArray(c)) return null;
+    let text = '';
+    for (const item of c as unknown[]) {
+        const m = typeof item === 'object' && item !== null ? (item as RawBlock) : null;
+        if (m === null) continue;
+        if (m.type === 'image') return null;
+        if (m.type === 'text' && typeof m.text === 'string') text += m.text;
+    }
+    return text;
+}
+
+function rangeOf(input: Record<string, unknown>): string | null {
+    const part = (v: unknown): string => (typeof v === 'number' || typeof v === 'string' ? String(v) : '');
+    const offset = part(input['offset']);
+    const limit = part(input['limit']);
+    return offset === '' && limit === '' ? null : `${offset}+${limit}`;
+}
+
+function advisedCalls(line: string): string | null {
+    const raw = parseLine(line) as { attachment?: { toolUseID?: unknown; hookEvent?: unknown; stdout?: unknown } } | null;
+    const a = raw?.attachment;
+    if (a?.hookEvent !== 'PreToolUse' || typeof a.toolUseID !== 'string' || typeof a.stdout !== 'string') return null;
+    return a.stdout.includes(REREAD_ADVISORY) ? a.toolUseID : null;
+}
+
+/** Per-result view of {@link scanToolResults}: same join, same dedup by `tool_use_id`, same `:image` split. */
+export function scanToolResultRecords(opts: ScanOptions = {}): ToolResultRecord[] {
+    const files = listTranscriptFiles(opts);
+    const root = opts.root ?? DEFAULT_PROJECTS_ROOT;
+    const base = opts.projectDir ? path.resolve(root, opts.projectDir) : root;
+    const calls = new Map<string, { name: string; command: string | null; path: string | null; range: string | null }>();
+    const advised = new Set<string>();
+    for (const file of files) {
+        for (const line of readLines(file)) {
+            if (line.includes('"attachment"') && line.includes(REREAD_ADVISORY)) {
+                const id = advisedCalls(line);
+                if (id !== null) advised.add(id);
+                continue;
+            }
+            if (!line.includes('"tool_use"')) continue;
+            const raw = parseLine(line);
+            if (!raw || raw.type !== 'assistant') continue;
+            for (const b of blocksOf(raw) as Array<RawBlock & { input?: Record<string, unknown> }>) {
+                if (b.type !== 'tool_use' || typeof b.id !== 'string' || typeof b.name !== 'string') continue;
+                const input = typeof b.input === 'object' && b.input !== null ? b.input : {};
+                const command = b.name === 'Bash' && typeof input['command'] === 'string' ? input['command'] : null;
+                const filePath = b.name === 'Read' && typeof input['file_path'] === 'string' ? input['file_path'] : null;
+                calls.set(b.id, { name: b.name, command, path: filePath, range: filePath === null ? null : rangeOf(input) });
+            }
+        }
+    }
+    const out: ToolResultRecord[] = [];
+    const seen = new Set<string>();
+    for (const file of files) {
+        const session = path.relative(base, file).replace(/\.jsonl$/, '');
+        for (const line of readLines(file)) {
+            if (!line.includes('"tool_result"')) continue;
+            const raw = parseLine(line);
+            if (!raw || raw.type !== 'user') continue;
+            const timestamp = typeof raw.timestamp === 'string' ? raw.timestamp : null;
+            for (const block of blocksOf(raw)) {
+                if (block.type !== 'tool_result' || typeof block.tool_use_id !== 'string' || seen.has(block.tool_use_id)) continue;
+                seen.add(block.tool_use_id);
+                const { bytes, image } = payloadOf(block);
+                const call = calls.get(block.tool_use_id);
+                const name = call?.name ?? 'unknown';
+                const text = image ? null : textOf(block);
+                out.push({
+                    tool: image ? `${name}:image` : name,
+                    command: call?.command ?? null,
+                    bytes,
+                    timestamp,
+                    session,
+                    path: call?.path ?? null,
+                    range: call?.range ?? null,
+                    digest: text === null ? null : createHash('sha256').update(text, 'utf8').digest('hex'),
+                    advised: advised.has(block.tool_use_id),
+                });
+            }
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/changelog_eras.ts

@@ -12,6 +12,7 @@
  *
  * Normative source: `docs/contracts/CHANGELOG-conventions.md § Era splits`.
  */
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -553,3 +554,85 @@ export function perform_split(plan: SplitPlan): void {
     fs.writeFileSync(plan.archive_path, archive_text, 'utf-8');
     fs.writeFileSync(CHANGELOG, new_text, 'utf-8');
 }
+
+/** A released tag of this repository, bare `N.Y.Z`. */
+const RELEASE_TAG_RE = /^\d+\.\d+\.\d+$/u;
+
+/**
+ * The headline of every `- **…` entry staged under `## [Unreleased]`.
+ *
+ * The headline alone, not the whole entry: it is the first line, which is what
+ * `git log -S` can search for as a single string. Entries wrap over many lines
+ * and a multi-line needle finds nothing.
+ */
+export function unreleased_entry_headlines(lines: readonly string[]): string[] {
+    const start = lines.findIndex((l) => /^## \[Unreleased\]/u.test(l));
+    if (start < 0) {
+        return [];
+    }
+    const out: string[] = [];
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i] ?? '';
+        if (/^## \[?\d+\.\d+\.\d+/u.test(l) || /^# Era:/u.test(l)) {
+            break;
+        }
+        if (l.startsWith('- **')) {
+            out.push(l.slice(2));
+        }
+    }
+    return out;
+}
+
+function _git(args: readonly string[], cwd: string): string | null {
+    const r = spawnSync('git', args as string[], {
+        encoding: 'utf-8',
+        cwd,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return r.status === 0 ? (r.stdout ?? '') : null;
+}
+
+/**
+ * The newest release tag reachable in this checkout, or null when git cannot
+ * say — a tagless clone, a shallow one with no tags fetched, or no git at all.
+ *
+ * Null is a real answer and the caller is expected to stop on it. A checkout
+ * that cannot see tags cannot distinguish "never shipped" from "not fetched",
+ * and asserting either way would be an answer invented from an absence.
+ */
+export function newest_release_tag(cwd: string = REPO_ROOT): string | null {
+    const out = _git(['tag', '--list', '--sort=-v:refname'], cwd);
+    if (out === null) {
+        return null;
+    }
+    const tags = out.split('\n').map((t) => t.trim()).filter((t) => RELEASE_TAG_RE.test(t));
+    return tags[0] ?? null;
+}
+
+/**
+ * Has the entry carrying this headline already shipped in `tag`?
+ *
+ * Asked of git: the OLDEST commit that introduced the headline into
+ * `CHANGELOG.md`, then whether `tag` contains it. The oldest rather than the
+ * newest, because an entry edited or moved later still dates from the commit
+ * that first wrote it, and the newest would make every touched entry look new.
+ *
+ * `false` on a headline no commit ever wrote — an entry added in the working
+ * tree and not yet committed is exactly that, and it is genuinely unreleased.
+ */
+export function entry_is_contained_in_tag(
+    headline: string,
+    tag: string,
+    cwd: string = REPO_ROOT,
+): boolean {
+    const log = _git(['log', '--format=%H', '-S', headline, '--', 'CHANGELOG.md'], cwd);
+    if (log === null) {
+        return false;
+    }
+    const shas = log.split('\n').map((s) => s.trim()).filter(Boolean);
+    const oldest = shas[shas.length - 1];
+    if (oldest === undefined) {
+        return false;
+    }
+    return _git(['merge-base', '--is-ancestor', oldest, tag], cwd) !== null;
+}