@bookedsolid/rea 0.30.1 → 0.32.0

package/dist/cli/audit-specialists.js

@@ -1,20 +1,33 @@
 /**
- * `rea audit specialists` — 0.29.0 reader CLI for delegation-telemetry.
+ * `rea audit specialists` — reader CLI for delegation-telemetry
+ * (0.29.0; `--since` / `--session` added 0.31.0).
  *
- * Walks `.rea/audit.jsonl`, filters records by
- * `tool_name === 'rea.delegation_signal'`, groups by
- * `metadata.subagent_type`, and prints a table (default) or JSON
- * document (`--json`).
+ * Walks `.rea/audit.jsonl` (plus any rotated files when `--since` is
+ * given), filters records by `tool_name === 'rea.delegation_signal'`,
+ * groups by `metadata.subagent_type`, and prints a table (default) or
+ * JSON document (`--json`).
  *
- * # Current-session-only in v1
+ * # Session filtering
  *
- * v1 has NO `--since` flag and NO `--session=ID` flag. The principal-
- * engineer scope-cut deferred both to 0.29.1. The filter is:
+ * Three ways to scope, in precedence order:
  *
- *   - If `CLAUDE_SESSION_ID` is set, include only records whose
- *     `metadata.session_id_observed` matches.
- *   - Otherwise, include all records in the chain and print a note so
- *     the operator knows what they're seeing.
+ *   1. `--session <id>`  — explicit. Filters to records whose
+ *      `metadata.session_id_observed` matches `<id>`. The literal
+ *      `--session all` disables filtering entirely (show every
+ *      session). Wins over the env var.
+ *   2. `$CLAUDE_SESSION_ID` — when set and `--session` is omitted,
+ *      filters to the current Claude Code session.
+ *   3. neither — no filter; every record in the walked files is shown,
+ *      and a note tells the operator what they're seeing.
+ *
+ * # `--since <rotated-file>`
+ *
+ * By default the reader walks only the current `.rea/audit.jsonl`.
+ * `--since audit-YYYYMMDD-HHMMSS.jsonl` extends the walk backward: the
+ * named rotated file and every rotated file after it (timestamp-
+ * ascending) are scanned, then the current `audit.jsonl` as the tail.
+ * Mirrors `rea audit verify --since`. The filename must match the
+ * canonical rotated-audit shape or the CLI exits 1.
  *
  * # Output shape
  *
@@ -23,14 +36,27 @@
  *   code-reviewer             5      2026-05-12T21:28:00Z
  *   deep-dive                 2      2026-05-12T21:14:00Z
  *
- * JSON mode prints `{ session_filter, records, groups }` where
- * `records` is the raw filtered subset (for piping into jq) and
+ * JSON mode prints `{ session_filter, records, groups, files_scanned }`
+ * where `records` is the raw filtered subset (for piping into jq) and
  * `groups` is the per-subagent rollup.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { DELEGATION_SIGNAL_TOOL_NAME, DELEGATION_SIGNAL_SCHEMA_VERSION, } from '../audit/delegation-event.js';
 import { AUDIT_FILE, REA_DIR, log } from './utils.js';
+/**
+ * Thrown by `computeAuditSpecialists` when `--since` names something
+ * that is not a valid rotated-audit basename, or names a rotated file
+ * that does not exist. The commander wrapper catches it and exits 1.
+ */
+export class AuditSpecialistsSinceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditSpecialistsSinceError';
+    }
+}
+/** Canonical rotated-audit filename shape — mirrors `audit.ts`. */
+const ROTATED_AUDIT_RE = /^audit-\d{8}-\d{6}(-\d+)?\.jsonl$/;
 /**
  * Type guard for a record that has the delegation-signal shape. Skips
  * envelope shape validation (zod runs at write time); checks only the
@@ -51,52 +77,167 @@ function isDelegationRecord(r) {
     return true;
 }
 /**
- * Read the audit file and return delegation records (filtered + parsed
- * into a reader-friendly shape). Malformed lines are skipped silently
- * — `rea audit verify` is the right tool for chain integrity.
+ * Sort key for a rotated-audit basename. Returns `[stamp, suffix]`:
+ *
+ *   - `stamp` — the `YYYYMMDD-HHMMSS` block. Zero-padded fixed-width, so
+ *     a plain lexical compare on it IS chronological order.
+ *   - `suffix` — the intra-second collision counter (`-N`), parsed as an
+ *     integer. The base file (`audit-...jsonl`, no `-N`) is the FIRST
+ *     rotation in its second, so its suffix is `0` and it sorts ahead of
+ *     `audit-...-1.jsonl`.
+ *
+ * Round-2 P3: the previous implementation sorted the whole basename
+ * lexically, which misorders the `-N` suffix once it reaches two digits
+ * (`...-10.jsonl` sorts BEFORE `...-2.jsonl`). A repo that rotates more
+ * than 9 times in one second would then have `resolveAuditFileWalk`
+ * slice from the wrong index and silently drop later segments — and,
+ * post-0.31.0, the delegation-advisory predicate (which reuses this
+ * resolution) would miss delegations and fire false-positive nudges.
+ */
+function rotatedAuditSortKey(name) {
+    // `ROTATED_AUDIT_RE` already guaranteed the shape; capture the parts.
+    const m = /^audit-(\d{8}-\d{6})(?:-(\d+))?\.jsonl$/.exec(name);
+    if (m === null) {
+        // Defensive — callers only pass names that matched ROTATED_AUDIT_RE.
+        return [name, 0];
+    }
+    const stamp = m[1];
+    const suffix = m[2] !== undefined ? Number.parseInt(m[2], 10) : 0;
+    return [stamp, Number.isInteger(suffix) ? suffix : 0];
+}
+/**
+ * List rotated audit files in `.rea/`, timestamp-ascending. Filenames
+ * follow `audit-YYYYMMDD-HHMMSS(-N).jsonl`. Sorted via
+ * `rotatedAuditSortKey` — the `YYYYMMDD-HHMMSS` block lexically (it is
+ * fixed-width zero-padded, so lexical == chronological) then the `-N`
+ * intra-second suffix NUMERICALLY (a plain lexical sort of the whole
+ * basename misorders two-digit suffixes — see `rotatedAuditSortKey`).
+ * Mirrors the private helper in `audit.ts` — kept local so this reader
+ * doesn't import the verify command's internals.
+ *
+ * Exported (0.31.0 round-2 P3) so `delegation-advisory.ts` can resolve
+ * the rotated-file set without duplicating the `ROTATED_AUDIT_RE` glob:
+ * the advisory's "did this session delegate" predicate must scan rotated
+ * segments too, or a delegation recorded before an audit rotation is
+ * invisible to the nudge and the session gets a false-positive advisory.
  */
