@event4u/agent-config 7.0.2 → 7.2.0

package/src/scripts/_lib/host_capability.ts

@@ -0,0 +1,59 @@
+/**
+ * Host-capability manifest normalizer.
+ *
+ * Pure, no-I/O helper that takes a partial / unknown object (typically the
+ * `subagents.host_capabilities` override from `.agent-settings.yml`, or the
+ * agent's own host-knowledge object) and returns a fully-populated manifest.
+ *
+ * Contract — see `src/agent-src/contexts/execution/host-capability-manifest.md`:
+ *
+ * - Safe default is ALL boolean fields `false` — an unknown host is assumed to
+ *   have no subagent primitive.
+ * - A missing or non-boolean field resolves to `false`, never `true`.
+ * - `schema_version` is always forced to `1`.
+ */
+
+/** Resolved host-capability manifest. All booleans, `schema_version` fixed at 1. */
+export interface HostCapabilityManifest {
+    schema_version: 1;
+    subagent_spawn: boolean;
+    parallel_spawn: boolean;
+    status_polling: boolean;
+    separate_quota_pool: boolean;
+}
+
+/** Safe default — unknown host assumes no subagent primitive. */
+const SAFE_DEFAULT: HostCapabilityManifest = {
+    schema_version: 1,
+    subagent_spawn: false,
+    parallel_spawn: false,
+    status_polling: false,
+    separate_quota_pool: false,
+};
+
+/** Coerce one field: only a strict boolean `true` survives; everything else is `false`. */
+function asBool(value: unknown): boolean {
+    return value === true;
+}
+
+/**
+ * Normalize a partial / unknown object into a full {@link HostCapabilityManifest}.
+ *
+ * Any missing or invalidly-typed field falls back to the all-`false` safe
+ * default; `schema_version` is always forced to `1`.
+ */
+export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
+    if (input === null || typeof input !== 'object') {
+        return { ...SAFE_DEFAULT };
+    }
+
+    const src = input as Record<string, unknown>;
+
+    return {
+        schema_version: 1,
+        subagent_spawn: asBool(src.subagent_spawn),
+        parallel_spawn: asBool(src.parallel_spawn),
+        status_polling: asBool(src.status_polling),
+        separate_quota_pool: asBool(src.separate_quota_pool),
+    };
+}

package/src/scripts/_lib/orchestration_gate.ts

