@event4u/agent-config 9.29.0 → 9.30.0

package/src/scripts/session_eol_report.ts

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * session_eol_report — session end-of-life baseline over the local
+ * Claude Code transcript store (road-to-token-economy-recycling Phases
+ * 1.1–1.3). Read-only; prints aggregate numbers, never content.
+ *
+ * Per session file (main chain only): final context size in parsed tokens
+ * (`cc_transcript.billableInputTokens` of the last assistant record), turn
+ * count, and every observed compaction event (`_lib/session_eol.ts`
+ * detector, pinned to the observed `compact_boundary` marker). The
+ * aggregate is the baseline the recycle threshold cites
+ * (`src/config/recycle-threshold-budget.json`), and the reproduce command
+ * for `agents/evidence/analysis/token-economy-recycling-phase1.md`:
+ *
+ *     ./scripts-run src/scripts/session_eol_report            # text
+ *     ./scripts-run src/scripts/session_eol_report -- --json  # machine
+ *
+ * Fallback honesty (Phase 1.2): sessions whose transcript yields NO
+ * parseable assistant usage are counted as `sessions_without_usage`, and
+ * the bytes↔tokens Pearson r over the READABLE set is printed so the
+ * byte-proxy's (un)fitness is a published number, not a vibe.
+ *
+ * Marker-drift alarm (blocker `compaction-marker-shape`): the scanner
+ * counts BOTH observed markers independently; a store-wide divergence
+ * between `compact_boundary` events and `isCompactSummary` records is
+ * reported as drift instead of silently zeroing the metric.
+ */
+
+import * as fs from 'node:fs';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as path from 'node:path';
+
+import { DEFAULT_PROJECTS_ROOT, listTranscriptFiles } from './_lib/cc_transcript.js';
+import { emptyCounters, scanEolSlice, type EolCounters } from './_lib/session_eol.js';
+
+export interface SessionSummary {
+    file: string;
+    bytes: number;
+    counters: EolCounters;
+    last_ts: string | null;
+}
+
+export interface EolReport {
+    schema_version: 1;
+    generated_at: string;
+    root: string;
+    files_scanned: number;
+    sessions: number;
+    sessions_with_usage: number;
+    sessions_without_usage: number;
+    final_context_tokens: Percentiles | null;
+    turns: Percentiles | null;
+    compaction: {
+        sessions_with_compaction: number;
+        events_total: number;
+        events_by_trigger: Record<string, number>;
+        pre_tokens: Percentiles | null;
+        post_tokens: Percentiles | null;
+        /** `isCompactSummary` records store-wide — drift alarm vs `events_total`. */
+        compact_summary_records: number;
+        marker_drift: boolean;
+    };
+    /** Pearson r of file bytes vs final context tokens over the readable set. */
+    bytes_tokens_pearson_r: number | null;
+    threshold_crossings: Record<string, number>;
+}
+
+export interface Percentiles {
+    n: number;
+    min: number;
+    median: number;
+    p90: number;
+    p95: number;
+    max: number;
+}
+
+function percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return NaN;
+    const k = (sorted.length - 1) * p;
+    const f = Math.floor(k);
+    const c = Math.min(f + 1, sorted.length - 1);
+    return (sorted[f] as number) + ((sorted[c] as number) - (sorted[f] as number)) * (k - f);
+}
+
+export function percentiles(values: number[]): Percentiles | null {
+    if (values.length === 0) return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        n: sorted.length,
+        min: sorted[0] as number,
+        median: percentile(sorted, 0.5),
+        p90: percentile(sorted, 0.9),
+        p95: percentile(sorted, 0.95),
+        max: sorted[sorted.length - 1] as number,
+    };
+}
+
+function pearson(pairs: Array<[number, number]>): number | null {
+    if (pairs.length < 3) return null;
+    const n = pairs.length;
+    const mx = pairs.reduce((s, [x]) => s + x, 0) / n;
+    const my = pairs.reduce((s, [, y]) => s + y, 0) / n;
+    let cov = 0;
+    let sx = 0;
+    let sy = 0;
+    for (const [x, y] of pairs) {
+        cov += (x - mx) * (y - my);
+        sx += (x - mx) ** 2;
+        sy += (y - my) ** 2;
+    }
+    if (sx === 0 || sy === 0) return null;
+    return cov / (Math.sqrt(sx) * Math.sqrt(sy));
+}
+
+/** Scan one transcript file into a session summary. Unreadable file → null. */
+export function scanSessionFile(file: string): SessionSummary | null {
+    let text: string;
+    let bytes: number;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+        bytes = fs.statSync(file).size;
+    } catch {
+        return null;
+    }
+    const counters = scanEolSlice(text, emptyCounters());
+    let last_ts: string | null = null;
+    // cheap: reuse the final assistant stamp; fall back to null.
+    last_ts = counters.final_context_at;
+    return { file, bytes, counters, last_ts };
+}
+
+export function buildReport(root: string, now: Date = new Date()): EolReport {
+    const files = listTranscriptFiles({ root });
+    const sessions: SessionSummary[] = [];
+    for (const file of files) {
+        const summary = scanSessionFile(file);
+        if (!summary) continue;
+        const c = summary.counters;
+        if (c.assistant_records === 0 && c.turns === 0 && c.compactions.length === 0) continue;
+        sessions.push(summary);
+    }
+
+    const withUsage = sessions.filter((s) => s.counters.final_context_tokens !== null);
+    const finals = withUsage.map((s) => s.counters.final_context_tokens as number);
+    const turns = withUsage.map((s) => s.counters.turns);
+
+    const allEvents = sessions.flatMap((s) => s.counters.compactions);
+    const byTrigger: Record<string, number> = {};
+    for (const e of allEvents) byTrigger[e.trigger] = (byTrigger[e.trigger] ?? 0) + 1;
+    const pre = allEvents.map((e) => e.pre_tokens).filter((v): v is number => v !== null);
+    const post = allEvents.map((e) => e.post_tokens).filter((v): v is number => v !== null);
+    const summaryRecords = sessions.reduce((s, x) => s + x.counters.compact_summaries, 0);
+
+    const crossings: Record<string, number> = {};
+    for (const thr of [200_000, 400_000, 600_000, 800_000]) {
+        crossings[`>=${thr / 1000}k`] = finals.filter((c) => c >= thr).length;
+    }
+
+    return {
+        schema_version: 1,
+        generated_at: now.toISOString(),
+        root,
+        files_scanned: files.length,
+        sessions: sessions.length,
+        sessions_with_usage: withUsage.length,
+        sessions_without_usage: sessions.length - withUsage.length,
+        final_context_tokens: percentiles(finals),
+        turns: percentiles(turns),
+        compaction: {
+            sessions_with_compaction: sessions.filter((s) => s.counters.compactions.length > 0).length,
+            events_total: allEvents.length,
+            events_by_trigger: byTrigger,
+            pre_tokens: percentiles(pre),
+            post_tokens: percentiles(post),
+            compact_summary_records: summaryRecords,
+            marker_drift: summaryRecords !== allEvents.length,
+        },
+        bytes_tokens_pearson_r: pearson(
+            withUsage
+                .filter((s) => (s.counters.final_context_tokens as number) > 1_000)
+                .map((s) => [s.bytes, s.counters.final_context_tokens as number]),
+        ),
+        threshold_crossings: crossings,
+    };
+}
+
+function fmt(n: number): string {
+    return Math.round(n).toLocaleString('en-US');
+}
+
+export function renderText(r: EolReport): string {
+    const lines: string[] = [];
+    lines.push(`session end-of-life baseline — ${r.root}`);
+    lines.push(`files scanned: ${r.files_scanned} · sessions: ${r.sessions}`);
+    lines.push(
+        `  with parseable final usage: ${r.sessions_with_usage} · without (fallback set, 1.2): ${r.sessions_without_usage}`,
+    );
+    if (r.final_context_tokens) {
+        const f = r.final_context_tokens;
+        lines.push(
+            `final context tokens: median=${fmt(f.median)} p90=${fmt(f.p90)} p95=${fmt(f.p95)} max=${fmt(f.max)}`,
+        );
+    }
+    if (r.turns) {
+        lines.push(`turns per session: median=${fmt(r.turns.median)} p90=${fmt(r.turns.p90)} max=${fmt(r.turns.max)}`);
+    }
+    const c = r.compaction;
+    lines.push(
+        `compaction: ${c.sessions_with_compaction} sessions, ${c.events_total} events (${Object.entries(c.events_by_trigger)
+            .map(([k, v]) => `${k}:${v}`)
+            .join(', ') || 'none'})`,
+    );
+    if (c.pre_tokens) {
+        lines.push(
+            `  trigger pre-tokens: min=${fmt(c.pre_tokens.min)} median=${fmt(c.pre_tokens.median)} max=${fmt(c.pre_tokens.max)}`,
+        );
+    }
+    if (c.post_tokens) {
+        lines.push(`  post-tokens median=${fmt(c.post_tokens.median)}`);
+    }
+    lines.push(
+        `  marker drift (${c.events_total} boundary vs ${c.compact_summary_records} summary records): ${c.marker_drift ? 'YES — detector shapes diverge, re-pin the fixture' : 'no'}`,
+    );
+    lines.push(
+        `bytes↔tokens Pearson r (readable set): ${r.bytes_tokens_pearson_r === null ? 'n/a' : r.bytes_tokens_pearson_r.toFixed(3)}`,
+    );
+    for (const [k, v] of Object.entries(r.threshold_crossings)) {
+        lines.push(`sessions ending ${k} tokens: ${v}`);
+    }
+    return lines.join('\n');
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const json = argv.includes('--json');
+    const rootFlag = argv.indexOf('--root');
+    const root =
+        rootFlag !== -1 && argv[rootFlag + 1] ? path.resolve(argv[rootFlag + 1] as string) : DEFAULT_PROJECTS_ROOT;
+    const report = buildReport(root);
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : `${renderText(report)}\n`);
+    return 0;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+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());
+}

