@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/update_counts.ts

@@ -162,6 +162,32 @@ export function count(kind: string): number {
         const [, , active] = canonical_counts();
         return active;
     }
+    if (kind === 'commands_toplevel') {
+        // Command files at the TOP LEVEL of the projected directory, not
+        // recursively. The README sub-note exists to explain why the badge and
+        // the linked directory disagree, so this count is the directory's own
+        // listing — a recursive count here would make the sentence explain
+        // nothing (`road-to-surfaces-no-gate-reads` 1.1).
+        const dir = path.join(REPO_ROOT, 'dist', 'agent-src', 'commands');
+        if (!_exists(dir)) return 0;
+        let n = 0;
+        for (const f of fs.readdirSync(dir)) {
+            if (f.endsWith('.md') && f !== 'AGENTS.md') n += 1;
+        }
+        return n;
+    }
+    if (kind === 'rules_projected') {
+        // Rules in the projection, which is NOT the source count: a dormant
+        // rule ships in `src/rules/` and is not projected. The sub-note states
+        // both and the difference is the thing it explains.
+        const dir = path.join(REPO_ROOT, 'dist', 'agent-src', 'rules');
+        if (!_exists(dir)) return 0;
+        let n = 0;
+        for (const f of fs.readdirSync(dir)) {
+            if (f.endsWith('.md') && f !== 'README.md') n += 1;
+        }
+        return n;
+    }
     if (kind === 'skills_scoped') {
         // Skills a DEFAULT `projection.mode: scoped` install deploys. Derived
         // by the installer's own prune predicate over the same walk the
@@ -197,6 +223,21 @@ export function count(kind: string): number {
     }
     let total = 0;
     const seen = new Set<string>();
+    if (kind === 'advisors') {
+        // The Advisors badge sat on the claim row with no pattern behind it,
+        // while the sub-note said all six badge counts are re-derived. The
+        // `personas` walk is flat, so the advisors subdirectory is its own kind.
+        for (const root of artefact_roots()) {
+            for (const f of _glob(path.join(root, 'personas', 'advisors'), (n) => n.endsWith('.md'))) {
+                if (path.basename(f) === 'README.md') continue;
+                const rel = path.relative(root, f).split(path.sep).join('/');
+                if (seen.has(rel)) continue;
+                seen.add(rel);
+                total += 1;
+            }
+        }
+        return total;
+    }
     if (kind === 'commands') {
         // Commands live under packages/*/commands/ AND the 6.0.0-D
         // src/domains/<pack>/<subpath>/command.md homes; iter_commands()
@@ -263,6 +304,20 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             ['(/badge/Commands-)(\\d+)(-)', 'commands_active'],
             ['(/badge/Guidelines-)(\\d+)(-)', 'guidelines'],
             ['(/badge/Personas-)(\\d+)(-)', 'personas'],
+            ['(/badge/Advisors-)(\\d+)(-)', 'advisors'],
+            // The sub-note under the badges. The comment above used to end at
+            // "Prose counts were removed from the README on purpose", and the
+            // sub-note re-added four of them in `fc1bdec4f` without an owner.
+            // At 2026-10-12 two had drifted — "Rules 121" against 122 source
+            // rules, "projection holds 120" against 121 — while the two
+            // Commands figures happened to be right, which is exactly how a
+            // hand-typed number fails: silently, and only on some of them.
+            // Gated rather than deleted (D1): the sentence answers a real
+            // reader question about why the badge and the directory differ.
+            ['(\\*\\*Commands )(\\d+)(\\*\\* counts every command file)', 'commands_active'],
+            ['(holds )(\\d+)( at its top level)', 'commands_toplevel'],
+            ['(\\*\\*Rules )(\\d+)(\\*\\* counts the)', 'rules'],
+            ['(projection holds )(\\d+)()', 'rules_projected'],
         ],
     ],
     [
@@ -294,6 +349,54 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
         'docs/command-flows.md',
         [['(\\*\\*)(\\d+)( commands\\*\\*)', 'commands_active']],
     ],