@@ -0,0 +1,98 @@
+/**
+ * Default-flip decision gate (Phase 6).
+ *
+ * Pure, no-I/O. Encodes the Phase-6 falsification gate: the SHIPPED default for
+ * `subagents.auto` flips toward `on` ONLY when a real benchmark shows a net
+ * token-or-time win at held quality, and only on hosts with a subagent
+ * primitive. Honest-null exit (no win, or quality regressed) keeps the
+ * conservative default. Contract:
+ * `src/agent-src/contexts/execution/orchestration-benchmark-gate.md`.
+ *
+ * This helper decides; it never runs the benchmark. The measurement is the
+ * empirical bench:ab step, authorised + run out of band.
+ */
+
+export interface BenchmarkResult {
+    /** Net token OR wall-clock win on the delegable-task subset. */
+    net_win: boolean;
+    /** Output quality held at or above the single-agent baseline. */
+    quality_held: boolean;
+}
+
+export type GateVerdict = 'pass' | 'fail';
+export type ShippedDefault = 'on' | 'ask' | 'off';
+
+/** Gate verdict: pass requires BOTH a net win AND held quality. */
+export function gateVerdict(r: BenchmarkResult): GateVerdict {
+    return r.net_win && r.quality_held ? 'pass' : 'fail';
+}
+
+/**
+ * Resolve the shipped default for `subagents.auto` after a benchmark.
+ *
+ * - Gate fail (no win or quality regressed) → keep conservative: `ask` on a
+ *   subagent-capable host, `off` elsewhere (honest-null exit).
+ * - Gate pass → `on` on a subagent-capable host, `off` elsewhere.
+ *
+ * `host_subagent_spawn` gates the result so the default is never `on`/`ask`
+ * where the host cannot spawn at all.
+ */
+export function resolveShippedDefault(r: BenchmarkResult, host_subagent_spawn: boolean): ShippedDefault {
+    if (!host_subagent_spawn) return 'off';
+    return gateVerdict(r) === 'pass' ? 'on' : 'ask';
+}
+
+/**
+ * Recursive-verification gate (ADR-106).
+ *
+ * Decides whether `verification.recursive` ships on for a (host, family) cell.
+ * Pure, no-I/O — the measurement is the empirical bench:ab step. Encodes the
+ * council-locked two-branch rule: capability-only is NOT the gate, because it
+ * assumes (without measuring) that recursion's discipline lift is redundant
+ * with the always-on rules. The `D₂ − D₁` (recursion over rules-only) baseline
+ * makes redundancy a measured fact, gated behind a concrete cost ceiling and a
+ * human-preference pre-test. Contract:
+ * `docs/decisions/ADR-106-recursive-verification-benchmark-gate.md`.
+ */
+export interface RecursiveBenchmarkResult {
+    /** Capability-axis lift is significant (McNemar/scorer p<0.05, effect≥0.5). */
+    capability_lift_significant: boolean;
+    /** Novel discipline lift `D₂ − D₁` (recursion over rules-only) exceeds ε_disc. */
+    novel_discipline_lift_significant: boolean;
+    /** Per-task cost is within the concrete ceiling (token-multiplier / $). */
+    cost_within_ceiling: boolean;
+    /** Phase 3a-pre human-preference rate (fraction preferring the recursion output). */
+    human_preference_rate: number;
+}
+
+/** Human-preference floor from ADR-106: below this the discipline branch cannot pass. */
+export const RECURSIVE_HUMAN_PREFERENCE_FLOOR = 0.6;
+
+/**
+ * Gate verdict for recursive verification (ADR-106 two-branch rule):
+ *   pass iff  capability_lift_significant
+ *             OR (novel_discipline_lift_significant AND cost_within_ceiling
+ *                 AND human_preference_rate > floor)
+ * The human-preference test gates the discipline branch only — a capability
+ * lift passes on its own.
+ */
+export function recursiveGateVerdict(r: RecursiveBenchmarkResult): GateVerdict {
+    if (r.capability_lift_significant) return 'pass';
+    const disciplineBranch =
+        r.novel_discipline_lift_significant &&
+        r.cost_within_ceiling &&
+        r.human_preference_rate > RECURSIVE_HUMAN_PREFERENCE_FLOOR;
+    return disciplineBranch ? 'pass' : 'fail';
+}
+
+/**
+ * Resolve the shipped default for `verification.recursive`.
+ *
+ * Default stays `off` until a cell passes (ADR-106) — an honest-null keeps it
+ * `off`, never `ask`. `host_supported` gates the result so a host where
+ * recursion is not viable always resolves `off`.
+ */
+export function resolveRecursiveDefault(r: RecursiveBenchmarkResult, host_supported: boolean): ShippedDefault {
+    if (!host_supported) return 'off';
+    return recursiveGateVerdict(r) === 'pass' ? 'on' : 'off';
+}

package/src/scripts/_lib/subagent_bundle.ts

