@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/_lib/orchestration_record.ts

@@ -19,8 +19,10 @@
 import type { LookupClass } from './auto_dispatch.js';
 
 export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
-/** Which route the lookup-class rung took (lean-init L0). */
-export type RouteTaken = 'primitive' | 'subagent';
+/** Which route the rung took: deterministic primitive (lean-init L0),
+ *  single-completion ask (token-economy-dispatch rung 0.5), or a full
+ *  subagent spawn. */
+export type RouteTaken = 'primitive' | 'subagent' | 'ask';
 export type VerifyMode = 'deterministic' | 'judge' | 'none';
 export type Provenance = 'measured' | 'estimated';
 export type TierChosen = 'lite' | 'medium' | 'high';
@@ -28,6 +30,8 @@ export type TierSource = 'static' | 'inferred' | 'inherit';
 export type Band = 'low' | 'medium' | 'high';
 export type LinePhase = 'refine' | 'memory' | 'analyze' | 'plan' | 'implement' | 'test' | 'verify' | 'report';
 export type LineOutcome = 'success' | 'blocked' | 'skipped' | 'error';
+/** Which capsule-emission trigger arm fired first (Phase 1 shadow comparison). */
+export type TriggerArm = 'watermark' | 'saturation' | 'tie';
 /** The orchestration form the form-gate selected (road-to-opt-subagent-harvest P2). */
 export type DispatchModeId =
     | 'do-and-judge'
