@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/advisory_inventory.ts

@@ -0,0 +1,405 @@
+/**
+ * What a project actually runs — the input to every advisory question
+ * (road-to-advisories-heard-the-same-day Phase 1).
+ *
+ * Deterministic and offline: it reads files, never a network and never a
+ * package manager. Each entry carries the `file:line` it was read from and a
+ * provenance, because a declared range and a deployed version are different
+ * claims: `composer.json` saying `"php": "^8.3"` is not the PHP a Dockerfile
+ * pins, and reporting one as the other is the confusion the roadmap names.
+ *
+ * Private names (path / link / VCS dependencies, packages from a registry other
+ * than the public one) are marked here, once, so no later stage has to decide
+ * it again — every outbound query filters on this flag (D4).
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export type Ecosystem = 'npm' | 'Packagist' | 'GitHub Actions' | 'runtime' | 'manager' | 'image';
+export type Provenance = 'lockfile' | 'declared' | 'image' | 'ci';
+
+export interface InventoryEntry {
+    ecosystem: Ecosystem;
+    /** Package name, runtime (`php`, `node`), manager (`npm`, `composer`), or image. */
+    name: string;
+    /** Exact version when the source pins one, else `null`. */
+    version: string | null;
+    /** The declared range when the source only constrains, else `null`. */
+    range: string | null;
+    provenance: Provenance;
+    /** Repo-relative path of the file read. */
+    file: string;
+    line: number;
+    /** Never sent to a public service. */
+    private: boolean;
+    /** `dev` for development-only lockfile packages; `null` where unknown. */
+    scope: 'runtime' | 'dev' | null;
+}
+
+export interface Inventory {
+    entries: InventoryEntry[];
+    /** sha256 over every file read, in order. */
+    hash: string;
+    /** `inventoryFingerprint` at read time — the cheap reuse check (1.2). */
+    fingerprint: string;
+    files: string[];
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'vendor', 'dist', '.claude', '.worktrees', 'coverage', '.next']);
+const MAX_DEPTH = 4;
+
+function lineOf(text: string, needle: string): number {
+    const i = text.indexOf(needle);
+    return i < 0 ? 1 : text.slice(0, i).split('\n').length;
+}
+
+/** Repo-relative files whose basename matches, walked to a bounded depth. */
+function walk(root: string, match: (name: string, rel: string) => boolean): string[] {
+    const out: string[] = [];
+    const visit = (dir: string, depth: number): void => {
+        let names: fs.Dirent[];
+        try {
+            names = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const d of names) {
+            const abs = path.join(dir, d.name);
+            const rel = path.relative(root, abs);
+            if (d.isDirectory()) {
+                if (depth < MAX_DEPTH && !SKIP_DIRS.has(d.name)) visit(abs, depth + 1);
+            } else if (d.isFile() && match(d.name, rel)) {
+                out.push(rel);
+            }
+        }
+    };
+    visit(root, 0);
+    return out.sort();
+}
+
+const PUBLIC_NPM = /^https:\/\/registry\.npmjs\.org\//;
+
+/** package-lock.json v2/v3 — the `packages` map is the resolved tree. */
+function readNpmLock(rel: string, text: string): InventoryEntry[] {
+    let doc: { packages?: Record<string, { version?: string; resolved?: string; dev?: boolean; link?: boolean }> };
+    try {
+        doc = JSON.parse(text);
+    } catch {
+        return [];
+    }
+    const out: InventoryEntry[] = [];
+    for (const [key, pkg] of Object.entries(doc.packages ?? {})) {
+        if (key === '' || typeof pkg?.version !== 'string') continue;
+        const name = key.replace(/^.*node_modules\//, '');
+        const resolved = typeof pkg.resolved === 'string' ? pkg.resolved : '';
+        out.push({
+            ecosystem: 'npm',
+            name,
+            version: pkg.version,
+            range: null,
+            provenance: 'lockfile',
+            file: rel,
+            line: lineOf(text, `"${key}": {`),
+            private: pkg.link === true || !PUBLIC_NPM.test(resolved),
+            scope: pkg.dev === true ? 'dev' : 'runtime',
+        });
+    }
+    return out;
+}
+
+/** composer.lock — a package without the public Packagist notification URL is private. */
+function readComposerLock(rel: string, text: string): InventoryEntry[] {
+    type Pkg = { name?: string; version?: string; 'notification-url'?: string };
+    let doc: { packages?: Pkg[]; 'packages-dev'?: Pkg[] };
+    try {
+        doc = JSON.parse(text);
+    } catch {
+        return [];
+    }
+    const out: InventoryEntry[] = [];
+    for (const [list, scope] of [
+        [doc.packages ?? [], 'runtime'],
+        [doc['packages-dev'] ?? [], 'dev'],
+    ] as const) {
+        for (const p of list) {
+            if (typeof p.name !== 'string' || typeof p.version !== 'string') continue;
+            out.push({
+                ecosystem: 'Packagist',
+                name: p.name,
+                version: p.version.replace(/^v(?=\d)/, ''),
+                range: null,
+                provenance: 'lockfile',
+                file: rel,
+                line: lineOf(text, `"name": "${p.name}"`),
+                private: p['notification-url'] !== 'https://packagist.org/downloads/',
+                scope,
+            });
+        }
+    }
+    return out;
+}
+
+function runtime(
+    name: string,
+    value: string,
+    provenance: Provenance,
+    file: string,
+    line: number,
+): InventoryEntry {
+    const v = value.trim();
+    const exact = /^v?\d+(\.\d+){0,2}([-+.][0-9A-Za-z.]+)*$/.test(v);
+    return {
+        ecosystem: 'runtime',
+        name,
+        version: exact ? v.replace(/^v/, '') : null,
+        range: exact ? null : v,
+        provenance,
+        file,
+        line,
+        private: false,
+        scope: 'runtime',
+    };
+}
+
+function readComposerJson(rel: string, text: string): InventoryEntry[] {
+    let doc: { require?: Record<string, string>; config?: { platform?: Record<string, string> } };
+    try {
+        doc = JSON.parse(text);
+    } catch {
+        return [];
+    }
+    const out: InventoryEntry[] = [];
+    const req = doc.require?.['php'];
+    if (typeof req === 'string') out.push(runtime('php', req, 'declared', rel, lineOf(text, '"php"')));
+    const platform = doc.config?.platform?.['php'];
+    if (typeof platform === 'string') {
+        out.push(runtime('php', platform, 'declared', rel, lineOf(text, '"platform"')));
+    }
+    return out;
+}
+
+function readPackageJson(rel: string, text: string): InventoryEntry[] {
+    let doc: {
+        engines?: Record<string, string>;
+        packageManager?: string;
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    };
+    try {
+        doc = JSON.parse(text);
+    } catch {
+        return [];
+    }
+    const out: InventoryEntry[] = [];
+    // Direct dependencies, as declared ranges: what decides whether a fix is a
+    // range bump of a direct dependency or an override of a transitive one.
+    // A range is never queried as if it were a version.
+    for (const [deps, scope] of [
+        [doc.dependencies ?? {}, 'runtime'],
+        [doc.devDependencies ?? {}, 'dev'],
+    ] as const) {
+        for (const [name, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string') continue;
+            out.push({
+                ecosystem: 'npm',
+                name,
+                version: null,
+                range: spec,
+                provenance: 'declared',
+                file: rel,
+                line: lineOf(text, `"${name}"`),
+                private: /^(file:|link:|git|github:|workspace:|\.|\/)/.test(spec),
+                scope,
+            });
+        }
+    }
+    const node = doc.engines?.['node'];
+    if (typeof node === 'string') out.push(runtime('node', node, 'declared', rel, lineOf(text, '"engines"')));
+    const pm = /^(npm|pnpm|yarn|bun)@(\d[^+\s]*)/.exec(doc.packageManager ?? '');
+    if (pm) {
+        out.push({
+            ecosystem: 'manager',
+            name: pm[1]!,
+            version: pm[2]!,
+            range: null,
+            provenance: 'declared',
+            file: rel,
+            line: lineOf(text, '"packageManager"'),
+            private: false,
+            scope: 'runtime',
+        });
+    }
+    return out;
+}
+
+/** `.nvmrc`, `.node-version`, `.php-version` — one version, first non-comment line. */
+function readVersionFile(rel: string, text: string, name: 'node' | 'php'): InventoryEntry[] {
+    const lines = text.split('\n');
+    const i = lines.findIndex((l) => l.trim() !== '' && !l.trim().startsWith('#'));
+    return i < 0 ? [] : [runtime(name, lines[i]!.trim(), 'declared', rel, i + 1)];
+}
+
+/** `.tool-versions` (asdf) and `mise.toml` [tools]. */
+function readToolVersions(rel: string, text: string): InventoryEntry[] {
+    const out: InventoryEntry[] = [];
+    text.split('\n').forEach((raw, i) => {
+        const l = raw.replace(/#.*/, '').trim();
+        const asdf = /^(nodejs|node|php)\s+(\S+)/.exec(l);
+        const mise = /^(node|php)\s*=\s*["']?([^"'\s]+)["']?/.exec(l);
+        const m = asdf ?? mise;
+        if (m) out.push(runtime(m[1] === 'nodejs' ? 'node' : m[1]!, m[2]!, 'declared', rel, i + 1));
+    });
+    return out;
+}
+
+/**
+ * An official `php` or `node` image tag names the runtime it ships
+ * (`php:8.3.12-fpm` → php 8.3.12). Any other image is recorded as an image,
+ * never guessed into a runtime.
+ */
+function imageEntry(ref: string, provenance: Provenance, file: string, line: number): InventoryEntry {
+    // Anchored: the image NAME must be exactly php or node (phpmyadmin, nodered/node-red are not).
+    const m = /^(?:docker\.io\/)?(?:library\/)?(php|node)(?::([^@\s]+))?(?:@\S+)?$/.exec(ref);
+    if (m) {
+        const tag = m[2] ?? 'latest';
+        const num = /^(\d+(?:\.\d+){0,2})/.exec(tag);
+        return runtime(m[1]!, num ? num[1]! : tag, provenance, file, line);
+    }
+    const [name, tag] = ref.split(/[:@]/, 2) as [string, string | undefined];
+    return {
+        ecosystem: 'image',
+        name,
+        version: tag ?? null,
+        range: null,
+        provenance,
+        file,
+        line,
+        private: false,
+        scope: 'runtime',
+    };
+}
+
+function readDockerfile(rel: string, text: string): InventoryEntry[] {
+    const out: InventoryEntry[] = [];
+    text.split('\n').forEach((raw, i) => {
+        const m = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)/i.exec(raw);
+        if (m && !m[1]!.startsWith('$') && m[1] !== 'scratch') out.push(imageEntry(m[1]!, 'image', rel, i + 1));
+    });
+    return out;
+}
+
+/** Compose files and CI workflows: `image:` lines, runtime setup keys, action pins. */
+function readYaml(rel: string, text: string, ci: boolean): InventoryEntry[] {
+    const out: InventoryEntry[] = [];
+    const prov: Provenance = ci ? 'ci' : 'image';
+    text.split('\n').forEach((raw, i) => {
+        const l = raw.replace(/\s#.*$/, '');
+        const img = /^\s*image:\s*["']?([^"'\s]+)["']?\s*$/.exec(l);
+        if (img && !img[1]!.includes('${')) out.push(imageEntry(img[1]!, prov, rel, i + 1));
+        if (!ci) return;
+        const setup = /^\s*(node-version|php-version):\s*["']?([^"'\s[\]]+)["']?\s*$/.exec(l);
+        if (setup && !setup[2]!.includes('${')) {
+            out.push(runtime(setup[1] === 'node-version' ? 'node' : 'php', setup[2]!, 'ci', rel, i + 1));
+        }
+        const uses = /^\s*-?\s*uses:\s*["']?([\w.-]+\/[\w./-]+)@([^"'\s]+)["']?/.exec(l);
+        if (uses) {
+            out.push({
+                ecosystem: 'GitHub Actions',
+                name: uses[1]!,
+                version: uses[2]!,
+                range: null,
+                provenance: 'ci',
+                file: rel,
+                line: i + 1,
+                private: false,
+                scope: 'runtime',
+            });
+        }
+    });
+    return out;
+}
+
+/** Every file this reader consults, with the parser for it. */
+function sources(root: string): Array<{ rel: string; parse: (rel: string, text: string) => InventoryEntry[] }> {
+    const list: Array<{ rel: string; parse: (rel: string, text: string) => InventoryEntry[] }> = [];
+    const add = (rels: string[], parse: (rel: string, text: string) => InventoryEntry[]): void => {
+        for (const rel of rels) list.push({ rel, parse });
+    };
+    add(walk(root, (n) => n === 'package-lock.json'), readNpmLock);
+    add(walk(root, (n) => n === 'composer.lock'), readComposerLock);
+    add(walk(root, (n) => n === 'composer.json'), readComposerJson);
+    add(walk(root, (n) => n === 'package.json'), readPackageJson);
+    add(walk(root, (n) => n === '.nvmrc' || n === '.node-version'), (r, t) => readVersionFile(r, t, 'node'));
+    add(walk(root, (n) => n === '.php-version'), (r, t) => readVersionFile(r, t, 'php'));
+    add(walk(root, (n) => n === '.tool-versions' || n === 'mise.toml' || n === '.mise.toml'), readToolVersions);
+    add(walk(root, (n) => /^Dockerfile(\..+)?$/.test(n) || n.endsWith('.Dockerfile')), readDockerfile);
+    add(walk(root, (n) => /^(docker-)?compose(\.[\w-]+)?\.ya?ml$/.test(n)), (r, t) => readYaml(r, t, false));
+    add(
+        walk(root, (_n, rel) => /^\.github[\\/]workflows[\\/][^\\/]+\.ya?ml$/.test(rel)),
+        (r, t) => readYaml(r, t, true),
+    );
+    return list;
+}
+
+/** Read the whole inventory. Unreadable files are skipped, never guessed. */
+/**
+ * Lockfiles this inventory cannot read: yarn, pnpm and bun locks, and an npm
+ * lock in the v1 format. Their packages are not in the inventory, so a refresh
+ * must say "not checked" for them — an empty list from a lock nobody read would
+ * otherwise read as a clean project.
+ */
+export function unsupportedLockfiles(root: string): string[] {
+    const out = walk(root, (n) => n === 'yarn.lock' || n === 'pnpm-lock.yaml' || n === 'bun.lock' || n === 'bun.lockb');
+    for (const rel of walk(root, (n) => n === 'package-lock.json')) {
+        try {
+            const v = (JSON.parse(fs.readFileSync(path.join(root, rel), 'utf-8')) as { lockfileVersion?: unknown }).lockfileVersion;
+            if (v === 1 || v === undefined) out.push(rel);
+        } catch {
+            out.push(rel);
+        }
+    }
+    return out.sort();
+}
+
+export function readInventory(root: string): Inventory {
+    const hash = createHash('sha256');
+    const finger = createHash('sha256');
+    const entries: InventoryEntry[] = [];
+    const files: string[] = [];
+    for (const { rel, parse } of sources(root)) {
+        let text: string;
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(path.join(root, rel));
+            text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        } catch {
+            continue;
+        }
+        files.push(rel);
+        hash.update(`${rel}\0${text}\0`);
+        finger.update(`${rel}\0${st.size}\0${st.mtimeMs}\0`);
+        entries.push(...parse(rel, text));
+    }
+    // The same fingerprint `inventoryFingerprint` computes, from the same walk.
+    return { entries, hash: hash.digest('hex'), fingerprint: finger.digest('hex'), files };
+}
+
+/**
+ * A fingerprint over every source file's path, size and mtime — never its
+ * body. Equal to the stored one means the stored inventory is still current,
+ * and no lockfile is read at all (1.2).
+ */
+export function inventoryFingerprint(root: string): string {
+    const hash = createHash('sha256');
+    for (const { rel } of sources(root)) {
+        try {
+            const st = fs.statSync(path.join(root, rel));
+            hash.update(`${rel}\0${st.size}\0${st.mtimeMs}\0`);
+        } catch {
+            /* an unreadable file is absent from both the fingerprint and the inventory */
+        }
+    }
+    return hash.digest('hex');
+}

package/src/scripts/_lib/advisory_notice.ts

@@ -0,0 +1,270 @@
+/**
+ * The read-only half of advisories — what a session start may do
+ * (road-to-advisories-heard-the-same-day Phase 4).
+ *
+ * Kept apart from `advisories.ts` on purpose: this module is inlined into the
+ * hook bundle, and it holds no network code at all — no fetch, no process
+ * spawn. A session start reads one cache file, prints at most a few lines, and
+ * writes one "already shown today" stamp. Everything that touches the network
+ * lives in `advisories.ts`, which a hook never imports.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { load_agent_settings, settings_layer_states } from './agent_settings.js';
+import type { InventoryEntry } from './advisory_inventory.js';
+import type { SourceReport } from './advisory_sources.js';
+import type { Acceptance, Finding, Ledger } from './advisory_verdicts.js';
+import { git_common_dir } from './git_common_dir.js';
+import type { Remediations } from './security_fix.js';
+import { mergedNotDeployed } from './undeployed_fixes.js';
+
+export type AdvisoriesMode = 'notify' | 'off';
+export type AdvisoriesEgress = 'query' | 'none';
+export type AdvisoriesKev = 'on' | 'off';
+
+/** Advisory data older than this makes the notice say so instead of looking current. */
+export const STALE_AFTER_HOURS = 24;
+/** Three days of a silent source is itself a notice (4.4). */
+export const SILENCE_NOTICE_DAYS = 3;
+
+export interface AdvisoryState {
+    schema: 1;
+    root: string;
+    at: string;
+    fingerprint: string;
+    /** The egress setting this state was refreshed under. */
+    egress?: AdvisoriesEgress;
+    inventory: InventoryEntry[];
+    findings: Finding[];
+    reports: SourceReport[];
+    ledger: Ledger;
+    acceptances: Acceptance[];
+    /** What the last refresh decided to announce; the session start prints it once. */
+    notice: { at: string; interrupt: string[]; digest: number } | null;
+    /** First time each source went silent, for the 4.4 silence notice. */
+    silent_since: Record<string, string>;
+    /** Fixes in flight and their lifecycle (road-to-security-fixes-carried-to-the-merge Phase 3). */
+    remediations?: Remediations;
+}
+
+export function readAdvisorySettings(root: string): { mode: AdvisoriesMode; egress: AdvisoriesEgress; kev: AdvisoriesKev } {
+    try {
+        if (settings_layer_states({ cwd: root }).some((l) => l.state === 'malformed')) return { mode: 'off', egress: 'none', kev: 'off' };
+        const section = load_agent_settings({ cwd: root })['advisories'];
+        const s = section !== null && typeof section === 'object' && !Array.isArray(section) ? (section as Record<string, unknown>) : {};
+        return {
+            // An unquoted `off` is YAML's boolean false: both mean off.
+            mode: s['mode'] === 'off' || s['mode'] === false ? 'off' : 'notify',
+            egress: s['egress'] === 'none' ? 'none' : 'query',
+            kev: s['kev'] === 'off' || s['kev'] === false ? 'off' : 'on',
+        };
+    } catch {
+        return { mode: 'off', egress: 'none', kev: 'off' };
+    }
+}
+
+/**
+ * One cache per checkout. The git common dir is shared by every worktree of a
+ * repository, so the file is keyed by the checkout's own real path: a refresh
+ * inside a fix worktree describes that branch and never overwrites the main
+ * checkout's findings.
+ */
+export function statePath(root: string): string | null {
+    const common = git_common_dir(root);
+    if (common === null) return null;
+    let real = path.resolve(root);
+    try {
+        real = fs.realpathSync(root);
+    } catch {
+        /* a vanished checkout still gets a stable key from its resolved path */
+    }
+    const key = createHash('sha256').update(real).digest('hex').slice(0, 16);
+    return path.join(common, 'agent-config', 'advisories', `${key}.json`);
+}
+
+/**
+ * Fix lifecycles are per REPOSITORY, not per checkout: a fix claimed in the main
+ * checkout is verified in its own worktree, and two worktrees must see one claim
+ * for one finding. So they live beside the per-checkout caches, in the common
+ * git dir every worktree shares.
+ */
+export function remediationsPath(root: string): string | null {
+    const common = git_common_dir(root);
+    return common === null ? null : path.join(common, 'agent-config', 'advisories', 'remediations.json');
+}
+
+export function readRemediations(root: string): Remediations {
+    const p = remediationsPath(root);
+    if (p !== null) {
+        try {
+            const doc = JSON.parse(fs.readFileSync(p, 'utf-8')) as unknown;
+            if (isObject(doc)) return doc as Remediations;
+        } catch {
+            /* absent or unreadable: fall back to a pre-shared cache below */
+        }
+    }
+    // A cache written before the shared file existed carries its own copy.
+    return readState(root)?.remediations ?? {};
+}
+
+export function readState(root: string): AdvisoryState | null {
+    const p = statePath(root);
+    if (p === null) return null;
+    try {
+        const doc = JSON.parse(fs.readFileSync(p, 'utf-8')) as AdvisoryState;
+        return isState(doc) ? doc : null;
+    } catch {
+        return null;
+    }
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** The shape every reader below relies on; a cache that is not it is no cache. */
+function isState(doc: unknown): doc is AdvisoryState {
+    if (!isObject(doc) || doc['schema'] !== 1 || typeof doc['at'] !== 'string') return false;
+    if (!Array.isArray(doc['findings']) || !doc['findings'].every((f) => isObject(f) && typeof f['key'] === 'string')) return false;
+    const n = doc['notice'];
+    if (n !== null && n !== undefined && !(isObject(n) && Array.isArray(n['interrupt']) && typeof n['digest'] === 'number')) return false;
+    if (doc['silent_since'] !== undefined && !isObject(doc['silent_since'])) return false;
+    if (doc['remediations'] !== undefined && !isObject(doc['remediations'])) return false;
+    return true;
+}
+
+/** Most lines a session start prints, whatever the cache holds. */
+export const MAX_NOTICE_LINES = 8;
+
+/**
+ * Every field a session line carries comes from a cache file on disk, and the
+ * line lands in privileged session context. JSON encoding protects the file's
+ * framing, not what the decoded string says — so each field is checked against
+ * a strict single-line grammar with a length cap before it is printed, and a
+ * field that fails is replaced, never passed through (council 2026-10-21, round 2).
+ */
+const FIELD = /^[A-Za-z0-9@._:/+~^<>=*-]{1,200}$/;
+
+export function safeField(v: unknown, max = 80): string {
+    if (typeof v === 'number' && Number.isInteger(v) && v >= 0 && v < 10_000_000) return String(v);
+    if (typeof v !== 'string' || v.length > max || !FIELD.test(v)) return '?';
+    return v;
+}
+
+const TIERS = new Set(['T0', 'T1', 'T2', 'T3']);
+const VERDICTS = new Set([
+    'affected', 'fix-available', 'fix-fresh', 'no-fix', 'malware', 'eol', 'eol-soon', 'pre-announced', 'unknown', 'accepted',
+]);
+
+function enumField(v: unknown, allowed: Set<string>): string {
+    return typeof v === 'string' && allowed.has(v) ? v : '?';
+}
+
+function where(f: Finding): string {
+    return f.file === '' ? '' : ` (${safeField(f.file, 200)}:${safeField(f.line)})`;
+}
+
+export function describe(f: Finding): string {
+    const tier = enumField(f.tier, TIERS);
+    const verdict = enumField(f.verdict, VERDICTS);
+    const pkg = safeField(f.package);
+    const ver = f.version === null ? '' : ` ${safeField(f.version)}`;
+    const fix = f.fixed === null ? '' : ` → ${safeField(f.fixed)}`;
+    const date = safeField(f.date);
+    const ids = [f.id, ...(Array.isArray(f.aliases) ? f.aliases : [])].slice(0, 3).map((i) => safeField(i)).join(', ');
+    // Provenance of the tier: "known exploited" is a fact, never a prediction.
+    const kev = f.kev === true ? ' — known exploited (KEV)' : '';
+    switch (verdict) {
+        case 'pre-announced':
+            return `${tier} ${pkg}: a security release is pre-announced (${date}); fixed versions not yet named${where(f)}`;
+        case 'eol':
+            return `${tier} ${pkg}${ver}: security support ended ${date}${where(f)}`;
+        case 'eol-soon':
+            return `${tier} ${pkg}${ver}: security support ends ${date}${where(f)}`;
+        case 'unknown':
+            if (typeof f.note === 'string' && f.note.includes('egress-none')) return `${tier} ${pkg}: not checked — advisories.egress is none`;
+            if (typeof f.note === 'string' && f.note.includes('lockfile-unsupported')) return `${tier} ${pkg}: not checked — a lockfile format this audit cannot read (yarn, pnpm, bun or npm v1)`;
+            if (typeof f.note === 'string' && f.note.startsWith('vendor-patched')) return `${tier} ${pkg}${ver}: distro-patched — judge it by the distro's own advisory${where(f)}`;
+            return `${tier} ${pkg}: unknown — the source did not answer`;
+        default:
+            return `${tier} ${pkg}${ver}${fix} [${verdict}] ${ids}${kev}${where(f)}`;
+    }
+}
+
+/**
+ * The session notice — computed from the cache, never from the network, and
+ * never an action. Each T0/T1 line ends in the offer; the routing behind the
+ * offer is owned by road-to-security-fixes-carried-to-the-merge.
+ */
+export function noticeLines(state: AdvisoryState | null, now: Date = new Date(), remediations: Remediations | null = null): string[] {
+    if (state === null) return [];
+    const lines: string[] = [];
+    // An unreadable or future timestamp proves nothing about freshness: stale.
+    const atMs = Date.parse(state.at);
+    const ageH = Number.isFinite(atMs) && atMs <= now.getTime() ? (now.getTime() - atMs) / 3600000 : Number.POSITIVE_INFINITY;
+    const byKey = new Map(state.findings.map((f) => [f.key, f]));
+    const pending = state.notice?.interrupt.map((k) => byKey.get(k)).filter((f): f is Finding => f !== undefined) ?? [];
+    for (const f of pending) {
+        lines.push(`advisory ${describe(f)} — fix now: /audit deps fix ${safeField(f.id)} (here or in its own worktree), or later`);
+    }
+    if ((state.notice?.digest ?? 0) > 0) lines.push(`advisories: ${safeField(state.notice!.digest)} more in the digest — /audit deps`);
+    for (const [source, since] of Object.entries(state.silent_since ?? {}).slice(0, 4)) {
+        const sinceMs = Date.parse(String(since));
+        if (!Number.isFinite(sinceMs) || sinceMs > now.getTime()) {
+            lines.push(`advisories: ${safeField(source)} silent since an unreadable date — findings from it are unknown, not clear`);
+            continue;
+        }
+        const days = (now.getTime() - sinceMs) / 86400000;
+        if (days >= SILENCE_NOTICE_DAYS) lines.push(`advisories: ${safeField(source)} has not answered for ${Math.floor(days)} days — findings from it are unknown, not clear`);
+    }
+    for (const u of mergedNotDeployed(remediations ?? state.remediations ?? {}, state.findings, now)) {
+        const sha = u.mergeSha === null ? '' : ` (${safeField(u.mergeSha.slice(0, 12))})`;
+        lines.push(`advisory ${safeField(u.id)}: merged${sha} but not deployed for ${safeField(u.hours)} h — deploy it the way this project deploys`);
+    }
+    if (ageH === Number.POSITIVE_INFINITY) {
+        lines.push('advisories: data age unreadable — run `agent-config audit:deps refresh`');
+    } else if (ageH >= STALE_AFTER_HOURS) {
+        lines.push(`advisories: data is ${Math.floor(ageH / 24) || 1} day(s) old — run \`agent-config audit:deps refresh\``);
+    }
+    return lines.length > MAX_NOTICE_LINES ? [...lines.slice(0, MAX_NOTICE_LINES - 1), `advisories: ${lines.length - MAX_NOTICE_LINES + 1} more — /audit deps`] : lines;
+}
+
+/** Shown once per notice: the stamp records which notice this checkout already printed. */
+export function sessionNotice(root: string, now: Date = new Date(), deliver?: (text: string) => boolean): string | null {
+    if (readAdvisorySettings(root).mode === 'off') return null;
+    const state = readState(root);
+    if (state === null) return null;
+    const stamp = statePath(root) + '.shown';
+    let prev: { day?: string; once?: string[]; today?: string[] } = {};
+    try {
+        prev = JSON.parse(fs.readFileSync(stamp, 'utf-8')) as typeof prev;
+    } catch {
+        prev = {};
+    }
+    const day = now.toISOString().slice(0, 10);
+    const lines = noticeLines(state, now, readRemediations(root));
+    // A finding announced by a refresh is printed ONCE, whatever day it is and
+    // however long the cache goes unrefreshed — the weekly budget and the delta
+    // ledger count at refresh time, and a re-print would escape both. Reminders
+    // (stale data, a silent source, merged-not-deployed) come back once a day.
+    // Numbers that only age (hours, days) are not part of a line's identity.
+    const keyOf = (l: string): string => createHash('sha256').update(l.replace(/\b\d+ (?:h|days?|day\(s\))\b/g, '#')).digest('hex').slice(0, 16);
+    const isReminder = (l: string): boolean => /^advisories: (?:data|\S+ (?:has not answered|silent since))|: merged/.test(l);
+    const once = new Set(Array.isArray(prev.once) ? prev.once : []);
+    const today = new Set(prev.day === day && Array.isArray(prev.today) ? prev.today : []);
+    const out = lines.filter((l) => (isReminder(l) ? !today.has(keyOf(l)) : !once.has(keyOf(l))));
+    if (out.length === 0) return null;
+    const text = out.join('\n');
+    // Stamped only once the text reached someone: a caller that could not
+    // deliver it leaves the notice for the next surface.
+    if (deliver !== undefined && !deliver(text)) return null;
+    for (const l of out) (isReminder(l) ? today : once).add(keyOf(l));
+    try {
+        fs.writeFileSync(stamp, `${JSON.stringify({ day, once: [...once].slice(-200), today: [...today] })}\n`);
+    } catch {
+        /* an unwritable stamp means the line may show twice; never a failure */
+    }
+    return text;
+}
+