@event4u/agent-config 9.28.0 → 9.29.0

package/src/scripts/_lib/self_repair.ts

@@ -38,6 +38,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 +68,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. */
@@ -115,7 +133,10 @@ export function egressBlockedReason(record: DefectRecord, repoRoot?: string | nu
 // 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 +146,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 +285,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 +376,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 +450,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;
 }

package/src/scripts/_lib/subagent_capsule.ts

@@ -0,0 +1,182 @@
+/**
+ * Worker-generation CHECKPOINT capsule (road-to-worker-generation-recycling, Phase 0).
+ *
+ * Pure, no-I/O. The structured state a worker emits BELOW its stop-loss
+ * watermark so a successor generation can continue the SAME task from the
+ * capsule alone — never from the transcript, never from an orchestrator-written
+ * re-brief. Today a worker that reaches `max_tokens_per_worker` is killed
+ * (`worker_budget.ts`) and its partial result returns as a `BLOCKED` envelope;
+ * there is no handoff. This is the handoff shape.
+ *
+ * TRANSCRIPT-EXCLUSION BY CONSTRUCTION: every field is a ref token, a single
+ * short line, or a count — there is NO field capable of holding a transcript,
+ * a file body, or prose at length, and the per-array caps mean a capsule cannot
+ * become one by accumulation either. This is not stylistic. A capsule that
+ * could smuggle raw context would make the successor's brief unmeasurable,
+ * which is the whole question the roadmap's claim asks. Do not add a free-form
+ * field. (Same principle as `orchestration_record.ts` for telemetry and
+ * `domain-safety-pii` § Surface 2 for logs.)
+ *
+ * Contract: `src/agent-src/contexts/execution/subagent-response-contract.md`
+ * Wire format: `src/skills/subagent-orchestration/schemas/subagent-status.json`
+ */
+
+/**
+ * Epistemic vocabulary for `assumptions[].epistemic_state` — pinned ONCE, here,
+ * to the three Evidence-Report buckets already in use for docs and discovery
+ * (`evidence-discipline.md` § Evidence Report). A capsule that graded its
+ * assumptions on a private scale would fork the vocabulary the rest of the
+ * suite reasons in, so it does not get one.
+ *
+ * - `verified` — confirmed against a real source during THIS worker generation.
+ * - `assumed`  — taken as a premise, not confirmed; explicitly a hypothesis.
+ * - `gap`      — known missing evidence the task needs.
+ */
+export const EPISTEMIC_STATES = ['verified', 'assumed', 'gap'] as const;
+export type EpistemicState = (typeof EPISTEMIC_STATES)[number];
+
+const EPISTEMIC: ReadonlySet<string> = new Set<string>(EPISTEMIC_STATES);
+
+/** Max chars for a ref token (`file:line`, id, path). Mirrors the spawn contract. */
+export const MAX_REF_CHARS = 200;
+/** Max chars for one capsule sentence. A paragraph does not fit; that is the point. */
+export const MAX_LINE_CHARS = 240;
+/** Max entries per capsule array. A transcript cannot be reached by accumulation. */
+export const MAX_ENTRIES = 40;
+
+/** One stated premise the successor generation inherits instead of re-deriving. */
+export interface CapsuleAssumption {
+    /** The premise, one line. */
+    statement: string;
+    /** What it rests on — a ref token (`file:line`, id, path, command). */
+    basis: string;
+    /** How well it is established. See {@link EPISTEMIC_STATES}. */
+    epistemic_state: EpistemicState;
+}
+
+/**
+ * The capsule a worker emits at its watermark. Rides as the body of a
+ * `CHECKPOINT` envelope (`subagent-status.json`).
+ */
+export interface WorkerCapsule {
+    /** One- or two-sentence outcome so far. */
+    summary: string;
+    /** Generation index in the chain; the first dispatch is 1. */
+    generation: number;
+    /** What is finished — ref tokens, never bodies. */
+    done: string[];
+    /** What is left, one short line each. */
+    remaining: string[];
+    /** Choices already made that the successor must not silently re-open. */
+    decisions: string[];
+    /** Known risks still open. */
+    open_risks: string[];
+    /** Files this generation touched — paths / `file:line`, never diffs. */
+    touched_files: string[];
+    /**
+     * Stated premises. Unstated assumptions are the first thing compression
+     * drops, which makes them the most likely mechanism behind a degraded
+     * capsule — the field gives the successor a target list instead of
+     * implicit premises.
+     */
+    assumptions: CapsuleAssumption[];
+}
+
+/** A single-line token no longer than `max` chars. Rejects any body-shaped value. */
+function isShortLine(value: unknown, max: number): value is string {
+    return typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\n');
+}
+
+function checkList(
+    errors: string[],
+    field: string,
+    value: unknown,
+    max: number,
+    required: boolean,
+): void {
+    if (value === undefined) {
+        if (required) errors.push(`${field} is required`);
+        return;
+    }
+    if (!Array.isArray(value)) {
+        errors.push(`${field} must be an array`);
+        return;
+    }
+    if (value.length > MAX_ENTRIES) {
+        errors.push(`${field} carries ${value.length} entries (max ${MAX_ENTRIES}) — a capsule is a handoff, not a transcript`);
+    }
+    const bad = value.filter((x) => !isShortLine(x, max));
+    if (bad.length > 0) {
+        errors.push(
+            `${field} carries ${bad.length} entr${bad.length === 1 ? 'y' : 'ies'} that are not single lines of ≤ ${max} chars (refs and short lines only, never bodies)`,
+        );
+    }
+}
+
+/**
+ * Validate a capsule body. Returns the list of violations (empty = valid).
+ *
+ * The orchestrator never briefs a successor from an invalid capsule — an
+ * invalid capsule falls back to today's stop-loss behaviour, loudly.
+ */
+export function validateCapsule(input: unknown): string[] {
+    const errors: string[] = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return ['not an object'];
+    }
+    const c = input as Record<string, unknown>;
+
+    if (!isShortLine(c['summary'], MAX_LINE_CHARS)) {
+        errors.push(`summary must be a single line of 1–${MAX_LINE_CHARS} chars`);
+    }
+
+    const generation = c['generation'];
+    if (typeof generation !== 'number' || !Number.isInteger(generation) || generation < 1) {
+        errors.push('generation must be an integer ≥ 1 (the first dispatch is generation 1)');
+    }
+
+    checkList(errors, 'done', c['done'], MAX_REF_CHARS, true);
+    checkList(errors, 'remaining', c['remaining'], MAX_LINE_CHARS, true);
+    checkList(errors, 'decisions', c['decisions'], MAX_LINE_CHARS, false);
+    checkList(errors, 'open_risks', c['open_risks'], MAX_LINE_CHARS, false);
+    checkList(errors, 'touched_files', c['touched_files'], MAX_REF_CHARS, false);
+
+    const assumptions = c['assumptions'];
+    if (assumptions !== undefined) {
+        if (!Array.isArray(assumptions)) {
+            errors.push('assumptions must be an array');
+        } else {
+            if (assumptions.length > MAX_ENTRIES) {
+                errors.push(`assumptions carries ${assumptions.length} entries (max ${MAX_ENTRIES})`);
+            }
+            for (const [i, raw] of assumptions.entries()) {
+                errors.push(...validateAssumption(raw, `assumptions[${i}]`));
+            }
+        }
+    }
+
+    return errors;
+}
+
+/**
+ * Validate one `{statement, basis, epistemic_state}` triple. Exported because
+ * the worker RESULT envelope carries the same field (`subagent_response.ts`) —
+ * one shape, one validator, so the two cannot drift.
+ */
+export function validateAssumption(input: unknown, label = 'assumption'): string[] {
+    const errors: string[] = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return [`${label} is not an object`];
+    }
+    const a = input as Record<string, unknown>;
+    if (!isShortLine(a['statement'], MAX_LINE_CHARS)) {
+        errors.push(`${label}.statement must be a single line of 1–${MAX_LINE_CHARS} chars`);
+    }
+    if (!isShortLine(a['basis'], MAX_REF_CHARS)) {
+        errors.push(`${label}.basis must be a ref token (file:line, id, path, command) of ≤ ${MAX_REF_CHARS} chars`);
+    }
+    if (typeof a['epistemic_state'] !== 'string' || !EPISTEMIC.has(a['epistemic_state'])) {
+        errors.push(`${label}.epistemic_state must be one of ${EPISTEMIC_STATES.join(' | ')}`);
+    }
+    return errors;
+}

