@event4u/agent-config 9.29.0 → 9.31.0

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';
@@ -128,6 +129,199 @@ 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

package/src/scripts/_lib/session_eol.ts

@@ -0,0 +1,230 @@
+/**
+ * Session end-of-life scanner (road-to-token-economy-recycling Phase 1).
+ *
+ * Pure counting over Claude Code transcript JSONL: per session, the FINAL
+ * main-chain context size in parsed tokens, the turn count, and every
+ * compaction event — the three numbers the recycle roadmap's baseline and
+ * threshold are built from. Token math delegates to `cc_transcript.ts`
+ * (`billableInputTokens` — input + cache_read + cache_creation); this module
+ * adds no second token definition ("no new parser", roadmap prerequisite).
+ *
+ * Compaction detector — pinned to OBSERVED reality (blocker
+ * `compaction-marker-shape`): a real auto-compaction recorded 2026-08-06 on
+ * host v2.1.222 writes TWO markers into the transcript:
+ *
+ *   1. `{"type":"system","subtype":"compact_boundary","compactMetadata":
+ *      {"trigger":"auto","preTokens":1000410,"postTokens":15870,...}}`
+ *   2. a `{"type":"user","isCompactSummary":true,...}` record carrying the
+ *      summary the session was restarted from.
+ *
+ * The fixture in `tests/scripts/_lib_session_eol.test.ts` freezes both
+ * shapes. Never-silent discipline: the scanner counts BOTH markers
+ * independently — `compactions[]` from the boundary records,
+ * `compact_summaries` from the summary records. A host update that changes
+ * one shape but not the other makes the two counters diverge, which the
+ * report surfaces as marker drift instead of silently zeroing the metric.
+ *
+ * Incremental by design: the Stop-slot carrier re-runs every turn, so
+ * `scanEolSlice` accepts prior counters and only the newly appended complete
+ * lines (`readNewCompleteLines`). A full rescan is only ever the bounded
+ * 50 MB `isSafeTranscriptPath` cap away.
+ */
+
+import * as fs from 'node:fs';
+
+import { billableInputTokens } from './cc_transcript.js';
+
+/** The observed compaction boundary marker (host v2.1.222, 2026-08-06). */
+export const COMPACT_BOUNDARY_SUBTYPE = 'compact_boundary';
+
+/** One compaction event, read from a `compact_boundary` system record. */
+export interface CompactionEvent {
+    /** `"auto"` observed; the field is host territory — kept as an open string. */
+    trigger: string;
+    /** Context tokens immediately before compaction (`compactMetadata.preTokens`). */
+    pre_tokens: number | null;
+    /** Context tokens immediately after (`compactMetadata.postTokens`). */
+    post_tokens: number | null;
+    timestamp: string | null;
+}
+
+/** Accumulated per-session end-of-life counters. Counts and refs only — never content. */
+export interface EolCounters {
+    schema_version: 1;
+    /** Byte offset up to which the transcript has been consumed (end of last complete line). */
+    scanned_bytes: number;
+    /** External user prompts on the main chain (excl. meta / compact-summary records). */
+    turns: number;
+    /** Main-chain assistant records carrying a `usage` block. */
+    assistant_records: number;
+    /** Billable input tokens of the LAST main-chain assistant record — the fill level. */
+    final_context_tokens: number | null;
+    /** `timestamp` of that record. */
+    final_context_at: string | null;
+    /** Every `compact_boundary` event seen, in order. */
+    compactions: CompactionEvent[];
+    /** `isCompactSummary` user records seen — the drift twin of `compactions`. */
+    compact_summaries: number;
+    /** Lines that failed `JSON.parse`. */
+    bad_lines: number;
+}
+
+export function emptyCounters(): EolCounters {
+    return {
+        schema_version: 1,
+        scanned_bytes: 0,
+        turns: 0,
+        assistant_records: 0,
+        final_context_tokens: null,
+        final_context_at: null,
+        compactions: [],
+        compact_summaries: 0,
+        bad_lines: 0,
+    };
+}
+
+function numOrNull(value: unknown): number | null {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function numOr0(value: unknown): number {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Detect the observed compaction boundary marker on one parsed record.
+ * Returns the event, or `null` for every other record shape.
+ */
+export function detectCompaction(record: Record<string, unknown>): CompactionEvent | null {
+    if (record['type'] !== 'system' || record['subtype'] !== COMPACT_BOUNDARY_SUBTYPE) {
+        return null;
+    }
+    const md = (record['compactMetadata'] ?? {}) as Record<string, unknown>;
+    return {
+        trigger: typeof md['trigger'] === 'string' ? md['trigger'] : 'unknown',
+        pre_tokens: numOrNull(md['preTokens']),
+        post_tokens: numOrNull(md['postTokens']),
+        timestamp: typeof record['timestamp'] === 'string' ? record['timestamp'] : null,
+    };
+}
+
+/** True for a main-chain external user PROMPT record (a turn), per the baseline heuristic. */
+function isTurnRecord(record: Record<string, unknown>): boolean {
+    if (record['type'] !== 'user') return false;
+    if (record['isCompactSummary'] === true || record['isMeta'] === true) return false;
+    const message = record['message'];
+    if (typeof message !== 'object' || message === null) return false;
+    const content = (message as Record<string, unknown>)['content'];
+    if (typeof content === 'string') return content.trim().length > 0;
+    if (Array.isArray(content)) {
+        return content.some(
+            (b) => typeof b === 'object' && b !== null && (b as Record<string, unknown>)['type'] === 'text',
+        );
+    }
+    return false;
+}
+
+/**
+ * Fold newly appended COMPLETE transcript lines into the counters. Pure —
+ * returns a new counters object; `scanned_bytes` is the caller's business
+ * (it knows the byte offsets, this function only sees text).
+ */
+export function scanEolSlice(text: string, prior: EolCounters): EolCounters {
+    const next: EolCounters = {
+        ...prior,
+        compactions: [...prior.compactions],
+    };
+    for (const line of text.split('\n')) {
+        if (line.trim().length === 0) continue;
+        let record: Record<string, unknown>;
+        try {
+            const parsed = JSON.parse(line) as unknown;
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                next.bad_lines += 1;
+                continue;
+            }
+            record = parsed as Record<string, unknown>;
+        } catch {
+            next.bad_lines += 1;
+            continue;
+        }
+        if (record['isSidechain'] === true) continue; // subagent legs are not this session's context
+
+        const compaction = detectCompaction(record);
+        if (compaction) {
+            next.compactions.push(compaction);
+            continue;
+        }
+        if (record['type'] === 'user' && record['isCompactSummary'] === true) {
+            next.compact_summaries += 1;
+            continue;
+        }
+        if (isTurnRecord(record)) {
+            next.turns += 1;
+            continue;
+        }
+        if (record['type'] === 'assistant') {
+            const message = record['message'];
+            const usage =
+                typeof message === 'object' && message !== null
+                    ? ((message as Record<string, unknown>)['usage'] as Record<string, unknown> | undefined)
+                    : undefined;
+            if (typeof usage === 'object' && usage !== null && usage['input_tokens'] !== undefined) {
+                next.assistant_records += 1;
+                next.final_context_tokens = billableInputTokens({
+                    input_tokens: numOr0(usage['input_tokens']),
+                    cache_read_input_tokens: numOr0(usage['cache_read_input_tokens']),
+                    cache_creation_input_tokens: numOr0(usage['cache_creation_input_tokens']),
+                });
+                next.final_context_at =
+                    typeof record['timestamp'] === 'string' ? record['timestamp'] : null;
+            }
+        }
+    }
+    return next;
+}
+
+export interface NewLinesRead {
+    /** The complete lines appended since `fromByte` (possibly empty). */
+    text: string;
+    /** The offset to persist — end of the last complete line consumed. */
+    nextOffset: number;
+    /** True when the file shrank below `fromByte` (rotation/truncation) — caller rescans from 0. */
+    truncated: boolean;
+}
+
+/**
+ * Read the bytes appended to `filePath` since `fromByte`, trimmed to the
+ * last complete line (a JSONL writer may be mid-line). Never throws — any
+ * fs error reads as "nothing new".
+ */
+export function readNewCompleteLines(filePath: string, fromByte: number): NewLinesRead {
+    try {
+        const { size } = fs.statSync(filePath);
+        if (size < fromByte) {
+            return { text: '', nextOffset: 0, truncated: true };
+        }
+        if (size === fromByte) {
+            return { text: '', nextOffset: fromByte, truncated: false };
+        }
+        const length = size - fromByte;
+        const buffer = Buffer.alloc(length);
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            fs.readSync(fd, buffer, 0, length, fromByte);
+        } finally {
+            fs.closeSync(fd);
+        }
+        const lastNewline = buffer.lastIndexOf(0x0a);
+        if (lastNewline === -1) {
+            return { text: '', nextOffset: fromByte, truncated: false };
+        }
+        return {
+            text: buffer.subarray(0, lastNewline + 1).toString('utf-8'),
+            nextOffset: fromByte + lastNewline + 1,
+            truncated: false,
+        };
+    } catch {
+        return { text: '', nextOffset: fromByte, truncated: false };
+    }
+}

