@event4u/agent-config 16.5.0 → 17.0.0

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(