@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/update_notice_hook.ts

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * `update-notice` — the `session_start` concern that tells a user their global
+ * install has a newer release, and, under `update.mode: auto`, lets a
+ * previously staged one install at that boundary.
+ *
+ * WHY A SESSION CONCERN AT ALL. The update banner is written by the CLI
+ * dispatcher after a subcommand and suppressed on a non-TTY
+ * (`_lib/update_check.ts`), while consumption of this package is global and
+ * through hosts — so the one surface that tells a user about an update is the
+ * one surface most users never see. `SECURITY.md:21` backports nothing, which
+ * makes an unnoticed stale install an unpatched one.
+ *
+ * WHAT IT COSTS. File reads only — the cached registry probe state, the
+ * installed `package.json`, the installed `CHANGELOG.md`, the session register.
+ * No network: the 24 h registry fetch stays with the CLI probe that owns it, so
+ * this concern is bounded by the disk and runs well inside its 1 s budget. It
+ * is day-throttled on top, through the same `probe_throttle` stamp the three
+ * sibling `session_start` probes use.
+ *
+ * WHAT IT NEVER DOES. It never installs anything and never swaps a file: it
+ * stages a verified candidate and says so, and `upgrade --unattended` — run by
+ * a human or a scheduler — is what installs. It used to be able to spawn that
+ * run itself; an independent review of 2026-10-20 refused the manifest for it,
+ * because `effect: notification` means "tells the human something and changes
+ * nothing else", and the capability was removed rather than the label widened.
+ * It never reads project settings, so a repository cannot set a contributor's
+ * global update mode. It never puts fetched text in front of the reader —
+ * every sentence is written in `_lib/update_notice.ts` or read from the
+ * CHANGELOG of the package already installed.
+ *
+ * It is fail-open on every path and returns 0 on every path, including an
+ * unreadable state file, an unwritable state directory and a missing changelog.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { originForPackageRoot } from './_cli/doctor_install_mode.js';
+import { user_global_settings_paths } from './_lib/agent_settings.js';
+import type { UpdateMode } from './_lib/classify_update.js';
+import { any_live_session, global_register_dir } from './_lib/session_register.js';
+import { STATE_FILENAME } from './_lib/update_check.js';
+import { write_atomic } from './_lib/fs_atomic.js';
+import { parseCuratedHead, RECONCILE_REASONS, updateNotice, type NoticeOutcome } from './_lib/update_notice.js';
+import { parse_version } from './_lib/version_order.js';
+import * as user_global_paths from './_lib/user_global_paths.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
+import { is_replay_mode } from './hooks/state_io.js';
+
+export const CONCERN = 'update-notice';
+export const NOTICE_STATE_FILENAME = 'update-notice.json';
+export const NOTICE_THROTTLE_FILENAME = 'update-notice.stamp';
+const VALID_MODES: readonly string[] = ['off', 'notify', 'ask', 'auto'];
+
+/**
+ * What this concern remembers between sessions, in the user-global
+ * `update-notice.json`. Everything else is re-read.
+ *
+ * Lifecycle: written atomically at mode 0600 by a session that is not
+ * suppressed; replaced whole each time; `staged` returns to `null` once nothing
+ * newer than the installed version is cached. A record that does not parse, or
+ * carries another schema, reads as empty and is replaced on the next write.
+ * Suppressed sessions — the kill switch included — neither write nor delete it.
+ * Deleting the file is always safe. `staged` is advisory output: no install
+ * path reads it. Beside it, `update-notice.stamp` records the day the notice
+ * last ran; it is user-global, replaced by rename, and written only after a run
+ * that was not suppressed.
+ */
+export const NOTICE_STATE_SCHEMA = 1;
+
+export interface NoticeState {
+    readonly staged: string | null;
+    readonly last_seen_installed: string | null;
+}
+
+export function readNoticeState(statePath: string | null): NoticeState {
+    try {
+        if (statePath === null) return { staged: null, last_seen_installed: null };
+        const raw: unknown = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+        const o = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+        if (o['schema'] !== undefined && o['schema'] !== NOTICE_STATE_SCHEMA) return { staged: null, last_seen_installed: null };
+        const str = (v: unknown): string | null => (typeof v === 'string' && parse_version(v.trim()) !== null ? v.trim() : null);
+        return { staged: str(o['staged']), last_seen_installed: str(o['last_seen_installed']) };
+    } catch {
+        return { staged: null, last_seen_installed: null };
+    }
+}
+
+export function writeNoticeState(statePath: string, state: NoticeState): void {
+    try {
+        write_atomic(statePath, `${JSON.stringify({ schema: NOTICE_STATE_SCHEMA, ...state }, null, 2)}\n`);
+    } catch {
+        /* unwritable state dir → the concern simply re-decides next session */
+    }
+}
+
+/**
+ * `update.mode` from the USER-GLOBAL settings only.
+ *
+ * Deliberately not the project cascade: the thing being updated is the global
+ * install, and a repository that could set this would be deciding how its
+ * contributors' machines update themselves. That is the pin hazard
+ * (`cmd_update.ts:11-13`) pointed the other way, and it is the reason this
+ * reads the global layers by hand instead of calling `load_agent_settings`.
+ */
+export function readUpdateMode(paths: readonly string[] = user_global_settings_paths()): UpdateMode | undefined {
+    let found: UpdateMode | undefined;
+    for (const p of paths) {
+        try {
+            const doc = parseYaml(fs.readFileSync(p, 'utf-8'), { version: '1.1' }) as Record<string, unknown> | null;
+            const block = doc?.['update'];
+            if (block === null || typeof block !== 'object' || Array.isArray(block)) continue;
+            const mode = (block as Record<string, unknown>)['mode'];
+            if (typeof mode === 'string' && VALID_MODES.includes(mode)) found = mode as UpdateMode;
+        } catch {
+            /* absent or malformed layer → it simply sets nothing */
+        }
+    }
+    return found;
+}
+
+function readJson(p: string): Record<string, unknown> {
+    try {
+        const raw: unknown = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+function readText(p: string): string {
+    try {
+        return fs.readFileSync(p, 'utf-8');
+    } catch {
+        return '';
+    }
+}
+
+function sessionIdFromEnvelope(raw: string): string | null {
+    try {
+        const doc: unknown = JSON.parse(raw);
+        const id = (doc as Record<string, unknown> | null)?.['session_id'];
+        return typeof id === 'string' && id.trim() !== '' ? id.trim() : null;
+    } catch {
+        return null;
+    }
+}
+
+export interface NoticeDeps {
+    readonly packageRoot: string;
+    readonly sessionId: string | null;
+    readonly env: NodeJS.ProcessEnv;
+    readonly isTty: boolean;
+    readonly mode: UpdateMode | undefined;
+    readonly probeStatePath: string | null;
+    readonly noticeStatePath: string;
+    /** The user-global day stamp; never under the workspace, which a repository controls. */
+    readonly throttlePath: string;
+    readonly registerDir: string;
+    readonly err: { write(text: string): void };
+}
+
+/**
+ * Decide and act. Separated from `main` so every input is injectable.
+ * `apply: false` decides only — it prints nothing and writes nothing.
+ */
+export function runNotice(deps: NoticeDeps, apply = true): NoticeOutcome {
+    const pkg = readJson(path.join(deps.packageRoot, 'package.json'));
+    const installed = typeof pkg['version'] === 'string' ? (pkg['version'] as string) : '';
+    if (installed === '') return { lines: [], stage: null, activate: null, suppressed: 'installed version unreadable' };
+
+    const probe = deps.probeStatePath === null ? {} : readJson(deps.probeStatePath);
+    const seen = probe['last_seen_version'];
+    const state = readNoticeState(deps.noticeStatePath);
+
+    const outcome = updateNotice({
+        installed,
+        candidate: typeof seen === 'string' && seen.trim() !== '' ? seen.trim() : null,
+        impactMap: probe['last_seen_impact'] ?? null,
+        mode: deps.mode,
+        origin: originForPackageRoot(deps.packageRoot),
+        env: {
+            ci: ['1', 'true'].includes((deps.env['CI'] ?? '').trim().toLowerCase()) || deps.env['GITHUB_ACTIONS'] === 'true',
+            interactive: deps.isTty,
+            noUpdateCheck: deps.env['AGENT_CONFIG_NO_UPDATE_CHECK'] === '1',
+        },
+        curatedHead: parseCuratedHead(readText(path.join(deps.packageRoot, 'CHANGELOG.md')), installed),
+        staged: state.staged,
+        lastSeenInstalled: state.last_seen_installed,
+        foreignSessionLive: any_live_session(deps.registerDir, deps.sessionId),
+    });
+
+    if (!apply) return outcome;
+    if (outcome.suppressed !== null) {
+        if (RECONCILE_REASONS.has(outcome.suppressed) && (state.staged !== null || state.last_seen_installed !== installed)) {
+            writeNoticeState(deps.noticeStatePath, { staged: null, last_seen_installed: installed });
+        }
+        return outcome;
+    }
+
+    for (const line of outcome.lines) deps.err.write(`[update] ${line}\n`);
+    writeNoticeState(deps.noticeStatePath, { staged: outcome.stage, last_seen_installed: installed });
+    return outcome;
+}
+
+/**
+ * The session-start entry: decide without side effects, honour the day
+ * throttle, then decide again and act — so the throttle stamp, like every other
+ * write, happens only in a context that may be written in at all. Returns
+ * `null` when the throttle or a suppressing context ends it before the act.
+ */
+export function noticeOncePerDay(deps: NoticeDeps): NoticeOutcome | null {
+    const dry = runNotice(deps, false);
+    if (dry.suppressed !== null && !RECONCILE_REASONS.has(dry.suppressed)) return null;
+    if (ranToday(deps.throttlePath)) return null;
+    const outcome = runNotice(deps);
+    stampToday(deps.throttlePath);
+    return outcome;
+}
+
+/** Local calendar day, so "once a day" follows the user's clock. */
+function localDay(d: Date): string {
+    return `${String(d.getFullYear())}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+/** True when the stamp is a regular file dated today. A link or any read problem is "not today". */
+export function ranToday(throttlePath: string): boolean {
+    try {
+        const st = fs.lstatSync(throttlePath);
+        return st.isFile() && localDay(st.mtime) === localDay(new Date());
+    } catch {
+        return false;
+    }
+}
+
+/** Replaces the stamp by rename, so a link at the path is replaced, never followed. */
+function stampToday(throttlePath: string): void {
+    if (is_replay_mode()) return;
+    try {
+        write_atomic(throttlePath, `${new Date().toISOString()}\n`);
+    } catch {
+        /* unwritable → the notice runs again next session, which only costs reads */
+    }
+}
+
+function packageRootOf(): string {
+    const env = process.env['AGENT_CONFIG_PACKAGE_ROOT'];
+    if (env) return env;
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+export function main(argv?: string[]): number {
+    void argv;
+    const raw = readHookStdin();
+    if (is_replay_mode()) return 0;
+    try {
+        const packageRoot = packageRootOf();
+        const mode = readUpdateMode();
+        // The throttle stamp is a WRITE, so it comes after the decision that
+        // this context may be written in at all — AC-2 asks for zero writes
+        // under CI, a non-TTY, a source checkout and the opt-out.
+        const deps: NoticeDeps = {
+            packageRoot,
+            sessionId: sessionIdFromEnvelope(raw),
+            env: process.env,
+            isTty: Boolean(process.stderr.isTTY) || Boolean(process.stdout.isTTY),
+            mode,
+            probeStatePath: user_global_paths.resolve_with_fallback(STATE_FILENAME),
+            noticeStatePath: user_global_paths.write_target(NOTICE_STATE_FILENAME),
+            throttlePath: user_global_paths.write_target(NOTICE_THROTTLE_FILENAME),
+            registerDir: global_register_dir(),
+            err: process.stderr,
+        };
+        noticeOncePerDay(deps);
+        return 0;
+    } catch {
+        return 0;
+    }
+}
+
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/validate_frontmatter.ts

@@ -935,6 +935,76 @@ export function check_scope_declaration(data: Record<string, YamlValue>): Schema
     return [];
 }
 
+// --- Host-key collision row ------------------------------------------------
+
+export interface HostSkillKeyList {
+    host: string;
+    url: string;
+    read_date: string;
+    expires: string;
+    keys: string[];
+}
+
+export interface HostSkillKeys {
+    hosts: HostSkillKeyList[];
+    /** Keys the package declares WITH the host's meaning, each with its reason. */
+    passthrough: Record<string, string>;
+}
+
+const _HOST_KEYS_PATH = path.join(_HERE, '..', 'config', 'host-skill-frontmatter-keys.json');
+
+export function load_host_skill_keys(file = _HOST_KEYS_PATH): HostSkillKeys {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8')) as Partial<HostSkillKeys>;
+    return { hosts: raw.hosts ?? [], passthrough: raw.passthrough ?? {} };
+}
+
+/**
+ * A schema property the package owns must not equal a key a host documents for
+ * skills: the host reads the key first, so the package's meaning is silently
+ * lost (`context: large` sat on the host's `context` until it was renamed).
+ * Checked against the schema rather than each artefact, so a colliding key is
+ * refused before any skill carries it.
+ */
+export function check_host_key_collisions(
+    artefactType: string,
+    schema: Record<string, YamlValue>,
+    hostKeys: HostSkillKeys,
+    today: string = new Date().toISOString().slice(0, 10),
+): SchemaError[] {
+    const errors: SchemaError[] = [];
+    const props = schema['properties'];
+    const declared = props !== null && typeof props === 'object' && !Array.isArray(props) ? Object.keys(props) : [];
+    for (const key of declared) {
+        if (Object.prototype.hasOwnProperty.call(hostKeys.passthrough, key)) continue;
+        const owners = hostKeys.hosts.filter((h) => h.keys.includes(key)).map((h) => h.host);
+        if (owners.length === 0) continue;
+        errors.push(
+            new SchemaError(
+                `$.properties.${key}`,
+                'host-key-collision',
+                `the ${artefactType} schema declares \`${key}\` as a package-owned key, but ` +
+                    `${owners.join(', ')} documents \`${key}\` for skills. Rename the package key, or ` +
+                    'list it under `passthrough` in src/config/host-skill-frontmatter-keys.json if the ' +
+                    "package uses it with the host's meaning.",
+            ),
+        );
+    }
+    for (const h of hostKeys.hosts) {
+        if (h.expires < today) {
+            errors.push(
+                new SchemaError(
+                    `$.hosts.${h.host}`,
+                    'host-key-list-expired',
+                    `the ${h.host} key list was read ${h.read_date} and expired ${h.expires} — ` +
+                        `re-read ${h.url} and refresh src/config/host-skill-frontmatter-keys.json.`,
+                    'warning',
+                ),
+            );
+        }
+    }
+    return errors;
+}
+
 // --- CLI entry point -------------------------------------------------------
 
 /** Yield `[artefact_type, path]` pairs for all lintable artefacts. */
