aiden-runtime 4.1.5 → 4.5.0

package/dist/core/v4/recoveryReport.js

@@ -0,0 +1,449 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/recoveryReport.ts — v4.2 Phase 3: Evidence Output +
+ * RecoveryReport.
+ *
+ * Pure synthesis. Consumes a TurnStateDiagnosticSnapshot (populated by
+ * Phase 1's verifier + Phase 2's classifier records) and produces a
+ * structured RecoveryReport that captures what the agent tried, what
+ * failed, why, what was recovered, and what's next.
+ *
+ * Surfaced ONLY when the TurnState recovery controller reaches the
+ * `surfaced` stage — quiet by design on hint/cooldown turns where the
+ * model self-corrects without user intervention. The report enriches
+ * the existing v4.1.6 tool_loop capability card by attaching summary
+ * lines (whatHappened) and a category breakdown (failuresByCategory).
+ *
+ * Reference notes: a comparable reference system's failure surface is
+ * text-only metadata (flat dict + appended guidance strings). Aiden's
+ * structured report is genuinely new — no patterns to port, but the
+ * single-source-of-truth synthesis approach mirrors the reference's
+ * `to_metadata()` style.
+ *
+ * Phase 3 stays consume-only: no changes to TurnState, verifier, or
+ * failureClassifier. Imports flow downstream (recoveryReport depends
+ * on TurnState's snapshot type and failureClassifier's category enum).
+ *
+ * Pure module — no I/O, no async, no side effects. Easy to unit test
+ * with synthetic snapshots.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractGoal = extractGoal;
+exports.guidanceFor = guidanceFor;
+exports.buildRecoveryReport = buildRecoveryReport;
+exports.enrichCardWithReport = enrichCardWithReport;
+// ── Goal extraction ────────────────────────────────────────────────────────
+const MAX_GOAL_CHARS = 140;
+/**
+ * Pull the first user message from the conversation as the turn's
+ * goal. Handles three shapes:
+ *   - string content (the common path)
+ *   - ContentBlock[] content (Anthropic structured shape) — concatenates
+ *     text blocks; ignores tool_use / image blocks
+ *   - missing user message — returns empty string
+ *
+ * Result truncated to MAX_GOAL_CHARS with ellipsis to keep the report
+ * line bounded.
+ */
+function extractGoal(messages) {
+    const firstUser = messages.find((m) => m.role === 'user');
+    if (!firstUser)
+        return '';
+    const raw = stringifyContent(firstUser.content);
+    const trimmed = raw.trim();
+    if (trimmed.length <= MAX_GOAL_CHARS)
+        return trimmed;
+    return trimmed.slice(0, MAX_GOAL_CHARS - 3) + '...';
+}
+function stringifyContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (block && typeof block === 'object') {
+                const b = block;
+                if (typeof b.text === 'string')
+                    parts.push(b.text);
+                else if (b.type === 'text' && typeof b.text === 'string')
+                    parts.push(b.text);
+            }
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+// ── Guidance map ───────────────────────────────────────────────────────────
+const GUIDANCE_BY_CATEGORY = {
+    permission: 'Adjust permissions or surface this to the user — the tool refused, so retrying without changes will not help.',
+    auth: 'Provide credentials before retrying — the tool needs auth that has not been supplied.',
+    timeout: 'Network or tool deadline exceeded. Retry with a longer budget or check connectivity.',
+    dependency_missing: 'A required binary or service is not available. Install it or use a different approach.',
+    rate_limit: 'Upstream rate-limited the call. Wait a moment and retry, or rotate to a different credential.',
+    network: 'Network unreachable or DNS failure. Check the connection and retry once it is stable.',
+    invalid_input: 'The tool arguments were rejected. Re-read the tool schema and fix the arguments before retrying.',
+    hallucination: 'The model used a path or name that does not exist. Re-read the surrounding state before retrying.',
+    not_found: 'The target resource was not found. Verify the path or name and try again with a corrected value.',
+    stale_ref: 'The page changed between snapshot and action. The observer already attempted resnapshot+retry once — re-read the visible state and try a different selector or approach.',
+    manual_blocker: 'The site requires a human action (login, 2FA, captcha, or verification). Surface this to the user and wait — do not retry automatically.',
+    sandbox_violation: 'Aiden\'s execution sandbox refused this operation. Surface the matched policy to the user and either widen the allowlist via AIDEN_SANDBOX_ALLOW=path1:path2 or disable the sandbox with AIDEN_SANDBOX=0 (not recommended). Denylist matches cannot be overridden — they signal sensitive paths the user explicitly wants protected.',
+    trigger_misconfigured: 'The trigger spec is invalid or its prompt template references variables the payload does not supply. Inspect the trigger via `aiden trigger list` and fix the spec — retrying without changes will produce the same failure.',
+    trigger_quota: 'The trigger\'s per-source fire-rate cap was hit. Investigate the upstream producer (file watcher loop, runaway webhook caller, mis-scheduled cron) or raise the fire_rate_limit on the trigger spec.',
+    trigger_dead_lettered: 'The trigger event exceeded its retry budget and moved to the dead-letter queue. Review the last_error on the trigger event row and either fix the root cause + re-queue, or accept the event as lost.',
+    other: 'The tool failed for an unclassified reason. Inspect the trace for details before retrying.',
+};
+/** Public for tests + plugin extensions. */
+function guidanceFor(category) {
+    return GUIDANCE_BY_CATEGORY[category] ?? GUIDANCE_BY_CATEGORY.other;
+}
+/**
+ * Pure function. Given the per-turn diagnostic snapshot plus three
+ * scalar inputs, produces a deterministic RecoveryReport. No I/O,
+ * no async, no Date.now() — all timestamps come from the snapshot
+ * or are passed explicitly.
+ */
+function buildRecoveryReport(input) {
+    const { snapshot, goal, exitReason, durationMs } = input;
+    // ── Attempts ────────────────────────────────────────────────────────────
+    // Total = every recorded tool call (toolCalls array).
+    // Succeeded = verifications with ok=true.
+    // Failed   = verifications with ok=false.
+    //
+    // Note: total may exceed succeeded+failed when callers run without
+    // a verification (verifier disabled or threw). The arithmetic
+    // tolerates that — the counters report exactly what's recorded.
+    const total = snapshot.toolCalls.length;
+    const succeeded = snapshot.verifications.filter((v) => v.verification.ok).length;
+    const failed = snapshot.verifications.filter((v) => !v.verification.ok).length;
+    // ── Failure breakdown ───────────────────────────────────────────────────
+    const breakdown = {};
+    for (const entry of snapshot.classifications) {
+        const cat = entry.classification.category;
+        breakdown[cat] = (breakdown[cat] ?? 0) + 1;
+    }
+    // ── Failed tools (latest classification per tool name) ──────────────────
+    // Iterate forward; later entries overwrite earlier ones, so the
+    // resulting map holds the most recent classification per name.
+    const latestByName = new Map();
+    for (const entry of snapshot.classifications) {
+        latestByName.set(entry.name, {
+            name: entry.name,
+            category: entry.classification.category,
+            reason: entry.classification.reason,
+            confidence: entry.classification.confidence,
+        });
+    }
+    const failedTools = [...latestByName.values()];
+    // ── Recovery stages (passthrough — already ordered by recordToolCall) ──
+    const recoveryStages = snapshot.recoveryEvents.map((e) => ({
+        stage: e.stage,
+        toolName: e.toolName,
+        count: e.count,
+    }));
+    // ── Guidance — dominant failure category ────────────────────────────────
+    const guidance = synthesizeGuidance(breakdown);
+    // ── v4.3 Phase 5 — browserContext enrichment ────────────────────────────
+    // Populated when an optional BrowserStateLike is provided AND it
+    // reports at least one tab. Counts stale-ref retries from the
+    // recoveryStages signal indirectly — Phase 2's auto-retry fires
+    // via the HOC, not TurnState's recovery state machine, so we look
+    // for retried classifications in the snapshot instead.
+    const browserContext = buildBrowserContext(input.browserState, snapshot);
+    // ── v4.4 Phase 5 — sandboxContext enrichment ────────────────────────────
+    // Populated when any classification this turn has category
+    // `sandbox_violation`. The classifier (Phase 5) attaches the raw
+    // envelope to ClassificationResult.sandboxViolation, so we don't
+    // re-parse tool results here.
+    const sandboxContext = buildSandboxContext(snapshot);
+    // ── v4.5 Phase 5a — triggerContext passthrough ─────────────────────────
+    // The dispatcher hands the context in directly; this module just
+    // attaches it to the report shape without re-deriving fields. Keeps
+    // the report module decoupled from the daemon dispatcher.
+    const triggerContext = input.triggerContext;
+    return {
+        goal,
+        exitReason,
+        durationMs,
+        attempts: { total, succeeded, failed },
+        failureBreakdown: breakdown,
+        failedTools,
+        successfulTools: [...snapshot.successfulTools],
+        recoveryStages,
+        guidance,
+        ...(browserContext ? { browserContext } : {}),
+        ...(sandboxContext ? { sandboxContext } : {}),
+        ...(triggerContext ? { triggerContext } : {}),
+    };
+}
+/**
+ * v4.4 Phase 5 — build the `sandboxContext` sidecar from the turn's
+ * classifications. Returns null when no `sandbox_violation` fired
+ * (the common path).
+ *
+ * Aggregates FS vs shell violation counts (FS = code starts with
+ * `fs.`; shell = anything else under the sandbox_violation category)
+ * and surfaces the most recent envelope's matched policy +
+ * auto-derived override suggestion.
+ */
+function buildSandboxContext(snapshot) {
+    const violations = snapshot.classifications.filter((c) => c.classification.category === 'sandbox_violation');
+    if (violations.length === 0)
+        return null;
+    const last = violations[violations.length - 1].classification;
+    const lastCode = last.matchedPattern ?? last.sandboxViolation?.code ?? '';
+    let fsViolations = 0;
+    let shellViolations = 0;
+    for (const v of violations) {
+        const code = v.classification.matchedPattern
+            ?? v.classification.sandboxViolation?.code
+            ?? '';
+        if (code.startsWith('fs.'))
+            fsViolations += 1;
+        else
+            shellViolations += 1;
+    }
+    const ctx = {
+        violationCount: violations.length,
+        fsViolations,
+        shellViolations,
+        lastCode,
+        lastMatched: last.sandboxViolation?.matchedPolicy ?? '',
+    };
+    if (last.sandboxViolation?.requestedPath) {
+        ctx.lastRequested = last.sandboxViolation.requestedPath;
+    }
+    if (last.recoveryHint?.detail) {
+        ctx.suggestedEnv = last.recoveryHint.detail;
+    }
+    return ctx;
+}
+/**
+ * v4.3 Phase 5 — build the `browserContext` sidecar from an optional
+ * BrowserStateLike + diagnostic snapshot. Returns null when no tabs
+ * exist (opt-out via AIDEN_BROWSER_DEPTH=0 or no browser action
+ * this turn) so
+ * the caller can decide whether to include the field.
+ *
+ * Stale-ref retry count derives from classifications with category
+ * `stale_ref` — Phase 5's classifier produces those when Phase 2's
+ * HOC-level retry attempted but failed. Successful retries don't
+ * appear in classifications (their final result has `success:true`).
+ */
+function buildBrowserContext(browserState, snapshot) {
+    if (!browserState)
+        return null;
+    const tabs = browserState.getTabs();
+    if (tabs.length === 0)
+        return null;
+    const active = browserState.getActiveTab();
+    const otherTabCount = active
+        ? tabs.filter((t) => !t.is_active).length
+        : tabs.length;
+    // Count stale_ref classifications recorded by Phase 5's browser
+    // classifier in the turn's classifications log.
+    const staleRefRetries = snapshot.classifications.filter((c) => c.classification.category === 'stale_ref').length;
+    const ctx = {
+        otherTabCount,
+        staleRefRetries,
+    };
+    if (active?.url)
+        ctx.activeTabUrl = active.url;
+    if (active?.title)
+        ctx.activeTabTitle = active.title;
+    if (active?.last_blocker)
+        ctx.activeBlocker = active.last_blocker.kind;
+    return ctx;
+}
+/**
+ * Pick the most-frequent failure category and return its guidance
+ * string. Ties broken by category priority (more recoverable first):
+ * timeout > rate_limit > network > invalid_input > not_found >
+ * hallucination > dependency_missing > permission > auth > other.
+ *
+ * No failures recorded → returns the generic `other` guidance.
+ */
+function synthesizeGuidance(breakdown) {
+    const entries = Object.entries(breakdown);
+    if (entries.length === 0)
+        return GUIDANCE_BY_CATEGORY.other;
+    const PRIORITY = [
+        'timeout', 'rate_limit', 'network', 'invalid_input',
+        'not_found',
+        'stale_ref', // v4.3 Phase 5 — auto-recoverable via wait+retry
+        'hallucination', 'dependency_missing',
+        'manual_blocker', // v4.3 Phase 5 — requires human action; semi-blocking
+        'sandbox_violation', // v4.4 Phase 5 — env-var override is the specific user action
+        'trigger_misconfigured', // v4.5 Phase 5a — trigger spec fix required
+        'trigger_quota', // v4.5 Phase 5a — anti-thrash, producer/cap fix
+        'trigger_dead_lettered', // v4.5 Phase 5a — terminal; re-queue or accept loss
+        'permission', 'auth', 'other',
+    ];
+    const rank = (c) => {
+        const i = PRIORITY.indexOf(c);
+        return i === -1 ? PRIORITY.length : i;
+    };
+    entries.sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1]; // desc by count
+        return rank(a[0]) - rank(b[0]); // tie → priority rank asc
+    });
+    return GUIDANCE_BY_CATEGORY[entries[0][0]];
+}
+// ── Card enrichment ────────────────────────────────────────────────────────
+/**
+ * Take a base CapabilityCardData (typically from TurnState's surface
+ * card) and overlay the RecoveryReport's summary lines. Returns a new
+ * card object — the base is not mutated. When report is undefined,
+ * returns the base unchanged.
+ *
+ * Three additions:
+ *   - whatHappened: one-line summary string with attempt counts +
+ *     duration (rendered above canStill section).
+ *   - failuresByCategory: inline pill row of non-zero category counts,
+ *     ordered by descending count then priority.
+ *   - fix: replaced with the report's guidance text (one sentence,
+ *     dominant-category aware).
+ *
+ * The base card's title / canStill / cannotReliably pass through.
+ */
+function enrichCardWithReport(base, report) {
+    const whatHappened = buildWhatHappenedLine(report);
+    const failuresByCategory = buildFailuresPills(report.failureBreakdown);
+    // v4.3 Phase 5 — browser-context inline row. Only present when the
+    // report carries browserContext (which requires an active BrowserState
+    // with tabs). Renderer treats this as a single-line muted addition
+    // below whatHappened.
+    const browserContext = report.browserContext
+        ? buildBrowserContextLine(report.browserContext)
+        : undefined;
+    // v4.4 Phase 5 — sandbox-context inline row. Present when the
+    // report carries sandboxContext (any sandbox_violation this turn).
+    // Renderer surfaces this as another muted line right below
+    // browserContext (or whatHappened when no browser activity).
+    const sandboxContext = report.sandboxContext
+        ? buildSandboxContextLine(report.sandboxContext)
+        : undefined;
+    // v4.5 Phase 5a — trigger-context inline row. Present when the
+    // run was fired from the daemon trigger bus. Surfaces below
+    // browser/sandbox lines so the operator sees the trigger
+    // identity + attempt count at-a-glance.
+    const triggerContext = report.triggerContext
+        ? buildTriggerContextLine(report.triggerContext)
+        : undefined;
+    return {
+        title: base.title,
+        canStill: base.canStill,
+        cannotReliably: base.cannotReliably,
+        fix: report.guidance,
+        whatHappened,
+        failuresByCategory,
+        ...(browserContext ? { browserContext } : {}),
+        ...(sandboxContext ? { sandboxContext } : {}),
+        ...(triggerContext ? { triggerContext } : {}),
+    };
+}
+/**
+ * v4.5 Phase 5a — format the triggerContext fields into a compact
+ * single-line summary for the recovery card. Mirrors
+ * `buildBrowserContextLine` / `buildSandboxContextLine` shape.
+ * Returns empty string only when no signal worth surfacing
+ * (defensive — the dispatcher always sets the core fields).
+ */
+function buildTriggerContextLine(ctx) {
+    const parts = [];
+    parts.push(`${ctx.source}/${ctx.triggerId}`);
+    parts.push(`attempt ${ctx.attempt}/${ctx.maxAttempts}`);
+    if (ctx.promptTemplateUsed)
+        parts.push('templated');
+    if (ctx.fireReason && ctx.fireReason !== 'trigger_fired') {
+        parts.push(`reason=${ctx.fireReason}`);
+    }
+    return parts.length > 0 ? `Trigger: ${parts.join(' · ')}` : '';
+}
+/**
+ * v4.3 Phase 5 — format the browserContext fields into a compact
+ * single-line summary for the recovery card. Returns empty string
+ * when no signal worth surfacing.
+ */
+function buildBrowserContextLine(ctx) {
+    const parts = [];
+    if (ctx.activeTabUrl) {
+        try {
+            parts.push(`active=${new URL(ctx.activeTabUrl).hostname || ctx.activeTabUrl}`);
+        }
+        catch {
+            parts.push(`active=${ctx.activeTabUrl}`);
+        }
+    }
+    if (ctx.activeBlocker)
+        parts.push(`${ctx.activeBlocker} blocker`);
+    if (ctx.otherTabCount > 0) {
+        parts.push(`${ctx.otherTabCount} other tab${ctx.otherTabCount === 1 ? '' : 's'}`);
+    }
+    if (ctx.staleRefRetries > 0) {
+        parts.push(`${ctx.staleRefRetries} stale-ref retr${ctx.staleRefRetries === 1 ? 'y' : 'ies'}`);
+    }
+    return parts.length > 0 ? `Browser: ${parts.join(' · ')}` : '';
+}
+/**
+ * v4.4 Phase 5 — format the sandboxContext fields into a compact
+ * single-line summary for the recovery card. Mirrors
+ * `buildBrowserContextLine` shape. Returns empty string when no
+ * signal worth surfacing.
+ */
+function buildSandboxContextLine(ctx) {
+    const parts = [];
+    parts.push(`${ctx.violationCount} blocked`);
+    if (ctx.fsViolations > 0 && ctx.shellViolations > 0) {
+        parts.push(`${ctx.fsViolations} fs · ${ctx.shellViolations} shell`);
+    }
+    else if (ctx.shellViolations > 0) {
+        parts.push(`${ctx.shellViolations} shell`);
+    }
+    if (ctx.lastCode)
+        parts.push(`last: ${ctx.lastCode}`);
+    if (ctx.suggestedEnv)
+        parts.push(`try: ${ctx.suggestedEnv}`);
+    return parts.length > 0 ? `Sandbox: ${parts.join(' · ')}` : '';
+}
+function buildWhatHappenedLine(report) {
+    const { attempts, durationMs } = report;
+    const dur = (durationMs / 1000).toFixed(1);
+    return (`Tried ${attempts.total} tool ${plural(attempts.total, 'call')} · ` +
+        `${attempts.succeeded} succeeded · ${attempts.failed} failed · ${dur}s`);
+}
+function plural(n, word) {
+    return n === 1 ? word : `${word}s`;
+}
+function buildFailuresPills(breakdown) {
+    const entries = Object.entries(breakdown);
+    // Same ordering rule as guidance synthesis: count desc, priority asc.
+    const PRIORITY = [
+        'timeout', 'rate_limit', 'network', 'invalid_input',
+        'not_found',
+        'stale_ref', // v4.3 Phase 5 — auto-recoverable via wait+retry
+        'hallucination', 'dependency_missing',
+        'manual_blocker', // v4.3 Phase 5 — requires human action; semi-blocking
+        'sandbox_violation', // v4.4 Phase 5 — env-var override is the specific user action
+        'trigger_misconfigured', // v4.5 Phase 5a — trigger spec fix required
+        'trigger_quota', // v4.5 Phase 5a — anti-thrash, producer/cap fix
+        'trigger_dead_lettered', // v4.5 Phase 5a — terminal; re-queue or accept loss
+        'permission', 'auth', 'other',
+    ];
+    const rank = (c) => {
+        const i = PRIORITY.indexOf(c);
+        return i === -1 ? PRIORITY.length : i;
+    };
+    entries.sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1];
+        return rank(a[0]) - rank(b[0]);
+    });
+    return entries.map(([category, count]) => ({ category, count }));
+}

