@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/cache_realization_report.ts

@@ -24,6 +24,7 @@
  *   ./scripts-run src/scripts/cache_realization_report [--format text|json]
  *     [--root <path>] [--max-age-days <n>] [--repo-root <path>]
  *     [--council-root <path>] [--user-rules-dir <path>] [--project-rules-dir <path>]
+ *     [--ledger-dir <path>]
  *
  * Defaults: `--root` is `~/.claude/projects` (the full tree, matching the
  * roadmap's own "First-party measurement" method — no per-project filter);
@@ -53,6 +54,7 @@ import {
     type TranscriptRecord,
 } from './_lib/cc_transcript.js';
 import { censusDuplicateScope } from './_lib/duplicate_scope_census.js';
+import { LEDGER_DIR, refFor } from './hooks/subagent_ledger_hook.js';
 import { load_prices, reprice_with_cache } from './ai_council/pricing.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -131,23 +133,25 @@ function firstCallsByLeg(records: readonly TranscriptRecord[]): TranscriptRecord
         byAgent.set(r.agentId, arr);
     }
     const firstCalls: TranscriptRecord[] = [];
-    for (const arr of byAgent.values()) {
-        const sorted = arr
-            .map((r, idx) => ({ r, idx }))
-            .sort((a, b) => {
-                const ta = a.r.timestamp;
-                const tb = b.r.timestamp;
-                if (ta !== null && tb !== null && ta !== tb) return ta < tb ? -1 : 1;
-                if (ta !== null && tb === null) return -1;
-                if (ta === null && tb !== null) return 1;
-                return a.idx - b.idx;
-            })
-            .map((x) => x.r);
-        firstCalls.push(sorted[0] as TranscriptRecord);
-    }
+    for (const arr of byAgent.values()) firstCalls.push(chronological(arr)[0] as TranscriptRecord);
     return firstCalls;
 }
 
+/** One leg's records in chronological order; scan order breaks ties, missing timestamps sort last. */
+function chronological(arr: readonly TranscriptRecord[]): TranscriptRecord[] {
+    return arr
+        .map((r, idx) => ({ r, idx }))
+        .sort((a, b) => {
+            const ta = a.r.timestamp;
+            const tb = b.r.timestamp;
+            if (ta !== null && tb !== null && ta !== tb) return ta < tb ? -1 : 1;
+            if (ta !== null && tb === null) return -1;
+            if (ta === null && tb !== null) return 1;
+            return a.idx - b.idx;
+        })
+        .map((x) => x.r);
+}
+
 export function computeColdStarts(records: readonly TranscriptRecord[]): ColdStartStats {
     const subagentRecords = records.filter((r) => r.bucket === 'subagent');
     const totalWriteVolume = subagentRecords.reduce((s, r) => s + r.usage.cache_creation_input_tokens, 0);
@@ -177,6 +181,127 @@ export function computeColdStarts(records: readonly TranscriptRecord[]): ColdSta
     };
 }
 