@@ -96,6 +100,37 @@ export interface RecordInput {
     /** Rules the worker actually applied/cited (count of the envelope's
      *  `rules_applied`-equivalent on the worker side). Counts only. */
     rules_used?: number | null | undefined;
+    // ── dispatch-economy additive fields (road-to-token-economy-dispatch
+    //    Phase 1.1). `init_tokens` above (lean-init) is the spawn-payload
+    //    half; `work_tokens` is the delta from first worker turn to envelope
+    //    close. Both are counts; the pair's provenance rides
+    //    `floor_provenance` exactly like `token_delta_provenance` tags
+    //    `token_delta`. ──
+    /** Tokens the worker consumed AFTER init (delta to envelope close). */
+    work_tokens?: number | null | undefined;
+    /** Chars the dispatch RETURNED into the orchestrator context (serialized
+     *  tool-result length on sync completions) — the Phase 6.3 detector for
+     *  "isolation win refunded through the return channel". A count, never
+     *  content. */
+    return_channel_chars?: number | null | undefined;
+    /** Provenance of the init/work pair: 'measured' (transcript ledger via
+     *  cc_transcript) or 'estimated'. Defaults to 'estimated' when either
+     *  field is present without a tag. */
+    floor_provenance?: Provenance | null | undefined;
+    // ── capsule shadow-measurement fields (road-to-worker-generation-recycling
+    //    Phase 1.2). SHADOW ONLY: the worker still runs to stop-loss, nothing
+    //    reads a capsule. All counts / enums — a capsule's CONTENT never
+    //    reaches telemetry, only its shape. ──
+    /** A CHECKPOINT capsule was emitted at the watermark. */
+    capsule_emitted?: boolean | undefined;
+    /** Total entries across the capsule's arrays — a size proxy, never content. */
+    capsule_entries?: number | null | undefined;
+    /** 1-based step at which the token-watermark arm fired (null = never). */
+    watermark_step?: number | null | undefined;
+    /** 1-based step at which the novelty-saturation arm fired (null = never). */
+    saturation_step?: number | null | undefined;
+    /** Which arm fired first on this dispatch — the paired-comparison datum. */
+    trigger_arm_earlier?: TriggerArm | null | undefined;
     // Audit-log envelope (sensible defaults for a dispatch record)
     phase?: LinePhase | undefined;
     outcome?: LineOutcome | undefined;
@@ -122,7 +157,8 @@ const TIER_SOURCES: readonly TierSource[] = ['static', 'inferred', 'inherit'];
 const BANDS: readonly Band[] = ['low', 'medium', 'high'];
 const PHASES: readonly LinePhase[] = ['refine', 'memory', 'analyze', 'plan', 'implement', 'test', 'verify', 'report'];
 const LOOKUP_CLASSES: readonly LookupClass[] = ['definition', 'references', 'string-existence', 'report-run'];
-const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent'];
+const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent', 'ask'];
+const TRIGGER_ARMS: readonly TriggerArm[] = ['watermark', 'saturation', 'tie'];
 /** Hex-only payload hash — a hash can never smuggle content (privacy by construction). */
 const PAYLOAD_HASH_RE = /^[a-f0-9]{8,64}$/i;
 /** Id-shaped origin tag — enum-ish, never free-form prose. */
@@ -147,13 +183,15 @@ function isInt(n: unknown): n is number {
 export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     const errors: string[] = [];
 
-    // A lookup-class primitive route is the ONE recordable zero-spawn event
-    // (lean-init L0): the routing decision itself is the datum the
-    // cost-reduction claim reads. Everything else with spawn_count 0 stays
-    // unrecordable in-session work.
-    const zeroSpawnPrimitive = input.route_taken === 'primitive' && input.spawn_count === 0;
-    if (!zeroSpawnPrimitive && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
-        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive lookup routes record with spawn_count 0)');
+    // A lookup-class primitive route (lean-init L0) and a rung-0.5 ask route
+    // (token-economy-dispatch Phase 4) are the TWO recordable zero-spawn
+    // events: the routing decision itself is the datum the cost-reduction
+    // claim reads. Everything else with spawn_count 0 stays unrecordable
+    // in-session work.
+    const zeroSpawnRoute =
+        (input.route_taken === 'primitive' || input.route_taken === 'ask') && input.spawn_count === 0;
+    if (!zeroSpawnRoute && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
+        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive|ask routes record with spawn_count 0)');
     }
     if (!isInt(input.token_delta)) errors.push('token_delta must be an integer (negative = net saved vs the in-session baseline)');
     if (input.task_size_estimate !== undefined && (!isInt(input.task_size_estimate) || input.task_size_estimate < 0)) {
@@ -222,9 +260,14 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     for (const [key, v] of [
         ['rules_carried', input.rules_carried],
         ['rules_used', input.rules_used],
+        ['work_tokens', input.work_tokens],
+        ['return_channel_chars', input.return_channel_chars],
     ] as const) {
         if (v != null && (!isInt(v) || v < 0)) errors.push(`${key} must be a non-negative integer count`);
     }
+    if (input.floor_provenance != null && !PROVENANCES.includes(input.floor_provenance)) {
+        errors.push(`floor_provenance must be one of ${PROVENANCES.join(' | ')} (or omitted)`);
+    }
     if (
         input.rules_carried != null &&
         input.rules_used != null &&
@@ -233,6 +276,20 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         errors.push('rules_used cannot exceed rules_carried (a worker cannot apply a rule it was not given)');
     }
 
+    if (input.capsule_emitted !== undefined && typeof input.capsule_emitted !== 'boolean') {
+        errors.push('capsule_emitted must be a boolean or omitted');
+    }
+    for (const [key, v] of [
+        ['capsule_entries', input.capsule_entries],
+        ['watermark_step', input.watermark_step],
+        ['saturation_step', input.saturation_step],
+    ] as const) {
+        if (v != null && (!isInt(v) || v < 0)) errors.push(`${key} must be a non-negative integer count`);
+    }
+    if (input.trigger_arm_earlier != null && !TRIGGER_ARMS.includes(input.trigger_arm_earlier)) {
+        errors.push(`trigger_arm_earlier must be one of ${TRIGGER_ARMS.join(' | ')} (or omitted / null when neither arm fired)`);
+    }
+
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID or content hash) is required');
 
@@ -267,6 +324,17 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         origin: input.origin ?? null,
         rules_carried: input.rules_carried ?? null,
         rules_used: input.rules_used ?? null,
+        // dispatch-economy additive fields — readers ignore unknowns per audit-log-v1
+        work_tokens: input.work_tokens ?? null,
+        return_channel_chars: input.return_channel_chars ?? null,
+        floor_provenance:
+            input.floor_provenance ?? (input.init_tokens != null || input.work_tokens != null ? 'estimated' : null),
+        // capsule shadow-measurement — readers ignore unknowns per audit-log-v1
+        capsule_emitted: input.capsule_emitted ?? null,
+        capsule_entries: input.capsule_entries ?? null,
+        watermark_step: input.watermark_step ?? null,
+        saturation_step: input.saturation_step ?? null,
+        trigger_arm_earlier: input.trigger_arm_earlier ?? null,
     };
 
     const line: Record<string, unknown> = {

package/src/scripts/_lib/orchestration_savings.ts

@@ -212,7 +212,7 @@ export function aggregateOrchestrationSavings(
 
     // Honest caveats — always attached so a consumer never over-reads the number.
     if (report.dispatches === 0) {
-        report.notes.push('No orchestration telemetry yet (0 dispatches). Data accrues as `subagents.auto: on` delegates real slices (recorded via orchestration_record).');
+        report.notes.push('No orchestration telemetry yet (0 dispatches). Data accrues as delegable slices dispatch (always-on orchestration; recorded via orchestration_record).');
     } else {
         report.notes.push('Token counts are MEASURED but blind to the downshift rate win (same tokens on a cheaper tier ≈ same count). The MODELED cost-% below captures that axis.');
         if (report.by_provenance.estimated.dispatches > 0) {

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -0,0 +1,35 @@
+/**
+ * Recycle-envelope filesystem contract (road-to-token-economy-recycling
+ * Phase 2.2/2.3) — the ONE place the producer (`session:recycle`) and the
+ * consumer (`handoff_context_hook`) agree on where the envelope lives and
+ * when it is stale. A second copy of any of these values is the drift seam
+ * Risk 6 warns about.
+ */
+import * as path from 'node:path';
+
+/** Where `session:recycle` writes the pending envelope (gitignored runtime state). */
+export const RECYCLE_ENVELOPE_REL = path.join('agents', 'runtime', 'state', 'recycle-envelope.json');
+
+/**
+ * Where the consumer MOVES the envelope on consumption — moved, not copied,
+ * so a consumed or rejected envelope can never leak into a later session,
+ * while the last one stays inspectable for debugging.
+ */
+export const RECYCLE_CONSUMED_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'recycle-envelope.consumed.json',
+);
+
+/** Staleness guard — mirrors the handoff file's 48 h discipline. */
+export const RECYCLE_MAX_AGE_HOURS = 48;
+
+/**
+ * Producer-side size cap on the serialized envelope. The schema's per-field
+ * caps make a transcript-shaped envelope invalid; this cap keeps even a
+ * legal envelope inside the `handoff-context` injection budget
+ * (`src/config/hook-token-budget.json`: 8192 B for the concern) with room
+ * for the wrapper block and a co-pending handoff.
+ */
+export const RECYCLE_ENVELOPE_MAX_BYTES = 6144;

package/src/scripts/_lib/self_repair.ts

@@ -28,6 +28,7 @@
 import { createHash } from 'node:crypto';
 
 import { redact_low_impact_entry } from '../ai_council/redact_low_impact_entry.js';
+import { is_kernel_rule } from './kernel_rules.js';
 
 /** Where a record came from. */
 export type DefectSource = 'user-reported' | 'self-detected';
@@ -38,6 +39,18 @@ export type DefectClass =
     | 'council-availability-claim'
     | 'language-mirror';
 
+/**
+ * Runtime mirror of `DefectClass`, in declaration order. The upstream issue
+ * form's dropdown (`.github/ISSUE_TEMPLATE/self_repair_report.yml`) is pinned
+ * against this list by test, so adding a detector class without extending the
+ * form is a red test, not silent drift.
+ */
+export const DEFECT_CLASSES: readonly DefectClass[] = [
+    'user-reported',
+    'council-availability-claim',
+    'language-mirror',
+];
+
 /** How far a record may travel outward. */
 export type EgressRoute = 'pull-request' | 'issue' | 'local-only';
 
@@ -56,6 +69,12 @@ export interface DefectRecord extends DefectFinding {
     last_seen: string;
     occurrences: number;
     status: 'open' | 'released';
+    /**
+     * Failed egress attempts from the most recent `release` call, sanitized at
+     * write time. Local-only bookkeeping: `renderReport` never includes them,
+     * so they cannot widen what leaves the machine.
+     */
+    release_errors?: string[];
 }
 
 /** One finished turn, as much of it as a hook can observe. */
@@ -110,12 +129,208 @@ export function egressBlockedReason(record: DefectRecord, repoRoot?: string | nu
     return `privacy floor refused the evidence (${kinds}) — record stays local`;
 }
 
+// ── may-not-modify deny-list ───────────────────────────────────────
+
+/**
+ * Surfaces self-repair may never target with a PATCH. Detection and reporting
+ * stay untouched — for a record targeting one of these, egress degrades to
+ * report-only: an issue (or the local record) is still allowed, the
+ * pull-request path refuses with the named reason.
+ *
+ * The point is structural: the loop that fixes the agent's own defects must
+ * not be a channel through which the agent loosens the floors it is bound by.
+ * Same posture as `block_kernel_rule_writes` (tool-call-time) and the settings
+ * class-C fence (write-time), applied to the one outward vehicle this loop
+ * owns. Nothing auto-applies a patch today; this keeps that true for the
+ * denied surfaces even when the PR path is otherwise available.
+ */
+export type DeniedSurface =
+    | 'kernel-rule'
+    | 'safety-floor-rule'
+    | 'settings-class-c'
+    | 'ci-enforcement'
+    | 'self-repair-policy';
+
+export interface PatchDenial {
+    surface: DeniedSurface;
+    /** The token in the record that matched. */
+    match: string;
+}
+
+/**
+ * Characters that decorate a token but never appear inside a real path, rule
+ * id, or settings key: markdown emphasis / strikethrough, autolink angle
+ * brackets, table pipes. They are removed ANYWHERE in the token, not just at
+ * its edges, so `src/rules/**scope-control**.md` reduces like `**…**` does.
+ */
+const DECORATION_RE = /[*~<>|]/g;
+
+/**
+ * Edge punctuation a sentence leaves on a token — sentence-final `.`, a `:`
+ * label separator, list/reference brackets, and underscore emphasis (`_` is
+ * stripped at the EDGES only: it is load-bearing inside `self_repair.ts`,
+ * `hook_manifest.yaml`, and every snake_case settings key).
+ */
+const EDGE_TRIM_RE = /^[.:[\]_]+|[.:[\]_]+$/g;
+
+/**
+ * Word-ish / path-ish tokens of a record's text, punctuation-stripped.
+ *
+ * `suggested_surface` is free-text the agent writes, and this repo's prose is
+ * saturated with `**bold**` file paths — so a tokenizer that only splits on
+ * whitespace-and-quotes lets ordinary markdown emphasis smuggle a denied
+ * surface past the scan (`**src/rules/scope-control.md**` read as ALLOWED
+ * while the same path bare read as DENIED). Both the raw token and its
+ * un-decorated form are emitted, and the edge trim runs AFTER the decoration
+ * strip so an unwrapped `**.github/workflows/ci.yml**` cannot keep a leading
+ * dot in front of the anchored `github/workflows/` match.
+ */
+function denyTokens(text: string): string[] {
+    const out: string[] = [];
+    for (const raw of text.split(/[\s,;()!?"'`]+/)) {
+        if (raw.length === 0) {
+            continue;
+        }
+        for (const candidate of new Set([raw, raw.replace(DECORATION_RE, '')])) {
+            const token = candidate.replace(EDGE_TRIM_RE, '');
+            if (token.length > 0) {
+                out.push(token);
+            }
+        }
+    }
+    return out;
+}
+
+/** Basename stem (no `.md`) of a path-or-id token. */
+function stemOf(token: string): string {
+    const base = token.replace(/\\/g, '/').split('/').pop() ?? token;
+    return base.replace(/\.md$/, '');
+}
+
+/** Dotted settings-key shape — `personal.autonomy`, `tokens.rich_skills`, … */
+const DOTTED_KEY_RE = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/;
+
+/**
+ * The surfaces through which enforcement is actually armed or disarmed. A
+ * workflow file is only ONE of them, and in this repo it is not even the usual
+ * one — a new gate is registered in the taskfiles the workflow calls, and a
+ * tool-call-time guard is armed in the hook manifest. Each entry, and why it
+ * arms enforcement:
+ *
+ *   - `.github/workflows/` — the CI job definitions; deleting a step removes
+ *     the gate from every PR. (The leading dot is stripped by `denyTokens`, so
+ *     the match is on the segment pair, not the dotfile spelling.)
+ *   - `Taskfile.yml` / `taskfiles/*.yml` — the task graph the workflows invoke
+ *     (`task ci`, `task ci-fast`). A gate that is not listed here does not run,
+ *     however green the workflow looks.
+ *   - `src/scripts/hook_manifest.yaml` — the concern↔slot bindings. Unbinding
+ *     a concern disarms a PreToolUse guard without touching the guard's code.
+ *   - `src/scripts/hooks/` — the guard implementations themselves
+ *     (`block_no_verify`, `block_kernel_rule_writes`, `block_config_weakening`).
+ *   - `src/scripts/check_*.ts` / `src/scripts/lint_*.ts` — the gate scripts. A
+ *     loosened threshold or a narrowed scan root disarms the gate in place,
+ *     which is exactly the "gates that scan nothing exit green" failure.
+ *
+ * Deliberately NOT the whole of `src/scripts/`: that would deny nearly every
+ * legitimate repair this loop exists to file.
+ */
+function isCiEnforcementPath(token: string): boolean {
+    const t = token.replace(/\\/g, '/');
+    if (/(^|\/)github\/workflows\//.test(t)) {
+        return true;
+    }
+    if (/(^|\/)Taskfile(\.[a-z0-9_-]+)?\.ya?ml$/i.test(t)) {
+        return true;
+    }
+    if (/(^|\/)taskfiles\//.test(t)) {
+        return true;
+    }
+    if (/(^|\/)hook_manifest\.ya?ml$/.test(t)) {
+        return true;
+    }
+    if (/(^|\/)scripts\/hooks\//.test(t)) {
+        return true;
+    }
+    return /(^|\/)scripts\/(check|lint)_[a-z0-9_]+\.ts$/.test(t);
+}
+
+/**
+ * Is this record's fix aimed at a denied surface? Scans the two fields that
+ * name what the fix should change (`suggested_surface`) and what was observed
+ * (`evidence`). A match errs toward denial on purpose — the cost of a false
+ * positive is a report instead of a patch, still egress; the cost of a false
+ * negative is a patch channel into a safety floor.
+ *
+ * The kernel set resolves from `kernel_rules.ts` — the same canonical source
+ * `block_kernel_rule_writes` uses — never a copy that can drift. Settings
+ * class-C keys are matched against `classCKeys` when the caller can supply
+ * them (parsed from `docs/contracts/settings-classes.md`); the contract file
+ * itself is denied by path regardless, so an unreadable contract narrows the
+ * dynamic check without opening the fence's own definition to patching.
+ */
+export function patchDeniedSurface(
+    record: DefectFinding,
+    opts?: { classCKeys?: ReadonlySet<string> | null },
+): PatchDenial | null {
+    const classCKeys = opts?.classCKeys ?? null;
+    for (const token of denyTokens(`${record.suggested_surface}\n${record.evidence}`)) {
+        // Checked before `ci-enforcement` so a self-repair file that also lives
+        // under an enforcement path (`src/scripts/hooks/self_repair_hook.ts`)
+        // reports the more specific surface. Either way it is denied.
+        if (/self[-_]repair/i.test(token)) {
+            return { surface: 'self-repair-policy', match: token };
+        }
+        if (isCiEnforcementPath(token)) {
+            return { surface: 'ci-enforcement', match: token };
+        }
+        if (token.includes('settings-classes.md')) {
+            return { surface: 'settings-class-c', match: token };
+        }
+        if (is_kernel_rule(token)) {
+            return { surface: 'kernel-rule', match: token };
+        }
+        if (stemOf(token).endsWith('-safety-floor')) {
+            return { surface: 'safety-floor-rule', match: token };
+        }
+        if (classCKeys !== null && DOTTED_KEY_RE.test(token)) {
+            // Exact key first, then every classified ancestor down to the root
+            // segment — a class-C key whose value is a MAP has children that
+            // never appear under the key's own name.
+            const parts = token.split('.');
+            for (let end = parts.length; end > 0; end--) {
+                if (classCKeys.has(parts.slice(0, end).join('.'))) {
+                    return { surface: 'settings-class-c', match: token };
+                }
+            }
+        }
+    }
+    return null;
+}
+
+/** The named refusal the patch/PR path reports. Null = patch path allowed. */
+export function patchDeniedReason(
+    record: DefectFinding,
+    opts?: { classCKeys?: ReadonlySet<string> | null },
+): string | null {
+    const denial = patchDeniedSurface(record, opts);
+    if (denial === null) {
+        return null;
+    }
+    return (
+        `self-repair may not patch a ${denial.surface} surface (matched: ${denial.match}) — ` +
+        'the pull-request path is refused; the record egresses report-only (issue / local record)'
+    );
+}
+
 // ── detectors ──────────────────────────────────────────────────────
 
 // An agent-directed complaint, not a complaint about the code. Deliberately
 // narrow: a spurious record becomes a spurious PR, so precision beats recall.
 const COMPLAINT_PATTERNS: readonly RegExp[] = [
-    /\bdu hast\b[^.!?]{0,60}\b(nicht|falsch|vergessen|ignoriert|übersehen)\b/i,
+    // No \b before the alternation: JS \b is ASCII-only, so a leading umlaut
+    // ("übersehen") never sits on a word boundary — the corpus gate's
+    // near-miss class caught that as a dead alternation branch.
+    /\bdu hast\b[^.!?]{0,60}(nicht|falsch|vergessen|ignoriert|übersehen)\b/i,
     /\bdu (ignorierst|übersiehst)\b/i,
     /\b(das|es) (war|ist) (aber )?falsch\b/i,
     /\bhat nicht (richtig|korrekt) (gearbeitet|funktioniert)\b/i,
@@ -125,11 +340,53 @@ const COMPLAINT_PATTERNS: readonly RegExp[] = [
     /\byou (worked|did (it|that)) (wrong|incorrectly)\b/i,
 ];
 
+// Phrasings that MATCH a complaint pattern but are not complaints — a curious
+// question or a reassurance. Scoped to the matched span (± a small margin),
+// never the whole prompt: a pleasantry in one clause must not mute a genuine
+// complaint in another (R2 finding #2). These feed the must-not-fire class of
+// the detector corpus gate.
+const COMPLAINT_EXONERATIONS: readonly RegExp[] = [
+    /\bdu hast nicht zufällig\b/i,
+    /\bhast du nicht zufällig\b/i,
+    /\byou didn'?t (need|have) to\b/i,
+    /\bit'?s fine\b/i,
+    /\b(kein problem|passt schon|alles gut)\b/i,
+    // Explicit absolution INSIDE the complaint span, which is why it has to be
+    // its own entry rather than relying on a neighbouring pleasantry: in
+    // "das ist fine, du hast nichts falsch gemacht" the matched span is
+    // `du hast nichts falsch`, and the `it's fine` above sits outside the
+    // ± EXONERATION_MARGIN window — correctly, since that margin exists to stop
+    // a pleasantry in one clause muting a complaint in another. `nichts falsch`
+    // is not a neighbouring pleasantry: it is the negation of the complaint
+    // itself. Caught by the detector-corpus gate, which flagged this exact
+    // string as a must-not-fire fixture that fired (PR #1231).
+    /\bnichts falsch\b/i,
+    /\bkein fehler\b/i,
+];
+
+/** How far (chars) an exoneration may sit from the complaint span it excuses. */
+const EXONERATION_MARGIN = 12;
+
+function spanExonerated(prompt: string, start: number, end: number): boolean {
+    for (const ex of COMPLAINT_EXONERATIONS) {
+        const g = new RegExp(ex.source, ex.flags.includes('g') ? ex.flags : `${ex.flags}g`);
+        let m: RegExpExecArray | null;
+        while ((m = g.exec(prompt)) !== null) {
+            const s = m.index;
+            const e = m.index + m[0].length;
+            if (e >= start - EXONERATION_MARGIN && s <= end + EXONERATION_MARGIN) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
 /** Intake path 1 — the user says the agent worked wrongly. */
 export function detectUserReport(prompt: string): DefectFinding | null {
     for (const re of COMPLAINT_PATTERNS) {
         const m = re.exec(prompt);
-        if (m !== null) {
+        if (m !== null && !spanExonerated(prompt, m.index, m.index + m[0].length)) {
             return {
                 defect_class: 'user-reported',
                 source: 'user-reported',
@@ -222,11 +479,38 @@ export function detectLanguageMirror(turn: TurnSnapshot): DefectFinding | null {
     };
 }
 
+/** One registered detector — the unit the corpus gate enumerates. */
+export interface RegisteredDetector {
+    defect_class: DefectClass;
+    source: DefectSource;
+    detect: (turn: TurnSnapshot) => DefectFinding | null;
+}
+
+/**
+ * The detector registry — the single list both `runDetectors` and the corpus
+ * gate (`tests/scripts/self_repair_detector_corpus.test.ts`) iterate. A
+ * detector added here without its three fixture classes (fire /
+ * near-miss-fire / must-not-fire) is a red test, not a silently untested
+ * code path.
+ */
+export const DETECTOR_REGISTRY: readonly RegisteredDetector[] = [
+    {
+        defect_class: 'user-reported',
+        source: 'user-reported',
+        detect: (turn) => detectUserReport(turn.prompt),
+    },
+    { defect_class: 'council-availability-claim', source: 'self-detected', detect: detectCouncilClaim },
+    { defect_class: 'language-mirror', source: 'self-detected', detect: detectLanguageMirror },
+];
+
 /** Run every self-detected detector over a finished turn. */
 export function runDetectors(turn: TurnSnapshot): DefectFinding[] {
     const out: DefectFinding[] = [];
-    for (const d of [detectCouncilClaim, detectLanguageMirror]) {
-        const f = d(turn);
+    for (const d of DETECTOR_REGISTRY) {
+        if (d.source !== 'self-detected') {
+            continue;
+        }
+        const f = d.detect(turn);
         if (f !== null) {
             out.push(f);
         }
@@ -286,23 +570,43 @@ export interface EgressCapability {
     hasAgentConfigCheckout: boolean;
     /** `gh` is installed AND authenticated. */
     ghAuthenticated: boolean;
-    /** The checkout can push a branch to the remote. */
-    canPush: boolean;
+    /**
+     * The authenticated user has push permission on the UPSTREAM repo — a
+     * pre-flight probe of actual rights (`gh api repos/<repo>` →
+     * `.permissions.push`), never an inference from `git remote` existing.
+     * A consumer who cloned the public repo has a remote and no write access;
+     * the old heuristic classified exactly that machine as push-capable.
+     */
+    canPushUpstream: boolean;
+    /** The upstream repo allows forking and the user is authenticated. */
+    canFork: boolean;
+}
+
+/** Where a pull-request route pushes its branch. */
+export type PushVia = 'upstream' | 'fork';
+
+export interface EgressChoice {
+    route: EgressRoute;
+    /** Set only when `route === 'pull-request'`. */
+    pushVia: PushVia | null;
 }
 
 /**
  * Route selection, exactly as specified: a pull request when the fix can be
- * authored and pushed, an issue when it cannot, and a local record when
- * nothing can leave the machine.
+ * authored and pushed (directly, or via fork → cross-repo PR), an issue when
+ * it cannot, and a local record when nothing can leave the machine.
  */
-export function chooseEgressRoute(cap: EgressCapability): EgressRoute {
-    if (cap.hasAgentConfigCheckout && cap.ghAuthenticated && cap.canPush) {
-        return 'pull-request';
+export function chooseEgress(cap: EgressCapability): EgressChoice {
+    if (cap.hasAgentConfigCheckout && cap.ghAuthenticated && cap.canPushUpstream) {
+        return { route: 'pull-request', pushVia: 'upstream' };
+    }
+    if (cap.hasAgentConfigCheckout && cap.ghAuthenticated && cap.canFork) {
+        return { route: 'pull-request', pushVia: 'fork' };
     }
     if (cap.ghAuthenticated) {
-        return 'issue';
+        return { route: 'issue', pushVia: null };
     }
-    return 'local-only';
+    return { route: 'local-only', pushVia: null };
 }
 
 /** The PR / issue body. Deterministic — same record, same bytes. */
@@ -340,3 +644,40 @@ export function renderReport(record: DefectRecord, route: EgressRoute): string {
         'construction — the record type has no field that can carry them.',
     ].join('\n');
 }
+
+/** The structured fields the upstream intake form collects. */
+export interface ParsedReport {
+    defect_class: string;
+    fingerprint: string;
+    occurrences: number;
+    evidence: string;
+    suggested_surface: string;
+}
+
+/**
+ * Inverse of `renderReport` for the structured fields — the round-trip that
+ * pins the rendered body to the upstream issue form: every field the form
+ * collects is recoverable from a rendered report, so a `release` body and a
+ * manually-filed form carry the same clustering keys (fingerprint above all).
+ */
+export function parseReport(body: string): ParsedReport | null {
+    const cls = /^## Self-repair report — `([^`]+)`$/m.exec(body)?.[1];
+    const fp = /^- \*\*Fingerprint:\*\* `([^`]+)`$/m.exec(body)?.[1];
+    const seen = /^- \*\*Seen:\*\* (.+)$/m.exec(body)?.[1];
+    const evidence = /^### Evidence\n\n> (.*)$/m.exec(body)?.[1];
+    const surface = /### What the fix should address\n\n([\s\S]*?)\n\n---/.exec(body)?.[1];
+    if (!cls || !fp || !seen || evidence === undefined || !surface) {
+        return null;
+    }
+    const occurrences = seen.startsWith('once') ? 1 : Number(/^(\d+)×/.exec(seen)?.[1] ?? Number.NaN);
+    if (!Number.isFinite(occurrences)) {
+        return null;
+    }
+    return {
+        defect_class: cls,
+        fingerprint: fp,
+        occurrences,
+        evidence,
+        suggested_surface: surface.trim(),
+    };
+}

package/src/scripts/_lib/self_repair_store.ts

@@ -94,7 +94,35 @@ export function markReleased(root: string, fp: string, now: string): DefectRecor
     if (rec === null) {
         return null;
     }
+    // A successful release supersedes any earlier failed attempts.
     const next: DefectRecord = { ...rec, status: 'released', last_seen: now };
+    delete next.release_errors;
+    writeRecord(root, next);
+    return next;
+}
+
+/**
+ * A release attempt exhausted the whole egress ladder: keep the record open
+ * and attach every failed step so the next `self-repair:status` shows what
+ * went wrong. Errors arrive pre-sanitized (the CLI runs them through
+ * `sanitizeEvidence` — command output can carry local paths).
+ */
+export function attachReleaseErrors(
+    root: string,
+    fp: string,
+    errors: string[],
+    now: string,
+): DefectRecord | null {
+    const rec = readRecord(root, fp);
+    if (rec === null) {
+        return null;
+    }
+    const next: DefectRecord = {
+        ...rec,
+        status: 'open',
+        last_seen: now,
+        release_errors: errors,
+    };
     writeRecord(root, next);
     return next;
 }