-export async function loadDelegationRecords(baseDir, sessionFilter) {
-    const auditFile = path.join(baseDir, REA_DIR, AUDIT_FILE);
-    let raw;
+export async function listRotatedAuditFiles(reaDir) {
+    let entries;
     try {
-        raw = await fs.readFile(auditFile, 'utf8');
+        entries = await fs.readdir(reaDir);
     }
-    catch (e) {
-        if (e.code === 'ENOENT') {
-            return { records: [], filesScanned: [] };
+    catch {
+        return [];
+    }
+    const rotated = entries.filter((n) => ROTATED_AUDIT_RE.test(n));
+    rotated.sort((a, b) => {
+        const [stampA, suffixA] = rotatedAuditSortKey(a);
+        const [stampB, suffixB] = rotatedAuditSortKey(b);
+        if (stampA !== stampB)
+            return stampA < stampB ? -1 : 1;
+        return suffixA - suffixB;
+    });
+    return rotated;
+}
+/**
+ * Resolve the ordered list of absolute audit-file paths to walk.
+ *
+ * - `since === undefined` → just the current `.rea/audit.jsonl` (when
+ *   it exists). Pre-0.31.0 behavior.
+ * - `since` set → validate it names a real rotated file, then walk
+ *   that file + every later rotated file (timestamp-ascending), with
+ *   the current `audit.jsonl` as the tail.
+ *
+ * The current `audit.jsonl` is included at the END of the walk
+ * whenever it exists — it is always the newest segment of the chain.
+ * A `--since` that names a non-rotated string, or a rotated file that
+ * isn't present on disk, throws `AuditSpecialistsSinceError`.
+ */
+export async function resolveAuditFileWalk(baseDir, since) {
+    const reaDir = path.join(baseDir, REA_DIR);
+    const currentAudit = path.join(reaDir, AUDIT_FILE);
+    const files = [];
+    if (since !== undefined && since.length > 0) {
+        const sinceName = path.basename(since);
+        if (!ROTATED_AUDIT_RE.test(sinceName)) {
+            throw new AuditSpecialistsSinceError(`--since must name a rotated audit file (audit-YYYYMMDD-HHMMSS.jsonl); got ${JSON.stringify(since)}`);
         }
-        throw e;
+        const allRotated = await listRotatedAuditFiles(reaDir);
+        const startIdx = allRotated.indexOf(sinceName);
+        if (startIdx === -1) {
+            throw new AuditSpecialistsSinceError(`Rotated file not found: ${path.join(REA_DIR, sinceName)}`);
+        }
+        for (const name of allRotated.slice(startIdx)) {
+            files.push(path.join(reaDir, name));
+        }
+    }
+    // The current audit.jsonl is always the tail of the walk (when present).
+    try {
+        const stat = await fs.stat(currentAudit);
+        if (stat.isFile())
+            files.push(currentAudit);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
     }
+    return files;
+}
+/**
+ * Read the audit file(s) and return delegation records (filtered +
+ * parsed into a reader-friendly shape). Malformed lines are skipped
+ * silently — `rea audit verify` is the right tool for chain integrity.
+ *
+ * `since` defaults to `undefined` (current `.rea/audit.jsonl` only) so
+ * existing callers — including `computeDelegationAdvisory` in
+ * `delegation-advisory.ts` — keep their pre-0.31.0 single-file
+ * behavior without passing the argument.
+ */
+export async function loadDelegationRecords(baseDir, sessionFilter, since) {
+    const filesToWalk = await resolveAuditFileWalk(baseDir, since);
     const records = [];
-    for (const line of raw.split('\n')) {
-        if (line.length === 0)
-            continue;
-        let parsed;
+    const filesScanned = [];
+    for (const auditFile of filesToWalk) {
+        let raw;
         try {
-            parsed = JSON.parse(line);
+            raw = await fs.readFile(auditFile, 'utf8');
         }
-        catch {
-            continue;
+        catch (e) {
+            if (e.code === 'ENOENT')
+                continue;
+            throw e;
         }
-        if (!isDelegationRecord(parsed))
-            continue;
-        const m = parsed.metadata;
-        if (sessionFilter !== null && m.session_id_observed !== sessionFilter)
-            continue;
-        const rec = {
-            timestamp: parsed.timestamp,
-            session_id_observed: m.session_id_observed,
-            delegation_tool: m.delegation_tool,
-            subagent_type: m.subagent_type,
-            parent_subagent_type: m.parent_subagent_type,
-            invocation_description_sha256: m.invocation_description_sha256,
-            ...(m.hook_event_timestamp !== undefined
-                ? { hook_event_timestamp: m.hook_event_timestamp }
-                : {}),
-        };
-        records.push(rec);
-    }
-    return { records, filesScanned: [auditFile] };
+        filesScanned.push(auditFile);
+        for (const line of raw.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isDelegationRecord(parsed))
+                continue;
+            const m = parsed.metadata;
+            if (sessionFilter !== null && m.session_id_observed !== sessionFilter)
+                continue;
+            const rec = {
+                timestamp: parsed.timestamp,
+                session_id_observed: m.session_id_observed,
+                delegation_tool: m.delegation_tool,
+                subagent_type: m.subagent_type,
+                parent_subagent_type: m.parent_subagent_type,
+                invocation_description_sha256: m.invocation_description_sha256,
+                ...(m.hook_event_timestamp !== undefined
+                    ? { hook_event_timestamp: m.hook_event_timestamp }
+                    : {}),
+            };
+            records.push(rec);
+        }
+    }
+    return { records, filesScanned };
 }
 /**
  * Group records by `subagent_type`. Sorts by descending count, then
@@ -136,7 +277,24 @@ export async function computeAuditSpecialists(options = {}) {
     const baseDir = options.baseDir ?? process.cwd();
     let sessionFilter;
     let source;
-    if (options.sessionFilter === undefined) {
+    // Precedence: explicit `sessionFilter` test seam > `--session` flag >
+    // `$CLAUDE_SESSION_ID` env > no filter.
+    if (options.sessionFilter !== undefined) {
+        sessionFilter = options.sessionFilter;
+        source = options.sessionFilter === null ? 'none' : 'option';
+    }
+    else if (options.sessionOption !== undefined && options.sessionOption.length > 0) {
+        // `--session all` (case-insensitive) means "show every session".
+        if (options.sessionOption.toLowerCase() === 'all') {
+            sessionFilter = null;
+            source = 'none';
+        }
+        else {
+            sessionFilter = options.sessionOption;
+            source = 'option';
+        }
+    }
+    else {
         const envId = process.env['CLAUDE_SESSION_ID'];
         if (typeof envId === 'string' && envId.length > 0) {
             sessionFilter = envId;
@@ -147,11 +305,7 @@ export async function computeAuditSpecialists(options = {}) {
             source = 'none';
         }
     }
-    else {
-        sessionFilter = options.sessionFilter;
-        source = options.sessionFilter === null ? 'none' : 'option';
-    }
-    const { records, filesScanned } = await loadDelegationRecords(baseDir, sessionFilter);
+    const { records, filesScanned } = await loadDelegationRecords(baseDir, sessionFilter, options.since);
     const groups = groupBySubagent(records);
     return {
         session_filter: sessionFilter,
@@ -186,11 +340,22 @@ function renderTable(result) {
     return lines.join('\n') + '\n';
 }
 /**
- * Commander entrypoint. Reads, renders, exits 0. The CLI is read-only
- * — no audit-chain writes, no exit-code-as-verdict semantics.
+ * Commander entrypoint. Reads, renders, exits 0 on success / 1 when
+ * `--since` is malformed or names a missing rotated file. The CLI is
+ * read-only — no audit-chain writes.
  */
 export async function runAuditSpecialists(options) {
-    const result = await computeAuditSpecialists(options);
+    let result;
+    try {
+        result = await computeAuditSpecialists(options);
+    }
+    catch (e) {
+        if (e instanceof AuditSpecialistsSinceError) {
+            process.stderr.write(`rea audit specialists: ${e.message}\n`);
+            process.exit(1);
+        }
+        throw e;
+    }
     if (options.json === true) {
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
         return;
@@ -199,7 +364,11 @@ export async function runAuditSpecialists(options) {
         log(`Delegation signals (session=${result.session_filter}, source=${result.session_filter_source}):`);
     }
     else {
-        log('Delegation signals (no session filter — set $CLAUDE_SESSION_ID to scope; v1 omits --since / --session by design):');
+        log('Delegation signals (no session filter — pass --session <id> to scope, ' +
+            '--session all to show every session, or set $CLAUDE_SESSION_ID):');
+    }
+    if (result.files_scanned.length > 1) {
+        log(`  scanned ${String(result.files_scanned.length)} audit files (--since walk).`);
     }
     process.stdout.write(renderTable(result));
 }
@@ -212,9 +381,15 @@ export async function runAuditSpecialists(options) {
 export function registerAuditSpecialistsSubcommand(auditCommand) {
     auditCommand
         .command('specialists')
-        .description('Summarize `rea.delegation_signal` audit records — counts per subagent / skill, last-seen timestamps, agent-vs-skill breakdown. Reads only the current `.rea/audit.jsonl`. Honors $CLAUDE_SESSION_ID for current-session filtering. v1 omits --since / --session by design (deferred to 0.29.1).')
-        .option('--json', 'emit JSON (records + groups) instead of the human-readable table. Composes with jq.')
+        .description('Summarize `rea.delegation_signal` audit records — counts per subagent / skill, last-seen timestamps, agent-vs-skill breakdown. Walks `.rea/audit.jsonl` (plus rotated files with --since). Honors --session / $CLAUDE_SESSION_ID for session scoping.')
+        .option('--json', 'emit JSON (records + groups + files_scanned) instead of the human-readable table. Composes with jq.')
+        .option('--session <id>', 'filter to a specific session_id_observed. Wins over $CLAUDE_SESSION_ID. The literal `all` disables session filtering (shows every session). When omitted, falls back to $CLAUDE_SESSION_ID then no filter.')
+        .option('--since <rotated-file>', 'extend the walk backward through rotated audit files. Names a rotated file (audit-YYYYMMDD-HHMMSS.jsonl); that file and every later rotated file are scanned, then the current audit.jsonl. Mirrors `rea audit verify --since`.')
         .action(async (opts) => {
-        await runAuditSpecialists({ ...(opts.json === true ? { json: true } : {}) });
+        await runAuditSpecialists({
+            ...(opts.json === true ? { json: true } : {}),
+            ...(opts.session !== undefined ? { sessionOption: opts.session } : {}),
+            ...(opts.since !== undefined ? { since: opts.since } : {}),
+        });
     });
 }

package/dist/cli/delegation-advisory.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `rea hook delegation-advisory` — the 0.31.0 delegation *nudge*.
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer (the
+ * `Agent|Skill` PreToolUse capture hook + `rea audit specialists`
+ * reader). It could *see* delegation patterns but said nothing about
+ * them. 0.31.0 closes the loop: the `delegation-advisory.sh` PostToolUse
+ * hook (matcher `Bash|Edit|Write|MultiEdit|NotebookEdit`) pipes each
+ * write-class tool call through this CLI, which maintains a per-session
+ * counter and — the FIRST time the counter crosses
+ * `policy.delegation_advisory.threshold` while the session has recorded
+ * ZERO real delegation signals — prints a one-time stderr advisory.
+ *
+ * # Advisory, never gating
+ *
+ * The CLI ALWAYS exits 0 except under HALT (exit 2, to keep the
+ * kill-switch contract uniform with the rest of the hook tree). It
+ * NEVER blocks a tool call. The whole point is a nudge — "this session
+ * has done a lot of work without delegating to a specialist" — not an
+ * enforcement gate. A consumer who disagrees sets
+ * `policy.delegation_advisory.enabled: false` (the schema default; only
+ * `bst-internal*` profiles pin `true`) and the hook is a silent no-op.
+ *
+ * # State: the per-session counter directory
+ *
+ * State lives under `.rea/.delegation-advisory/`:
+ *
+ *   - `<state-key>.count`  — a single integer, the running write-class
+ *     tool-call count for the session.
+ *   - `<state-key>.fired` — a sentinel file; present once the advisory
+ *     has fired for the session, so it never fires twice.
+ *
+ * The session id comes from the untrusted hook payload, so it is run
+ * through `sessionStateKey` before it touches a filesystem path. That
+ * key is `<readable-prefix>-<hash>`: a sanitized, length-capped prefix
+ * (`[A-Za-z0-9._-]` only — keeps the directory glanceable) plus a short
+ * SHA-256 hex digest of the RAW id. The hash suffix is the correctness
+ * half — a bare sanitized prefix is lossy (`a/b` and `a:b` both
+ * sanitize to `a_b`), so two distinct sessions would otherwise share
+ * `count`/`fired` files and one could inherit the other's counter or
+ * suppress the other's advisory. A missing / empty / non-string session
+ * id collapses to the literal `unknown` key, so sessions Claude Code
+ * didn't tag still get a (deliberately shared) counter rather than
+ * crashing the hook — and that matches the `'unknown'` audit-form id
+ * `runHookDelegationSignal` records for the same untagged sessions.
+ *
+ * The directory is best-effort: any filesystem error (ENOSPC, EACCES,
+ * a read-only `.rea/`) is swallowed and the CLI exits 0. Losing the
+ * nudge is acceptable; breaking tool dispatch is not.
+ *
+ * # The "did this session delegate" predicate
+ *
+ * A session has delegated when `.rea/audit.jsonl` contains at least one
+ * `rea.delegation_signal` record whose `session_id_observed` matches
+ * the current session AND that record counts as a REAL delegation per
+ * `countsAsRealDelegation` (see `src/cli/roster.ts`): every `Skill`
+ * signal counts; an `Agent` signal counts when its `subagent_type` is
+ * a discovered curated specialist and not in the exempt set.
+ *
+ * Scanning the whole audit chain on every write-class tool call would
+ * be wasteful, so the scan is gated: it only runs when the counter has
+ * actually reached the threshold (the rare case). Below the threshold
+ * the CLI just bumps the counter and exits.
+ */
+/**
+ * Resolved `policy.delegation_advisory` knobs the CLI actually acts on.
+ * Defaults mirror `DelegationAdvisoryPolicySchema` in
+ * `src/policy/loader.ts` — kept in sync by hand; the policy-schema test
+ * pins both so drift fails loud.
+ */
+interface ResolvedAdvisoryPolicy {
+    enabled: boolean;
+    threshold: number;
+    exemptSubagents: readonly string[];
+}
+export interface HookDelegationAdvisoryOptions {
+    /**
+     * Override REA_ROOT. Tests set this; the production caller relies on
+     * `$CLAUDE_PROJECT_DIR` or `process.cwd()`.
+     */
+    reaRoot?: string;
+    /**
+     * Test seam — inject the resolved policy instead of reading
+     * `.rea/policy.yaml`. Production omits; the CLI reads policy itself.
+     */
+    policyOverride?: ResolvedAdvisoryPolicy;
+    /**
+     * Test seam — inject stdin instead of reading the real stream.
+     * Production omits.
+     */
+    stdinOverride?: string;
+}
+/**
+ * Derive a filesystem-safe, **collision-free** per-session state-key
+ * basename from an untrusted session id.
+ *
+ * Shape: `<readable-prefix>-<hash>` where
+ *
+ *   - `<readable-prefix>` is the raw id with every byte outside
+ *     `[A-Za-z0-9._-]` replaced by `_`, length-capped at
+ *     `STATE_KEY_PREFIX_CAP`. Path-traversal basenames (`.`, `..`) and
+ *     an empty/all-stripped result collapse to `unknown`. This half is
+ *     purely for human glanceability of the `.rea/.delegation-advisory/`
+ *     directory — it is intentionally lossy.
+ *   - `<hash>` is the first 16 hex chars of `sha256(raw)`. This is the
+ *     correctness half: the sanitized prefix alone is lossy (`a/b` and
+ *     `a:b` both sanitize to `a_b`), so without the hash two distinct
+ *     sessions would share `count`/`fired` files — one could inherit the
+ *     other's counter or suppress the other's advisory. The hash is
+ *     computed over the RAW id, so distinct raw ids always get distinct
+ *     keys.
+ *
+ * A missing / empty / non-string id returns the fixed key `unknown` (no
+ * hash suffix) — every untagged session deliberately shares one counter,
+ * matching the `'unknown'` audit-form id `runHookDelegationSignal`
+ * records for the same sessions.
+ *
+ * The result is always a safe single path segment: no `/`, no `..`, no
+ * leading dot beyond the literal `unknown`, bounded length.
+ */
+export declare function sessionStateKey(raw: unknown): string;
+/**
+ * The advisory text. Factored out so the test can assert on it without
+ * duplicating the prose. Printed to stderr (the hook's only output
+ * channel) exactly once per session.
+ */
+export declare function advisoryMessage(count: number, threshold: number): string;
+/**
+ * Core logic, exported for direct unit testing without spawning a
+ * process. Returns the action taken so tests can assert without
+ * capturing stderr.
+ */
+export interface DelegationAdvisoryResult {
+    /** `'disabled'` when policy is off; `'halt'` under HALT; otherwise `'ran'`. */
+    outcome: 'disabled' | 'halt' | 'ran' | 'no-payload';
+    /** Post-increment counter value (only meaningful when `outcome === 'ran'`). */
+    count?: number;
+    /** `true` when the advisory was printed this invocation. */
+    fired?: boolean;
+    /**
+     * The `sessionStateKey()`-derived filesystem basename used for the
+     * `.count` / `.fired` state files (`<readable-prefix>-<hash>`, or the
+     * literal `unknown` for an untagged session). Collision-free across
+     * distinct raw session ids. Field name kept as `sessionId` for
+     * backward-compatible result-shape; it is a state key, not the raw id.
+     */
+    sessionId?: string;
+}
+export declare function computeDelegationAdvisory(options: HookDelegationAdvisoryOptions): Promise<DelegationAdvisoryResult>;
+/**
+ * Commander entrypoint. Reads the hook payload, runs the advisory
+ * logic, exits.
+ *
+ * Exit-code contract:
+ *   0 — always, EXCEPT HALT. Disabled, no-payload, below-threshold,
+ *       already-fired, just-fired — all exit 0. The advisory is a
+ *       nudge, never a gate.
+ *   2 — HALT active (kill-switch contract uniform with the hook tree).
+ */
+export declare function runHookDelegationAdvisory(options?: HookDelegationAdvisoryOptions): Promise<void>;
+export {};