@event4u/agent-config 16.5.0 → 17.1.0

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;
     }
 
@@ -509,7 +542,7 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         cache_warmer(latest);
     }
     _refresh_state(latest, latest, state_path);
-    _refresh_global_lockfile(latest, out);
+    _report_global_install(latest, out);
     return 0;
 }
 
@@ -523,30 +556,28 @@ function _relativeToOr(target: string, base: string): string {
 }
 
 /**
- * Update the global `installed.lock` if it exists.
- *
- * Resolution prefers `~/.event4u/agent-config/installed.lock` and falls back to
- * the legacy `~/.config/agent-config/installed.lock`.
+ * Name `agent-config upgrade` when the global install is older than the pin.
  *
- * Phase 1.6 — the lockfile is only present when the user has run a global
- * install; we never create one here, but we keep it in lockstep when `update`
- * flips the pin. Atomic write goes through `installed_lock.write_lockfile`.
+ * Read-only by design: `installed.lock` records what the global install
+ * deployed, and `upgrade` (plus its `--check` and unattended paths) reads it as
+ * the installed version. This command used to rewrite it to the pin, so after
+ * `update` the lock claimed a version no `npm install -g` had installed and
+ * `upgrade --check` reported "up to date" over the old binary.
  */
-function _refresh_global_lockfile(version: string, out: OutSink): void {
-    const read_path = installed_lock.lockfile_path();
-    const write_path = installed_lock.lockfile_write_path();
-    const existing = installed_lock.read_lockfile(read_path);
+function _report_global_install(version: string, out: OutSink): void {
+    const existing = installed_lock.read_lockfile(installed_lock.lockfile_path());
     if (existing === null) {
         return;
     }
     const recorded = (existing as unknown as Record<string, unknown>)['agent_config_version'];
-    const tools = [...(existing.tools ?? [])];
-    if (recorded === version && read_path === write_path) {
-        _print(out, `ℹ️  ${write_path} already records ${version}.`);
+    if (typeof recorded !== 'string' || !update_check._is_newer(version, _normalize(recorded))) {
         return;
     }
-    installed_lock.write_lockfile(version, tools, { path: write_path });
-    _print(out, `✅  Refreshed global lockfile at ${write_path}.`);
+    _print(
+        out,
+        `ℹ️  The global install is ${_normalize(recorded)}; this pin does not change it. ` +
+            `Run \`agent-config upgrade\` to install ${version} globally.`,
+    );
 }
 
 /** Read `version` from the package's own `package.json`. */

package/src/scripts/_cli/cmd_upgrade.ts

@@ -94,6 +94,7 @@ import { event4u_root, write_target } from '../_lib/user_global_paths.js';
 import { project_settings_path } from '../_lib/agent_settings.js';
 import { _is_source_repo } from './cmd_refresh.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { parse_version } from '../_lib/version_order.js';
 
 const PACKAGE_NAME = '@event4u/agent-config';
 const PACKAGE_ROOT = resolvePackageRoot(import.meta.url);
@@ -409,10 +410,12 @@ interface Args {
     check: boolean;
     dry_run: boolean;
     converge: boolean;
+    unattended: boolean;
+    skip: string | null;
 }
 
 const PROG = 'agent-config upgrade';
-const USAGE = `usage: ${PROG} [-h] [--check] [--dry-run] [--converge]\n`;
+const USAGE = `usage: ${PROG} [-h] [--check] [--dry-run] [--converge] [--unattended] [--skip VERSION]\n`;
 
 function _argError(msg: string): never {
     _stderr.write(USAGE);
@@ -421,7 +424,7 @@ function _argError(msg: string): never {
 }
 
 function _parse(argv: string[]): Args {
-    const args: Args = { check: false, dry_run: false, converge: false };
+    const args: Args = { check: false, dry_run: false, converge: false, unattended: false, skip: null };
     const positionals: string[] = [];
     let i = 0;
     while (i < argv.length) {
@@ -457,6 +460,23 @@ function _parse(argv: string[]): Args {
             i += 1;
             continue;
         }
+        if (flag === '--unattended') {
+            if (inlineVal !== null) {
+                _argError(`argument --unattended: ignored explicit argument '${inlineVal}'`);
+            }
+            args.unattended = true;
+            i += 1;
+            continue;
+        }
+        if (flag === '--skip') {
+            const value = inlineVal ?? argv[i + 1];
+            if (value === undefined || value === '' || (inlineVal === null && value.startsWith('-'))) {
+                _argError('argument --skip: expected one argument');
+            }
+            args.skip = lstripV(value.trim());
+            i += inlineVal === null ? 2 : 1;
+            continue;
+        }
         if (a.startsWith('-') && a !== '-') {
             _argError(`unrecognized arguments: ${a}`);
         }
@@ -466,6 +486,15 @@ function _parse(argv: string[]): Args {
     if (positionals.length > 0) {
         _argError(`unrecognized arguments: ${positionals.join(' ')}`);
     }
+    if (args.unattended && (args.check || args.converge || args.skip !== null)) {
+        _argError('argument --unattended: not allowed with --check, --converge or --skip');
+    }
+    if (args.skip !== null && (args.check || args.dry_run || args.converge)) {
+        _argError('argument --skip: not allowed with --check, --dry-run or --converge');
+    }
+    if (args.skip !== null && parse_version(args.skip) === null) {
+        _argError(`argument --skip: '${args.skip}' is not a version`);
+    }
     return args;
 }
 
@@ -485,6 +514,13 @@ export async function main(argv: string[] | null = null, options: MainOptions =
     const err = options.err ?? _stderr;
     const args = _parse(argv ?? process.argv.slice(2));
 
+    if (args.skip !== null || args.unattended) {
+        const unattended = await import('./upgrade_unattended.js');
+        return args.skip !== null
+            ? unattended.skip_version(args.skip, out)
+            : unattended.run_unattended_default({ dryRun: args.dry_run, out, err, agentConfigBin: _agent_config_bin() });
+    }
+
     const installed =
         options.installed !== undefined && options.installed !== null
             ? options.installed

package/src/scripts/_cli/detection_report.ts

@@ -418,6 +418,13 @@ export function renderSpendDisclosure(report: DetectionReport): string {
     if (free.length > 0) {
         segments.push(`${free.length} manual (no provider call): ${free.map((r) => r.provider).join(', ')}`);
     }
+    const unmetered = billed.filter((r) => r.billing === 'free-quota' || r.billing === 'self-hosted');
+    if (unmetered.length > 0) {
+        segments.push(
+            `${unmetered.length} unmetered route(s): ` +
+                unmetered.map((r) => `${r.provider}→${r.billing}`).join(', '),
+        );
+    }
 
     return `council spend disclosure · ${segments.join(' · ')}${excludedTail}`;
 }

package/src/scripts/_cli/doctor_execution.ts

@@ -2,8 +2,7 @@
  * The `execution` block of `agent-config doctor --json`.
  *
  * `road-to-adversarial-verification-and-long-runs` Phase 0.3. Its own module
- * rather than a function inside `cmd_doctor.ts` for the reason
- * `_lib/continuation_ladder.ts` states for itself: `check_source_size_budget` is
+ * rather than a function inside `cmd_doctor.ts` because `check_source_size_budget` is
  * a shrink-only ratchet and `cmd_doctor.ts` sits far past the 1,500-line cap, so
  * every line added there is an added violation. A phase pays for its additions by
  * putting new code in a file under the cap rather than by raising a baseline.

package/src/scripts/_cli/doctor_install_mode.ts

@@ -17,6 +17,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import type { InstallOrigin } from '../_lib/classify_update.js';
+import { classify_install_origin } from '../_lib/update_check.js';
+
 function isFile(p: string): boolean {
     try {
         return fs.statSync(p).isFile();
@@ -39,6 +42,21 @@ function isDir(p: string): boolean {
  * the install-mode marker (written on every install) or the `agents/overrides/`
  * scaffold. Either is sufficient.
  */
+/**
+ * Whether the PACKAGE we are running from is a source checkout rather than an
+ * installed release — a different question from `_is_source_repo`, which asks
+ * whether a directory is an agent-config tree at all.
+ *
+ * A `.git` entry is the only signal that separates the two: npm never ships
+ * one, while both of `_is_source_repo`'s positive signals — a `dist/agent-src/`
+ * directory and a `package.json` named `@event4u/agent-config` — are present in
+ * every published tarball. `.git` is a directory in a normal clone and a file
+ * in a worktree, so existence is tested, never the kind.
+ */
+export function isSourceCheckoutPackage(packageRoot: string): boolean {
+    return fs.existsSync(path.join(packageRoot, '.git'));
+}
+
 export const INSTALL_MODE_MARKER_RELATIVE = 'agents/.agent-state/install-mode.txt';
 
 export function _is_global_only_consumer(project_root: string): boolean {
@@ -47,3 +65,24 @@ export function _is_global_only_consumer(project_root: string): boolean {
         isDir(path.join(project_root, 'agents', 'overrides'))
     );
 }
+
+/**
+ * The install origin of a package root, as the unattended gates and the
+ * `update-notice` session concern read it.
+ *
+ * Lives beside {@link isSourceCheckoutPackage} rather than in
+ * `upgrade_unattended.ts`, where it started, because two surfaces now ask the
+ * question and the second one is a hook: importing the unattended runner to
+ * reach one predicate would pull the registry fetch, the provenance verifier
+ * and the install lock into the bundle every hook event loads.
+ *
+ * Exported rather than inlined because `running_origin` resolves its own root
+ * from `import.meta.url` and so cannot be pointed at a fixture: in this
+ * repository the answer is legitimately `source-checkout`, and a test calling
+ * it here would pass for the wrong reason. The distinguishing input is a tree
+ * that carries the shipped `dist/agent-src/` and no `.git`.
+ */
+export function originForPackageRoot(root: string): InstallOrigin {
+    if (isSourceCheckoutPackage(root)) return 'source-checkout';
+    return classify_install_origin({ package_root: root, project_pin: null, latest: null, is_global_consumer: false });
+}

package/src/scripts/_cli/doctor_network_posture.ts

@@ -76,9 +76,9 @@ export interface TrafficVariable {
      * May THIS PACKAGE write the variable into the host env block?
      *
      * `false` on both traffic variables and it is not a policy setting — it is a
-     * structural fact: `install.ts`'s `WRITABLE_HOST_ENV` is a two-row allow
-     * table and the settings schema admits only those two keys, so neither
-     * traffic variable is expressible anywhere in the write path. Reported
+     * structural fact: `WRITABLE_HOST_ENV` is an allow table naming neither
+     * traffic variable, and the settings schema admits no key for either, so
+     * neither is expressible anywhere in the write path. Reported
      * because a consumer reading `set` on a row deserves to know whether this
      * package could have been the one that set it.
      */

package/src/scripts/_cli/doctor_ownership_ledger.ts

@@ -0,0 +1,126 @@
+/**
+ * `doctor` reads the user-scoped ownership ledger.
+ *
+ * `cmd_doctor` classified only PROJECT-scope manifest entries and skipped every
+ * global-scope tool, so a globally installed file the installer had just
+ * preserved — exit 3, "the active installation is not current" — was invisible
+ * to it, and the two surfaces reporting on one install disagreed by
+ * construction. The ledger is the record of what every global deploy wrote,
+ * wherever it ran from, so it is what doctor reads for global scope.
+ *
+ * A file is reported `modified` exactly when the installer would preserve it
+ * ON THE EVIDENCE DOCTOR HAS: the shared classifier says `recorded-modified`
+ * and the package still ships it. A retired file the user edited is kept by
+ * the installer without failing the run, so doctor does not fail on it either
+ * — reporting it here would make the two surfaces disagree in the other
+ * direction.
+ *
+ * THE ONE CASE THIS CANNOT COVER, named rather than left to be discovered.
+ * The installer also preserves a path the ledger LISTS but holds no digest
+ * for — an install predating the ledger — when the bytes on disk differ from
+ * what it would write. Doctor cannot reach that verdict, and the reason is
+ * structural rather than an omission: the test is "does this differ from what
+ * we WOULD write", and doctor is not installing, so it has no packaged digest
+ * to compare against. `recorded_digests` returns only paths carrying a digest,
+ * so such a path is not even enumerated here.
+ *
+ * It is left uncovered rather than guessed at. Reporting every digest-less
+ * ledger path as `modified` would assert an edit nobody proved, which is the
+ * claim the installer's own migration branch exists because it cannot make.
+ * The divergence is asserted in `tests/install/ownership_parity.test.ts` so it
+ * stays a known gap instead of becoming a surprise.
+ *
+ * Its own module because `cmd_doctor.ts` sits far above the 1,500-line source
+ * ceiling `check_source_size_budget` ratchets.
+ */
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { classifyFileState, ownershipOfState } from '../../install/recordedOwnership.js';
+import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
+
+/** Re-exported so `cmd_doctor`'s manifest classifier is the installer's own. */
+export { classifyOwnership } from '../../install/recordedOwnership.js';
+
+type Dict = Record<string, unknown>;
+
+/** Expand a leading `~` against `home`. */
+function expandAt(p: string, home: string): string {
+    if (p === '~') return home;
+    if (p.startsWith('~/')) return path.join(home, p.slice(2));
+    return p;
+}
+
+/**
+ * `modified` records for every ledger-recorded global file the installer would
+ * preserve. `inventoryPath` / `home` default to the running process's own.
+ */
+export function ledgerModifiedRecords(inventoryPath?: string | null, home?: string | null): Dict[] {
+    const inventory = global_deploy_inventory.load_inventory(inventoryPath ?? null);
+    const tools = (inventory['tools'] as Record<string, unknown> | undefined) ?? {};
+    const out: Dict[] = [];
+    for (const tool_id of Object.keys(tools).sort()) {
+        const entry = tools[tool_id];
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) continue;
+        const anchor = (entry as Dict)['anchor'];
+        if (typeof anchor !== 'string') continue;
+        const expanded = expandAt(anchor, home ?? os.homedir());
+        const digests = global_deploy_inventory.recorded_digests(tool_id, expanded, inventory);
+        for (const rel of [...digests.keys()].sort()) {
+            const rec = digests.get(rel) as global_deploy_inventory.LedgerDigest;
+            if (rec.kind === 'sidecar' || rec.packaged_sha256 === null) continue;
+            const target = path.join(expanded, rel);
+            const state = classifyFileState(
+                rec.installed_sha256,
+                rec.packaged_sha256,
+                global_deploy_inventory.file_sha256(target),
+            );
+            if (ownershipOfState(state) !== 'recorded-modified') continue;
+            out.push({
+                tool: tool_id,
+                path: target,
+                kind: 'deployed',
+                state,
+                fix: 'merge the staged *.agent-config.new into it, or re-install with --force',
+            });
+        }
+    }
+    return out;
+}
+
+/** Tools the global deploy ledger records at least one file for. */
+export function globalInstalledTools(inventoryPath?: string | null): string[] {
+    const inventory = global_deploy_inventory.load_inventory(inventoryPath ?? null);
+    const tools = (inventory['tools'] as Record<string, unknown> | undefined) ?? {};
+    return Object.keys(tools)
+        .filter((id) => {
+            const e = tools[id];
+            const files = typeof e === 'object' && e !== null ? (e as Dict)['files'] : null;
+            return Array.isArray(files) && files.length > 0;
+        })
+        .sort();
+}
+
+/**
+ * What `doctor` says about a project that has no project-scope install.
+ *
+ * It used to say one thing — "no project lockfile and no consumer install
+ * marker", as a warning — whether or not the machine had a working GLOBAL
+ * install. A global-only consumer is the shape ADR-020 makes the default, and
+ * every fresh worktree of any project has no project-scope install by
+ * construction, so the warning fired on exactly the healthy case. It now says
+ * which scopes it checked and what it found in each.
+ */
+export function noProjectInstallLines(projectRoot: string, inventoryPath?: string | null): Array<['out' | 'err', string]> {
+    const global = globalInstalledTools(inventoryPath);
+    if (global.length > 0) {
+        return [
+            ['out', `  ℹ️   global install present (${global.join(', ')}); no project-scope install at ${projectRoot}`],
+            ['out', '      expected for a global-only consumer — checked: global deploy ledger, project lockfile, project install marker'],
+        ];
+    }
+    return [
+        ['err', `  ⚠️   no agent-config install found — not globally (deploy ledger empty) and not at ${projectRoot}`],
+        ['err', '      run `agent-config init` (global install) or `agent-config refresh --project` (global-only consumer)'],
+    ];
+}

package/src/scripts/_cli/doctor_update_verdict.ts

@@ -0,0 +1,104 @@
+/**
+ * The `update_verdict` block of `doctor --json`: `classifyUpdate`'s verdict on
+ * the newest version the update probe has cached, with its reasons. Nothing acts
+ * on it — it is a report, the surface ADR-041 names instead of a new verb.
+ *
+ * It reads the cached `update-check.json` and never writes it, and it never
+ * queries the registry: the banner owns that file and its 24 h cadence. The
+ * cache keeps only the version, so the impact map, `engines.node` and the
+ * provenance attestation reach the classifier as unknowns, and an unknown never
+ * resolves to `auto`. The verdict is the one a terminal session would get, so a
+ * piped `doctor --json` does not report itself as non-interactive.
+ */
+import * as fs from 'node:fs';
+
+import * as agent_settings from '../_lib/agent_settings.js';
+import { classifyUpdate, type InstallOrigin } from '../_lib/classify_update.js';
+import type { EnvMap } from '../_lib/user_global_paths.js';
+import * as user_global_paths from '../_lib/user_global_paths.js';
+import { STATE_FILENAME, classify_install_origin } from '../_lib/update_check.js';
+import { _is_global_only_consumer, isSourceCheckoutPackage } from './doctor_install_mode.js';
+
+export interface UpdateVerdictSources {
+    readonly installed: string | null;
+    /** The parsed `update-check.json`; `{}` when absent or unreadable. */
+    readonly state: Record<string, unknown>;
+    readonly origin: InstallOrigin;
+    readonly env: EnvMap;
+    readonly nodeVersion: string;
+    readonly now: Date;
+    readonly projectPin: string | null;
+}
+
+/** Read the cached probe state, read-only. A missing or corrupt file is an empty cache. */
+export function readCachedUpdateState(statePath: string | null = user_global_paths.resolve_with_fallback(STATE_FILENAME)): Record<string, unknown> {
+    if (statePath === null) return {};
+    try {
+        const data: unknown = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        return data !== null && typeof data === 'object' && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+/** What the probe cache does not keep, so the classifier sees it as unknown rather than absent. */
+const NOT_CACHED = ['agentConfig.impact', 'engines', 'dist.attestations', 'time', 'deprecated'] as const;
+
+export function updateVerdictJson(src: UpdateVerdictSources): Record<string, unknown> {
+    const seen = src.state['last_seen_version'];
+    const candidate = typeof seen === 'string' && seen.trim() !== '' ? seen.trim() : null;
+    const head = { installed: src.installed, candidate, origin: src.origin, reporting_read_only: true, not_cached: NOT_CACHED };
+    if (src.installed === null) return { ...head, action: 'none', reasons: ['installed version unreadable'] };
+    if (candidate === null) {
+        return { ...head, action: 'none', reasons: ['no cached registry version: the update probe has not run'] };
+    }
+    const verdict = classifyUpdate({
+        installed: src.installed,
+        candidate,
+        origin: src.origin,
+        env: {
+            ci: src.env['CI'] === '1' || src.env['CI'] === 'true' || src.env['GITHUB_ACTIONS'] === 'true',
+            interactive: true,
+            noUpdateCheck: src.env['AGENT_CONFIG_NO_UPDATE_CHECK'] === '1',
+            nodeVersion: src.nodeVersion,
+            now: src.now.toISOString(),
+        },
+        impactMap: null,
+        engines: null,
+        publishedAt: null,
+        deprecated: null,
+        provenance: null,
+        settings: { projectPin: src.projectPin },
+    });
+    return { ...head, action: verdict.action, reasons: [...verdict.reasons] };
+}
+
+function readProjectPin(projectRoot: string): string | null {
+    try {
+        const pin = agent_settings.load_agent_settings({ cwd: projectRoot })['agent_config_version'];
+        return typeof pin === 'string' && pin.trim() !== '' ? pin.trim() : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Gather the sources and report. The source-checkout test is shared with
+ * `upgrade --unattended` (`isSourceCheckoutPackage`) so the two surfaces cannot
+ * drift: both ask whether the running package is a checkout or a release, and a
+ * `.git` entry is the only signal that answers it.
+ */
+export function updateVerdictFor(projectRoot: string, packageRoot: string, installed: string | null): Record<string, unknown> {
+    const state = readCachedUpdateState();
+    const projectPin = readProjectPin(projectRoot);
+    const seen = state['last_seen_version'];
+    const origin: InstallOrigin = isSourceCheckoutPackage(packageRoot)
+        ? 'source-checkout'
+        : classify_install_origin({
+              package_root: packageRoot,
+              project_pin: projectPin,
+              latest: typeof seen === 'string' ? seen : null,
+              is_global_consumer: _is_global_only_consumer(projectRoot),
+          });
+    return updateVerdictJson({ installed, state, origin, env: process.env, nodeVersion: process.version, now: new Date(), projectPin });
+}

package/src/scripts/_cli/explain_last/scrubber.ts

@@ -16,7 +16,7 @@
  *
  * Masks applied (resolution order):
  *
- * 1. Raw-key secret prefixes (`sk_live_…`, `ghp_…` etc.) and inline
+ * 1. Raw-key secret prefixes (the rule table's, at a token start) and inline
  *    `api_key=…` shapes → `<secret>`.
  * 2. Emails → `<email>`.
  * 3. Absolute file paths (`/Users/…`, `/home/…`, `C:\…`) → `<path>`.
@@ -39,31 +39,19 @@
  *    matching the original's `f"<{len(out)} chars>"`.
  */
 
-export const LONG_STRING_THRESHOLD = 200;
-
-const _RAW_KEY_PREFIXES: readonly string[] = [
-    'sk_live_', 'sk_test_', 'ghp_', 'github_pat_', 'gho_', 'ghs_',
-    'ghu_', 'xoxb-', 'xoxp-', 'AIza', 'AKIA',
-];
+import { assignmentPattern, rawKeyPrefixPattern } from '../../_lib/egress_rules.js';
 
-/** Escape a literal for a RegExp, mirroring Python's `re.escape`. */
-function _reEscape(literal: string): string {
-    // Python `re.escape` escapes non-alphanumerics; under the `u` flag a
-    // `\-` is an illegal escape, so `-` is escaped via its unicode form.
-    // The fixed prefixes only contain `-` (e.g. `xoxb-`), so this is the
-    // sole case that matters; the broad class covers the rest faithfully.
-    return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/-/g, '\\u002d');
-}
+export const LONG_STRING_THRESHOLD = 200;
 
 // Unicode word-char class standing in for Python's default-mode `\w`.
 const _W = '\\p{L}\\p{N}_';
 
-const _RAW_KEY_RE = new RegExp(
-    '(?:' + _RAW_KEY_PREFIXES.map(_reEscape).join('|') + ')[A-Za-z0-9_-]{6,}',
-    'gu',
-);
-const _API_KEY_RE = new RegExp(
-    '\\bapi[_-]?key\\b\\s*[:=]\\s*[A-Za-z0-9+/=_-]{12,}',
+// The raw-key prefixes are the rule table's (road-to-one-detector-and-the-
+// senders-we-own 2.2); this surface keeps its own policy: prefix plus six key
+// characters is enough to mask, because it cannot refuse.
+const _RAW_KEY_RE = rawKeyPrefixPattern(6);
+const _API_KEY_RE = assignmentPattern(
+    { keywords: ['apiKey'], before: '\\b', after: '\\b', value: '[A-Za-z0-9+/=_-]{12,}' },
     'giu',
 );
 const _EMAIL_RE = new RegExp(