+    // The documentation site carried the same figures by hand and nothing read
+    // them. Measured 2026-10-14 against a tree of skills 300 / rules 122 /
+    // commands 205 / guidelines 121, the two "what's inside" tables were stale
+    // on EVERY generated row — 278 / 105 / 190 / 101 — and seven further
+    // literal `190`s sat across five files, while the README two directories up
+    // said one canonical counter re-derives the figures and fails CI on a drift
+    // of one. It did; its TARGETS list simply stopped at `docs/`. Gated rather
+    // than deleted, the same call the README sub-note took: the numbers answer
+    // a reader's question, and a generated number is a better answer than none.
+    [
+        'site/src/content/docs/architecture/overview.md',
+        [
+            ['(\\| \\*\\*Skills\\*\\* \\| )(\\d+)( \\|)', 'skills'],
+            ['(\\| \\*\\*Rules\\*\\* \\| )(\\d+)( \\|)', 'rules'],
+            ['(\\| \\*\\*Commands\\*\\* \\| )(\\d+)( \\|)', 'commands_active'],
+            ['(\\| \\*\\*Guidelines\\*\\* \\| )(\\d+)( \\|)', 'guidelines'],
+            ['(\\| \\*\\*Personas\\*\\* \\| )(\\d+)( \\()', 'personas'],
+        ],
+    ],
+    [
+        'site/src/content/docs/getting-started/introduction.md',
+        [
+            ['(\\| \\*\\*Skills\\*\\* \\| )(\\d+)( \\|)', 'skills'],
+            ['(\\| \\*\\*Rules\\*\\* \\| )(\\d+)( \\|)', 'rules'],
+            ['(\\| \\*\\*Commands\\*\\* \\| )(\\d+)( \\|)', 'commands_active'],
+            ['(\\| \\*\\*Guidelines\\*\\* \\| )(\\d+)( \\|)', 'guidelines'],
+            ['(\\| \\*\\*Personas\\*\\* \\| )(\\d+)( \\|)', 'personas'],
+        ],
+    ],
+    [
+        'site/src/content/docs/agent-commands/overview.md',
+        [
+            ['(ships \\*\\*)(\\d+)(\\*\\* agent commands)', 'commands_active'],
+            ['(index of all )(\\d+)(:)', 'commands_active'],
+        ],
+    ],
+    [
+        'site/src/content/docs/agent-commands/key-commands.md',
+        [['(exhaustive list of all )(\\d+)(, see)', 'commands_active']],
+    ],
+    [
+        'site/src/content/docs/agent-commands/clusters.md',
+        // The page's own `description:` frontmatter carried a second copy of
+        // the figure. A meta description is not where a reader goes for a
+        // count, so that one is dropped rather than generated; the body line
+        // that a reader does act on stays, and is generated.
+        [['(\\) lists all )(\\d+)(\\.)', 'commands_active']],
+    ],
     [
         'docs/getting-started-by-role.md',
         [
@@ -343,13 +446,24 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
     ],
 ];
 
