@event4u/agent-config 9.27.0 → 9.29.0

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/transcript_entry.ts

@@ -0,0 +1,80 @@
+/**
+ * One reader for a transcript entry's text — the shape half, shared.
+ *
+ * WHY THIS EXISTS, measured rather than anticipated. A Claude Code transcript
+ * carries a user entry's `message.content` in TWO shapes: a bare string, and an
+ * array of content blocks. `conformance_scan` handled both; a second reader
+ * written against the same field handled only the string, and the store says why
+ * that is fatal rather than cosmetic:
+ *
+ *   user entries in one 30-session store:  1 440 string · 23 907 array
+ *   injected skill bodies among them:      0 via string · 41 via array
+ *
+ * So the narrower reader saw **none** of them, and the failure was invisible:
+ * a detector whose loaded-set is empty returns no findings, which is
+ * indistinguishable from compliance. `grep` over the raw JSONL finds the marker
+ * either way — reading raw text is not evidence about the parse path, and that
+ * is the mistake this module removes the opportunity to repeat.
+ *
+ * Scope is deliberately just the shape, plus the sidechain exclusion. Semantic
+ * filters (a `<system-reminder>` is not a chat message, an injected body is not a
+ * user turn) stay with the caller that needs them: they differ per question, and
+ * folding them in here would make one module answer two.
+ */
+
+/** A parsed transcript line. */
+export type TranscriptEntry = Record<string, unknown>;
+
+function _isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A subagent's own turns. Excluded by every reader in this tree: a sidechain turn
+ * did not happen in the main thread, so counting it lets a skill loaded in one
+ * context be paired with an act taken in another.
+ */
+export function isSidechain(entry: TranscriptEntry): boolean {
+    return entry['isSidechain'] === true;
+}
+
+/**
+ * Flatten `message.content` to text, whichever shape it arrived in.
+ *
+ * Returns `''` when there is no text (a tool-result-only entry, an unparseable
+ * shape) — never `null`, so a caller cannot forget the second branch.
+ */
+export function entryText(entry: TranscriptEntry): string {
+    const msg = entry['message'];
+    const content = _isObject(msg) ? msg['content'] : undefined;
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    return content
+        .filter((b) => _isObject(b) && b['type'] === 'text')
+        .map((b) => String((b as Record<string, unknown>)['text'] ?? ''))
+        .join('\n');
+}
+
+/** Tool calls in an entry, flattened to name + input. Both shapes are arrays. */
+export function toolUses(entry: TranscriptEntry): Array<{ name: string; input: Record<string, unknown> }> {
+    const msg = entry['message'];
+    const content = _isObject(msg) ? msg['content'] : undefined;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const out: Array<{ name: string; input: Record<string, unknown> }> = [];
+    for (const part of content) {
+        if (!_isObject(part) || part['type'] !== 'tool_use') {
+            continue;
+        }
+        out.push({
+            name: typeof part['name'] === 'string' ? part['name'] : '',
+            input: _isObject(part['input']) ? part['input'] : {},
+        });
+    }
+    return out;
+}

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})`,
     };
 }
 

package/src/scripts/ai_council/clients.ts

@@ -1052,9 +1052,12 @@ export class SubprocessError extends Error {
  * `~/.event4u/agent-config/cli-calls.json` and resets on UTC date rollover.
  *
  * Subclass contract:
- * - `name`: provider key (`anthropic`, `openai`, `gemini`, …).
- * - `default_binary`: executable name resolved via PATH when the member-level
- *   `binary:` field is not set.
+ * - `super(opts, { name, default_binary })`: `name` is the provider key
+ *   (`anthropic`, `openai`, `gemini`, …); `default_binary` is the executable
+ *   resolved via PATH when the member-level `binary:` field is not set. Both
+ *   are passed explicitly to `super()` — not read off subclass instance
+ *   fields — because a subclass's own field initializers run only AFTER this
+ *   `super()` call returns.
  * - `_build_command(system_prompt, user_prompt, max_tokens)`: return the argv.
  * - `_parse_output(stdout, stderr)`: return a partial `CouncilResponse`.
  *
@@ -1097,8 +1100,22 @@ export abstract class CliClient extends ExternalAIClient {
         'usage limit',
     ];
 
-    constructor(opts: CliClientOptions & { model: string }) {
+    /**
+     * `identity` carries the subclass constants (`name`, `default_binary`)
+     * that construction validates against. They are passed explicitly rather
+     * than read off `this.name` / `this.default_binary` because subclass
+     * instance-field initializers (`override default_binary = 'claude'`,
+     * declared in the subclass body) run only AFTER this `super()` call
+     * returns — reading them here, before that happens, would always see the
+     * base class's own field defaults (`''`), not the subclass override.
+     */
+    constructor(
+        opts: CliClientOptions & { model: string },
+        identity: { name: string; default_binary: string },
+    ) {
         super();
+        this.name = identity.name;
+        this.default_binary = identity.default_binary;
         this.model = opts.model;
         this.timeout_seconds = opts.timeout_seconds ?? DEFAULT_CLI_TIMEOUT_SECONDS;
         this.max_calls_per_day = opts.max_calls_per_day ?? null;
@@ -1353,19 +1370,20 @@ export abstract class CliClient extends ExternalAIClient {
  * collides with argv length limits.
  */
 export class AnthropicCliClient extends CliClient {
-    override name = 'anthropic';
-    override default_binary = 'claude';
     override subscription_label = 'claude-pro';
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'anthropic', default_binary: 'claude' },
+        );
     }
 
     protected override _build_command(
@@ -1446,8 +1464,6 @@ export class AnthropicCliClient extends CliClient {
  * token usage in `usage.input_tokens` / `usage.output_tokens`.
  */
 export class OpenAICliClient extends CliClient {
-    override name = 'openai';
-    override default_binary = 'codex';
     override subscription_label = 'chatgpt-plus';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1458,14 +1474,17 @@ export class OpenAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'openai', default_binary: 'codex' },
+        );
     }
 
     protected override _build_command(
@@ -1569,8 +1588,6 @@ export class OpenAICliClient extends CliClient {
  * stdin to dodge argv limits.
  */
 export class GeminiCliClient extends CliClient {
-    override name = 'gemini';
-    override default_binary = 'gemini';
     override subscription_label = 'gemini-pro';
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1581,14 +1598,17 @@ export class GeminiCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'gemini', default_binary: 'gemini' },
+        );
     }
 
     protected override _build_command(
@@ -1686,8 +1706,6 @@ export class GeminiCliClient extends CliClient {
  * heuristically (chars / 4) for the audit-trail.
  */
 export class XAICliClient extends CliClient {
-    override name = 'xai';
-    override default_binary = 'grok';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1698,14 +1716,17 @@ export class XAICliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_XAI_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_XAI_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'xai', default_binary: 'grok' },
+        );
     }
 
     protected override _build_command(
@@ -1752,8 +1773,6 @@ export class XAICliClient extends CliClient {
  * Invokes `perplexity -p <prompt>`. Output is plain text — no JSON envelope.
  */
 export class PerplexityCliClient extends CliClient {
-    override name = 'perplexity';
-    override default_binary = 'perplexity';
     override billable = true; // community CLI consumes an API key — billable applies
 
     static override _AUTH_FAILURE_PATTERNS: readonly string[] = [
@@ -1764,14 +1783,17 @@ export class PerplexityCliClient extends CliClient {
     ];
 
     constructor(opts: CliClientOptions = {}) {
-        super({
-            model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
-            binary: opts.binary,
-            timeout_seconds: opts.timeout_seconds,
-            max_calls_per_day: opts.max_calls_per_day,
-            warn_at: opts.warn_at,
-            cli_calls_path: opts.cli_calls_path,
-        });
+        super(
+            {
+                model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
+                binary: opts.binary,
+                timeout_seconds: opts.timeout_seconds,
+                max_calls_per_day: opts.max_calls_per_day,
+                warn_at: opts.warn_at,
+                cli_calls_path: opts.cli_calls_path,
+            },
+            { name: 'perplexity', default_binary: 'perplexity' },
+        );
     }
 
     protected override _build_command(