package/dist/core/v4/runtimeToggles.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/runtimeToggles.ts — v4.5 Phase 8a.
+ *
+ * Single source of truth for the v4.2/v4.3/v4.4 subsystem
+ * default-on toggles (TCE, browser depth, sandbox). Replaces the
+ * direct `process.env.AIDEN_*` reads scattered across:
+ *
+ *   - core/v4/sandboxConfig.ts        (AIDEN_SANDBOX)
+ *   - core/v4/turnState.ts            (AIDEN_TCE)
+ *   - core/v4/browserState.ts         (AIDEN_BROWSER_DEPTH)
+ *
+ * with a centralised resolver that supports:
+ *
+ *   - **Live flip** via slash commands (/sandbox on|off, /tce on|off,
+ *     /browser-depth on|off). The slash command updates the in-process
+ *     state + persists to config.yaml, and fires onChange callbacks so
+ *     cached consumers (sandboxConfig's singleton) invalidate.
+ *
+ *   - **Persistence** across restarts via
+ *     `<AIDEN_HOME>/config.yaml :: runtime_toggles.{sandbox,tce,browser_depth}`.
+ *
+ *   - **Env-var precedence** (Q-P8a-1a): explicit env var > config.yaml >
+ *     default (true for all three). Matches the existing AIDEN_*
+ *     escape-hatch contract.
+ *
+ * The singleton is initialised by the CLI at boot via `initRuntimeToggles`
+ * with a ConfigProvider seam. Core modules that read the toggles call
+ * `getRuntimeToggles().isEnabled(key)` — when the singleton hasn't been
+ * initialised (test bench, core-only invocation), an env-only fallback
+ * resolver is used so the modules keep working with their pre-v4.5
+ * semantics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._TOGGLE_KEYS = void 0;
+exports.buildRuntimeToggles = buildRuntimeToggles;
+exports.getRuntimeToggles = getRuntimeToggles;
+exports.initRuntimeToggles = initRuntimeToggles;
+exports._resetRuntimeTogglesForTests = _resetRuntimeTogglesForTests;
+// ── Env var mapping ────────────────────────────────────────────────────────
+const ENV_VAR = {
+    sandbox: 'AIDEN_SANDBOX',
+    tce: 'AIDEN_TCE',
+    browser_depth: 'AIDEN_BROWSER_DEPTH',
+    // v4.5 Phase 8b — contextual capability suggestions. Rarely set as
+    // env (this is mostly a UX toggle) but included for symmetry with
+    // the other subsystem toggles.
+    suggestions: 'AIDEN_SUGGESTIONS',
+};
+const CONFIG_KEY = {
+    sandbox: 'runtime_toggles.sandbox',
+    tce: 'runtime_toggles.tce',
+    browser_depth: 'runtime_toggles.browser_depth',
+    suggestions: 'runtime_toggles.suggestions',
+};
+const ALL_KEYS = ['sandbox', 'tce', 'browser_depth', 'suggestions'];
+// ── Resolver primitives ────────────────────────────────────────────────────
+/**
+ * Strict env interpretation matching existing v4.2/v4.3/v4.4
+ * semantics: literal `'0'` (or `'false'` for forgiveness) means off;
+ * unset means defer to next leg; anything else means on. Returns
+ * `null` when the env var is unset / empty — caller falls through to
+ * config or default.
+ */
+function readEnv(env, key) {
+    const raw = env[ENV_VAR[key]];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed === '0' || trimmed === 'false' || trimmed === 'off' || trimmed === 'no') {
+        return false;
+    }
+    return true;
+}
+function readConfig(cfg, key) {
+    if (!cfg)
+        return null;
+    const raw = cfg(CONFIG_KEY[key]);
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === 'boolean')
+        return raw;
+    if (typeof raw === 'string') {
+        const t = raw.trim().toLowerCase();
+        if (t === 'true' || t === '1' || t === 'on' || t === 'yes')
+            return true;
+        if (t === 'false' || t === '0' || t === 'off' || t === 'no')
+            return false;
+    }
+    if (typeof raw === 'number')
+        return raw !== 0;
+    return null;
+}
+// ── Singleton ──────────────────────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Build a RuntimeToggles instance bound to the supplied deps.
+ * Public so tests can construct isolated instances.
+ */
+function buildRuntimeToggles(deps = {}) {
+    const env = deps.env ?? process.env;
+    // In-process overrides — set() updates this map; subsequent
+    // isEnabled() reads see the override before falling through to
+    // env/config/default.
+    const overrides = new Map();
+    const subscribers = new Map();
+    function resolve(key) {
+        // 1. env (Q-P8a-1a — explicit env always wins)
+        const envValue = readEnv(env, key);
+        if (envValue !== null)
+            return { value: envValue, source: 'env' };
+        // 2. in-process override (slash-command flip not yet persisted)
+        if (overrides.has(key))
+            return { value: overrides.get(key), source: 'config' };
+        // 3. config.yaml
+        const cfgValue = readConfig(deps.configRead, key);
+        if (cfgValue !== null)
+            return { value: cfgValue, source: 'config' };
+        // 4. default
+        return { value: true, source: 'default' };
+    }
+    function fire(key) {
+        const set = subscribers.get(key);
+        if (!set)
+            return;
+        for (const cb of set) {
+            try {
+                cb();
+            }
+            catch { /* never let an invalidation callback crash the flip */ }
+        }
+    }
+    return {
+        isEnabled(key) { return resolve(key).value; },
+        async set(key, value, opts = {}) {
+            overrides.set(key, value);
+            if (opts.persist !== false && deps.configWriteAndSave) {
+                await deps.configWriteAndSave(CONFIG_KEY[key], value);
+            }
+            fire(key);
+        },
+        snapshot() {
+            const out = {};
+            for (const k of ALL_KEYS)
+                out[k] = resolve(k);
+            return out;
+        },
+        onChange(key, cb) {
+            let set = subscribers.get(key);
+            if (!set) {
+                set = new Set();
+                subscribers.set(key, set);
+            }
+            set.add(cb);
+        },
+    };
+}
+/**
+ * Return the process-wide RuntimeToggles. When `initRuntimeToggles`
+ * hasn't been called, returns a env-only fallback resolver so core
+ * modules (sandboxConfig, turnState, browserState) keep working in
+ * test benches + core-only invocations.
+ */
+function getRuntimeToggles() {
+    if (!_singleton)
+        _singleton = buildRuntimeToggles();
+    return _singleton;
+}
+/**
+ * Initialise the singleton with the CLI's ConfigManager seam. Called
+ * once by `aidenCLI.ts::buildAgentRuntime` after config.yaml is loaded.
+ */
+function initRuntimeToggles(deps) {
+    _singleton = buildRuntimeToggles(deps);
+    return _singleton;
+}
+/** Test-only reset. */
+function _resetRuntimeTogglesForTests() {
+    _singleton = null;
+}
+exports._TOGGLE_KEYS = ALL_KEYS;