@@ -0,0 +1,154 @@
+/**
+ * Subagent bundle resolver (Phase 2 / A2).
+ *
+ * Pure, no-I/O. Maps a task slice to a concrete subagent bundle by selecting
+ * from the EXISTING surfaces — role-modes, the `judge-*` review-lens skills,
+ * personas, knowledge-card refs, and an ADR-035 tier — instead of a new parallel
+ * registry. Feeds `composeSpawnBrief` (subagent_spawn.ts) real values.
+ *
+ * Contract: `src/agent-src/contexts/execution/subagent-spawn-contract.md`.
+ *
+ * ADR-100 guard: proprietary knowledge-card refs never enter a cross-project
+ * subagent bundle. The resolver drops them and records the drop.
+ */
+
+import type { RoleMode, SpawnSelection } from './subagent_spawn.js';
+
+export type Tier = 'lite' | 'medium' | 'high' | 'inherit';
+
+/** The well-known delegable slice kinds and their lens/role/tier mapping. */
+export type SliceKind =
+    | 'review'
+    | 'security'
+    | 'tests'
+    | 'bug-hunt'
+    | 'research'
+    | 'docs'
+    | 'refactor'
+    | 'plan';
+
+interface KindProfile {
+    /** Reuse a `judge-*` skill as a ready-made subagent role-profile, or null. */
+    judge_lens: string | null;
+    role_mode: RoleMode | null;
+    tier: Tier;
+}
+
+/**
+ * Slice-kind → bundle profile. The `judge-*` skills are reused as subagent
+ * role-profiles (the package already ships them as review lenses).
+ */
+const KIND_PROFILE: Record<SliceKind, KindProfile> = {
+    review: { judge_lens: 'judge-code-quality', role_mode: 'reviewer', tier: 'medium' },
+    security: { judge_lens: 'judge-security-auditor', role_mode: 'reviewer', tier: 'high' },
+    tests: { judge_lens: 'judge-test-coverage', role_mode: 'tester', tier: 'medium' },
+    'bug-hunt': { judge_lens: 'judge-bug-hunter', role_mode: 'developer', tier: 'medium' },
+    research: { judge_lens: null, role_mode: null, tier: 'lite' },
+    docs: { judge_lens: null, role_mode: null, tier: 'lite' },
+    refactor: { judge_lens: null, role_mode: 'developer', tier: 'high' },
+    plan: { judge_lens: null, role_mode: 'planner', tier: 'high' },
+};
+
+/** A knowledge-card ref tagged with its sharing tier (ADR-100). */
+export interface KnowledgeRef {
+    ref: string;
+    tier: 'public' | 'vendor' | 'proprietary';
+}
+
+export interface SliceInput {
+    kind: SliceKind;
+    task: string;
+    /** Active profile id (e.g. 'developer'), inherited from the session unless overridden. */
+    profile?: string | null;
+    /** Persona ids cited by the task's skill. */
+    personas?: string[];
+    /** Candidate knowledge-card refs (tier-tagged) for this slice. */
+    knowledge?: KnowledgeRef[];
+    /** Will this bundle be visible across project boundaries? */
+    cross_project?: boolean;
+}
+
+export interface ResolvedBundle {
+    selection: SpawnSelection;
+    judge_lens: string | null;
+    tier: Tier;
+    dropped_proprietary: number;
+    reason: string;
+}
+
+/**
+ * ADR-100 guard: keep refs whose tier is shareable in the bundle's visibility
+ * scope. In a cross-project bundle, `proprietary` refs are dropped.
+ */
+export function filterKnowledgeByPolicy(
+    knowledge: KnowledgeRef[],
+    cross_project: boolean,
+): { kept: string[]; dropped: number } {
+    const kept: string[] = [];
+    let dropped = 0;
+    for (const k of knowledge) {
+        if (cross_project && k.tier === 'proprietary') {
+            dropped += 1;
+            continue;
+        }
+        kept.push(k.ref);
+    }
+    return { kept, dropped };
+}
+
+/**
+ * Resolve a task slice into a subagent bundle: role-mode + reused judge lens +
+ * personas + ADR-100-filtered knowledge refs + tier. The result's `selection`
+ * is ready for `composeSpawnBrief`.
+ */
+export function resolveBundle(slice: SliceInput): ResolvedBundle {
+    const profile = KIND_PROFILE[slice.kind];
+    const cross = slice.cross_project === true;
+    const { kept, dropped } = filterKnowledgeByPolicy(slice.knowledge ?? [], cross);
+
+    // The reused judge lens rides as a persona-equivalent so the subagent loads it.
+    const personas = [...(slice.personas ?? [])];
+    if (profile.judge_lens && !personas.includes(profile.judge_lens)) {
+        personas.unshift(profile.judge_lens);
+    }
+
+    const selection: SpawnSelection = {
+        task: slice.task,
+        role_mode: profile.role_mode,
+        profile: slice.profile ?? null,
+        personas,
+        knowledge_refs: kept,
+    };
+
+    const reasonParts = [`kind=${slice.kind}`, `tier=${profile.tier}`];
+    if (profile.judge_lens) reasonParts.push(`lens=${profile.judge_lens}`);
+    if (dropped > 0) reasonParts.push(`dropped ${dropped} proprietary (cross-project)`);
+
+    return {
+        selection,
+        judge_lens: profile.judge_lens,
+        tier: profile.tier,
+        dropped_proprietary: dropped,
+        reason: reasonParts.join(' · '),
+    };
+}
+
+/**
+ * Auditable bundle signature for the orchestration-telemetry object — counts +
+ * ids only, never bodies (preserves the audit-log privacy floor).
+ */
+export function bundleAuditLine(b: ResolvedBundle): {
+    role_mode: RoleMode | null;
+    judge_lens: string | null;
+    tier: Tier;
+    knowledge_ref_count: number;
+    dropped_proprietary: number;
+} {
+    return {
+        role_mode: b.selection.role_mode ?? null,
+        judge_lens: b.judge_lens,
+        tier: b.tier,
+        knowledge_ref_count: b.selection.knowledge_refs?.length ?? 0,
+        dropped_proprietary: b.dropped_proprietary,
+    };
+}