+// A resumed subagent keeps its `agentId`, so `firstCallsByLeg` folds a
+// resume's first call into the original leg and the cold-start median cannot
+// see whether a resume was cheap. The ledger records a `subagent_start` per
+// run under `ref = refFor(agentId)`; every start after the first for one ref
+// opens a new run, and each run gets its own first-call metrics.
+
+export interface LedgerStart {
+    ref: string;
+    ts: string;
+}
+
+export interface SubagentRun {
+    /** Ledger ref of the leg — never the host's agent id. */
+    ref: string;
+    /** 1 for the original spawn, 2+ for each resume the ledger saw. */
+    ordinal: number;
+    calls: number;
+    first_call_written_or_uncached: number;
+    first_call_cache_read_share: number;
+}
+
+export interface SubagentRunStats {
+    /** Legs whose ref has at least one `subagent_start` in the ledger. */
+    legs_with_ledger_start: number;
+    resumed_runs: number;
+    /** `null` when no resumed run exists — a median of nothing is not 0. */
+    median_resumed_first_call_written_or_uncached: number | null;
+    runs: SubagentRun[];
+}
+
+/** `subagent_start` lines carrying a ref, from every `*.jsonl` in `ledgerDir`. Missing dir → []. */
+export function readLedgerStarts(ledgerDir: string): LedgerStart[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(ledgerDir).filter((n) => n.endsWith('.jsonl'));
+    } catch {
+        return [];
+    }
+    const out: LedgerStart[] = [];
+    for (const name of names.sort()) {
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(ledgerDir, name), 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim()) continue;
+            let v: unknown;
+            try {
+                v = JSON.parse(line);
+            } catch {
+                continue;
+            }
+            if (typeof v !== 'object' || v === null) continue;
+            const o = v as Record<string, unknown>;
+            if (o['event'] !== 'subagent_start') continue;
+            const ref = o['ref'];
+            const ts = o['ts'];
+            if (typeof ref !== 'string' || typeof ts !== 'string') continue;
+            out.push({ ref, ts });
+        }
+    }
+    return out;
+}
+
+export function segmentLegsIntoRuns(records: readonly TranscriptRecord[], starts: readonly LedgerStart[]): SubagentRunStats {
+    const startsByRef = new Map<string, string[]>();
+    for (const s of starts) {
+        const arr = startsByRef.get(s.ref) ?? [];
+        arr.push(s.ts);
+        startsByRef.set(s.ref, arr);
+    }
+    for (const arr of startsByRef.values()) arr.sort();
+
+    const byAgent = new Map<string, TranscriptRecord[]>();
+    for (const r of records) {
+        if (r.bucket !== 'subagent' || r.agentId === null) continue;
+        const arr = byAgent.get(r.agentId) ?? [];
+        arr.push(r);
+        byAgent.set(r.agentId, arr);
+    }
+
+    const runs: SubagentRun[] = [];
+    let legsWithStart = 0;
+    for (const [agentId, recs] of byAgent) {
+        const ref = refFor(agentId);
+        const legStarts = startsByRef.get(ref) ?? [];
+        if (legStarts.length > 0) legsWithStart++;
+        const boundaries = legStarts.slice(1);
+        const byOrdinal = new Map<number, TranscriptRecord[]>();
+        for (const r of chronological(recs)) {
+            const ts = r.timestamp;
+            const ordinal = 1 + (ts === null ? 0 : boundaries.filter((b) => b <= ts).length);
+            const arr = byOrdinal.get(ordinal) ?? [];
+            arr.push(r);
+            byOrdinal.set(ordinal, arr);
+        }
+        for (const ordinal of [...byOrdinal.keys()].sort((a, b) => a - b)) {
+            const arr = byOrdinal.get(ordinal) as TranscriptRecord[];
+            const first = arr[0] as TranscriptRecord;
+            const billable = billableInputTokens(first.usage);
+            runs.push({
+                ref,
+                ordinal,
+                calls: arr.length,
+                first_call_written_or_uncached: first.usage.cache_creation_input_tokens + first.usage.input_tokens,
+                first_call_cache_read_share: billable > 0 ? first.usage.cache_read_input_tokens / billable : 0,
+            });
+        }
+    }
+    const resumed = runs.filter((r) => r.ordinal > 1);
+    return {
+        legs_with_ledger_start: legsWithStart,
+        resumed_runs: resumed.length,
+        median_resumed_first_call_written_or_uncached:
+            resumed.length > 0 ? median(resumed.map((r) => r.first_call_written_or_uncached)) : null,
+        runs,
+    };
+}
+
 // ── per-agentId breakdown ───────────────────────────────────────────────
 
 export interface AgentAggregate extends BucketAggregate {
@@ -642,6 +767,7 @@ export interface Options {
     userRulesDir: string;
     projectRulesDir: string;
     auditDir: string;
+    ledgerDir: string;
 }
 
 function defaultOptions(): Options {
@@ -654,6 +780,7 @@ function defaultOptions(): Options {
         userRulesDir: path.join(homedir(), '.claude', 'rules'),
         projectRulesDir: path.join(REPO_ROOT, 'dist', 'agent-src', 'rules'),
         auditDir: path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'audit'),
+        ledgerDir: path.join(REPO_ROOT, LEDGER_DIR),
     };
 }
 
@@ -678,6 +805,8 @@ export function parseArgs(argv: string[]): Options {
         else if (a.startsWith('--project-rules-dir=')) opts.projectRulesDir = a.slice('--project-rules-dir='.length);
         else if (a === '--audit-dir') opts.auditDir = argv[++i] ?? opts.auditDir;
         else if (a.startsWith('--audit-dir=')) opts.auditDir = a.slice('--audit-dir='.length);
+        else if (a === '--ledger-dir') opts.ledgerDir = argv[++i] ?? opts.ledgerDir;
+        else if (a.startsWith('--ledger-dir=')) opts.ledgerDir = a.slice('--ledger-dir='.length);
     }
     if (opts.format !== 'text' && opts.format !== 'json') opts.format = 'text';
     return opts;
