@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/_lib/quota_parked.ts

@@ -0,0 +1,133 @@
+/**
+ * quota_parked — the marker that says a run stopped because plan quota ran out,
+ * rather than because it crashed.
+ *
+ * `run_supervise` can already tell a dead session from a live one, and a
+ * finished run from an unfinished one. What it cannot tell is WHY a run
+ * stopped, and for one cause that distinction decides the whole response: a run
+ * held back by an exhausted plan quota is not broken, it is early. Reported as
+ * `relaunchable` with "the session is gone" it reads as a crash, and the one
+ * fact an operator needs — that waiting is a strategy here and is not a
+ * strategy for a crash — is the fact that gets lost.
+ *
+ * **The trigger is ours, and that is the point.** Detecting the billing cliff
+ * inside Claude Code needs a host signal nobody has shown exists
+ * (`agents/roadmaps/later/road-to-billing-cliff-detection.md`). But the council
+ * establishes the same fact under its own roof: when `api_on_quota: 'ask'`
+ * parks a seat, plan quota for that provider is exhausted, measured by us, with
+ * no host surface involved. This marker is written from there.
+ *
+ * PII-exclusion-by-construction, the same shape as `billing_grant`: a record
+ * holds a run id, provider names, and an ISO stamp. There is no field capable
+ * of carrying a prompt, a path, or an error body, so there is no scrubbing pass
+ * here that could fail.
+ *
+ * **It records, it does not act.** Nothing here sleeps, probes, or relaunches.
+ * Unattended relaunch is a published refusal
+ * (road-to-long-horizon-execution 4.0, AI council 2026-08-19) whose reopen
+ * condition has since fired — see
+ * `agents/evidence/billing-cliff/spawn-reopen-condition.md` — and a fired
+ * condition reopens the question in the venue that closed it, never the
+ * capability by itself.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Directory, relative to the repo root, holding one marker per parked run. */
+export const QUOTA_PARKED_DIR_REL = path.join('agents', 'runtime', 'state', 'quota-parked');
+
+export interface QuotaParkedMarker {
+    readonly run_id: string;
+    /** Providers whose plan quota was exhausted, sorted and deduplicated. */
+    readonly providers: string[];
+    readonly parked_at: string;
+}
+
+/** Filesystem-safe path for a run's marker. Mirrors `billing_grant.grantFile`. */
+export function markerFile(repoRoot: string, runId: string): string {
+    return path.join(
+        repoRoot,
+        QUOTA_PARKED_DIR_REL,
+        `${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`,
+    );
+}
+
+/**
+ * Record that `runId` is held back by exhausted plan quota on `providers`.
+ *
+ * Idempotent on the timestamp: a second park inside one run keeps the original
+ * `parked_at` and merges the provider set, so "when did this run first hit the
+ * cliff" survives a round that parks twice.
+ */
+export function writeQuotaParked(
+    repoRoot: string,
+    runId: string,
+    providers: readonly string[],
+    now: () => Date = () => new Date(),
+): QuotaParkedMarker {
+    const file = markerFile(repoRoot, runId);
+    const existing = readMarker(file);
+    const merged = [...new Set([...(existing?.providers ?? []), ...providers])].sort();
+    const marker: QuotaParkedMarker = {
+        run_id: runId,
+        providers: merged,
+        parked_at: existing?.parked_at ?? now().toISOString(),
+    };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+    return marker;
+}
+
+/** Remove a run's marker. Safe to call when none exists. */
+export function clearQuotaParked(repoRoot: string, runId: string): void {
+    try {
+        fs.unlinkSync(markerFile(repoRoot, runId));
+    } catch {
+        // Already gone is the state the caller asked for.
+    }
+}
+
+/**
+ * The marker for a session, or `null`.
+ *
+ * Looks up by run id first, then scans. The scan is not redundant: the run id
+ * the council writes comes from `currentRunId`, whose chain is
+ * `AC_BILLING_GRANT` → `AC_RUN_ID` → `CLAUDE_CODE_SESSION_ID`, while the
+ * register's `session_id` comes from `AGENT_CONFIG_SESSION_ID` →
+ * `CLAUDE_CODE_SESSION_ID`. The two coincide in an ordinary Claude Code session
+ * and diverge the moment an orchestrator sets `AC_RUN_ID` — so a direct hit is
+ * the common case and the scan is what stops the uncommon one from silently
+ * reporting a parked run as a crashed one. The directory holds one small file
+ * per parked run, so the scan is cheap by construction.
+ */
+export function findQuotaParked(repoRoot: string, sessionId: string): QuotaParkedMarker | null {
+    const direct = readMarker(markerFile(repoRoot, sessionId));
+    if (direct !== null) return direct;
+    let names: string[];
+    try {
+        names = fs.readdirSync(path.join(repoRoot, QUOTA_PARKED_DIR_REL));
+    } catch {
+        return null;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        const m = readMarker(path.join(repoRoot, QUOTA_PARKED_DIR_REL, name));
+        if (m !== null && m.run_id === sessionId) return m;
+    }
+    return null;
+}
+
+function readMarker(file: string): QuotaParkedMarker | null {
+    try {
+        const raw: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (raw === null || typeof raw !== 'object') return null;
+        const o = raw as Record<string, unknown>;
+        if (typeof o['run_id'] !== 'string' || typeof o['parked_at'] !== 'string') return null;
+        if (!Array.isArray(o['providers'])) return null;
+        const providers = o['providers'].filter((p): p is string => typeof p === 'string');
+        return { run_id: o['run_id'], providers, parked_at: o['parked_at'] };
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -85,6 +85,68 @@ export function sanitize_text(s: string): string {
     return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
 }
 
+/**
+ * Report the INVISIBLE layer without removing it.
+ *
+ * `sanitize_text` above strips four channels — hidden-instruction vectors
+ * (bidi, zero-width, tag, deprecated-format, private-use-area, per `_classify`),
+ * strippable control chars, and invisible fillers. Stripping is the right
+ * disposition for a retrieval path that is about to hand text to a model.
+ *
+ * It is the WRONG disposition for a reporting surface. A warn-only PostToolUse
+ * hook must not rewrite what the agent already read, so it cannot call
+ * `sanitize_text` at all — and `scan_encoding_findings` is the VISIBLE-layer
+ * twin and deliberately says nothing about these four. Measured over the frozen
+ * corpus before this function existed: `deprecated-format`, `private-use-area`,
+ * `control-char` and `invisible-filler` reported **0 of 20 each** through the
+ * reporting API while `sanitize_text` changed **20 of 20** for every one of
+ * them. So the layer had a reporting blind spot exactly where its stripping was
+ * perfect, and a consumer that may not strip was blind to a quarter of the
+ * channel set.
+ *
+ * The published 99.00 % recall figure is the STRIPPING pipeline's. The reporting
+ * half alone measured 72.33 %. Both numbers are correct about different things,
+ * and conflating them is what made "import the measured layer and get 15
+ * channels" read as true.
+ *
+ * Additive by construction: nothing that exists changes behaviour, and the
+ * predicates are the SAME ones `sanitize_text` uses — not copies — so a channel
+ * cannot become strippable without becoming reportable in the same edit.
+ */
+export function scan_invisible_findings(s: string): EncodingFinding[] {
+    const out: EncodingFinding[] = [];
+    const seen = new Set<string>();
+    const add = (channel: string, cp: number): void => {
+        const key = `${channel}:${cp}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        out.push({
+            channel,
+            detail: `U+${cp.toString(16).toUpperCase().padStart(4, '0')} in the invisible layer`,
+        });
+    };
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined) continue;
+        const classified = _classify(cp);
+        if (classified !== null) {
+            // `_classify` already names the channel; reuse its label rather than
+            // re-deriving one, so the hook's output and the authoring-time
+            // linter's speak the same vocabulary.
+            add(typeof classified === 'string' ? classified : 'hidden-instruction', cp);
+            continue;
+        }
+        if (_isStrippableControl(cp)) {
+            add('control-char', cp);
+            continue;
+        }
+        if (_INVISIBLE_FILLERS.has(cp)) {
+            add('invisible-filler', cp);
+        }
+    }
+    return out;
+}
+
 // ---------------------------------------------------------------------------
 // Visible-layer scanner — FLAG ONLY, never rewrites
 // ---------------------------------------------------------------------------

package/src/scripts/_lib/review_telemetry.ts

@@ -0,0 +1,196 @@
+/**
+ * One structural line per review run — the review surface's only telemetry.
+ *
+ * Why it exists: before this file the review surface emitted nothing. Nothing
+ * recorded how often a review ran, which judges fired, or whether the spec
+ * axis ever changed a recommendation — so the value of adding a sixth judge
+ * was unmeasurable in either direction, and the cheapest response to a slower
+ * default path is to switch the new judge off. A number is the only defence
+ * against that, and the honest number includes "it changed nothing".
+ *
+ * PII-exclusion by CONSTRUCTION, not by scrubbing. `ReviewLine` has no field
+ * able to hold free-form content: every member is an enum, a boolean, a
+ * non-negative integer, or an ISO timestamp. There is no `payload`, `notes`,
+ * `extra`, `prompt`, `diff` or `path` member, and `buildReviewLine` REJECTS an
+ * input object carrying one rather than dropping it silently — a scrubber can
+ * fail, an absent field cannot. Same principle the artifact-engagement event
+ * and `orchestration_record`'s hex-only `payload_hash` apply.
+ *
+ * Deliberately NOT reused from `_lib/orchestration_record.ts`: that line
+ * describes a subagent DISPATCH (tier, route, token deltas, cache hits). A
+ * review is not a dispatch, and widening `RecordInput` with review-shaped
+ * optionals would make both types describe neither thing precisely.
+ */
+
+/** Was the spec axis able to run at all, and on what basis? */
+export type SpecAxisReach = 'reachable_with_criteria' | 'reachable_no_criteria' | 'unreachable';
+
+/**
+ * Did the spec axis change the recommendation the craft judges would have
+ * produced on their own?
+ *
+ * `null` is NOT "no" — it means the comparison never happened (the axis did
+ * not run, so there is no counterfactual). A `false` here would claim a
+ * comparison that was never made, which is the mis-attribution this field
+ * exists to expose. Same reasoning as `modelDivergent` in
+ * `_lib/orchestration_record.ts`.
+ */
+export type SpecAxisEffect = 'changed' | 'unchanged' | null;
+
+/** The recommendation word the synthesis emitted. */
+export type ReviewRecommendation = 'block' | 'revise' | 'proceed';
+
+/** The criteria-source state, mirroring `judge-spec-compliance`'s three states. */
+export type CriteriaSource = 'supplied' | 'not_provided' | 'supplied_unparseable';
+
+/** The closed field set. A member not on this list cannot be written. */
+export const REVIEW_LINE_FIELDS = [
+    'schema',
+    'at',
+    'judges_declared',
+    'judges_ran',
+    'spec_axis_reach',
+    'criteria_source',
+    'criteria_count',
+    'spec_missing',
+    'spec_partial',
+    'recommendation',
+    'spec_axis_effect',
+] as const;
+
+export type ReviewLineField = (typeof REVIEW_LINE_FIELDS)[number];
+
+/**
+ * Field names that must never appear on this line — the free-form shapes a
+ * reviewer would reach for first. Checked as an INPUT rejection, so adding one
+ * fails loudly at the call site instead of being stripped downstream.
+ */
+export const FORBIDDEN_FREEFORM_FIELDS = [
+    'payload',
+    'notes',
+    'extra',
+    'prompt',
+    'diff',
+    'path',
+    'file',
+    'criteria',
+    'findings',
+    'message',
+    'body',
+    'content',
+    'text',
+] as const;
+
+export interface ReviewLine {
+    readonly schema: 'review-axis-v1';
+    /** ISO-8601 UTC. Caller-supplied so the line is reproducible in a test. */
+    readonly at: string;
+    readonly judges_declared: number;
+    readonly judges_ran: number;
+    readonly spec_axis_reach: SpecAxisReach;
+    readonly criteria_source: CriteriaSource;
+    readonly criteria_count: number;
+    readonly spec_missing: number;
+    readonly spec_partial: number;
+    readonly recommendation: ReviewRecommendation;
+    readonly spec_axis_effect: SpecAxisEffect;
+}
+
+export interface ReviewLineInput {
+    at: string;
+    judges_declared: number;
+    judges_ran: number;
+    spec_axis_reach: SpecAxisReach;
+    criteria_source: CriteriaSource;
+    criteria_count: number;
+    spec_missing: number;
+    spec_partial: number;
+    recommendation: ReviewRecommendation;
+    spec_axis_effect?: SpecAxisEffect;
+}
+
+export interface BuiltReviewLine {
+    line: ReviewLine | null;
+    errors: string[];
+}
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z$/;
+const REACH: readonly SpecAxisReach[] = ['reachable_with_criteria', 'reachable_no_criteria', 'unreachable'];
+const SOURCE: readonly CriteriaSource[] = ['supplied', 'not_provided', 'supplied_unparseable'];
+const RECO: readonly ReviewRecommendation[] = ['block', 'revise', 'proceed'];
+
+function isCount(n: unknown): n is number {
+    return typeof n === 'number' && Number.isInteger(n) && n >= 0;
+}
+
+/**
+ * Build + validate one `review-axis-v1` line.
+ *
+ * Returns `{line, errors}`; when `errors` is non-empty, `line` is null and the
+ * caller must NOT write. Never throws, never partially writes, never silently
+ * repairs an invalid input — the same contract as `buildOrchestrationLine`.
+ */
+export function buildReviewLine(input: ReviewLineInput): BuiltReviewLine {
+    const errors: string[] = [];
+    const raw = input as unknown as Record<string, unknown>;
+
+    for (const banned of FORBIDDEN_FREEFORM_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(raw, banned)) {
+            errors.push(
+                `'${banned}' is a free-form field and review-axis-v1 carries none — ` +
+                    'privacy here is a property of the schema shape, not of a scrubbing pass',
+            );
+        }
+    }
+
+    if (typeof input.at !== 'string' || !ISO_RE.test(input.at)) {
+        errors.push('at must be an ISO-8601 UTC timestamp (…Z)');
+    }
+    for (const k of ['judges_declared', 'judges_ran', 'criteria_count', 'spec_missing', 'spec_partial'] as const) {
+        if (!isCount(input[k])) errors.push(`${k} must be a non-negative integer`);
+    }
+    if (isCount(input.judges_ran) && isCount(input.judges_declared) && input.judges_ran > input.judges_declared) {
+        errors.push('judges_ran cannot exceed judges_declared');
+    }
+    if (!REACH.includes(input.spec_axis_reach)) errors.push(`spec_axis_reach must be one of ${REACH.join(' | ')}`);
+    if (!SOURCE.includes(input.criteria_source)) errors.push(`criteria_source must be one of ${SOURCE.join(' | ')}`);
+    if (!RECO.includes(input.recommendation)) errors.push(`recommendation must be one of ${RECO.join(' | ')}`);
+
+    const effect = input.spec_axis_effect ?? null;
+    if (effect !== null && effect !== 'changed' && effect !== 'unchanged') {
+        errors.push('spec_axis_effect must be changed | unchanged | null');
+    }
+    // A counterfactual that never ran is `null`, never `unchanged`.
+    if (input.spec_axis_reach === 'unreachable' && effect !== null) {
+        errors.push('spec_axis_effect must be null when the axis was unreachable — there was no comparison to report');
+    }
+    // The two honest pairings of reach and source.
+    if (input.spec_axis_reach === 'reachable_with_criteria' && input.criteria_source !== 'supplied') {
+        errors.push('reachable_with_criteria requires criteria_source=supplied');
+    }
+    if (input.spec_axis_reach === 'reachable_no_criteria' && input.criteria_source === 'supplied') {
+        errors.push('reachable_no_criteria contradicts criteria_source=supplied');
+    }
+    if (input.criteria_source !== 'supplied' && isCount(input.criteria_count) && input.criteria_count > 0) {
+        errors.push('criteria_count must be 0 unless criteria were supplied');
+    }
+
+    if (errors.length > 0) return { line: null, errors };
+
+    return {
+        line: {
+            schema: 'review-axis-v1',
+            at: input.at,
+            judges_declared: input.judges_declared,
+            judges_ran: input.judges_ran,
+            spec_axis_reach: input.spec_axis_reach,
+            criteria_source: input.criteria_source,
+            criteria_count: input.criteria_count,
+            spec_missing: input.spec_missing,
+            spec_partial: input.spec_partial,
+            recommendation: input.recommendation,
+            spec_axis_effect: effect,
+        },
+        errors: [],
+    };
+}

package/src/scripts/_lib/subagent_response.ts

@@ -61,10 +61,102 @@ export interface SubagentResponse {
      * the same claim as "no assumptions were made".
      */
     assumptions?: CapsuleAssumption[];
+    /**
+     * Where the tests in this change were authored FROM.
+     *
+     * `from-spec` — written against the acceptance criteria, before the diff
+     * existed. `from-diff` — written after reading the implementation.
+     * `unknown` — not recorded.
+     *
+     * **`unknown` is the default and an ABSENT field resolves to it, never to
+     * `from-spec`.** That asymmetry is the whole point of the field. The claim
+     * this metric exists to keep measurable is that a suite written by the same
+     * context as the implementation inherits its blind spots — so the valuable
+     * state is `from-spec`, and a default that let absence read as the valuable
+     * state would report the claim as satisfied by silence.
+     *
+     * Structural enum only: three string values and nothing that can hold
+     * free-form content. Same exclusion-by-construction the rest of this
+     * envelope uses — a field that cannot carry a prompt or a diff has no
+     * scrubber to fail.
+     *
+     * OPTIONAL, and deliberately not in `RESPONSE_REQUIRED_FIELDS`: that list
+     * is calibrated against a recorded ledger equivalence (`error_count: 5`),
+     * and adding a sixth required field would break it. A metric is not worth
+     * invalidating a measurement for.
+     */
+    test_authorship?: TestAuthorship;
+}
+
+/**
+ * Three states. `unknown` is one of them, not the absence of the other two.
+ *
+ * Ordered by what they license rather than alphabetically: `from-spec` is the
+ * only value that supports the independence claim, `from-diff` is the weaker
+ * form the claim says is worthless, and `unknown` licenses nothing.
+ */
+export type TestAuthorship = 'from-spec' | 'from-diff' | 'unknown';
+
+export const TEST_AUTHORSHIP: ReadonlySet<string> = new Set<TestAuthorship>([
+    'from-spec',
+    'from-diff',
+    'unknown',
+]);
+
+/**
+ * Resolve the field from a decoded envelope. ABSENT and UNRECOGNISED both
+ * resolve to `unknown`.
+ *
+ * An unrecognised value resolving to `unknown` rather than throwing is
+ * deliberate: this is a metric, and a producer that emits `from_spec` with an
+ * underscore should show up in the distribution as unrecorded, not stop a
+ * dispatch. The report is what surfaces it — a spike of `unknown` IS the
+ * finding that the field is not reaching its producers.
+ */
+export function resolveTestAuthorship(input: unknown): TestAuthorship {
+    if (input === null || typeof input !== 'object') return 'unknown';
+    const v = (input as Record<string, unknown>)['test_authorship'];
+    return typeof v === 'string' && TEST_AUTHORSHIP.has(v) ? (v as TestAuthorship) : 'unknown';
 }
 
 const CONFIDENCE: ReadonlySet<string> = new Set<Confidence>(['low', 'medium', 'high']);
 
+/**
+ * The five fields `validateResponse` REQUIRES. Exported so the ledger's
+ * classifier counts contract fields against the validator's own list rather
+ * than a second copy that can drift from it.
+ *
+ * The optional fields (`artifact_paths`, `assumptions`) are deliberately NOT
+ * here. The boundary this list defines is "did the author aim at the envelope
+ * at all", and it is calibrated against a recorded measurement: every `fail`
+ * in the live ledger carries `error_count: 5`, which is exactly the count of
+ * required-field errors an object with none of them produces. Counting an
+ * optional field as a hit would break that equivalence, so an object carrying
+ * only `assumptions` reads as foreign — recorded here as a known edge, not as
+ * an oversight.
+ */
+export const RESPONSE_REQUIRED_FIELDS: readonly string[] = [
+    'summary',
+    'handoff',
+    'confidence',
+    'findings',
+    'risks',
+];
+
+/**
+ * How many required contract fields are PRESENT on a decoded object.
+ *
+ * Presence, never validity: a `summary: 123` is a contract attempt with a
+ * wrong type, which is a different defect from a fenced tool call that never
+ * aimed at the envelope. That distinction is the whole point of the count —
+ * `validateResponse` already reports the type errors.
+ */
+export function countContractFields(input: unknown): number {
+    if (input === null || typeof input !== 'object') return 0;
+    const r = input as Record<string, unknown>;
+    return RESPONSE_REQUIRED_FIELDS.filter((k) => Object.hasOwn(r, k)).length;
+}
+
 export interface ValidationResult {
     valid: boolean;
     errors: string[];