-/** Return [new_text, drifts]. Each drift is [kind, old, new]. */
+/**
+ * Return [new_text, drifts, unapplied]. Each drift is [kind, old, new]; each
+ * unapplied entry is a pattern that produced NO substitution and the reason.
+ *
+ * A pattern that matches nothing used to warn on stderr and continue, so
+ * `--check` reported "All counts in sync" for a sentence it could no longer
+ * find — a figure that drifts after its pattern stops matching it is exactly
+ * the silent pass a counter exists to prevent. The caller decides what to do
+ * with the list; in check mode it is a failure.
+ */
 export function apply_to_text(
     text: string,
     patterns: ReadonlyArray<[string, string]>,
     counts: Record<string, number>,
-): [string, Array<[string, number, number]>] {
+): [string, Array<[string, number, number]>, Array<[string, string, string]>] {
     const drifts: Array<[string, number, number]> = [];
+    // [pattern, kind, reason]
+    const unapplied: Array<[string, string, string]> = [];
     let new_text = text;
     for (const [pattern, kind] of patterns) {
         // Python re.compile(pattern).finditer / .sub — global, non-overlapping.
@@ -357,34 +471,100 @@ export function apply_to_text(
         const matches = [...new_text.matchAll(reFind)];
         if (matches.length === 0) {
             process.stderr.write(`  ⚠️  pattern missed: /${pattern}/ (kind=${kind})\n`);
+            unapplied.push([pattern, kind, 'pattern matched nothing']);
+            continue;
+        }
+        // A kind with no count is a BUG in TARGETS or KINDS, and writing it
+        // anyway puts the literal `undefined` into a published file. Measured
+        // on 2026-10-12: adding two patterns without adding their kinds to
+        // KINDS rewrote the README sub-note to "holds undefined at its top
+        // level" and `--check` then reported "All counts in sync", because the
+        // pattern no longer matched its own output. Refuse instead, loudly.
+        const next = counts[kind];
+        if (typeof next !== 'number' || !Number.isFinite(next)) {
+            process.stderr.write(
+                `  ❌  no count for kind=${kind} (pattern /${pattern}/) — ` +
+                    'add it to KINDS; refusing to write `undefined` into the target\n',
+            );
+            unapplied.push([pattern, kind, 'no count for this kind']);
             continue;
         }
         for (const m of matches) {
             const old = Number.parseInt(m[2] as string, 10);
-            const next = counts[kind] as number;
             if (old !== next) {
                 drifts.push([kind, old, next]);
             }
         }
         const reSub = new RegExp(pattern, 'g');
         new_text = new_text.replace(reSub, (_full, g1: string, _g2: string, g3: string) => {
-            return `${g1}${counts[kind] as number}${g3}`;
+            return `${g1}${next}${g3}`;
         });
     }
-    return [new_text, drifts];
+    return [new_text, drifts, unapplied];
 }
 
-const KINDS = [
+export const KINDS = [
     'skills',
     'skills_scoped',
     'rules',
     'commands',
     'commands_active',
+    'commands_toplevel',
+    'rules_projected',
     'guidelines',
     'personas',
+    'advisors',
     'router_rules',
 ] as const;
 
+export const CLAIM_ROW_MARKER = '<!-- claim:published-artifact-counts -->';
+
+/**
+ * Badges on a claim-row line that no count pattern re-derives.
+ *
+ * The counts are matched by URL pattern, never by position, so a badge dropped
+ * onto the claim row that matches no pattern used to pass `--check` unseen
+ * while the row promises every figure on it is machine-checked. The allowed
+ * set is the target's own `/badge/` patterns, so adding a count adds its badge.
+ * Inline, reference-style and HTML `<img>` images are all read.
+ */
+export function claim_row_findings(
+    text: string,
+    patterns: ReadonlyArray<[string, string]>,
+): Array<[number, string]> {
+    const badge_patterns = patterns
+        .filter(([pattern]) => pattern.includes('/badge/'))
+        .map(([pattern]) => new RegExp(pattern));
+    const definitions = new Map<string, string>();
+    for (const m of text.matchAll(/^ {0,3}\[([^\]]+)\]:\s*<?([^\s>]+)>?/gm)) {
+        definitions.set((m[1] as string).trim().toLowerCase(), m[2] as string);
+    }
+    const findings: Array<[number, string]> = [];
+    text.split('\n').forEach((line, index) => {
+        if (!line.includes(CLAIM_ROW_MARKER)) return;
+        const urls: string[] = [];
+        for (const m of line.matchAll(/!\[([^\]]*)\](?:\(([^)\s]+)[^)]*\)|\[([^\]]*)\])?/g)) {
+            if (m[2] !== undefined) {
+                urls.push(m[2]);
+                continue;
+            }
+            // Reference (`![a][ref]`), collapsed (`![a][]`) and shortcut (`![a]`)
+            // forms. An unresolvable label is reported as itself, never skipped.
+            const label = (m[3] || m[1] || '').trim();
+            urls.push(definitions.get(label.toLowerCase()) ?? `[${label}]`);
+        }
+        for (const m of line.matchAll(/<img\b[^>]*?\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) {
+            urls.push((m[1] ?? m[2] ?? m[3]) as string);
+        }
+        for (const url of urls) {
+            if (!badge_patterns.some((re) => re.test(url))) {
+                findings.push([index + 1, url]);
+            }
+        }
+    });
+    return findings;
+}
+
 function parse_args(argv: readonly string[]): { check: boolean } {
     const args = { check: false };
     const usage = 'usage: update_counts.py [-h] [--check]\n';
@@ -403,8 +583,19 @@ function parse_args(argv: readonly string[]): { check: boolean } {
     return args;
 }
 
-export function main(argv: readonly string[] = process.argv.slice(2)): number {
+/**
+ * `opts` exists so the check-mode contract can be tested against a fixture
+ * tree instead of the real one. A test that has to edit a tracked file to
+ * exercise a gate is a test that cannot run, so the seam is here rather than
+ * in the test.
+ */
+export function main(
+    argv: readonly string[] = process.argv.slice(2),
+    opts: { root?: string; targets?: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> } = {},
+): number {
     const args = parse_args(argv);
+    const root = opts.root ?? REPO_ROOT;
+    const targets = opts.targets ?? TARGETS;
 
     const counts: Record<string, number> = {};
     for (const k of KINDS) {
@@ -415,19 +606,32 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             `rules=${counts['rules']} commands=${counts['commands']} ` +
             `commands_active=${counts['commands_active']} ` +
             `guidelines=${counts['guidelines']} ` +
-            `personas=${counts['personas']} router_rules=${counts['router_rules']}\n`,
+            `personas=${counts['personas']} advisors=${counts['advisors']} ` +
+            `router_rules=${counts['router_rules']}\n`,
     );
 
     let any_drift = false;
     let any_change = false;
-    for (const [rel, patterns] of TARGETS) {
-        const p = path.join(REPO_ROOT, rel);
+    let any_unapplied = false;
+    let any_unguarded = false;
+    for (const [rel, patterns] of targets) {
+        const p = path.join(root, rel);
         if (!_exists(p)) {
             process.stderr.write(`❌  Missing target: ${rel}\n`);
             return 1;
         }
         const text = fs.readFileSync(p, 'utf-8');
-        const [new_text, drifts] = apply_to_text(text, patterns, counts);
+        const [new_text, drifts, unapplied] = apply_to_text(text, patterns, counts);
+        for (const [line, url] of claim_row_findings(text, patterns)) {
+            any_unguarded = true;
+            process.stderr.write(
+                `  ❌  ${rel}:${line}: badge on the claim row that no count re-derives — ${url}\n`,
+            );
+        }
+        for (const [pattern, kind, reason] of unapplied) {
+            any_unapplied = true;
+            process.stderr.write(`  ❌  ${rel}: ${reason} — /${pattern}/ (kind=${kind})\n`);
+        }
         if (drifts.length > 0) {
             any_drift = true;
             for (const [kind, old, next] of drifts) {
@@ -441,6 +645,21 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     }
 
     if (args.check) {
+        if (any_unapplied) {
+            process.stderr.write(
+                '\n❌  A pattern applied to nothing (named above). The figure it owns is ' +
+                    'no longer generated, so a drift in it would pass unseen. Fix the pattern ' +
+                    'or drop it with the figure.\n',
+            );
+            return 1;
+        }
+        if (any_unguarded) {
+            process.stderr.write(
+                '\n❌  A badge on the claim row is not re-derived (named above). Move it off ' +
+                    'the line carrying the claim marker, or add a count that derives it.\n',
+            );
+            return 1;
+        }
         if (any_drift) {
             process.stderr.write('\n❌  Stale counts detected. Run `task counts-update` to fix.\n');
             return 1;

package/src/scripts/update_invite_hook.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * `update-auto-invite` — the `stop` concern that asks an EXISTING install,
+ * once, whether updates may install themselves.
+ *
+ * ADR-291 is the policy: `auto` may default for a new install; an existing one
+ * is asked once, after the ring-0 exit and the live-session register, with a
+ * binding "never", and dismissal keeps `notify`. Step 4.3 adds the moment —
+ * after a turn that ended on a verified success, which is the one point in a
+ * session where an unrelated question is not an interruption of something.
+ *
+ * **It is closed today, by a file rather than by a flag.**
+ * The ring-0 record (`RING_ZERO_PREFIX`) carries a single
+ * `ring-0-exit:` line, written by a human after reading the record's own table,
+ * and while it reads `no` this concern returns before it has read anything
+ * else. That is deliberate: the gate on asking an existing install to change
+ * how it updates itself should be a record somebody signed, not a boolean in
+ * code the next change can flip.
+ *
+ * **It never writes `update.mode`.** That key is class C — only a hand-edit or
+ * the GUI's write route may set it. The invitation says how, and setting it to
+ * anything but `ask` is also how it stops.
+ *
+ * **State: one timestamp, per user-global config home.** `update-invite.json`
+ * holds `{invited_at}`. Every repository and session of one OS user shares it,
+ * so "once" means once per config home. Absent means never invited; present but
+ * unreadable counts as invited, because a corrupt record must not re-open the
+ * question. Deleting the file is the reset. Created once, exclusively, at mode
+ * 0600 — see {@link claimInvite}.
+ *
+ * Fail-open, exit 0 on every path except the one that carries the question,
+ * which exits 2 — the warn path, so the question reaches the agent that can
+ * put it to the user in the host's own ask shape.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { readTurnRunState } from './before_complete_hook.js';
+import type { UpdateMode } from './_lib/classify_update.js';
+import { autoInviteDecision, ringZeroExited, type InviteDecision } from './_lib/update_invite.js';
+import { readRunEvidence } from './_lib/verification_evidence.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';
+import { readUpdateMode } from './update_notice_hook.js';
+
+export const CONCERN = 'update-auto-invite';
+export const INVITE_STATE_FILENAME = 'update-invite.json';
+export const RING_ZERO_GLOB_DIR = path.join('agents', 'evidence', 'analysis');
+export const RING_ZERO_PREFIX = 'ring-0-unattended-record-';
+
+export interface InviteState {
+    /** `null` only when no record exists; a record that does not parse reads as invited. */
+    readonly invited_at: string | null;
+}
+
+export const UNREADABLE_INVITE_RECORD = 'unreadable record';
+
+export function readInviteState(statePath: string): InviteState {
+    let text: string;
+    try {
+        text = fs.readFileSync(statePath, 'utf-8');
+    } catch (err) {
+        return { invited_at: (err as NodeJS.ErrnoException).code === 'ENOENT' ? null : UNREADABLE_INVITE_RECORD };
+    }
+    try {
+        const raw: unknown = JSON.parse(text);
+        const o = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+        return { invited_at: typeof o['invited_at'] === 'string' && o['invited_at'] !== '' ? o['invited_at'] : UNREADABLE_INVITE_RECORD };
+    } catch {
+        return { invited_at: UNREADABLE_INVITE_RECORD };
+    }
+}
+
+/**
+ * Claim the one invitation: create the record only if it does not exist yet.
+ *
+ * `O_CREAT | O_EXCL` makes the claim, not the read before it, so of two
+ * sessions that both decided to ask, exactly one creates the record and only
+ * that one prints. It also refuses a symlink at the path. Nothing here throws:
+ * a claim that cannot be made asks nothing, because a question that cannot be
+ * recorded could repeat; a record created but not fully written is removed
+ * again, so a failed write cannot silence the invitation forever. A reader
+ * racing the content write sees an unreadable record, which counts as invited.
+ */
+export function claimInvite(
+    statePath: string,
+    invitedAt: string,
+    writeRecord: (fd: number, text: string) => void = (fd, text) => fs.writeFileSync(fd, text),
+): boolean {
+    let fd: number;
+    try {
+        fs.mkdirSync(path.dirname(statePath), { recursive: true });
+        fd = fs.openSync(statePath, 'wx', 0o600);
+    } catch {
+        return false;
+    }
+    let written = false;
+    try {
+        writeRecord(fd, `${JSON.stringify({ invited_at: invitedAt } satisfies InviteState, null, 2)}\n`);
+        written = true;
+    } catch {
+        /* handled below: the half-written claim is withdrawn */
+    }
+    try {
+        fs.closeSync(fd);
+    } catch {
+        written = false;
+    }
+    if (!written) {
+        try {
+            fs.unlinkSync(statePath);
+        } catch {
+            /* an unremovable half-record reads as invited, the direction that cannot repeat */
+        }
+    }
+    return written;
+}
+
+/**
+ * The newest ring-0 record's text, or `null`.
+ *
+ * Newest by filename, which carries the date — the records are dated and never
+ * renamed, so a lexical sort is a chronological one. A directory with none is
+ * `null`, which reads as "not exited".
+ */
+export function readRingZeroRecord(packageRoot: string): string | null {
+    try {
+        const dir = path.join(packageRoot, RING_ZERO_GLOB_DIR);
+        const names = fs
+            .readdirSync(dir)
+            .filter((n) => n.startsWith(RING_ZERO_PREFIX) && n.endsWith('.md'))
+            .sort();
+        const newest = names[names.length - 1];
+        return newest === undefined ? null : fs.readFileSync(path.join(dir, newest), 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+export interface InviteDeps {
+    readonly packageRoot: string;
+    readonly workspaceRoot: string;
+    readonly sessionId: string;
+    readonly mode: UpdateMode | undefined;
+    readonly statePath: string;
+    readonly ringZeroText: string | null;
+    readonly env: NodeJS.ProcessEnv;
+    readonly isTty: boolean;
+    readonly out: { write(text: string): void };
+    /** Overrides the read of the turn's verification evidence. */
+    readonly turnEndedOnVerifiedSuccess?: boolean;
+}
+
+/** Decide, claim, emit. Returns the decision so a test asserts on a value. */
+export function runInvite(deps: InviteDeps): InviteDecision {
+    const state = readInviteState(deps.statePath);
+    const decision = autoInviteDecision({
+        mode: deps.mode,
+        ringZeroExited: ringZeroExited(deps.ringZeroText),
+        // Step 1.4 landed the machine-wide register, so this is true wherever
+        // this code runs. It stays an input because the condition is ADR-291's,
+        // not this file's, and a reader should see it being checked.
+        registerAvailable: true,
+        alreadyInvited: state.invited_at !== null,
+        turnEndedOnVerifiedSuccess: deps.turnEndedOnVerifiedSuccess ?? verifiedSuccess(deps.workspaceRoot, deps.sessionId),
+        env: {
+            ci: ['1', 'true'].includes((deps.env['CI'] ?? '').trim().toLowerCase()) || deps.env['GITHUB_ACTIONS'] === 'true',
+            noUpdateCheck: deps.env['AGENT_CONFIG_NO_UPDATE_CHECK'] === '1',
+            interactive: deps.isTty,
+            headless: deps.env['AGENT_CONFIG_NO_UI'] === '1' || (deps.env['DISPLAY'] === '' && deps.env['AGENT_CONFIG_HEADLESS'] === '1'),
+            jsonOutput: deps.env['AGENT_CONFIG_JSON'] === '1' || (deps.env['AGENT_CONFIG_ARGV'] ?? '').includes('--json'),
+            subagent: deps.env['AGENT_CONFIG_SUBAGENT'] === '1' || deps.env['CLAUDE_AGENT_TYPE'] !== undefined,
+        },
+    });
+    if (!decision.ask) return decision;
+    if (!claimInvite(deps.statePath, new Date().toISOString())) return { ask: false, reason: 'already invited once' };
+    for (const line of decision.lines) deps.out.write(`${line}\n`);
+    return decision;
+}
+
+function verifiedSuccess(workspaceRoot: string, sessionId: string): boolean {
+    const runState = readTurnRunState(workspaceRoot, sessionId);
+    return runState !== null && readRunEvidence(runState).passed;
+}
+
+function envelopeField(raw: string, key: string): string {
+    try {
+        const doc: unknown = JSON.parse(raw);
+        const v = (doc as Record<string, unknown> | null)?.[key];
+        return typeof v === 'string' ? v : '';
+    } catch {
+        return '';
+    }
+}
+
+function packageRootOf(): string {
+    return process.env['AGENT_CONFIG_PACKAGE_ROOT'] ?? 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();
+        // The cheapest refusal first: while the record says `no` there is
+        // nothing else worth reading, and on every install today it says `no`.
+        const ringZeroText = readRingZeroRecord(packageRoot);
+        if (!ringZeroExited(ringZeroText)) return 0;
+        const decision = runInvite({
+            packageRoot,
+            workspaceRoot: envelopeField(raw, 'workspace_root') || process.cwd(),
+            sessionId: envelopeField(raw, 'session_id'),
+            mode: readUpdateMode(),
+            statePath: user_global_paths.write_target(INVITE_STATE_FILENAME),
+            ringZeroText,
+            env: process.env,
+            isTty: Boolean(process.stderr.isTTY) && Boolean(process.stdout.isTTY),
+            out: process.stderr,
+        });
+        // Exit 2 is the warn delivery path: the question reaches the agent,
+        // which puts it to the user in this host's declared ask shape.
+        return decision.ask ? 2 : 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)));
+}