@@ -763,6 +892,8 @@ export interface Report {
     deduped_count: number;
     buckets: Record<TranscriptBucket, BucketAggregate>;
     subagent_cold_start: ColdStartStats;
+    /** Runs within each leg, split at ledger re-starts. */
+    subagent_runs: SubagentRunStats;
     by_agent: AgentAggregate[];
     duplicate_scope: DuplicateScopeResult;
     council_mispricing: CouncilMispricingResult;
@@ -848,6 +979,7 @@ export function buildReport(opts: Options): Report {
         deduped_count: scan.dedupedCount,
         buckets,
         subagent_cold_start: subagentColdStart,
+        subagent_runs: segmentLegsIntoRuns(scan.records, readLedgerStarts(opts.ledgerDir)),
         by_agent: byAgent,
         duplicate_scope: duplicateScope,
         council_mispricing: councilMispricing,
@@ -941,6 +1073,15 @@ export function renderText(r: Report): string {
     );
     out.push('');
 
+    const sr = r.subagent_runs;
+    const resumedMedian = sr.median_resumed_first_call_written_or_uncached;
+    out.push('Subagent runs (a leg split at every ledger re-start):');
+    out.push(
+        `  legs_with_ledger_start=${sr.legs_with_ledger_start} runs=${sr.runs.length} resumed_runs=${sr.resumed_runs}` +
+            ` median_resumed_written_or_uncached=${resumedMedian === null ? 'none' : Math.round(resumedMedian)}`,
+    );
+    out.push('');
+
     out.push(`Per-agent breakdown: ${r.by_agent.length} distinct subagent legs (--format json carries all; top 10 by weighted_input_units below)`);
     const top10 = [...r.by_agent].sort((a, b) => b.weighted_input_units - a.weighted_input_units).slice(0, 10);
     for (const a of top10) {

package/src/scripts/canary_liveness.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Liveness of the weekly cross-model canary (free-hands 5.3, gateway M9).
+ *
+ * ADR-118 makes the canary's red the maintainer notification, and six ignored
+ * scheduled reds made it decorative. No new scheduled workflow: this reads the
+ * existing workflow's scheduled runs, and a streak of three or more reds writes
+ * one status line that `agent-config doctor` and the session-start
+ * council-availability fact surface. One green run clears it.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/canary_liveness [--refresh] [--json]
+ *
+ * `--refresh` asks `gh` for the workflow's recent scheduled runs; without it the
+ * recorded state is printed. Nothing here calls a model or spends anything.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { CANARY_LIVENESS_RELPATH, CANARY_RED_STREAK, readCanaryStatusLine } from './_lib/canary_status.js';
+import { sanitize_text } from './_lib/retrieval_sanitize.js';
+
+const _ISO_TS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+export const CANARY_WORKFLOW = 'cross-model-canary.yml';
+
+export interface CanaryRun {
+    readonly id: number;
+    /** The run's conclusion as `gh` reports it: `success`, `failure`, `skipped`, `cancelled`, … */
+    readonly conclusion: string;
+    readonly created_at: string;
+}
+
+export interface CanaryLiveness {
+    readonly red_streak: number;
+    /** `created_at` of the oldest red in the current streak; null without a streak. */
+    readonly red_since: string | null;
+    readonly last_run_id: number | null;
+}
+
+/** A red counts, a green ends the streak, anything else (skipped, cancelled, pending) is no evidence. */
+export function foldCanaryRuns(runs: readonly CanaryRun[]): CanaryLiveness {
+    const newestFirst = [...runs].sort((a, b) => b.created_at.localeCompare(a.created_at));
+    let red_streak = 0;
+    let red_since: string | null = null;
+    for (const r of newestFirst) {
+        if (r.conclusion === 'success') break;
+        if (r.conclusion !== 'failure' && r.conclusion !== 'timed_out') continue;
+        red_streak += 1;
+        red_since = r.created_at;
+    }
+    return { red_streak, red_since, last_run_id: newestFirst[0]?.id ?? null };
+}
+
+export function statusLine(l: CanaryLiveness): string | null {
+    if (l.red_streak < CANARY_RED_STREAK || l.red_since === null) return null;
+    return (
+        `cross-model canary: ${String(l.red_streak)} scheduled runs red in a row since ${l.red_since.slice(0, 10)} — ` +
+        `the live tier is not answering; read \`gh run list --workflow ${CANARY_WORKFLOW} --event schedule\``
+    );
+}
+
+export function recordCanaryRuns(repoRoot: string, runs: readonly CanaryRun[], now: Date = new Date()): string | null {
+    const l = foldCanaryRuns(runs);
+    const line = statusLine(l);
+    const target = path.join(repoRoot, CANARY_LIVENESS_RELPATH);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify({ ...l, observed_at: now.toISOString(), line }, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, target);
+    return line;
+}
+
+/** The workflow's recent scheduled runs, or null when `gh` cannot answer. */
+export function fetchScheduledRuns(cwd: string): CanaryRun[] | null {
+    const r = spawnSync(
+        'gh',
+        ['run', 'list', '--workflow', CANARY_WORKFLOW, '--event', 'schedule', '--limit', '10', '--json', 'databaseId,conclusion,createdAt'],
+        { cwd, encoding: 'utf8', timeout: 30_000 },
+    );
+    if (r.status !== 0) return null;
+    try {
+        // `created_at` reaches the session-start context, so only a timestamp shape is kept.
+        const rows = JSON.parse(sanitize_text(r.stdout)) as { databaseId?: unknown; conclusion?: unknown; createdAt?: unknown }[];
+        return rows
+            .filter((x) => typeof x.databaseId === 'number' && typeof x.createdAt === 'string' && _ISO_TS.test(x.createdAt))
+            .map((x) => ({
+                id: x.databaseId as number,
+                conclusion: typeof x.conclusion === 'string' && /^[a-z_]+$/.test(x.conclusion) ? x.conclusion : '',
+                created_at: x.createdAt as string,
+            }));
+    } catch {
+        return null;
+    }
+}
+
+export function main(argv: readonly string[], cwd: string = process.cwd()): number {
+    if (argv.includes('--refresh')) {
+        const runs = fetchScheduledRuns(cwd);
+        if (runs === null) {
+            process.stderr.write('canary_liveness: gh could not list the scheduled runs; the recorded state is unchanged\n');
+            return 3;
+        }
+        recordCanaryRuns(cwd, runs);
+    }
+    const line = readCanaryStatusLine(cwd);
+    if (argv.includes('--json')) process.stdout.write(`${JSON.stringify({ line })}\n`);
+    else process.stdout.write(`${line ?? 'cross-model canary: no red streak recorded'}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/chat_history.ts

@@ -65,9 +65,18 @@ function _is_replay_mode(): boolean {
 }
 
 const _WS_RE = /\s+/g;
-export const SESSION_ID_LEN = 16;
-export const SESSION_ID_UNKNOWN = '<unknown>';
-export const SESSION_ID_LEGACY = '<legacy>';
+// The session tag and its sentinels live in `_lib/session_tag.ts` and are
+// re-exported here so this module's public API is unchanged. They moved out
+// so `hooks/interruption_ledger_hook.ts` can import five lines without
+// pulling this module's ~121 KB closure into the hook dispatch bundle.
+import {
+    SESSION_ID_LEGACY,
+    SESSION_ID_LEN,
+    SESSION_ID_UNKNOWN,
+    derive_session_tag,
+    fingerprint,
+} from './_lib/session_tag.js';
+export { SESSION_ID_LEGACY, SESSION_ID_LEN, SESSION_ID_UNKNOWN, derive_session_tag, fingerprint };
 // Sentinel for entries without an `agent` field — legacy rows or
 // direct `append` calls that bypassed the platform-hook surface.
 export const AGENT_UNKNOWN = '<unknown>';
@@ -318,18 +327,6 @@ function _now(): string {
     return new Date().toISOString().replace(/\.\d{3}Z$/, '+00:00');
 }
 
-export function fingerprint(value: string): string {
-    const normalized = _strip((value || '').replace(_WS_RE, ' '));
-    return createHash('sha256').update(normalized, 'utf-8').digest('hex');
-}
-
-export function derive_session_tag(session_id: string): string {
-    if (!session_id) {
-        return SESSION_ID_UNKNOWN;
-    }
-    return fingerprint(session_id).slice(0, SESSION_ID_LEN);
-}
-
 function _isFile(p: string): boolean {
     try {
         return fs.statSync(p).isFile();