@bookedsolid/rea 0.30.1 → 0.31.0

package/dist/cli/audit-specialists.d.ts

@@ -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,8 +36,8 @@
  *   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 type { Command } from 'commander';
@@ -34,17 +47,48 @@ export interface AuditSpecialistsOptions {
     json?: boolean;
     /**
      * Override session filtering. Production callers omit (the CLI reads
-     * `CLAUDE_SESSION_ID` from the env). Tests set this so they don't
-     * mutate `process.env`.
+     * `--session` then `CLAUDE_SESSION_ID` from the env). Tests set this
+     * so they don't mutate `process.env`.
      *
      * - `string` → filter to records whose `session_id_observed` matches.
      * - `null`   → no filter (show all records).
-     * - `undefined` → derive from env.
+     * - `undefined` → derive from `--session` flag then env.
      */
     sessionFilter?: string | null;
+    /**
+     * 0.31.0 — explicit `--session <id>` flag value. Resolution rules:
+     *
+     *   - `'all'` (case-insensitive) → no filter (equivalent to
+     *     `sessionFilter: null`), `session_filter_source: 'option'`.
+     *   - any other non-empty string → filter to that session,
+     *     `session_filter_source: 'option'`.
+     *   - `undefined` → fall through to `sessionFilter`, then env.
+     *
+     * `sessionFilter` (the test seam) still wins over this when both are
+     * set — tests inject `sessionFilter` directly and don't pass
+     * `sessionOption`.
+     */
+    sessionOption?: string;
+    /**
+     * 0.31.0 — `--since <rotated-file>` flag value. When set, the named
+     * rotated audit file plus every later rotated file (timestamp-
+     * ascending) are walked before the current `.rea/audit.jsonl`.
+     * Must match `audit-YYYYMMDD-HHMMSS(-N).jsonl`. Validation failure
+     * throws `AuditSpecialistsSinceError` so the commander wrapper can
+     * exit 1 with a clear message.
+     */
+    since?: string;
     /** Override CWD. Tests set this; production uses `process.cwd()`. */
     baseDir?: string;
 }
+/**
+ * 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 declare class AuditSpecialistsSinceError extends Error {
+    constructor(message: string);
+}
 interface DelegationGroup {
     subagent_type: string;
     count: number;
@@ -53,7 +97,7 @@ interface DelegationGroup {
     /** Breakdown of which delegation_tool fired (Agent vs. Skill). */
     by_tool: Record<DelegationTool, number>;
 }
-interface DelegationRecord {
+export interface DelegationRecord {
     timestamp: string;
     session_id_observed: string;
     delegation_tool: DelegationTool;
@@ -78,11 +122,48 @@ interface AuditSpecialistsResult {
     files_scanned: string[];
 }
 /**
- * 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.
+ * 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 declare function listRotatedAuditFiles(reaDir: string): Promise<string[]>;
+/**
+ * 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 declare function resolveAuditFileWalk(baseDir: string, since: string | undefined): Promise<string[]>;
+/**
+ * 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 declare function loadDelegationRecords(baseDir: string, sessionFilter: string | null): Promise<{
+export declare function loadDelegationRecords(baseDir: string, sessionFilter: string | null, since?: string): Promise<{
     records: DelegationRecord[];
     filesScanned: string[];
 }>;
@@ -99,8 +180,9 @@ export declare function groupBySubagent(records: DelegationRecord[]): Delegation
  */
 export declare function computeAuditSpecialists(options?: AuditSpecialistsOptions): Promise<AuditSpecialistsResult>;
 /**
- * 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 declare function runAuditSpecialists(options: AuditSpecialistsOptions): Promise<void>;
 /**

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 } : {}),
+        });
     });
 }