@event4u/agent-config 9.29.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

@@ -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`) —

package/src/scripts/_lib/subagent_response.ts

@@ -21,12 +21,38 @@ export interface Finding {
     mutating?: boolean;
 }
 
+// ── Committed envelope size caps (road-to-token-economy-dispatch Phase 6.1) ──
+// The envelope is the ONLY return channel: a worker's full result lands on
+// disk (runtime artifact dir, gitignored) and the envelope carries paths +
+// verdict + a BOUNDED summary. Without caps, transcript-shaped output flows
+// back into the orchestrator context and refunds the isolation win — the
+// measured spawn floor is ~251k tokens; a capped envelope is ≤ ~3k. Caps are
+// validator ERRORS, never silent truncation (never-silent discipline): an
+// oversized envelope is rejected loudly and the author shortens it.
+/** Max chars for the summary — bounded prose, not a transcript. */
+export const MAX_SUMMARY_CHARS = 2000;
+/** Max chars for one line-shaped field (handoff, a risk, a finding title). */
+export const MAX_RESPONSE_LINE_CHARS = 240;
+/** Max entries per array (findings, risks, artifact_paths) — mirrors the capsule. */
+export const MAX_RESPONSE_ENTRIES = 40;
+/** Max chars for one artifact path ref. Mirrors the capsule's ref cap. */
+export const MAX_ARTIFACT_REF_CHARS = 200;
+/** Committed max for the WHOLE serialized envelope (~3k tokens ceiling). */
+export const MAX_ENVELOPE_CHARS = 12000;
+
 export interface SubagentResponse {
     summary: string;
     findings: Finding[];
     risks: string[];
     confidence: Confidence;
     handoff: string;
+    /**
+     * Where the worker's FULL results live on disk (runtime artifact dir,
+     * gitignored) — the orchestrator consumes from these paths on demand,
+     * never via wholesale transcript ingestion (Phase 6.1/6.2). Ref tokens
+     * only, capped like every other array.
+     */
+    artifact_paths?: string[];
     /**
      * Premises the worker acted on, `{statement, basis, epistemic_state}` —
      * the same shape and the same validator as the CHECKPOINT capsule
@@ -74,6 +100,55 @@ export function validateResponse(input: unknown): ValidationResult {
             }
         }
     }
+    // ── Committed size caps (Phase 6.1) — errors, never silent truncation ──
+    if (typeof r.summary === 'string' && r.summary.length > MAX_SUMMARY_CHARS) {
+        errors.push(`summary is ${r.summary.length} chars (max ${MAX_SUMMARY_CHARS}) — the envelope carries a bounded summary; the full result belongs on disk (artifact_paths)`);
+    }
+    if (typeof r.handoff === 'string' && r.handoff.length > MAX_RESPONSE_LINE_CHARS) {
+        errors.push(`handoff is ${r.handoff.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+    }
+    for (const [key, arr] of [
+        ['findings', r.findings],
+        ['risks', r.risks],
+        ['artifact_paths', r.artifact_paths],
+    ] as const) {
+        if (Array.isArray(arr) && arr.length > MAX_RESPONSE_ENTRIES) {
+            errors.push(`${key} carries ${arr.length} entries (max ${MAX_RESPONSE_ENTRIES}) — an envelope is a handoff, not a transcript`);
+        }
+    }
+    if (Array.isArray(r.risks)) {
+        for (const [i, risk] of (r.risks as unknown[]).entries()) {
+            if (typeof risk === 'string' && risk.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`risks[${i}] is ${risk.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (Array.isArray(r.findings)) {
+        for (const [i, f] of (r.findings as Finding[]).entries()) {
+            if (f && typeof f.title === 'string' && f.title.length > MAX_RESPONSE_LINE_CHARS) {
+                errors.push(`finding[${i}] title is ${f.title.length} chars (max ${MAX_RESPONSE_LINE_CHARS})`);
+            }
+        }
+    }
+    if (r.artifact_paths !== undefined) {
+        if (!Array.isArray(r.artifact_paths)) {
+            errors.push('artifact_paths must be an array of path ref tokens');
+        } else {
+            for (const [i, p] of (r.artifact_paths as unknown[]).entries()) {
+                if (typeof p !== 'string' || p.includes('\n') || p.length > MAX_ARTIFACT_REF_CHARS) {
+                    errors.push(`artifact_paths[${i}] must be a single-line path ref ≤ ${MAX_ARTIFACT_REF_CHARS} chars`);
+                }
+            }
+        }
+    }
+    try {
+        const serialized = JSON.stringify(input);
+        if (serialized.length > MAX_ENVELOPE_CHARS) {
+            errors.push(`envelope serializes to ${serialized.length} chars (max ${MAX_ENVELOPE_CHARS}) — move content to disk and reference it via artifact_paths`);
+        }
+    } catch {
+        errors.push('envelope is not JSON-serializable');
+    }
     return { valid: errors.length === 0, errors };
 }
 

package/src/scripts/ai_council/clients.ts

@@ -45,6 +45,37 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { SESSION_ROLE_ENV } from '../_lib/session_role.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+
+// Session-wide subagent model ceiling (token-economy-dispatch Phase 5.2):
+// class-C setting, default absent, HUMAN-set only. When present, the CLI
+// spawn below exports CLAUDE_CODE_SUBAGENT_MODEL so the spawned vendor
+// session caps its own subagents' models. Memoised PER CWD, not per
+// process (review finding 2026-08-10): a long-lived server process may
+// serve several projects, and a single-slot memo would apply project A's
+// spend cap to project B's spawns. A human edit still needs a process
+// restart to be seen — acceptable for a per-install cap, stated here.
+const _modelCeilingMemo = new Map<string, string | null>();
+export function _subagentModelCeiling(cwd: string = process.cwd()): string | null {
+    const hit = _modelCeilingMemo.get(cwd);
+    if (hit !== undefined) return hit;
+    let ceiling: string | null;
+    try {
+        const settings = load_agent_settings({ cwd }) as Record<string, unknown>;
+        const sub = (settings['subagents'] ?? {}) as Record<string, unknown>;
+        const v = typeof sub['model_ceiling'] === 'string' ? sub['model_ceiling'].trim() : '';
+        ceiling = v.length > 0 ? v : null;
+    } catch {
+        ceiling = null; // unreadable settings → no ceiling (fail-open)
+    }
+    _modelCeilingMemo.set(cwd, ceiling);
+    return ceiling;
+}
+/** Test seam: reset the per-cwd ceiling memo. */
+export function _resetModelCeilingMemo(): void {
+    _modelCeilingMemo.clear();
+}
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import { appendEvent } from './events_log.js';
 
@@ -1179,7 +1210,25 @@ export abstract class CliClient extends ExternalAIClient {
             // (loader preload, git *_COMMAND, NODE_OPTIONS, …) so an
             // attacker-influenced parent env cannot RCE via the spawned CLI
             // or a `git` it invokes internally.
-            env: hardenedSpawnEnv(),
+            // Role marking (token-economy-dispatch Phase 2.2): a council
+            // member CLI session is worker-class — it never talks to OUR
+            // user, never dispatches sub-workers, never runs a council.
+            // The spawned vendor CLI loads this repo's hook chains; the
+            // marker lets the dispatcher run the thinner worker chain
+            // (manifest `roles.worker.drop`; pre_tool_use guards are
+            // structurally exempt). This is the ONE in-tree spawn point
+            // that launches a separate CLI session today — Agent-tool
+            // subagents share the host process env and cannot be marked
+            // (probed live 2026-08-10; see _lib/session_role.ts).
+            // The optional model ceiling (subagents.model_ceiling, class C)
+            // rides the same spawn: a spend cap the human set per install.
+            env: hardenedSpawnEnv({
+                [SESSION_ROLE_ENV]: 'worker',
+                ...((): Record<string, string> => {
+                    const ceiling = _subagentModelCeiling();
+                    return ceiling !== null ? { CLAUDE_CODE_SUBAGENT_MODEL: ceiling } : {};
+                })(),
+            }),
         };
         if (stdinPayload !== null) {
             spawnOpts.input = stdinPayload;