package/src/scripts/_lib/subagent_response.ts

@@ -0,0 +1,82 @@
+/**
+ * Structured subagent-response envelope + synthesis helpers (Phase 3 / A3).
+ *
+ * Pure, no-I/O. Pins the body a subagent returns inside the 4-status envelope
+ * (the status stays the envelope; this is the body) and gives the orchestrator
+ * the synthesis duties: surface evidence gaps, and force the full cross-model
+ * judge when a mutating finding is low-confidence.
+ *
+ * Contract: `src/agent-src/contexts/execution/subagent-response-contract.md`.
+ */
+
+export type Confidence = 'low' | 'medium' | 'high';
+
+export interface Finding {
+    title: string;
+    /** Refs (file:line / id / path) backing this finding — never inline bodies. */
+    evidence_refs?: string[];
+    /** Does acting on this finding mutate files / state? */
+    mutating?: boolean;
+}
+
+export interface SubagentResponse {
+    summary: string;
+    findings: Finding[];
+    risks: string[];
+    confidence: Confidence;
+    handoff: string;
+}
+
+const CONFIDENCE: ReadonlySet<string> = new Set<Confidence>(['low', 'medium', 'high']);
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+
+/** Validate the envelope shape. Counts/refs only — reject inline-body evidence. */
+export function validateResponse(input: unknown): ValidationResult {
+    const errors: string[] = [];
+    if (input === null || typeof input !== 'object') {
+        return { valid: false, errors: ['response is not an object'] };
+    }
+    const r = input as Record<string, unknown>;
+    if (typeof r.summary !== 'string') errors.push('summary missing or not a string');
+    if (typeof r.handoff !== 'string') errors.push('handoff missing or not a string');
+    if (!CONFIDENCE.has(r.confidence as string)) errors.push(`confidence must be low|medium|high (got ${String(r.confidence)})`);
+    if (!Array.isArray(r.findings)) errors.push('findings missing or not an array');
+    if (!Array.isArray(r.risks)) errors.push('risks missing or not an array');
+    if (Array.isArray(r.findings)) {
+        for (const [i, f] of (r.findings as Finding[]).entries()) {
+            if (!f || typeof f.title !== 'string') errors.push(`finding[${i}] missing title`);
+            const refs = f?.evidence_refs;
+            if (refs && refs.some((x) => typeof x !== 'string' || x.includes('\n'))) {
+                errors.push(`finding[${i}] evidence_refs must be ref tokens, not bodies`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Synthesis gaps the orchestrator must resolve before adopting the response:
+ * a finding with no evidence ref is an unbacked claim to re-check.
+ */
+export function synthesisGaps(response: SubagentResponse): string[] {
+    const gaps: string[] = [];
+    for (const f of response.findings) {
+        if (!f.evidence_refs || f.evidence_refs.length === 0) {
+            gaps.push(`finding "${f.title}" has no evidence — re-check before adopting`);
+        }
+    }
+    return gaps;
+}
+
+/**
+ * Confidence → verify-budget link. A mutating finding returned at `low`
+ * confidence forces the full cross-model judge (no deterministic-only pass).
+ * Returns true when the full judge is mandatory for this finding.
+ */
+export function forcesJudge(f: Finding, confidence: Confidence): boolean {
+    return f.mutating === true && confidence === 'low';
+}

package/src/scripts/_lib/subagent_routing.ts

@@ -0,0 +1,81 @@
+/**
+ * Subagent routing (Phase 2) — cost/speed downshift + optional quota arbitrage.
+ *
+ * Pure, no-I/O, VENDOR-NEUTRAL. Resolves which model a delegated sub-task runs
+ * on, from the sub-task's declared capability tier, the `subagents.*` settings,
+ * and the host-capability manifest. Contract:
+ * `src/agent-src/contexts/execution/subagent-routing.md`.
+ *
+ * Invariants:
+ * - The orchestrator stays on the session/high tier (this resolves SUB-tasks).
+ * - Downshift off → every sub-task runs on the session tier.
+ * - Downshift on → a sub-task runs on the lowest-capable tier it declares.
+ * - Quota arbitrage is an OPTIONAL bonus: it only prefers the separate pool
+ *   when BOTH the setting and the host manifest allow it. Where unsupported,
+ *   routing is identical minus the quota win — never a hard-coded vendor model.
+ */
+
+export type Tier = 'lite' | 'medium' | 'high' | 'inherit';
+export type QuotaPool = 'separate' | 'shared';
+
+/** Per-tier model alias overrides (empty string = use the tier's runtime default). */
+export interface ModelMap {
+    lite?: string;
+    medium?: string;
+    high?: string;
+}
+
+export interface RoutingInputs {
+    /** The sub-task's declared capability tier. */
+    task_tier: Tier;
+    /** The orchestrator's session tier (used when downshift is off / tier is inherit). */
+    session_tier: Tier;
+    downshift: boolean;
+    quota_arbitrage: boolean;
+    model_map: ModelMap;
+    /** From the host-capability manifest. */
+    separate_quota_pool: boolean;
+}
+
+export interface RoutingDecision {
+    /** Resolved tier the sub-task runs on. */
+    tier: Tier;
+    /** Model alias, or '' meaning "use the tier's runtime default" (no vendor name baked in). */
+    model: string;
+    /** Whether a separate quota pool is used (bonus) or the shared one. */
+    quota_pool: QuotaPool;
+    reason: string;
+}
+
+/** Resolve a model alias for a tier from the map; '' = tier default sentinel. */
+function modelForTier(tier: Tier, map: ModelMap): string {
+    if (tier === 'lite') return map.lite ?? '';
+    if (tier === 'medium') return map.medium ?? '';
+    if (tier === 'high') return map.high ?? '';
+    return ''; // inherit → session default
+}
+
+/**
+ * Resolve routing for one delegated sub-task. Vendor-neutral: returns a tier +
+ * an optional model alias (never a hard-coded provider model) + the quota pool.
+ */
+export function resolveSubagentRouting(inp: RoutingInputs): RoutingDecision {
+    // Downshift off, or an `inherit` task → run on the session tier.
+    const tier: Tier = !inp.downshift || inp.task_tier === 'inherit' ? inp.session_tier : inp.task_tier;
+    const downshifted = inp.downshift && inp.task_tier !== 'inherit' && tier !== inp.session_tier;
+
+    // Quota arbitrage: a bonus, only when BOTH the setting and the host allow it.
+    const useSeparate = inp.quota_arbitrage && inp.separate_quota_pool;
+    const quota_pool: QuotaPool = useSeparate ? 'separate' : 'shared';
+
+    const reasonParts: string[] = [];
+    reasonParts.push(downshifted ? `downshift to ${tier}` : `session tier ${tier}`);
+    reasonParts.push(useSeparate ? 'separate quota pool (bonus)' : 'shared quota pool');
+
+    return {
+        tier,
+        model: modelForTier(tier, inp.model_map),
+        quota_pool,
+        reason: reasonParts.join(' · '),
+    };
+}

package/src/scripts/_lib/subagent_spawn.ts

@@ -0,0 +1,97 @@
+/**
+ * Subagent spawn-brief composition (Phase 3) — task-optimal configuration.
+ *
+ * Pure, no-I/O. Composes a subagent's brief from the existing config seams —
+ * role-mode + profile + persona(s) + a MINIMAL knowledge slice — so each
+ * subagent is configured for its task. Contract:
+ * `src/agent-src/contexts/execution/subagent-spawn-contract.md`.
+ *
+ * Hard invariant (lethal-trifecta-guard): knowledge is passed as a small set of
+ * REFERENCES, never as inline bodies, and is capped. Never bulk-dump context
+ * into a subagent — keep the private-data leg narrow.
+ */
+
+export type RoleMode = 'developer' | 'reviewer' | 'tester' | 'po' | 'incident' | 'planner';
+
+const ROLE_MODES: ReadonlySet<string> = new Set<RoleMode>([
+    'developer',
+    'reviewer',
+    'tester',
+    'po',
+    'incident',
+    'planner',
+]);
+
+/** Max knowledge slice refs handed to one subagent (minimal-slice cap). */
+export const MAX_KNOWLEDGE_REFS = 5;
+/** Max personas overlaid on one subagent. */
+export const MAX_PERSONAS = 2;
+
+export interface SpawnSelection {
+    task: string;
+    /** Role-mode contract the subagent runs under, or null for none. */
+    role_mode?: RoleMode | null;
+    /** Active profile id (e.g. 'developer', 'content_creator'), or null. */
+    profile?: string | null;
+    /** Persona ids (review lenses) cited by the task's skill, capped. */
+    personas?: string[];
+    /** Knowledge slice REFERENCES (ids / paths) — never inline bodies. */
+    knowledge_refs?: string[];
+}
+
+export interface SpawnBrief {
+    task: string;
+    role_mode: RoleMode | null;
+    profile: string | null;
+    personas: string[];
+    knowledge_refs: string[];
+    warnings: string[];
+}
+
+/** A ref is acceptable only if it looks like an id/path token, not a body. */
+function isRefLike(s: unknown): s is string {
+    return typeof s === 'string' && s.length > 0 && s.length <= 200 && !s.includes('\n');
+}
+
+/**
+ * Compose a validated spawn brief. Invalid role-mode → dropped to null;
+ * personas capped at {@link MAX_PERSONAS}; knowledge refs filtered to
+ * ref-like tokens and capped at {@link MAX_KNOWLEDGE_REFS}. Anything dropped is
+ * recorded in `warnings` (surfaced, never silent).
+ */
+export function composeSpawnBrief(sel: SpawnSelection): SpawnBrief {
+    const warnings: string[] = [];
+
+    let role_mode: RoleMode | null = null;
+    if (sel.role_mode != null) {
+        if (ROLE_MODES.has(sel.role_mode)) role_mode = sel.role_mode;
+        else warnings.push(`unknown role_mode '${sel.role_mode}' dropped`);
+    }
+
+    const personasIn = sel.personas ?? [];
+    let personas = personasIn.filter((p) => typeof p === 'string' && p.length > 0);
+    if (personas.length > MAX_PERSONAS) {
+        warnings.push(`personas capped ${personas.length} → ${MAX_PERSONAS}`);
+        personas = personas.slice(0, MAX_PERSONAS);
+    }
+
+    const refsIn = sel.knowledge_refs ?? [];
+    const bodyLike = refsIn.filter((r) => !isRefLike(r));
+    if (bodyLike.length > 0) {
+        warnings.push(`${bodyLike.length} non-ref knowledge entr${bodyLike.length === 1 ? 'y' : 'ies'} rejected (refs only, no bodies)`);
+    }
+    let knowledge_refs = refsIn.filter(isRefLike);
+    if (knowledge_refs.length > MAX_KNOWLEDGE_REFS) {
+        warnings.push(`knowledge refs capped ${knowledge_refs.length} → ${MAX_KNOWLEDGE_REFS}`);
+        knowledge_refs = knowledge_refs.slice(0, MAX_KNOWLEDGE_REFS);
+    }
+
+    return {
+        task: sel.task,
+        role_mode,
+        profile: sel.profile ?? null,
+        personas,
+        knowledge_refs,
+        warnings,
+    };
+}

package/src/scripts/_lib/subagent_steering.ts

@@ -0,0 +1,64 @@
+/**
+ * Subagent steering & guardrails (Phase 5).
+ *
+ * Pure, no-I/O. The guardrails that keep auto-dispatch from becoming a token
+ * sink: the N=3 per-target budget, the kill-switch, and the rollback
+ * guardrail-threshold checks. Contract:
+ * `src/agent-src/contexts/execution/subagent-steering.md`.
+ *
+ * Automatic cohort-level disable is OUT OF SCOPE — a config package runs no
+ * daemon. Breaches are surfaced for the maintainer/user to act on; the only
+ * automatic stop is the per-target N=3 budget.
+ */
+
+/** Max consecutive failed attempts on one validation target before halting. */
+export const MAX_ATTEMPTS_PER_TARGET = 3;
+
+/** Rollback guardrail thresholds (council-defined). */
+export const GUARDRAILS = {
+    /** Token spend vs single-agent baseline. */
+    token_blowup_ratio: 2,
+    /** Subagent spawn-failure rate. */
+    spawn_failure_rate: 0.1,
+    /** Fraction of dispatches that completed without a required verification. */
+    verify_skip_rate: 0.01,
+    /** Fraction of users manually disabling the layer. */
+    user_override_rate: 0.3,
+} as const;
+
+export interface LayerState {
+    enabled: boolean;
+    auto: 'off' | 'ask' | 'on';
+}
+
+/** The kill-switch: layer is disabled when the master switch is off or auto is off. */
+export function isLayerDisabled(state: LayerState): boolean {
+    return !state.enabled || state.auto === 'off';
+}
+
+/** N=3 per-target budget: halt once consecutive failed attempts reach the cap. */
+export function budgetHalt(consecutiveFailures: number): boolean {
+    return consecutiveFailures >= MAX_ATTEMPTS_PER_TARGET;
+}
+
+export interface GuardrailMetrics {
+    /** Observed token spend / single-agent baseline (e.g. 2.4 = 2.4x). */
+    token_ratio: number;
+    spawn_failure_rate: number;
+    verify_skip_rate: number;
+    user_override_rate: number;
+}
+
+/**
+ * Evaluate the rollback guardrails. Returns the list of breached threshold
+ * names (empty = all clear). The orchestrator surfaces a non-empty result —
+ * it does NOT auto-disable (no daemon); the maintainer/user decides.
+ */
+export function breachedGuardrails(m: GuardrailMetrics): string[] {
+    const breached: string[] = [];
+    if (m.token_ratio > GUARDRAILS.token_blowup_ratio) breached.push('token_blowup');
+    if (m.spawn_failure_rate > GUARDRAILS.spawn_failure_rate) breached.push('spawn_failure');
+    if (m.verify_skip_rate > GUARDRAILS.verify_skip_rate) breached.push('verify_skip');
+    if (m.user_override_rate > GUARDRAILS.user_override_rate) breached.push('user_override');
+    return breached;
+}