@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/lint_workflow_security_allowlist.json

@@ -1,20 +1,4 @@
 {
-  "_comment": "Legitimate workflow security findings. Hard-capped at 20 entries (lint_workflow_security.py ALLOWLIST_CAP). Exceeding the cap signals the linter is wrong, not the content — tighten the heuristic, do not grow this list (autonomous-execution allowlist-growth antipattern). Each entry MUST cite why the finding is acceptable in `reason`.",
-  "findings": [
-    {
-      "workflow": "bench-drift.yml",
-      "rule": "mutable-action-tag",
-      "reason": "marocchino/sticky-pull-request-comment@v2 — sticky PR comment for bench drift reporting; no code execution, output-only action. SHA-pinning tracked in road-to-security-hardening P3."
-    },
-    {
-      "workflow": "skill-lint.yml",
-      "rule": "mutable-action-tag",
-      "reason": "marocchino/sticky-pull-request-comment@v2 — sticky PR comment for skill-lint reporting; same rationale as bench-drift.yml. SHA-pinning tracked in road-to-security-hardening P3."
-    },
-    {
-      "workflow": "cloud-release.yml",
-      "rule": "mutable-action-tag",
-      "reason": "softprops/action-gh-release@v2 — creates GitHub releases; runs only on push to main (not on pull_request_target), no untrusted input. SHA-pinning tracked in road-to-security-hardening P3."
-    }
-  ]
+  "_comment": "Legitimate workflow security findings. Hard-capped at 20 entries (lint_workflow_security.py ALLOWLIST_CAP). Exceeding the cap signals the linter is wrong, not the content \u2014 tighten the heuristic, do not grow this list (autonomous-execution allowlist-growth antipattern). Each entry MUST cite why the finding is acceptable in `reason`. EMPTIED 2026-08-22 (road-to-ci-supply-chain-integrity 0.2). It held three mutable-action-tag exemptions for marocchino/sticky-pull-request-comment and softprops/action-gh-release. All three are now pinned to full commit SHAs, so the findings they excused no longer exist and the entries matched nothing \u2014 lint_workflow_security reports \"0 allowlisted\". The roadmap step asked to REPAIR their `reason` text, each of which closed by naming an archived roadmap phase as the tracker for SHA-pinning; that phase is a git-discipline hook and its file mentions pinning nowhere, so the pointer dangled. Deleting a dead exemption is the honest repair \u2014 rewriting the reason on an entry that excuses nothing would have kept the allowlist looking load-bearing. The dangling pointer is also WHY the three survived: each one read as deferred rather than open. The full trace lives in the archived roadmap's completion note.",
+  "findings": []
 }