package/src/scripts/_lib/session_role.ts

@@ -0,0 +1,42 @@
+/**
+ * Session-role detection — the ONE shared detector (road-to-token-economy-
+ * dispatch Phase 2.2: "one detector, two consumers, test-pinned equal").
+ *
+ * Consumers:
+ *   - `hooks/dispatch_hook.ts` — applies the manifest's role axis (a marked
+ *     worker session runs a shorter concern chain).
+ *   - `hooks/delegation_nudge_hook.ts` — feeds the judgment ladder's
+ *     recursive-dispatch guard (`insideSubagentSession`), whose own header
+ *     documents the fact as CALLER-SUPPLIED: no verified host discriminator
+ *     exists (upstream agent-identity request closed NOT_PLANNED), and
+ *     probing for invented host variable names is the hallucinated-field
+ *     failure `source-discovery-gate` exists to stop.
+ *
+ * `AGENT_CONFIG_SESSION_ROLE` is therefore this suite's OWN variable, set
+ * only by suite-owned spawn wrappers that launch a separate CLI session
+ * (council transports, bench runners, future worker wrappers). Host
+ * limitation, pre-registered in the roadmap's `worker-chain-host-delivery`
+ * blocker: an in-process Agent-tool subagent shares the host process env
+ * and CANNOT be marked per-spawn — on that path the role resolves
+ * `orchestrator` and the full chain runs (fail-open, Phase 2.4).
+ *
+ * Fail-open is the contract: unset, empty, or unknown values resolve to
+ * `orchestrator` — the thin path is the opt-in of a marked spawn, never
+ * the accident of a missing or typo'd variable.
+ */
+
+export const SESSION_ROLE_ENV = 'AGENT_CONFIG_SESSION_ROLE';
+
+/** `reviewer` is enum-reserved for Phase 3.2; until a `roles.reviewer`
+ *  manifest entry exists it resolves to the full chain like any role
+ *  without a manifest entry. */
+export type SessionRole = 'orchestrator' | 'worker' | 'reviewer';
+
+const KNOWN_ROLES: ReadonlySet<string> = new Set(['orchestrator', 'worker', 'reviewer']);
+
+export function resolveSessionRole(
+    env: Record<string, string | undefined> = process.env,
+): SessionRole {
+    const raw = (env[SESSION_ROLE_ENV] ?? '').trim().toLowerCase();
+    return (KNOWN_ROLES.has(raw) ? raw : 'orchestrator') as SessionRole;
+}