@@ -1082,6 +1152,21 @@ export function _main(argv: string[]): number {
         }
     }
 
+    // Expiry warnings are per host list, so they are reported once, under the first type.
+    const hostKeys = load_host_skill_keys();
+    for (const [i, artefactType] of ['skill', 'command'].entries()) {
+        const rows = check_host_key_collisions(artefactType, load_schema(artefactType), hostKeys).filter(
+            (e) => i === 0 || e.severity === 'error',
+        );
+        if (rows.some((e) => e.severity === 'error')) failing += 1;
+        for (const error of rows) {
+            const marker = error.severity === 'warning' ? '⚠️ ' : '❌ ';
+            process.stdout.write(
+                `${marker}[${artefactType}-schema] ${artefactType}.schema.json: ${error.rule} at ${error.path} – ${error.message}\n`,
+            );
+        }
+    }
+
     process.stdout.write(
         `\n== Frontmatter schema: ${total} artefacts, ${failing} failing, ${warned} with warnings ==\n`,
     );

package/src/scripts/worker_reuse_shadow_report.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * The worker-reuse shadow window, read from the subagent ledger, and the four
+ * flip conditions of `docs/contracts/concern-activation-policy.md` as code.
+ *
+ * The guard flips from shadow to blocking only when ALL FOUR hold: a failure
+ * the threshold would have caught is in the window, the false-positive rate is
+ * measured and within 1 %, the economics are measured and favour it, and the
+ * window holds at least 100 calls or two weeks. A condition nobody measured is
+ * missing, never assumed. A window in which every reuse was refused is a valid
+ * null.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { LEDGER_DIR } from './hooks/subagent_ledger_hook.js';
+
+export interface ShadowLine {
+    event: string;
+    ts: string;
+    tool?: string;
+    dispatch_kind?: string;
+    reuse?: { verdict: 'would_resume' | 'fresh'; name: string | null; reasons: string[] };
+}
+
+export interface ShadowWindow {
+    first_ts: string | null;
+    last_ts: string | null;
+    days: number;
+    agent_calls: number;
+    would_resume: number;
+    would_resume_by_name: Record<string, number>;
+    refusal_reasons: Record<string, number>;
+    resumes_observed: number;
+    null_window: boolean;
+}
+
+export const FALSE_POSITIVE_TOLERANCE = 0.01;
+export const WINDOW_MIN_CALLS = 100;
+export const WINDOW_MIN_DAYS = 14;
+
+const sorted = (m: Record<string, number>): Record<string, number> =>
+    Object.fromEntries(Object.entries(m).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+export function summariseShadowWindow(lines: readonly ShadowLine[]): ShadowWindow {
+    const shadow = lines.filter((l) => l.event === 'spawn_guard_shadow');
+    const spawns = shadow.filter((l) => l.reuse !== undefined);
+    const byName: Record<string, number> = {};
+    const reasons: Record<string, number> = {};
+    let would = 0;
+    for (const l of spawns) {
+        if (l.reuse!.verdict === 'would_resume' && l.reuse!.name !== null) {
+            would++;
+            byName[l.reuse!.name] = (byName[l.reuse!.name] ?? 0) + 1;
+        } else {
+            for (const r of l.reuse!.reasons) reasons[r] = (reasons[r] ?? 0) + 1;
+        }
+    }
+    const times = spawns.map((l) => Date.parse(l.ts)).filter((t) => Number.isFinite(t)).sort((a, b) => a - b);
+    const first = times.length ? times[0]! : null;
+    const last = times.length ? times[times.length - 1]! : null;
+    return {
+        first_ts: first === null ? null : new Date(first).toISOString(),
+        last_ts: last === null ? null : new Date(last).toISOString(),
+        days: first === null || last === null ? 0 : (last - first) / 86_400_000,
+        agent_calls: spawns.length,
+        would_resume: would,
+        would_resume_by_name: sorted(byName),
+        refusal_reasons: sorted(reasons),
+        resumes_observed: shadow.filter((l) => l.dispatch_kind === 'resume').length,
+        null_window: spawns.length > 0 && would === 0,
+    };
+}
+
+/** Measurements the shadow log cannot produce on its own; null means unmeasured. */
+export interface FlipMeasurements {
+    false_positive_rate: number | null;
+    cost_avoided: number | null;
+    friction: number | null;
+}
+
+export type FlipCondition = 'failure_observed' | 'false_positive_rate_measured' | 'economics_measured' | 'window_met';
+
+export function flipReadiness(w: ShadowWindow, m: FlipMeasurements): { ready: boolean; missing: FlipCondition[] } {
+    const missing: FlipCondition[] = [];
+    if (w.would_resume === 0) missing.push('failure_observed');
+    if (m.false_positive_rate === null || m.false_positive_rate > FALSE_POSITIVE_TOLERANCE) missing.push('false_positive_rate_measured');
+    if (m.cost_avoided === null || m.friction === null || m.cost_avoided <= m.friction) missing.push('economics_measured');
+    if (w.agent_calls < WINDOW_MIN_CALLS && w.days < WINDOW_MIN_DAYS) missing.push('window_met');
+    return { ready: missing.length === 0, missing };
+}
+
+function readLedger(root: string): ShadowLine[] {
+    const dir = path.join(root, LEDGER_DIR);
+    if (!fs.existsSync(dir)) return [];
+    const out: ShadowLine[] = [];
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.jsonl')).sort()) {
+        for (const line of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+            if (!line.includes('spawn_guard_shadow')) continue;
+            try {
+                out.push(JSON.parse(line) as ShadowLine);
+            } catch {
+                // A torn line is not a record.
+            }
+        }
+    }
+    return out;
+}
+
+function main(): number {
+    const root = process.argv[2] ?? process.cwd();
+    const w = summariseShadowWindow(readLedger(root));
+    const r = flipReadiness(w, { false_positive_rate: null, cost_avoided: null, friction: null });
+    process.stdout.write(`${JSON.stringify({ window: w, flip: r }, null, 2)}\n`);
+    return 0;
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+    process.exit(main());
+}