package/src/scripts/report_envelope_rate.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env tsx
+/**
+ * Publish `valid_envelope_rate` — three numbers, never one.
+ *
+ * `road-to-subagent-envelope-adoption` step 1.2: a rate with no denominator is
+ * a claim, not a measurement. So every line carries the rate, the window
+ * bounds, the stop count, AND the path it read — because the ledger is
+ * gitignored and machine-local, so a figure with no path is not reproducible
+ * even in principle.
+ *
+ * Named `report_` and not `check_` deliberately: this publishes a number and
+ * gates nothing. `gate_population.matchesGatePattern` classifies on a
+ * `lint|check|audit|skill|verify_` prefix, and a reporting script wearing a gate
+ * prefix would be required to carry a coverage floor it has no business having.
+ *
+ * ## Rows this counts, and rows it refuses
+ *
+ * Only `subagent_stop` rows carrying a POST-SPLIT `envelope_parse` value. The
+ * retired `absent` value collapsed `no_message` and `no_envelope` into one
+ * bucket, so a rate computed across the boundary would mix two vocabularies and
+ * report a number that is not about either. Rows with `absent` are excluded and
+ * counted separately, so the exclusion is visible rather than silent.
+ *
+ * Exit 0 always: a report that fails is a gate, and this is not one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const LEDGER_DIR = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'subagent-ledger');
+
+export interface RateReport {
+    ledger_paths: string[];
+    stops: number;
+    ok: number;
+    rate: number;
+    window_start: string | null;
+    window_end: string | null;
+    by_verdict: Record<string, number>;
+    excluded_absent: number;
+    by_agent_type: Record<string, number>;
+}
+
+export function computeRate(lines: readonly string[], paths: readonly string[]): RateReport {
+    const by: Record<string, number> = {};
+    const types: Record<string, number> = {};
+    let stops = 0;
+    let absent = 0;
+    let start: string | null = null;
+    let end: string | null = null;
+    for (const line of lines) {
+        let r: Record<string, unknown>;
+        try {
+            r = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        if (r['event'] !== 'subagent_stop') continue;
+        const verdict = r['envelope_parse'];
+        if (typeof verdict !== 'string') continue;
+        if (verdict === 'absent') {
+            absent += 1;
+            continue;
+        }
+        stops += 1;
+        by[verdict] = (by[verdict] ?? 0) + 1;
+        const at = typeof r['agent_type'] === 'string' ? r['agent_type'] : '(null)';
+        types[at] = (types[at] ?? 0) + 1;
+        const ts = r['ts'];
+        if (typeof ts === 'string') {
+            if (start === null || ts < start) start = ts;
+            if (end === null || ts > end) end = ts;
+        }
+    }
+    const ok = by['ok'] ?? 0;
+    return {
+        ledger_paths: [...paths],
+        stops,
+        ok,
+        // 0/0 is 0, not NaN: an empty ledger has a rate of zero valid envelopes
+        // and a denominator that says so on the same line.
+        rate: stops === 0 ? 0 : ok / stops,
+        window_start: start,
+        window_end: end,
+        by_verdict: by,
+        excluded_absent: absent,
+        by_agent_type: types,
+    };
+}
+
+function readLedger(dir: string): { lines: string[]; paths: string[] } {
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.jsonl')).sort();
+    } catch {
+        return { lines: [], paths: [] };
+    }
+    const lines: string[] = [];
+    const paths: string[] = [];
+    for (const n of names) {
+        const abs = path.join(dir, n);
+        paths.push(path.relative(REPO_ROOT, abs).split(path.sep).join('/'));
+        lines.push(...fs.readFileSync(abs, 'utf-8').split('\n'));
+    }
+    return { lines, paths };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    // `--dir` so the report is reproducible against a ledger that is not this
+    // checkout's. The ledger is gitignored and machine-local, so without it the
+    // only readable ledger is the one beside the running copy — and a worktree
+    // has none, which would make the figure unobtainable exactly where the work
+    // happens.
+    const i = argv.indexOf('--dir');
+    const dir = i >= 0 && i + 1 < argv.length ? path.resolve(argv[i + 1] as string) : LEDGER_DIR;
+    const { lines, paths } = readLedger(dir);
+    const r = computeRate(lines, paths);
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return 0;
+    }
+    if (r.ledger_paths.length === 0) {
+        // Not a failure, and not a rate either. The ledger is gitignored, so a
+        // clean clone has none — reporting 0 % there would be a number about
+        // nothing.
+        process.stdout.write(
+            `valid_envelope_rate: NO LEDGER at ${dir} — ` +
+                'the ledger is gitignored and machine-local, so this is expected in a fresh ' +
+                'clone and is not a measurement of zero.\n',
+        );
+        return 0;
+    }
+    const pct = (r.rate * 100).toFixed(2);
+    process.stdout.write(
+        `valid_envelope_rate: ${pct}% — ${String(r.ok)} ok of ${String(r.stops)} stops, ` +
+            `window ${r.window_start ?? '?'} → ${r.window_end ?? '?'}, ` +
+            `read from ${r.ledger_paths.join(', ')}\n`,
+    );
+    const verdicts = Object.entries(r.by_verdict)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => `${k} ${String(v)}`)
+        .join(' · ');
+    process.stdout.write(`    verdicts: ${verdicts}\n`);
+    process.stdout.write(
+        `    excluded (retired \`absent\` vocabulary): ${String(r.excluded_absent)}\n`,
+    );
+    const comp = Object.entries(r.by_agent_type)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => `${k} ${String(v)}`)
+        .join(' · ');
+    process.stdout.write(`    agent-type composition: ${comp}\n`);
+    process.stdout.write(
+        '    CAVEAT: machine-local. This ledger is one machine\'s drain traffic, so the\n' +
+            '    composition above is the shape of THIS traffic and the rate does not\n' +
+            '    generalise. Published with the composition rather than alone, so the limit\n' +
+            '    is readable instead of hidden.\n',
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/review_axis_report.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Report the spec axis's measured effect on the review surface.
+ *
+ * The question this answers, and the only one: over the observation window,
+ * how often did the spec axis change the recommendation the craft judges would
+ * have produced alone? The honest answers include **zero**, and **"nothing was
+ * recorded"** — which is a third answer, not a variant of zero. A report that
+ * printed `0 changed` over an empty ledger would read as evidence the axis is
+ * useless, when it is evidence that nothing has been observed yet; those two
+ * states are separated everywhere below.
+ *
+ * Three populations, never collapsed (the same model `check_pack_size` and
+ * `check_requirements_trace` use):
+ *   observed   — lines in the window
+ *   comparable — lines where the axis ran, so a counterfactual exists
+ *   changed    — comparable lines where it flipped the recommendation
+ *
+ * `comparable` is the denominator, never `observed`: a run where the axis was
+ * unreachable carries `spec_axis_effect: null` and contributes to neither
+ * numerator nor denominator. Dividing by `observed` would report a low rate for
+ * an axis that was never given the chance to act, which is the mis-attribution
+ * this split exists to prevent.
+ *
+ * Exit code is 0 on every outcome including the empty one. This is a REPORT,
+ * not a gate — there is no threshold it could honestly enforce with the window
+ * this repo has, and a gate over an unmeasured surface fails for the wrong
+ * reason. `--self-test` exercises the pure summariser and exits non-zero on a
+ * mismatch.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { ReviewLine } from './_lib/review_telemetry.js';
+
+export interface ReviewAxisSummary {
+    observed: number;
+    /** Lines where the axis ran, i.e. a counterfactual exists. */
+    comparable: number;
+    changed: number;
+    unchanged: number;
+    /** Lines where the axis could not run at all. */
+    unreachable: number;
+    /** Reviews that ran with no criteria supplied — the axis reached, nothing to measure against. */
+    no_criteria: number;
+    /** Criteria handed over and unreadable — an error state, never folded into no_criteria. */
+    unparseable: number;
+    /** Earliest / latest `at` seen, or null over an empty window. */
+    window_start: string | null;
+    window_end: string | null;
+}
+
+/** Pure summariser — the unit under `--self-test`. */
+export function summarise(lines: readonly ReviewLine[]): ReviewAxisSummary {
+    const s: ReviewAxisSummary = {
+        observed: 0,
+        comparable: 0,
+        changed: 0,
+        unchanged: 0,
+        unreachable: 0,
+        no_criteria: 0,
+        unparseable: 0,
+        window_start: null,
+        window_end: null,
+    };
+    for (const l of lines) {
+        s.observed += 1;
+        if (s.window_start === null || l.at < s.window_start) s.window_start = l.at;
+        if (s.window_end === null || l.at > s.window_end) s.window_end = l.at;
+        if (l.spec_axis_reach === 'unreachable') s.unreachable += 1;
+        if (l.criteria_source === 'not_provided') s.no_criteria += 1;
+        if (l.criteria_source === 'supplied_unparseable') s.unparseable += 1;
+        if (l.spec_axis_effect === 'changed') {
+            s.comparable += 1;
+            s.changed += 1;
+        } else if (l.spec_axis_effect === 'unchanged') {
+            s.comparable += 1;
+            s.unchanged += 1;
+        }
+    }
+    return s;
+}
+
+/** Render the summary as the prose a human reads. Empty window says so in words. */
+export function render(s: ReviewAxisSummary): string {
+    const out: string[] = [];
+    if (s.observed === 0) {
+        out.push('NO WINDOW — 0 reviews recorded, so the spec axis has no measured effect in either direction.');
+        out.push('This is not "the axis changed nothing": nothing has been observed yet. Rerun once reviews have run.');
+        return out.join('\n');
+    }
+    out.push(`window: ${String(s.window_start)} … ${String(s.window_end)}`);
+    out.push(`observed: ${s.observed} review(s)`);
+    if (s.comparable === 0) {
+        out.push(
+            'comparable: 0 — the axis ran in none of them, so it changed nothing BY CONSTRUCTION, ' +
+                'which is not evidence about the axis.',
+        );
+    } else {
+        const pct = ((s.changed / s.comparable) * 100).toFixed(1);
+        out.push(`comparable: ${s.comparable} (the axis ran; a counterfactual exists)`);
+        out.push(`changed the recommendation: ${s.changed} of ${s.comparable} (${pct}%)`);
+        if (s.changed === 0) {
+            out.push('The honest reading of 0: the axis ran and never flipped a verdict over this window.');
+        }
+    }
+    out.push(
+        `not comparable: ${s.unreachable} unreachable · ${s.no_criteria} ran with no criteria · ` +
+            `${s.unparseable} with unreadable criteria (an error state, counted apart)`,
+    );
+    return out.join('\n');
+}
+
+function readLedger(dir: string): ReviewLine[] {
+    if (!fs.existsSync(dir)) return [];
+    const lines: ReviewLine[] = [];
+    for (const f of fs.readdirSync(dir).sort()) {
+        if (!f.endsWith('.jsonl')) continue;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+            const t = raw.trim();
+            if (!t) continue;
+            try {
+                const o = JSON.parse(t) as ReviewLine;
+                if (o && o.schema === 'review-axis-v1') lines.push(o);
+            } catch {
+                // A malformed line is skipped, never guessed at.
+            }
+        }
+    }
+    return lines;
+}
+
+function selfTest(): number {
+    const at = '2026-08-22T00:00:00Z';
+    const base = {
+        schema: 'review-axis-v1' as const,
+        at,
+        judges_declared: 6,
+        judges_ran: 6,
+        criteria_count: 2,
+        spec_missing: 0,
+        spec_partial: 0,
+        recommendation: 'proceed' as const,
+    };
+    const cases: { name: string; lines: ReviewLine[]; want: Partial<ReviewAxisSummary>; wantText?: string }[] = [
+        { name: 'empty window is not zero-effect', lines: [], want: { observed: 0, comparable: 0 }, wantText: 'NO WINDOW' },
+        {
+            name: 'unreachable contributes to neither population',
+            lines: [
+                {
+                    ...base,
+                    spec_axis_reach: 'unreachable',
+                    criteria_source: 'not_provided',
+                    criteria_count: 0,
+                    spec_axis_effect: null,
+                },
+            ],
+            want: { observed: 1, comparable: 0, changed: 0, unreachable: 1 },
+            wantText: 'BY CONSTRUCTION',
+        },
+        {
+            name: 'changed and unchanged both land in comparable',
+            lines: [
+                { ...base, spec_axis_reach: 'reachable_with_criteria', criteria_source: 'supplied', spec_axis_effect: 'changed' },
+                { ...base, spec_axis_reach: 'reachable_with_criteria', criteria_source: 'supplied', spec_axis_effect: 'unchanged' },
+            ],
+            want: { observed: 2, comparable: 2, changed: 1, unchanged: 1 },
+        },
+        {
+            name: 'unparseable is counted apart from no_criteria',
+            lines: [
+                {
+                    ...base,
+                    spec_axis_reach: 'reachable_no_criteria',
+                    criteria_source: 'supplied_unparseable',
+                    criteria_count: 0,
+                    spec_axis_effect: 'unchanged',
+                },
+            ],
+            want: { observed: 1, no_criteria: 0, unparseable: 1, comparable: 1 },
+        },
+    ];
+    let pass = 0;
+    let fail = 0;
+    for (const c of cases) {
+        const got = summarise(c.lines);
+        const bad = Object.entries(c.want).filter(([k, v]) => got[k as keyof ReviewAxisSummary] !== v);
+        const text = render(got);
+        const textBad = c.wantText !== undefined && !text.includes(c.wantText);
+        if (bad.length === 0 && !textBad) {
+            pass += 1;
+        } else {
+            fail += 1;
+            console.error(`❌ ${c.name}`);
+            for (const [k, v] of bad) console.error(`   ${k}: want ${String(v)}, got ${String(got[k as keyof ReviewAxisSummary])}`);
+            if (textBad) console.error(`   prose missing: ${String(c.wantText)}`);
+        }
+    }
+    process.stdout.write(`review_axis_report --self-test: ${pass} pass, ${fail} fail\n`);
+    return fail === 0 ? 0 : 1;
+}
+
+function main(argv: string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const dirIdx = argv.indexOf('--dir');
+    const dir =
+        dirIdx >= 0 && argv[dirIdx + 1] !== undefined
+            ? String(argv[dirIdx + 1])
+            : path.join(process.cwd(), 'agents', 'runtime', 'state', 'review-axis');
+    const lines = readLedger(dir);
+    process.stdout.write(render(summarise(lines)) + '\n');
+    process.stdout.write(`scanned: ${lines.length}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('review_axis_report')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/routing_doctor.ts

@@ -276,7 +276,11 @@ export function render_standing_delivery(m: StandingDeliveryMeasure | null): str
     lines.push(
       `⚠️ Standing delivery: both rule layers active — ${m.overlap_rules} rule(s) delivered twice ` +
         `(~${m.overlap_tokens} tok). This session's host receives ${m.received_tokens} rule tokens; ` +
-        `scoped delivery would be ~${scoped} — run \`agent-config install --layer=<global|project>\`.`,
+        `single-layer delivery would be ~${scoped} — run \`agent-config install\` to arm the ` +
+        `ADR-236 partition on this machine (it fingerprints the host layer; the next ` +
+        `\`task generate-tools\` then withholds the globally-owned artefacts). The former advice ` +
+        `here, \`install --layer=<global|project>\`, was layer suppression — declined by ADR-226 ` +
+        `and superseded by the partition.`,
     );
     if (m.divergent_rules > 0) {
       // Suppressing a layer whose copies differ drops whichever obligations only

package/src/scripts/run_supervise.ts

@@ -51,6 +51,7 @@ import {
     roadmapPath,
 } from './_lib/run_checkpoint.js';
 import { readBudget } from './_lib/unattended_guard.js';
+import { findQuotaParked, type QuotaParkedMarker } from './_lib/quota_parked.js';
 import {
     LIVE_SPAWN_REFUSAL,
     planResume,
@@ -80,6 +81,7 @@ export type Disposition =
     | 'no-roadmap'
     | 'roadmap-unreadable'
     | 'complete'
+    | 'quota-parked'
     | 'budget-exhausted'
     | 'relaunchable';
 
@@ -246,6 +248,21 @@ export function classify(
             reason: 'no open steps remain — the run finished, the session just never said so',
         };
     }
+    // Before the relaunch cap, and the order is load-bearing in one direction
+    // only: a parked run that has also spent its relaunches should still read
+    // as parked, because "waiting for a reset" is the cause and "spent three
+    // relaunches" is a consequence of it. Reported the other way round, an
+    // operator sees a run that failed repeatedly rather than one that keeps
+    // meeting the same wall.
+    const parked = findQuotaParked(repoRoot, rec.session_id);
+    if (parked !== null) {
+        return {
+            ...base,
+            disposition: 'quota-parked',
+            open_steps: counts.open,
+            reason: quotaParkedReason(parked, counts.open),
+        };
+    }
     if (base.relaunches >= MAX_RELAUNCHES_PER_RUN) {
         return {
             ...base,
@@ -264,6 +281,23 @@ export function classify(
     };
 }
 
+/**
+ * The one sentence a human acts on for a parked run.
+ *
+ * It states the reset time is unknown rather than omitting it, and rather than
+ * guessing an interval. There is no reset-time parser and there will not be one
+ * until a verified error string exists to pin a fixture against — see
+ * `later/road-to-billing-cliff-detection.md`. An omitted unknown reads as "no
+ * wait needed"; a guessed interval reads as a fact.
+ */
+export function quotaParkedReason(m: QuotaParkedMarker, open: number): string {
+    return (
+        `plan quota exhausted on ${m.providers.join(', ')} since ${m.parked_at} — ` +
+        `${open} open step(s) remain; the run is waiting, not broken. ` +
+        `Reset time unknown (no parser: no verified error string yet).`
+    );
+}
+
 export interface ScanOptions {
     readonly now?: Date;
 }
@@ -434,10 +468,21 @@ export function digest(repoRoot: string, candidates: readonly Candidate[], now:
 
     const dead = candidates.filter((c) => c.disposition !== 'alive');
     const relaunchable = candidates.filter((c) => c.disposition === 'relaunchable');
+    const quotaParked = candidates.filter((c) => c.disposition === 'quota-parked');
     lines.push(
         `  sessions: ${candidates.length} registered · ${candidates.length - dead.length} alive · ` +
-            `${relaunchable.length} relaunchable`,
+            `${relaunchable.length} relaunchable` +
+            (quotaParked.length > 0 ? ` · ${quotaParked.length} quota-parked` : ''),
     );
+    // Named on its own line, not folded into the relaunchable count, because
+    // the two call for opposite responses: a relaunchable run wants a session,
+    // a parked one wants time. Suppressed at zero so the ordinary digest does
+    // not carry a line about a state nothing is in.
+    for (const c of quotaParked) {
+        lines.push(
+            `  parked:   ${c.roadmap ?? '-'} — ${c.reason}`,
+        );
+    }
 
     const budget = readBudget(repoRoot, now);
     lines.push(

package/src/scripts/schemas/evals.schema.json

@@ -48,6 +48,11 @@
             "minLength": 1,
             "description": "The input fixture handed to the skill under test."
           },
+          "_why": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional rationale: why this fixture exists at all. Annotation, never input — nothing reads it at run time, and it carries the same underscore prefix as the top-level `_calibration` to say so. Added because the alternative, on scenarios whose rationale IS the negative-control argument for the pair above them, was to delete the argument to satisfy additionalProperties."
+          },
           "environment": {
             "type": "string",
             "minLength": 1,