@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_cli/cmd_route_explain.ts

@@ -32,6 +32,10 @@ import {
 import { measure, method_note } from '../_lib/token_count.js';
 import { load_agent_settings } from '../_lib/agent_settings.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { resolveSkillCatalogueRoots } from '../_lib/skill_catalogue.js';
+import { splitQualifiedName } from '../_lib/skill_origin.js';
+import { rankDetailed, type RankRow } from '../skill_tools/score_skill_relevance.js';
+import { DEFAULT_SUGGEST_LIMIT } from '../../shared/skillRanking.js';
 
 // Marker-anchored, not hop-counted: this module runs from `src/scripts/_cli/`
 // (three levels down) AND from the precompiled `dist/cli-delegate/` (two), and
@@ -231,16 +235,162 @@ export function render_text(report: Report): string {
     return out.join('\n') + '\n';
 }
 
+/**
+ * `--skills "<task>"` — the SAME ranked rows the MCP servers return, on a host
+ * that has no MCP server at all.
+ *
+ * WHY A FLAG AND NOT A VERB. The ranker already exists as a script; what was
+ * missing was a reachable `agent-config` surface for it. A new top-level verb
+ * is the thing the package's own kill register refuses, and this answers the
+ * same question `route:explain` already answers — "what does this prompt
+ * reach" — one layer up from rules.
+ *
+ * WHY IT NAMES THE ROOT. Reproduced before the fallback below existed: a
+ * workspace carrying only another host's directory, with an empty home,
+ * resolves to zero catalogue roots and the shell path answers nothing, even
+ * though the installed package ships its own projected skills. The fallback
+ * closes that — but a row ranked out of the PACKAGE's own tree is a different
+ * claim from a row ranked out of the consumer's catalogue, so the output says
+ * which root answered rather than leaving the reader to assume.
+ */
+export interface SkillRow {
+    skill: string;
+    score: number;
+    personas: string[];
+    description: string;
+}
+
+export interface SkillsReport {
+    measurement_level: string;
+    task: string;
+    /** Every root that was ranked, in precedence order. Empty is a real answer. */
+    skills_roots: string[];
+    /** True when the ONLY root is the installed package's own projection. */
+    package_fallback_used: boolean;
+    skills_indexed: number;
+    limit: number;
+    suggestions: SkillRow[];
+    /**
+     * Ranked rows reachable from the installed package's own projection whose
+     * name no resolved root carries — a skill the package ships but this host
+     * does not have. Empty when the projection IS the only root: then every
+     * suggestion is not installed, and the text output says so per row.
+     */
+    not_installed: SkillRow[];
+}
+
+export const SKILLS_MEASUREMENT_HEADER =
+    'Measurement level: lexical ranking only — a high score is a pointer, not a verdict.';
+
+export function build_skills_report(
+    task: string,
+    opts: { workspaceRoot: string; packageRoot: string; limit: number; home?: string },
+): SkillsReport {
+    const roots = resolveSkillCatalogueRoots(opts.workspaceRoot, opts.home, {
+        packageFallback: opts.packageRoot,
+    });
+    const packageRootAbs = path.join(opts.packageRoot, 'dist', 'agent-src', 'skills');
+    const { rows, descriptions } = roots.length > 0
+        ? rankDetailed(task, roots)
+        : { rows: [], descriptions: new Map<string, string>() };
+    const fallbackOnly = roots.length === 1 && roots[0] === packageRootAbs;
+    const toRow = (d: ReadonlyMap<string, string>) => ([name, score, personas]: RankRow): SkillRow => ({
+        skill: name,
+        score,
+        personas,
+        description: d.get(name) ?? '',
+    });
+    let notInstalled: SkillRow[] = [];
+    if (roots.length > 0 && !fallbackOnly && _hasSkills(packageRootAbs)) {
+        const installed = new Set(roots.flatMap(_skillNames));
+        const pkg = rankDetailed(task, [packageRootAbs]);
+        notInstalled = pkg.rows
+            .filter(([name]) => !installed.has(splitQualifiedName(name).name))
+            .slice(0, opts.limit)
+            .map(toRow(pkg.descriptions));
+    }
+    return {
+        measurement_level: SKILLS_MEASUREMENT_HEADER,
+        task,
+        skills_roots: roots,
+        package_fallback_used: fallbackOnly,
+        skills_indexed: rows.length,
+        limit: opts.limit,
+        suggestions: rows.slice(0, opts.limit).map(toRow(descriptions)),
+        not_installed: notInstalled,
+    };
+}
+
+function _skillNames(root: string): string[] {
+    try {
+        return fs
+            .readdirSync(root)
+            .filter((n) => fs.existsSync(path.join(root, n, 'SKILL.md')));
+    } catch {
+        return [];
+    }
+}
+
+function _hasSkills(root: string): boolean {
+    return _skillNames(root).length > 0;
+}
+
+function _pushRow(out: string[], r: SkillRow, label: string): void {
+    out.push(`  · ${r.skill}  [${r.score}]${label}`);
+    if (r.description) out.push(`      ${r.description}`);
+    if (r.personas.length > 0) out.push(`      personas: ${r.personas.join(', ')}`);
+}
+
+export function render_skills_text(report: SkillsReport): string {
+    const out: string[] = [report.measurement_level, ''];
+    out.push(`task: ${JSON.stringify(report.task)}`);
+    if (report.skills_roots.length === 0) {
+        out.push('catalogue: NONE readable — no workspace root, no host root, no package fallback.');
+        out.push('');
+        out.push('  · (no catalogue to rank — this is "unknown", never "no skill covers this")');
+        return out.join('\n') + '\n';
+    }
+    out.push(
+        `catalogue: ${report.skills_roots.join(' · ')}`
+        + (report.package_fallback_used ? "  [the installed package's own projection — no workspace or host root resolved]" : ''),
+    );
+    out.push('');
+    out.push(`ranked skills (${report.suggestions.length} of ${report.skills_indexed} scoring above zero, limit ${report.limit}):`);
+    const label = report.package_fallback_used ? '  not-installed' : '';
+    for (const r of report.suggestions) _pushRow(out, r, label);
+    if (report.suggestions.length === 0) {
+        out.push('  · (nothing scored above zero — say that, and proceed without a skill)');
+    }
+    if (report.not_installed.length > 0) {
+        out.push('');
+        out.push(
+            `not installed on this host — reachable from the installed package's own projection (${report.not_installed.length}):`,
+        );
+        for (const r of report.not_installed) _pushRow(out, r, '  not-installed');
+    }
+    return out.join('\n') + '\n';
+}
+
 export function main(argv: string[]): number {
     const args = [...argv];
     const as_json = args.includes('--json');
     let files: string[] = [];
     let profile = 'full';
+    let skillsTask: string | null = null;
+    let limit = DEFAULT_SUGGEST_LIMIT;
     const positional: string[] = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i] as string;
         if (a === '--json') continue;
-        if (a === '--files') {
+        if (a === '--skills') {
+            skillsTask = String(args[++i] ?? '');
+        } else if (a.startsWith('--skills=')) {
+            skillsTask = a.slice('--skills='.length);
+        } else if (a === '--limit') {
+            limit = Number.parseInt(String(args[++i] ?? ''), 10);
+        } else if (a.startsWith('--limit=')) {
+            limit = Number.parseInt(a.slice('--limit='.length), 10);
+        } else if (a === '--files') {
             files = String(args[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
         } else if (a.startsWith('--files=')) {
             files = a.slice('--files='.length).split(',').map((s) => s.trim()).filter(Boolean);
@@ -250,13 +400,37 @@ export function main(argv: string[]): number {
             profile = a.slice('--profile='.length);
         } else if (a === '-h' || a === '--help') {
             process.stdout.write(
-                'usage: agent-config route:explain "<prompt>" [--files a,b] [--profile full|balanced] [--json]\n',
+                'usage: agent-config route:explain "<prompt>" [--files a,b] [--profile full|balanced] [--json]\n'
+                + '       agent-config route:explain --skills "<task>" [--limit N] [--json]\n',
             );
             return 0;
         } else {
             positional.push(a);
         }
     }
+    if (skillsTask !== null) {
+        const task = (skillsTask.trim() === '' ? positional.join(' ') : skillsTask).trim();
+        if (!task) {
+            process.stderr.write('route:explain: --skills needs a task description\n');
+            return 2;
+        }
+        if (!Number.isFinite(limit) || limit < 1) {
+            process.stderr.write('route:explain: --limit expects a positive integer\n');
+            return 2;
+        }
+        const report = build_skills_report(task, {
+            workspaceRoot: process.cwd(),
+            packageRoot: REPO_ROOT,
+            limit,
+        });
+        process.stdout.write(
+            as_json ? JSON.stringify(report, null, 2) + '\n' : render_skills_text(report),
+        );
+        // 1 is "nothing to show", the same meaning the rule arm gives it. A
+        // catalogue that could not be read and a catalogue with no match are
+        // both 1 here and are distinguished in the OUTPUT, never silently.
+        return report.suggestions.length === 0 && report.not_installed.length === 0 ? 1 : 0;
+    }
     const prompt = positional.join(' ').trim();
     if (!prompt) {
         process.stderr.write('route:explain: a prompt is required\n');

package/src/scripts/_cli/cmd_uninstall.ts

@@ -61,12 +61,23 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as fs_atomic from '../_lib/fs_atomic.js';
+import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
 import { remove_managed_hooks } from '../_lib/claude_settings_hooks.js';
+import {
+    recordPath as overridesRecordPath,
+    removeListingOverrides,
+} from '../_lib/skill_listing_overrides.js';
+import {
+    codexSkillRoots,
+    recordPath as codexResidentRecordPath,
+    removeCodexResidentSet,
+} from '../_lib/codex_resident_set.js';
 import { resolve_project_root } from '../_lib/agent_settings.js';
 import { subtract_pointers } from '../_lib/json_pointers.js';
 import { PROJECT_BRIDGE_MARKERS, USER_SCOPE_PATHS } from '../install.js';
+import { removeStagedRuntime } from '../../install/stagedRuntime.js';
 
 type AnyDict = Record<string, unknown>;
 
@@ -256,10 +267,39 @@ function _remove_project_marker(
     }
 }
 
-function _remove_global_content(
+/**
+ * Delete the files a previous global deploy RECORDED writing under `anchor`.
+ *
+ * This used to call `fs.rmSync` recursively on the resolved anchor itself —
+ * spelled out rather than quoted, because AC-2 of
+ * `road-to-an-uninstall-that-only-removes-what-it-brought` greps this file for
+ * that exact call and a comment reproducing it would read as a survivor.
+ * The anchors are whole host configuration roots — `~/.claude/`,
+ * `~/.codex/`, `~/.config/zed/` — so a purge took everything under them,
+ * whoever wrote it, including a host's own credentials file. That is not a
+ * quirk this port replicated from Python deliberately; it is a defect, and the
+ * ownership proof that fixes it has existed since the 2026-06 Zed fix:
+ * `global_deploy_inventory` records, per tool, the anchor plus the
+ * anchor-relative path of every file the deploy maintains there.
+ *
+ * Three properties, each one a thing the old code could not do:
+ *
+ * - **Only recorded paths are deleted.** `recorded_rel_files` returns the empty
+ *   set when the inventory's anchor does not match the one being purged, so a
+ *   moved anchor purges nothing rather than purging the wrong tree.
+ * - **An unreadable or empty record REFUSES.** There is deliberately no
+ *   fall-back to the old recursive delete: a fall-back on missing evidence is
+ *   how this defect would return on the first corrupted inventory.
+ * - **Symlinks are unlinked, never followed.** `lstatSync` + `unlinkSync`, so a
+ *   recorded path that is a link removes the link and leaves its target alone.
+ *
+ * Directories are pruned only when they are left empty, and only up to the
+ * anchor — an anchor that still holds a user's own files stays.
+ */
+export function _remove_global_content(
     tool: string,
     opts: { dry_run: boolean; purge: boolean },
-): [string, boolean] {
+): [string, boolean, boolean?] {
     const anchor = USER_SCOPE_PATHS[tool];
     if (!anchor) {
         return [`${tool}: no global anchor registered (skipped)`, false];
@@ -269,21 +309,95 @@ function _remove_global_content(
         return [`${tool}: ${anchor} already absent`, false];
     }
     if (!opts.purge) {
-        return [`${tool}: ${anchor} preserved (pass --purge to delete)`, false];
+        return [
+            `${tool}: ${anchor} preserved (--purge removes the files this package recorded writing there)`,
+            false,
+        ];
     }
+
+    let recorded: ReadonlySet<string>;
+    try {
+        recorded = global_deploy_inventory.recorded_rel_files(tool, target);
+    } catch (exc) {
+        return [
+            `${tool}: ❌ refusing to purge ${anchor} — deploy inventory unreadable (${_osErr(exc)})`,
+            false,
+            true,
+        ];
+    }
+    if (recorded.size === 0) {
+        return [
+            `${tool}: ❌ refusing to purge ${anchor} — no recorded inventory for this anchor; nothing was deleted`,
+            false,
+            true,
+        ];
+    }
+
     if (opts.dry_run) {
-        return [`${tool}: would purge ${anchor}`, true];
+        return [`${tool}: would purge ${recorded.size} recorded file(s) under ${anchor}`, true];
     }
+
+    const resolved_anchor = path.resolve(target);
+    // The lexical check below does not see a symlinked intermediate directory,
+    // so each parent is also resolved and held to the anchor's real path.
+    let real_anchor: string;
     try {
-        if (_isDir(target)) {
-            fs.rmSync(target, { recursive: true, force: false });
-        } else {
-            fs.unlinkSync(target);
-        }
-        return [`${tool}: purged ${anchor}`, true];
+        real_anchor = fs.realpathSync(resolved_anchor);
     } catch (exc) {
-        return [`${tool}: ❌ failed to purge ${anchor} (${_osErr(exc)})`, false];
+        return [`${tool}: ❌ refusing to purge ${anchor} — anchor unresolvable (${_osErr(exc)})`, false, true];
+    }
+    const really_inside = (p: string): boolean => {
+        try {
+            const real = fs.realpathSync(p);
+            return real === real_anchor || real.startsWith(real_anchor + path.sep);
+        } catch {
+            return false;
+        }
+    };
+    let deleted = 0;
+    const touched_dirs = new Set<string>();
+    for (const rel of recorded) {
+        const abs = path.resolve(resolved_anchor, rel);
+        // Containment, re-checked here rather than trusted: a `..` in a
+        // recorded path must not reach outside the anchor even if the record
+        // was written by an older or tampered-with install.
+        if (abs !== resolved_anchor && !abs.startsWith(resolved_anchor + path.sep)) {
+            continue;
+        }
+        if (!really_inside(path.dirname(abs))) {
+            continue;
+        }
+        try {
+            // lstat, so a symlink is removed as a link and its target is not
+            // touched; a directory recorded by mistake is skipped rather than
+            // recursed into.
+            const st = fs.lstatSync(abs);
+            if (st.isDirectory()) continue;
+            fs.unlinkSync(abs);
+            deleted += 1;
+            touched_dirs.add(path.dirname(abs));
+        } catch {
+            // Already gone is success; anything else is reported by the count.
+        }
     }
+
+    // Prune directories this package emptied, deepest first, never the anchor's
+    // parent and never a directory that still holds somebody else's file.
+    for (const dir of [...touched_dirs].sort((a, b) => b.length - a.length)) {
+        let cur = dir;
+        while (cur.startsWith(resolved_anchor + path.sep)) {
+            try {
+                if (!really_inside(cur) || fs.realpathSync(cur) === real_anchor) break;
+                if (fs.readdirSync(cur).length > 0) break;
+                fs.rmdirSync(cur);
+            } catch {
+                break;
+            }
+            cur = path.dirname(cur);
+        }
+    }
+
+    return [`${tool}: purged ${deleted} recorded file(s) under ${anchor}`, deleted > 0];
 }
 
 /** Render an OSError-shaped message: Python `str(OSError)` is the strerror. */
@@ -668,6 +782,16 @@ function _uninstall_project(opts: Options): number {
             continue;
         }
 
+        if (entry['scope'] === 'global') {
+            // A global entry's files belong to the user-scoped ledger; a lock
+            // committed before they left it still lists `$HOME` paths, and the
+            // project-marker map below names a PROJECT file the global install
+            // never wrote. Neither is this command's to delete: `uninstall --global` is.
+            const verb = opts.dry_run ? 'would remove' : 'removed';
+            _print(_stdout, `  · ${tool}: ${verb} global-scope entry, no file touched (content: \`uninstall --global\`)`);
+            if (!opts.dry_run) removed_names.push(tool);
+            continue;
+        }
         if (!_is_v2_entry(entry)) {
             // v1 entry — keep the legacy single-marker behaviour.
             const [line, removed] = _remove_project_marker(project_root, tool, {
@@ -738,6 +862,56 @@ function _uninstall_project(opts: Options): number {
     return 0;
 }
 
+/**
+ * Tools whose anchor still holds files the deploy inventory records.
+ *
+ * The lockfile is what makes a purge possible at all: `_uninstall_global`
+ * resolves the tool set from it, so a run that finds no lockfile prints
+ * `no tools to uninstall` and returns before the deletion function is
+ * reached. Deleting the lockfile while recorded content is still on disk
+ * therefore does not merely lose a record — it strands the content, because
+ * the inventory is a deletion ALLOWLIST (D1) and there is deliberately no
+ * path that deletes without one.
+ *
+ * Measured end to end on 2026-10-16: `uninstall --global` then
+ * `uninstall --global --purge` gave `plain_rc=0 purge_after_rc=1
+ * files_left=892` — the run and its reproduction are recorded in
+ * `tests/install/uninstall_lockfile_retention.test.ts`, which pins the flow at
+ * CLI level. The sibling unit case passed throughout, because the
+ * defect sits between the deletion function and the lockfile block that runs
+ * after it.
+ *
+ * An unreadable record counts as content left, deliberately: that is the
+ * state in which the lockfile is most needed and least able to prove it.
+ */
+function _tools_with_recorded_content_left(tools: readonly string[]): string[] {
+    const left: string[] = [];
+    for (const tool of tools) {
+        const anchor = USER_SCOPE_PATHS[tool];
+        if (!anchor) {
+            continue;
+        }
+        const target = expanduser(anchor);
+        if (!_exists(target)) {
+            continue;
+        }
+        let recorded: ReadonlySet<string>;
+        try {
+            recorded = global_deploy_inventory.recorded_rel_files(tool, target);
+        } catch {
+            left.push(tool);
+            continue;
+        }
+        for (const rel of recorded) {
+            if (_exists(path.join(target, rel))) {
+                left.push(tool);
+                break;
+            }
+        }
+    }
+    return left;
+}
+
 function _uninstall_global(opts: Options): number {
     const lock_path = installed_lock.lockfile_path();
     const write_path = installed_lock.lockfile_write_path();
@@ -763,22 +937,65 @@ function _uninstall_global(opts: Options): number {
         `${opts.dry_run ? '[dry-run] ' : ''}uninstalling ${tools.length} tool(s) from global scope:`,
     );
     const removed_names: string[] = [];
+    // A purge that REFUSED must not look like a purge that succeeded. The
+    // refusal is the whole point of reading the inventory — reporting it on
+    // stdout and exiting 0 would leave the caller believing the content is
+    // gone, which is the state this fix exists to make impossible.
+    let refused = false;
+    // The codex resident set writes one policy file into each non-resident skill
+    // directory. That file is not in the deploy inventory, so the content removal
+    // below cannot see it — drop it first, or it survives as the only thing left
+    // in a directory the uninstall emptied.
+    if (tools.includes('codex') && !opts.dry_run) {
+        try {
+            let removed = 0;
+            let kept = 0;
+            let finder = 0;
+            for (const anchor of codexSkillRoots(os.homedir())) {
+                const res = removeCodexResidentSet(anchor, codexResidentRecordPath(anchor));
+                removed += res.removed.length;
+                kept += res.kept_user.length;
+                if (res.finder === 'removed') finder += 1;
+            }
+            if (removed > 0 || kept > 0 || finder > 0) {
+                _print(
+                    _stdout,
+                    `  · codex: removed ${removed} resident-set policy file(s) and ${finder} finder entr(ies), ` +
+                        `kept ${kept} the user changed`,
+                );
+            }
+        } catch (e) {
+            _print(_stderr, `⚠️  codex: resident-set removal skipped — ${String(e)}`);
+        }
+    }
     for (const tool of tools) {
-        const [line, removed] = _remove_global_content(tool, {
+        const [line, removed, refusedHere] = _remove_global_content(tool, {
             dry_run: opts.dry_run,
             purge: opts.purge,
         });
         _print(_stdout, `  · ${line}`);
+        if (refusedHere === true) {
+            refused = true;
+        }
         if (removed && !opts.dry_run) {
             removed_names.push(tool);
         }
     }
-    // Managed Claude hooks live in ~/.claude/settings.json (single-surface
-    // model) — remove exactly our entries, never user-owned ones.
+    // The staged hook runtime is the package's own; a plain uninstall keeps it
+    // because the preserved stubs under ~/.claude point into it.
+    if (tools.includes('claude-code') && opts.purge && !refused && !opts.dry_run) {
+        const staged = removeStagedRuntime();
+        if (staged !== null) _print(_stdout, `  · claude-code: removed the staged hook runtime (${staged})`);
+    }
+    // Managed Claude hooks and the listing override live in ~/.claude/settings.json
+    // (single-surface model) — remove exactly our entries, never user-owned ones.
     if (tools.includes('claude-code')) {
         const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
         if (opts.dry_run) {
-            _print(_stdout, `  · claude-code: would remove managed hooks from ${settings_path}`);
+            _print(
+                _stdout,
+                `  · claude-code: would remove managed hooks and recorded listing overrides from ${settings_path}`,
+            );
         } else {
             try {
                 const res = remove_managed_hooks(settings_path);
@@ -791,6 +1008,18 @@ function _uninstall_global(opts: Options): number {
             } catch (e) {
                 _print(_stderr, `⚠️  claude-code: managed-hook removal skipped — ${String(e)}`);
             }
+            try {
+                const res = removeListingOverrides(settings_path, overridesRecordPath());
+                if (res.changed || res.kept_user.length > 0) {
+                    _print(
+                        _stdout,
+                        `  · claude-code: removed ${res.removed.length} listing override(s), ` +
+                            `kept ${res.kept_user.length} the user changed`,
+                    );
+                }
+            } catch (e) {
+                _print(_stderr, `⚠️  claude-code: listing-override removal skipped — ${String(e)}`);
+            }
         }
     }
     if (lock !== null && !opts.dry_run) {
@@ -812,21 +1041,36 @@ function _uninstall_global(opts: Options): number {
                 `✅  lockfile updated (${tools.length} entries removed, ${remaining.length} kept)`,
             );
         } else {
-            // Python iterates a set `{lock_path, write_path}` (order
-            // irrelevant — both unlinks are best-effort, no output depends
-            // on order); a deduped list reproduces it.
-            const targets = lock_path === write_path ? [write_path] : [lock_path, write_path];
-            for (const target of targets) {
-                try {
-                    fs.unlinkSync(target);
-                } catch {
-                    // pass
+            // Nothing is left to KEEP in the lockfile — but that is not the
+            // same question as whether the lockfile may go. See
+            // `_tools_with_recorded_content_left`: the record is the only
+            // route to the content it records.
+            const stranded = refused ? tools : _tools_with_recorded_content_left(tools);
+            if (stranded.length) {
+                _print(
+                    _stdout,
+                    `ℹ️   lockfile kept (${write_path}) — ${stranded.join(', ')} still holds ` +
+                        'files this package recorded writing; `--purge` removes them, and ' +
+                        'without this record nothing can',
+                );
+            } else {
+                // Python iterates a set `{lock_path, write_path}` (order
+                // irrelevant — both unlinks are best-effort, no output depends
+                // on order); a deduped list reproduces it.
+                const targets =
+                    lock_path === write_path ? [write_path] : [lock_path, write_path];
+                for (const target of targets) {
+                    try {
+                        fs.unlinkSync(target);
+                    } catch {
+                        // pass
+                    }
                 }
+                _print(_stdout, `✅  lockfile deleted (${write_path})`);
             }
-            _print(_stdout, `✅  lockfile deleted (${write_path})`);
         }
     }
-    return 0;
+    return refused ? 1 : 0;
 }
 
 export function main(argv: string[] | null = null): number {

package/src/scripts/_cli/cmd_update.ts

@@ -14,7 +14,9 @@
  *
  * Flags:
  *
- * - `--check` — print the available latest version + return; no write.
+ * - `--check` — print the available latest version + return; no write. In a
+ *   project that pins a version, also list what the latest release's impact
+ *   map records between the pin and latest (skipped with `--offline`).
  * - `--to <version>` — pin to an exact version (registry-existence checked).
  *   Downgrades are allowed; the pin is a project decision.
  * - (no flag) — pin to the registry's `latest` tag.
@@ -68,6 +70,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as update_check from '../_lib/update_check.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { pin_advice_lines } from '../_lib/pin_advice.js';
 import {
     DEFAULT_PROJECT_FILE,
     LOCAL_PROJECT_FILE,
@@ -291,6 +294,30 @@ function _read_pin_line(p: string): number | null {
     return null;
 }
 
+/** The pinned version in `p`, unquoted; `null` when the file carries no pin. */
+function _read_pin_value(p: string): string | null {
+    const idx = _read_pin_line(p);
+    if (idx === null) return null;
+    const line = _splitlinesKeepends(fs.readFileSync(p, { encoding: 'utf-8' }))[idx] as string;
+    const raw = (PIN_LINE_RE.exec(line)?.[2] ?? '').replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '');
+    return raw === '' ? null : _normalize(raw);
+}
+
+/** The release's `agentConfig.impact`: `null` when the document carries none, `undefined` when it could not be fetched. */
+async function _fetch_impact_map(version: string, timeout = 1.0): Promise<unknown> {
+    try {
+        const resp = await fetch(REGISTRY_VERSION_URL.replace('{version}', _normalize(version)), {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(timeout * 1000),
+        });
+        if (resp.status !== 200) return undefined;
+        const doc = (await resp.json()) as { agentConfig?: { impact?: unknown } } | null;
+        return doc?.agentConfig?.impact ?? null;
+    } catch {
+        return undefined;
+    }
+}
+
 /** Rewrite the pin in `path`; return `true` if the file changed. */
 function _write_pin(p: string, new_version: string): boolean {
     const target = `agent_config_version: "${_normalize(new_version)}"\n`;
@@ -374,6 +401,7 @@ interface MainOptions {
     fetcher?: () => string | null | Promise<string | null>;
     version_checker?: (version: string) => boolean | Promise<boolean>;
     cache_warmer?: (version: string) => void;
+    impact_fetcher?: (version: string) => unknown;
     state_path?: string | null;
     out?: OutSink;
     err?: OutSink;
@@ -490,6 +518,11 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         } else {
             _print(out, `agent-config is up to date (${installed_version}).`);
         }
+        const pin = _read_pin_value(_find_pin_file(cwd));
+        if (pin !== null && !offline) {
+            const fetch_impact = options.impact_fetcher ?? _fetch_impact_map;
+            for (const line of pin_advice_lines(pin, latest, await fetch_impact(latest), args.to ? 'target' : 'latest')) _print(out, line);
+        }
         return 0;
     }