package/src/scripts/_lib/subagent_capsule.ts

@@ -82,6 +82,23 @@ export interface WorkerCapsule {
     assumptions: CapsuleAssumption[];
 }
 
+/**
+ * Capsule schema version (road-to-token-economy-recycling Phase 2.1).
+ * Versioning is INTRODUCED here — the Phase-0 worker capsule shipped
+ * unversioned and stays valid without a version field (implicit v1, wire
+ * shape unchanged, `subagent-status.json` untouched). Version 2 adds the
+ * explicit `capsule_version` + `variant` discriminator that the
+ * main-session recycle envelope requires. Policy: additive only — a new
+ * version may add fields or variants, never repurpose or remove one; both
+ * variants validate through THIS module (one schema file, one validator
+ * family — roadmap 5.6's anti-fork rule).
+ */
+export const CAPSULE_SCHEMA_VERSION = 2;
+
+/** The two CHECKPOINT variants sharing this schema. */
+export const CAPSULE_VARIANTS = ['worker', 'main_session'] as const;
+export type CapsuleVariant = (typeof CAPSULE_VARIANTS)[number];
+
 /** 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');
@@ -158,6 +175,148 @@ export function validateCapsule(input: unknown): string[] {
     return errors;
 }
 
+/**
+ * The main-session recycle envelope (road-to-token-economy-recycling
+ * Phase 2.1) — the `main_session` CHECKPOINT variant. Unlike the worker
+ * capsule there is NO surviving orchestrator to receive it: the successor
+ * session bootstraps from the envelope ALONE, so the required set is
+ * stricter — the active task, its acceptance criteria, the open work, and
+ * the explicit NOT-carried-forward list (what the successor must re-derive
+ * from source rather than trust) are all mandatory.
+ *
+ * Same transcript-exclusion-by-construction as the worker capsule: every
+ * field is a ref token or a single short line, validated by the SAME
+ * primitives. A prose transcript summary is schema-invalid twice over —
+ * any multi-line value fails `isShortLine`, and any field not listed below
+ * (e.g. `transcript_summary`) fails the unknown-key sweep. The strict
+ * sweep is deliberate where the worker validator stays open: the worker
+ * side has `subagent-status.json` (`additionalProperties: false`) as its
+ * wire gate; this variant is consumed from a FILE by
+ * `handoff_context_hook`, so the module itself must be the strict gate.
+ */
+export interface MainSessionRecycleEnvelope {
+    /** Must be {@link CAPSULE_SCHEMA_VERSION}. */
+    capsule_version: number;
+    variant: 'main_session';
+    /** One- or two-sentence outcome so far. */
+    summary: string;
+    /** The active task, one line. */
+    task: string;
+    /** Workspace root this envelope belongs to — the consumer's identity check (Risk 4). */
+    workspace: string;
+    /** ISO-8601 stamp of the write — the consumer's staleness guard. */
+    written_at: string;
+    /** What "done" means — one short line each. Required, ≥ 1. */
+    acceptance_criteria: string[];
+    /** Open work, one short line each. Required (may be empty when only verification remains). */
+    remaining: string[];
+    /**
+     * What the successor must RE-DERIVE from source instead of trusting —
+     * the explicit omission list that makes envelope loss visible instead
+     * of silent. Required; an empty list is a claim, not a default.
+     */
+    not_carried_forward: string[];
+    /** Choices already made, each with its one-line rationale in the same line. */
+    decisions?: string[];
+    /** Binding constraints the successor must not silently re-open. */
+    constraints?: string[];
+    /** Open worker CHECKPOINT envelopes by path — never inlined bodies. */
+    open_worker_envelopes?: string[];
+    /** Artifact paths (deliverables, notes, evidence) — refs, never bodies. */
+    artifact_paths?: string[];
+    /** Stated premises — the shared `{statement, basis, epistemic_state}` shape. */
+    assumptions?: CapsuleAssumption[];
+}
+
+/** Every key `validateRecycleEnvelope` accepts — anything else is schema-invalid. */
+const RECYCLE_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
+    'capsule_version',
+    'variant',
+    'summary',
+    'task',
+    'workspace',
+    'written_at',
+    'acceptance_criteria',
+    'remaining',
+    'not_carried_forward',
+    'decisions',
+    'constraints',
+    'open_worker_envelopes',
+    'artifact_paths',
+    'assumptions',
+]);
+
+/**
+ * Validate a main-session recycle envelope. Returns the list of violations
+ * (empty = valid). The consumer never injects an invalid envelope — it is
+ * consumed and discarded loudly instead (`handoff_context_hook`).
+ */
+export function validateRecycleEnvelope(input: unknown): string[] {
+    const errors: string[] = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return ['not an object'];
+    }
+    const e = input as Record<string, unknown>;
+
+    for (const key of Object.keys(e)) {
+        if (!RECYCLE_ENVELOPE_KEYS.has(key)) {
+            errors.push(
+                `unknown field "${key}" — a recycle envelope carries selection and pointers only; ` +
+                    'free-form additions (prose summaries included) are schema-invalid by construction',
+            );
+        }
+    }
+
+    if (e['capsule_version'] !== CAPSULE_SCHEMA_VERSION) {
+        errors.push(`capsule_version must be ${CAPSULE_SCHEMA_VERSION}`);
+    }
+    if (e['variant'] !== 'main_session') {
+        errors.push("variant must be 'main_session'");
+    }
+    if (!isShortLine(e['summary'], MAX_LINE_CHARS)) {
+        errors.push(`summary must be a single line of 1–${MAX_LINE_CHARS} chars`);
+    }
+    if (!isShortLine(e['task'], MAX_LINE_CHARS)) {
+        errors.push(`task must be a single line of 1–${MAX_LINE_CHARS} chars`);
+    }
+    if (!isShortLine(e['workspace'], MAX_REF_CHARS)) {
+        errors.push(`workspace must be a path ref of ≤ ${MAX_REF_CHARS} chars`);
+    }
+    const writtenAt = e['written_at'];
+    if (typeof writtenAt !== 'string' || Number.isNaN(Date.parse(writtenAt))) {
+        errors.push('written_at must be a parseable ISO-8601 timestamp');
+    }
+
+    checkList(errors, 'acceptance_criteria', e['acceptance_criteria'], MAX_LINE_CHARS, true);
+    if (Array.isArray(e['acceptance_criteria']) && e['acceptance_criteria'].length === 0) {
+        errors.push('acceptance_criteria must carry at least one entry — the successor cannot know "done" without it');
+    }
+    checkList(errors, 'remaining', e['remaining'], MAX_LINE_CHARS, true);
+    checkList(errors, 'not_carried_forward', e['not_carried_forward'], MAX_LINE_CHARS, true);
+    checkList(errors, 'decisions', e['decisions'], MAX_LINE_CHARS, false);
+    checkList(errors, 'constraints', e['constraints'], MAX_LINE_CHARS, false);
+    checkList(errors, 'open_worker_envelopes', e['open_worker_envelopes'], MAX_REF_CHARS, false);
+    checkList(errors, 'artifact_paths', e['artifact_paths'], MAX_REF_CHARS, false);
+
+    // `remaining` and `not_carried_forward` must be PRESENT (checkList already
+    // enforces that) — empty arrays are legal, explicit claims.
+    const assumptions = e['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`) —