package/src/scripts/_lib/subagent_response.ts

@@ -9,6 +9,8 @@
  * Contract: `src/agent-src/contexts/execution/subagent-response-contract.md`.
  */
 
+import { validateAssumption, type CapsuleAssumption } from './subagent_capsule.js';
+
 export type Confidence = 'low' | 'medium' | 'high';
 
 export interface Finding {
@@ -25,6 +27,14 @@ export interface SubagentResponse {
     risks: string[];
     confidence: Confidence;
     handoff: string;
+    /**
+     * Premises the worker acted on, `{statement, basis, epistemic_state}` —
+     * the same shape and the same validator as the CHECKPOINT capsule
+     * (`subagent_capsule.ts`), so the completed-result and handoff surfaces
+     * cannot drift apart. Optional: absent means not recorded, which is not
+     * the same claim as "no assumptions were made".
+     */
+    assumptions?: CapsuleAssumption[];
 }
 
 const CONFIDENCE: ReadonlySet<string> = new Set<Confidence>(['low', 'medium', 'high']);
@@ -55,6 +65,15 @@ export function validateResponse(input: unknown): ValidationResult {
             }
         }
     }
+    if (r.assumptions !== undefined) {
+        if (!Array.isArray(r.assumptions)) {
+            errors.push('assumptions must be an array of {statement, basis, epistemic_state}');
+        } else {
+            for (const [i, a] of (r.assumptions as unknown[]).entries()) {
+                errors.push(...validateAssumption(a, `assumptions[${i}]`));
+            }
+        }
+    }
     return { valid: errors.length === 0, errors };
 }
 