package/src/server/schemas/settings.ts

@@ -350,6 +350,9 @@ export const settingsSchema = z.object({
         judge_model: z.string().default('').describe(
             'Override the model used for review / judge subagents that critique implementer output. Empty (default) = one tier above the implementer model — picks up nuance the implementer missed.',
         ),
+        model_ceiling: z.string().default('').describe(
+            'Session-wide model CEILING for subagents (spend cap). Empty (default) = no ceiling. When set, suite-owned CLI spawn wrappers export CLAUDE_CODE_SUBAGENT_MODEL to the sessions they launch. Class C: a human sets it; the agent never writes or infers one.',
+        ),
         max_parallel: z.number().int().min(1).default(3).describe(
             'Hard cap on subagents running in parallel during /do-in-parallel, /do-competitively, and /judge runs. Raise for faster fan-out, lower if you hit rate limits or want lower token spend.',
         ),
@@ -517,6 +520,17 @@ export const settingsSchema = z.object({
                 'PreToolUse code-graph nudge (ADR-124 Phase 4). Default off. When on AND a native code-graph cache or a consumer-shipped graph.json/SCIP index is present, warns once per session (never blocks) as the agent is about to Grep/Glob or Read a source file — query the graph first for who-calls/where-used/impact questions (or rebuild if stale, build if absent). Source G’s strict block-first-read mode is deliberately un-ported.',
             ),
         }).default({}),
+        turn_end_gate: z.object({
+            enabled: z.boolean().default(false).describe(
+                'Stop-slot turn-end gate (road-to-conformance-round5 Phase 3). Default off, and it is the only concern that can REFUSE a turn-end rather than a tool call — so it soaks behind an explicit opt-in before it binds. Round 5 measured the reason: both blocking carriers reached zero violations, neither advisory carrier did, and 19 wrong-language replies survived a pin that had fired 26-35 seconds earlier. A refused turn continues in the SAME turn and is never refused twice.',
+            ),
+            promissory: z.boolean().default(true).describe(
+                'Detector A of the turn-end gate: refuse a turn whose closing paragraph promises work not yet performed while asking the user nothing (20 measured occurrences). Inert while hooks.turn_end_gate.enabled is false.',
+            ),
+            language: z.boolean().default(true).describe(
+                'Detector B of the turn-end gate: refuse a turn whose user-visible prose is not in the pinned language, with fenced code, inline code, quoted tool output, tables, URLs, paths and identifiers excluded first (19 measured occurrences). Fires 18.0% of turns on the measured corpus, which is why the master switch is off by default. Inert while hooks.turn_end_gate.enabled is false.',
+            ),
+        }).default({}),
     }),
     decision_engine: z.object({
         surface_traces: z.boolean().default(false).describe(

package/src/templates/compact-instructions.md

@@ -0,0 +1,40 @@
+# Compact-instructions template — lose less when you compact anyway
+
+Fallback lane of `road-to-token-economy-recycling` Phase 3.3. The recycle
+envelope (`agent-config session:recycle` + `/clear`) is the primary path —
+validated state, no summarizer. This template is for the user who compacts
+instead: Claude Code honours a `# Compact instructions` section in the
+project's `CLAUDE.md` when it summarizes (see the "Manage context
+proactively" section of the host's cost docs), and `/compact <instructions>`
+accepts the same guidance ad hoc.
+
+**Adopt:** paste the section below into your project's `CLAUDE.md` (root),
+or pass the body to `/compact` directly. One committed file, no hook —
+verified against the host docs 2026-08-10.
+
+---
+
+```markdown
+# Compact instructions
+
+When compacting this conversation, preserve in full:
+
+- every DECISION made, each with its one-line rationale
+- binding CONSTRAINTS (things I was told not to do, scope fences,
+  permission grants and their exact wording)
+- the current task, its acceptance criteria, and the precise list of
+  remaining steps
+- VERIFY state: which checks/tests ran, their exact outcomes, and which
+  claims are still unverified
+- file paths and `file:line` references that later steps depend on
+
+Drop aggressively:
+
+- raw tool output (test logs, diffs, file bodies) — keep only the one-line
+  conclusion each produced and the path to re-read
+- exploratory dead ends, superseded plans, and repeated content
+- pleasantries and process narration
+
+Never convert an unverified claim into a fact while summarizing — keep its
+epistemic state (verified / assumed / gap) attached.
+```