@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/update_check.ts

@@ -1,7 +1,7 @@
 /**
  * Daily update-check banner for the `agent-config` dispatcher.
  *
- * Ported from the retired Python `src/scripts/_lib/update_check.py` (ADR-200,
+ * Ported from its retired Python twin (ADR-200,
  * Phase 2 / Wave 1 batch B). Pure functions: `check_for_update()`
  * decides whether a banner should be emitted and returns the banner
  * string (or `null`). The dispatcher prints the returned string to
@@ -31,6 +31,7 @@ import * as path from 'node:path';
 
 import type { EnvMap } from './user_global_paths';
 import * as user_global_paths from './user_global_paths';
+import { compare_versions } from './version_order';
 
 export const PACKAGE_NAME = '@event4u/agent-config';
 export const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
@@ -79,6 +80,32 @@ export async function fetch_latest_from_npm(
         fetch_impl?: typeof fetch;
     } = {},
 ): Promise<string | null> {
+    return (await fetch_latest_document(options))?.version ?? null;
+}
+
+/** The version, and the impact block worth caching beside it. */
+export interface LatestDocument {
+    readonly version: string;
+    /** The registry's `agentConfig.impact` block, UNVALIDATED — see {@link _cacheable_impact}. */
+    readonly impact: unknown;
+}
+
+/**
+ * The registry's `latest` document, reduced to what a cached decision needs.
+ *
+ * One fetch, two consumers: the banner wants the version, and the
+ * `update-notice` session concern wants to know whether a security fix lies in
+ * range — a question the version alone cannot answer and that a hook has no
+ * business opening a socket for. Adding a second network call for the second
+ * reader would make a once-a-day probe a twice-a-day one.
+ */
+export async function fetch_latest_document(
+    options: {
+        timeout?: number;
+        url?: string;
+        fetch_impl?: typeof fetch;
+    } = {},
+): Promise<LatestDocument | null> {
     const timeout = options.timeout ?? FETCH_TIMEOUT_S;
     const url = options.url ?? NPM_REGISTRY_URL;
     const fetch_impl = options.fetch_impl ?? fetch;
@@ -92,9 +119,12 @@ export async function fetch_latest_from_npm(
         });
         const payload: unknown = await resp.json();
         if (payload !== null && typeof payload === 'object' && !Array.isArray(payload)) {
-            const version = (payload as Record<string, unknown>).version;
+            const doc = payload as Record<string, unknown>;
+            const version = doc['version'];
             if (typeof version === 'string' && version.trim()) {
-                return version.trim();
+                const cfg = doc['agentConfig'];
+                const impact = cfg !== null && typeof cfg === 'object' && !Array.isArray(cfg) ? (cfg as Record<string, unknown>)['impact'] : null;
+                return { version: version.trim(), impact: impact ?? null };
             }
         }
     } catch {
@@ -103,6 +133,30 @@ export async function fetch_latest_from_npm(
     return null;
 }
 
+/**
+ * The impact block reduced to what may be written into the state file.
+ *
+ * The cache is the SANITISING BOUNDARY, deliberately: everything downstream
+ * reads this file rather than the registry, so a hostile description, version
+ * label or nested object is dropped here once instead of being re-checked by
+ * every reader. Keys must parse as versions and values must carry an impact
+ * from the published enum; a `security` flag survives only as a boolean.
+ * Anything else is simply absent, which every reader already handles as an
+ * unknown — and an unknown never resolves to `auto`.
+ */
+export function _cacheable_impact(impact: unknown): Record<string, { impact: string; security: boolean }> | null {
+    if (impact === null || typeof impact !== 'object' || Array.isArray(impact)) return null;
+    const out: Record<string, { impact: string; security: boolean }> = {};
+    for (const [version, entry] of Object.entries(impact as Record<string, unknown>)) {
+        if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) continue;
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        const value = (entry as Record<string, unknown>)['impact'];
+        if (!['none', 'automatic', 'notice', 'action'].includes(String(value))) continue;
+        out[version] = { impact: String(value), security: (entry as Record<string, unknown>)['security'] === true };
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
+
 function _read_state(state_path: string): Record<string, unknown> {
     try {
         const raw = fs.readFileSync(state_path, 'utf-8');
@@ -161,11 +215,58 @@ function _should_check(state: Record<string, unknown>, now: Date): boolean {
     return now.getTime() - last_ms >= CHECK_WINDOW_MS;
 }
 
-function _format_banner(latest: string, installed: string): string {
-    return (
-        `ℹ️  agent-config ${latest} available (you have ${installed}).\n` +
-        `    Update: npx ${PACKAGE_NAME} update`
-    );
+/**
+ * The install shape that is running. It decides which command the banner may
+ * name: `upgrade` replaces the global binary, `update` flips a project's
+ * `agent_config_version` pin, and an ephemeral `npx` run has nothing to update.
+ */
+export type InstallOrigin = 'global' | 'project-pin' | 'ephemeral' | 'unknown';
+
+const GLOBAL_TREE = /[\\/](?:lib|npm)[\\/]node_modules[\\/]@event4u[\\/]agent-config[\\/]?$/;
+
+/**
+ * Classify the running install from signals the caller gathers.
+ *
+ * Order matters: a pinned project also runs from the npx cache, so the pin is
+ * read before the `_npx` segment. `latest` is the registry version the banner
+ * announces; the pin is compared against it, never the running executable. An origin nobody enumerated is `unknown` and
+ * gets no command, because a guessed command is the defect this replaces.
+ */
+export function classify_install_origin(signals: {
+    package_root: string;
+    project_pin: string | null;
+    latest: string | null;
+    is_global_consumer: boolean;
+}): InstallOrigin {
+    const pin = signals.project_pin?.trim() ?? '';
+    if (pin !== '') {
+        // `update` moves the pin, not the running executable: a pin already at
+        // or past latest has nothing to move, and no other command is known
+        // to be right for a pinned project.
+        return signals.latest && _is_newer(signals.latest, pin) ? 'project-pin' : 'unknown';
+    }
+    if (signals.package_root.split(/[\\/]+/).includes('_npx')) {
+        return 'ephemeral';
+    }
+    if (signals.is_global_consumer || GLOBAL_TREE.test(signals.package_root)) {
+        return 'global';
+    }
+    return 'unknown';
+}
+
+export function _format_banner(
+    latest: string,
+    installed: string,
+    origin: InstallOrigin = 'unknown',
+): string {
+    const head = `ℹ️  agent-config ${latest} available (you have ${installed}).`;
+    if (origin === 'global') {
+        return `${head}\n    Update: agent-config upgrade`;
+    }
+    if (origin === 'project-pin') {
+        return `${head}\n    Update: agent-config update`;
+    }
+    return head;
 }
 
 /** Strict integer parse mirroring Python's `int(p)` (else 0). */
@@ -212,6 +313,23 @@ export function _is_newer(latest: string, installed: string): boolean {
     return false;
 }
 
+/**
+ * The comparator for policy decisions: full SemVer precedence, so a final
+ * release is newer than its own prerelease, and unparseable input on either
+ * side is never newer. `_is_newer` above keeps its truncating behaviour and
+ * still feeds the banner; it is the regression witness that the two differ.
+ */
+export function is_newer_version(latest: string, installed: string): boolean {
+    return compare_versions(latest, installed) === 1;
+}
+
+function _resolve_origin(
+    origin: InstallOrigin | ((latest: string) => InstallOrigin) | undefined,
+    latest: string,
+): InstallOrigin | undefined {
+    return typeof origin === 'function' ? origin(latest) : origin;
+}
+
 /** Format a Date as `%Y-%m-%dT%H:%M:%SZ` (UTC, no milliseconds). */
 function _format_utc(d: Date): string {
     return d.toISOString().replace(/\.\d{3}Z$/, 'Z');
@@ -233,6 +351,7 @@ export async function check_for_update(
         is_tty?: boolean | null;
         settings_enabled?: boolean;
         fetcher?: Fetcher;
+        origin?: InstallOrigin | ((latest: string) => InstallOrigin);
     } = {},
 ): Promise<string | null> {
     const env = options.env ?? process.env;
@@ -264,13 +383,22 @@ export async function check_for_update(
     if (!_should_check(state, now)) {
         const latest = state.last_seen_version;
         if (typeof latest === 'string' && _is_newer(latest, installed_version)) {
-            return _format_banner(latest, installed_version);
+            return _format_banner(latest, installed_version, _resolve_origin(options.origin, latest));
         }
         return null;
     }
 
-    const fetcher = options.fetcher ?? (() => fetch_latest_from_npm());
-    const latest = await fetcher();
+    // An injected fetcher yields a version only, so no impact is cached on that
+    // path — a caller that pins the network pins what reaches the state file too.
+    let impact: unknown = null;
+    let latest: string | null;
+    if (options.fetcher === undefined) {
+        const doc = await fetch_latest_document();
+        latest = doc?.version ?? null;
+        impact = doc?.impact ?? null;
+    } else {
+        latest = await options.fetcher();
+    }
     const fallback_seen = Object.prototype.hasOwnProperty.call(state, 'last_seen_version')
         ? state.last_seen_version
         : '';
@@ -280,6 +408,9 @@ export async function check_for_update(
         last_seen_version: latest ? latest : fallback_seen,
         installed_version,
     };
+    const cacheable = _cacheable_impact(impact);
+    if (cacheable !== null) payload['last_seen_impact'] = cacheable;
+    else if (state['last_seen_impact'] !== undefined && !latest) payload['last_seen_impact'] = state['last_seen_impact'];
     try {
         _write_state(write_path, payload);
     } catch (err) {
@@ -293,5 +424,5 @@ export async function check_for_update(
     if (!latest || !_is_newer(latest, installed_version)) {
         return null;
     }
-    return _format_banner(latest, installed_version);
+    return _format_banner(latest, installed_version, _resolve_origin(options.origin, latest));
 }

package/src/scripts/_lib/update_invite.ts

@@ -0,0 +1,116 @@
+/**
+ * Whether an install that already exists may be ASKED, once, to let updates
+ * install themselves — and the question it would be asked.
+ *
+ * ADR-291 settled the policy: `auto` may default for a NEW install; an
+ * existing one is asked once, after the ring-0 exit and the live-session
+ * register, with a binding "never", and a dismissal keeps `notify`. This
+ * module is that policy as a function, so the thing a reviewer checks is a
+ * table of conditions rather than a hook's control flow.
+ *
+ * **Narrower than ADR-291 reads, on purpose.** A council round of 2026-10-20
+ * refused the ring-0 record as the gate — a rollout switch opens the question
+ * for every install at once, which is not consent — and asked for a user-owned
+ * opt-in. The opt-in is `update.mode: ask`, a class-C value only a human can
+ * set, and ring-0 stays as an additional kill switch. An install that never
+ * chose `ask` is therefore never asked, which is ADR-291's dismissal outcome
+ * (`notify`) reached without the question. Whether that is the reading the
+ * next round accepts is for that round; this module only stops the rollout
+ * switch from standing in for consent.
+ *
+ * **Every condition is a reason to stay silent.** The function returns the
+ * question only when all of them clear, and returns WHY otherwise, because a
+ * prompt that appears in CI, in a pipe, in a headless run, under `--json` or
+ * inside a subagent is not a question — it is output nobody can answer, in a
+ * place that may be parsed.
+ *
+ * **It never writes the setting.** `update.mode` is class C: only a human's
+ * hand-edit or the GUI's write route may set it. The invitation says how, and
+ * stopping it is the same setting: `ask` is the opt-in, so any other value
+ * ends every future invitation. One mechanism, rather than a second "never"
+ * record that could disagree with the setting.
+ *
+ * **It is one-way text on every host.** The concern collects no answer; the
+ * user acts by editing the setting. A host with a native ask shape may relay
+ * the text through it, which changes how it is shown, not what it can decide.
+ */
+import type { UpdateMode } from './classify_update.js';
+
+/** The exact line `ring-0-unattended-record-*.md` carries, and the only one read. */
+export const RING_ZERO_EXIT_LINE = /^ring-0-exit:\s*(yes|no)\s*$/m;
+
+/**
+ * Whether the ring-0 record says the exit happened.
+ *
+ * Absent file, absent line, or anything but a literal `yes` is `false`. The
+ * line is written by a human after reading the table; nothing recomputes it
+ * from the rows, because a count an agent could compute is a count an agent
+ * could be wrong about, and this one authorises a prompt on an install the
+ * user already has.
+ */
+export function ringZeroExited(recordText: string | null): boolean {
+    if (recordText === null) return false;
+    const m = RING_ZERO_EXIT_LINE.exec(recordText);
+    return m !== null && m[1] === 'yes';
+}
+
+export interface InviteEnv {
+    readonly ci: boolean;
+    /** `AGENT_CONFIG_NO_UPDATE_CHECK=1`, the kill switch both update concerns honour. */
+    readonly noUpdateCheck: boolean;
+    /** stdout AND stderr are a terminal a human is looking at. */
+    readonly interactive: boolean;
+    readonly headless: boolean;
+    /** The run was asked for machine-readable output. */
+    readonly jsonOutput: boolean;
+    readonly subagent: boolean;
+}
+
+export interface InviteInput {
+    readonly mode: UpdateMode | undefined;
+    /** The ring-0 record's exit line. */
+    readonly ringZeroExited: boolean;
+    /** True once a global live-session register exists — step 1.4. */
+    readonly registerAvailable: boolean;
+    /** The invitation was already shown once. It is a once, not a cadence. */
+    readonly alreadyInvited: boolean;
+    /** The turn that just ended finished on a verified success. */
+    readonly turnEndedOnVerifiedSuccess: boolean;
+    readonly env: InviteEnv;
+}
+
+export type InviteDecision = { readonly ask: true; readonly lines: readonly string[] } | { readonly ask: false; readonly reason: string };
+
+/** The question, once, or the reason there is none. */
+export function autoInviteDecision(input: InviteInput): InviteDecision {
+    if (input.env.ci) return { ask: false, reason: 'CI' };
+    if (input.env.noUpdateCheck) return { ask: false, reason: 'AGENT_CONFIG_NO_UPDATE_CHECK=1' };
+    if (input.env.jsonOutput) return { ask: false, reason: '--json output' };
+    if (input.env.subagent) return { ask: false, reason: 'subagent run' };
+    if (input.env.headless) return { ask: false, reason: 'headless' };
+    if (!input.env.interactive) return { ask: false, reason: 'non-TTY' };
+    // A user-owned opt-in before the rollout switch: the council round of
+    // 2026-10-20 refused a ring-0 record as consent, because once it flips it
+    // opens the question for every install at once. `ask` is the only value
+    // that says "ask me", and only a human can write it.
+    if (input.mode !== 'ask') return { ask: false, reason: 'no user opt-in: update.mode is not ask' };
+    if (!input.ringZeroExited) return { ask: false, reason: 'ring-0 has not exited' };
+    if (!input.registerAvailable) return { ask: false, reason: 'no machine-wide session register' };
+    if (input.alreadyInvited) return { ask: false, reason: 'already invited once' };
+    if (!input.turnEndedOnVerifiedSuccess) return { ask: false, reason: 'the turn did not end on a verified success' };
+    return {
+        ask: true,
+        lines: [
+            'agent-config can install its own updates at a session start, once every gate passes',
+            'and no other session is open on this machine. It is off on your install, and it stays',
+            'off unless you say otherwise — nothing here changes it for you.',
+            '',
+            '  1. Turn it on — set `update: { mode: auto }` in your user-global settings,',
+            '     by hand or in `agent-config setup`.',
+            '  2. Leave it as it is — you keep being told, and nothing installs itself.',
+            '  3. Stop these invitations — set `update.mode` back to `notify`; update notices continue.',
+            '',
+            'Recommendation: 2, unless this machine is one you maintain rather than one you work on.',
+        ],
+    };
+}

package/src/scripts/_lib/update_notice.ts

@@ -0,0 +1,259 @@
+/**
+ * What a session start should say about an available update, and whether it may
+ * activate one — pure, so the hook around it is a thin wiring layer.
+ *
+ * Three properties this module exists to hold, in the order they matter:
+ *
+ * **No fetched text ever reaches the reader.** Everything in the notice is
+ * either a number this module parsed as a semver, a sentence written here, or a
+ * line read from the CHANGELOG of the package that is ALREADY INSTALLED. The
+ * impact map arrives from the registry and is therefore attacker-influenceable;
+ * {@link sanitiseImpactMap} reduces it to a closed enum and a boolean before
+ * anything else looks at it, so a hostile changelog, description or version
+ * label has nothing to travel on. That is roadmap decision D3, implemented as a
+ * shape rather than as a scrubbing pass that could miss a case.
+ *
+ * **Nothing is activated at all, and that is narrower than it started.** A
+ * candidate is STAGED and reported; the install stays with
+ * `upgrade --unattended`, which a human or a scheduler runs. The concern used
+ * to be able to spawn that run itself, and an independent review of 2026-10-20
+ * refused the manifest for it: `effect: notification` means "tells the human
+ * something and changes nothing else", and a hook that can replace the global
+ * install is not that, whatever its `severity` says. The capability was
+ * removed rather than the label widened.
+ *
+ * **A security release is loud in every mode but `off`.** It is the one notice
+ * that does not wait for a mode to invite it, because `SECURITY.md:21` backports
+ * nothing: an install that is not current is an install that is unpatched.
+ */
+import { CONSUMER_IMPACT_VALUES, type ConsumerImpact } from './consumer_impact.js';
+import type { InstallOrigin, UpdateMode } from './classify_update.js';
+import { compare_versions, parse_version } from './version_order.js';
+
+/** The `SECURITY.md` line the security notice names, so the reader can check it. */
+export const SECURITY_POLICY_REF = 'SECURITY.md:21 — fixes land on the latest version only; older releases are not backported';
+
+/** The curated-head labels, most consequential first — the order the one line is picked in. */
+export const HEAD_PRIORITY: readonly string[] = [
+    'Security and correctness',
+    'Default changes + migration',
+    'Known limitations',
+    'Behaviour changes',
+    'Honest nulls',
+];
+
+/** One release's entry in the published impact map, after validation. */
+export interface ImpactEntry {
+    readonly impact: ConsumerImpact;
+    readonly security: boolean;
+}
+
+/**
+ * The registry's `agentConfig.impact` block reduced to versions this module
+ * parsed and values from a closed enum.
+ *
+ * Anything else is dropped rather than reported: a map that does not validate
+ * is an unknown, and an unknown is already handled by never resolving to
+ * `auto`. Returning the forged text so the notice could explain itself would
+ * put attacker-chosen bytes in front of the reader, which is the one thing this
+ * surface may not do.
+ */
+export function sanitiseImpactMap(map: unknown): ReadonlyMap<string, ImpactEntry> {
+    const clean = new Map<string, ImpactEntry>();
+    if (map === null || typeof map !== 'object' || Array.isArray(map)) return clean;
+    for (const [version, entry] of Object.entries(map as Record<string, unknown>)) {
+        if (parse_version(version) === null) continue;
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        const impact = (entry as Record<string, unknown>)['impact'];
+        if (!(CONSUMER_IMPACT_VALUES as readonly unknown[]).includes(impact)) continue;
+        clean.set(version, { impact: impact as ConsumerImpact, security: (entry as Record<string, unknown>)['security'] === true });
+    }
+    return clean;
+}
+
+/** The worst impact and whether any security fix lies in `(installed, candidate]`. */
+export function impactInRange(
+    map: ReadonlyMap<string, ImpactEntry>,
+    installed: string,
+    candidate: string,
+): { readonly worst: ConsumerImpact | null; readonly security: boolean } {
+    const rank = (i: ConsumerImpact): number => CONSUMER_IMPACT_VALUES.indexOf(i);
+    let worst: ConsumerImpact | null = null;
+    let security = false;
+    for (const [version, entry] of map) {
+        if (compare_versions(version, installed) !== 1 || compare_versions(version, candidate) === 1) continue;
+        if (worst === null || rank(entry.impact) > rank(worst)) worst = entry.impact;
+        security = security || entry.security;
+    }
+    return { worst, security };
+}
+
+export interface NoticeEnv {
+    readonly ci: boolean;
+    readonly interactive: boolean;
+    readonly noUpdateCheck: boolean;
+}
+
+export interface NoticeInput {
+    /** The version running right now, from the installed `package.json`. */
+    readonly installed: string;
+    /** The newest version the update probe cached; `null` when it has never run. */
+    readonly candidate: string | null;
+    /** The registry's impact block as cached — untrusted, validated here. */
+    readonly impactMap: unknown;
+    readonly mode: UpdateMode | undefined;
+    readonly origin: InstallOrigin;
+    readonly env: NoticeEnv;
+    /** `{label: text}` from the INSTALLED package's changelog section for {@link installed}. */
+    readonly curatedHead: ReadonlyMap<string, string>;
+    /** The version a previous session staged, if any. */
+    readonly staged: string | null;
+    /** The version this concern last reported as installed, if any. */
+    readonly lastSeenInstalled: string | null;
+    /** True when another session is live on this machine right now. */
+    readonly foreignSessionLive: boolean;
+}
+
+export interface NoticeOutcome {
+    /** Lines for the user, in order. Empty means say nothing. */
+    readonly lines: readonly string[];
+    /** The version to record as staged, or `null` to clear the staging record. */
+    readonly stage: string | null;
+    /**
+     * Always `null`. Kept as a field, not deleted, because its absence is the
+     * finding: an independent review of 2026-10-20 refused the manifest while
+     * this concern could spawn `upgrade --unattended`, on the ground that
+     * `effect: notification` means "tells the human something and changes
+     * nothing else" and a concern that can mutate the installation is not
+     * that. The capability was removed rather than the label widened —
+     * widening a closed effect vocabulary to fit one concern is the shape that
+     * makes the vocabulary stop meaning anything. Activation stays with
+     * `upgrade --unattended`, which a human or a scheduler runs.
+     */
+    readonly activate: null;
+    /** Why nothing was said, for the lifecycle log. `null` when something was. */
+    readonly suppressed: string | null;
+}
+
+const NOTHING = (reason: string): NoticeOutcome => ({ lines: [], stage: null, activate: null, suppressed: reason });
+
+/**
+ * Silences that still reconcile the record: nothing newer is cached, so a
+ * previously staged candidate is stale — typically because it was installed.
+ * Every other silence ({@link noticeSuppression}) is a context that writes
+ * nothing at all, the kill switch included.
+ */
+export const RECONCILE_REASONS: ReadonlySet<string> = new Set(['no cached candidate', 'nothing newer cached']);
+
+/** Contexts where a session start says nothing and writes nothing. */
+export function noticeSuppression(input: Pick<NoticeInput, 'env' | 'origin' | 'mode'>): string | null {
+    if (input.env.ci) return 'CI';
+    if (!input.env.interactive) return 'non-interactive';
+    if (input.env.noUpdateCheck) return 'AGENT_CONFIG_NO_UPDATE_CHECK=1';
+    if (input.origin === 'source-checkout') return 'source checkout';
+    if (input.origin === 'ephemeral') return 'ephemeral run';
+    if (input.mode === 'off') return 'update.mode off';
+    return null;
+}
+
+/** The one curated-head line for a version, or `null` when the head says nothing. */
+export function oneCuratedLine(head: ReadonlyMap<string, string>): string | null {
+    for (const label of HEAD_PRIORITY) {
+        const text = head.get(label);
+        if (text !== undefined && text.trim() !== '' && text.trim() !== '_none_') {
+            return `${label}: ${text.trim()}`;
+        }
+    }
+    return null;
+}
+
+/**
+ * The candidate as the reader sees it: rebuilt from the parsed numeric core.
+ * The cached string came from the registry, and `parse_version` accepts a
+ * prerelease label of any length, so the label itself is never printed.
+ */
+function shownVersion(candidate: string): string {
+    const v = parse_version(candidate)!;
+    return `${v.major}.${v.minor}.${v.patch}${v.pre.length > 0 ? ' (pre-release)' : ''}`;
+}
+
+/**
+ * What to say and what may happen.
+ *
+ * The post-update branch comes first because it is the one that reports a
+ * change that already occurred; an available-update notice about a version the
+ * reader just moved past would be noise.
+ */
+export function updateNotice(input: NoticeInput): NoticeOutcome {
+    const suppressed = noticeSuppression(input);
+    if (suppressed !== null) return NOTHING(suppressed);
+
+    // Post-update: the installed version moved since this concern last looked.
+    if (input.lastSeenInstalled !== null && compare_versions(input.installed, input.lastSeenInstalled) === 1) {
+        const line = oneCuratedLine(input.curatedHead);
+        const lines = [`agent-config is now ${input.installed} (was ${input.lastSeenInstalled}).`];
+        if (line !== null) lines.push(`  ${line}`);
+        return { lines, stage: null, activate: null, suppressed: null };
+    }
+
+    if (input.candidate === null || parse_version(input.candidate) === null) return NOTHING('no cached candidate');
+    if (compare_versions(input.candidate, input.installed) !== 1) return NOTHING('nothing newer cached');
+
+    const range = impactInRange(sanitiseImpactMap(input.impactMap), input.installed, input.candidate);
+    const lines = [`agent-config ${shownVersion(input.candidate)} is available (installed: ${input.installed}).`];
+    if (range.security) lines.push(`  Security fix in range. ${SECURITY_POLICY_REF}.`);
+    if (range.worst === 'notice') lines.push('  A release in range carries a notice — read it before upgrading.');
+    if (range.worst === 'action') lines.push('  A release in range needs a hand; it is never installed unattended.');
+
+    // Staging only. This concern records which candidate it verified and says
+    // so; it installs nothing, ever. Under `auto` it still names the live-session
+    // state, because that is what decides whether an `upgrade --unattended` run
+    // would be allowed to swap at all, and a reader under `auto` is entitled to
+    // know which of the two reasons is holding their install back.
+    const stageable = range.worst !== 'action';
+
+    if (input.mode === 'auto' && stageable) {
+        lines.push(
+            input.foreignSessionLive
+                ? '  Staged. Another session is open on this machine, so a swap would break its hooks.'
+                : '  Staged. Run `agent-config upgrade --unattended` to install it.',
+        );
+    } else {
+        lines.push('  Run `agent-config upgrade` to install it.');
+    }
+
+    return { lines, stage: stageable ? input.candidate : null, activate: null, suppressed: null };
+}
+
+/**
+ * The curated head of one version's CHANGELOG section, as `{label: text}`.
+ *
+ * Parses the SHIPPED changelog — the one inside the installed package — which
+ * is why this takes text rather than a path: the caller decides which tree it
+ * is reading, and no caller may point it at a fetched document.
+ *
+ * The shape is the one `_lib/release_highlights.ts` writes: a `## [<version>]`
+ * section, a `### Release highlights` heading inside it, then one
+ * `- **<Label>:** <text>` bullet per label. A section without a highlights
+ * heading yields an empty map, which the notice renders as no line at all —
+ * absence is a legitimate answer here, not an error.
+ */
+export function parseCuratedHead(changelog: string, version: string): ReadonlyMap<string, string> {
+    const head = new Map<string, string>();
+    const lines = changelog.split('\n');
+    const sectionStart = lines.findIndex((l) => new RegExp(`^## \\[?${version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\]?(\\s|$)`).test(l));
+    if (sectionStart < 0) return head;
+    let inHighlights = false;
+    for (let i = sectionStart + 1; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        if (/^#{1,2} /.test(line)) break; // the next release section, or a new era
+        if (/^### /.test(line)) {
+            inHighlights = /^### Release highlights\s*$/.test(line);
+            continue;
+        }
+        if (!inHighlights) continue;
+        const m = /^- \*\*(.+?):\*\*\s*(.*)$/.exec(line);
+        if (m !== null) head.set(m[1] as string, (m[2] as string).trim());
+    }
+    return head;
+}