package/src/scripts/_lib/subagent_spawn.ts

@@ -13,6 +13,8 @@
 
 import * as crypto from 'node:crypto';
 
+import { CAPSULE_WATERMARK_FRACTION } from './worker_budget.js';
+
 export type RoleMode = 'developer' | 'reviewer' | 'tester' | 'po' | 'incident' | 'planner';
 
 const ROLE_MODES: ReadonlySet<string> = new Set<RoleMode>([
@@ -55,6 +57,12 @@ export interface SpawnBrief {
     knowledge_refs: string[];
     /** Per-worker token stop-loss; null = unset (legacy dispatch). */
     max_tokens_per_worker: number | null;
+    /**
+     * Token count at which the worker emits a CHECKPOINT capsule — DERIVED from
+     * `max_tokens_per_worker`, never set independently, so the watermark cannot
+     * drift away from the budget it sits under. Null when no budget is set.
+     */
+    capsule_watermark: number | null;
     warnings: string[];
 }
 
@@ -112,6 +120,10 @@ export function composeSpawnBrief(sel: SpawnSelection): SpawnBrief {
         personas,
         knowledge_refs,
         max_tokens_per_worker,
+        capsule_watermark:
+            max_tokens_per_worker === null
+                ? null
+                : Math.floor(max_tokens_per_worker * CAPSULE_WATERMARK_FRACTION),
         warnings,
     };
 }
@@ -133,6 +145,7 @@ export function serializeSpawnPayload(brief: SpawnBrief): string {
         profile: brief.profile,
         personas: brief.personas,
         max_tokens_per_worker: brief.max_tokens_per_worker,
+        capsule_watermark: brief.capsule_watermark,
     });
     const variableTail = JSON.stringify({
         task: brief.task,

package/src/scripts/_lib/subagent_steering.ts

@@ -26,14 +26,19 @@ export const GUARDRAILS = {
     user_override_rate: 0.3,
 } as const;
 
+/**
+ * Always-on orchestration (road-to-always-on-orchestration Phase 1) removed
+ * the `enabled`/`auto` settings this state used to carry — the only
+ * surviving switch is the audited incident halt.
+ */
 export interface LayerState {
-    enabled: boolean;
-    auto: 'off' | 'ask' | 'on';
+    /** `emergency.orchestration_halt`. */
+    halted: boolean;
 }
 
-/** The kill-switch: layer is disabled when the master switch is off or auto is off. */
+/** The kill-switch: layer is disabled only during an active emergency halt. */
 export function isLayerDisabled(state: LayerState): boolean {
-    return !state.enabled || state.auto === 'off';
+    return state.halted;
 }
 
 /** N=3 per-target budget: halt once consecutive failed attempts reach the cap. */

package/src/scripts/_lib/tier_budget_routing.ts

@@ -43,7 +43,12 @@ export interface PickTierInputs {
     adequate_tier: BudgetTier;
     /** Per-tier budget state, complete over TIER_ORDER. */
     budgets: Record<BudgetTier, TierBudgetState>;
-    /** subagents.budget_routing setting. */
+    /**
+     * Caller-supplied switch. Formerly sourced from the `subagents.budget_routing`
+     * settings key, deleted by always-on orchestration (Phase 1) — this
+     * function has no production caller today, so the field stays as the
+     * DESIGNED input shape; a future wiring supplies its own source.
+     */
     routing_switch: BudgetRoutingSwitch;
     /** Estimated cost of the dispatch (USD) for the availability check. */
     estimated_cost_usd: number;

package/src/scripts/_lib/worker_budget.ts

@@ -35,6 +35,24 @@ export function budgetForTier(tier: Tier, sessionTier: Exclude<Tier, 'inherit'>
     return MAX_TOKENS_PER_WORKER[effective];
 }
 
+/**
+ * Fraction of the stop-loss budget at which a worker emits its CHECKPOINT
+ * capsule (road-to-worker-generation-recycling, Phase 1).
+ *
+ * The headroom IS the mechanism: a worker at 100 % of its budget cannot
+ * summarise itself, so the watermark sits below the kill line rather than on
+ * it. A start value, not a tuned one — Phase 1 measures it in shadow against a
+ * second trigger arm before anything acts on it, and `blocker:
+ * capsule-quality-near-budget` exists because a bad watermark and a bad
+ * mechanism look identical from one sample.
+ */
+export const CAPSULE_WATERMARK_FRACTION = 0.8;
+
+/** Token count at which a worker of this tier emits its capsule. */
+export function watermarkForTier(tier: Tier, sessionTier: Exclude<Tier, 'inherit'> = 'high'): number {
+    return Math.floor(budgetForTier(tier, sessionTier) * CAPSULE_WATERMARK_FRACTION);
+}
+
 /** Where the orchestrator should send the task after a budget hit. */
 export type NextRung = 'primitive' | 'higher-tier-subagent' | 'in-session';
 
@@ -64,19 +82,36 @@ export interface BudgetEvaluation {
     budget_hit: boolean;
     consumed: number;
     budget: number;
+    /** Token count at which the CHECKPOINT capsule is due (below the kill line). */
+    watermark: number;
+    /** Consumption reached the watermark but not yet the stop-loss. */
+    watermark_hit: boolean;
     reason: string;
 }
 
-/** Evaluate consumption against the worker's budget. */
+/**
+ * Evaluate consumption against the worker's budget.
+ *
+ * Two lines, not one: the **watermark** (emit a capsule, still working) and the
+ * **stop-loss** (return a partial result, stop). A budget hit implies the
+ * watermark was passed, so `watermark_hit` marks the band BETWEEN them — the
+ * only window in which a capsule can still be written.
+ */
 export function evaluateWorkerBudget(consumed: number, budget: number): BudgetEvaluation {
     const hit = consumed >= budget;
+    const watermark = Math.floor(budget * CAPSULE_WATERMARK_FRACTION);
+    const watermarkHit = !hit && consumed >= watermark;
     return {
         budget_hit: hit,
         consumed,
         budget,
+        watermark,
+        watermark_hit: watermarkHit,
         reason: hit
             ? `budget hit (${consumed} >= ${budget}) — return partial result + escalation flag, stop exploring`
-            : `within budget (${consumed} < ${budget})`,
+            : watermarkHit
+              ? `watermark reached (${consumed} >= ${watermark}) — emit a CHECKPOINT capsule while there is headroom to write one`
+              : `within budget (${consumed} < ${budget})`,
     };
 }