@event4u/agent-config 9.28.0 → 9.30.0

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

@@ -0,0 +1,341 @@
+/**
+ * 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[];
+}
+
+/**
+ * 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');
+}
+
+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;
+}
+
+/**
+ * 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`) —
+ * 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;
+}