@aitne/daemon 0.1.0

package/dist/services/delegated-backend-invoker.js

@@ -0,0 +1,2372 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { filterDeniedToolsForBackend, getAgentDayDateStr, } from "@aitne/shared";
+import { createLogger } from "../logging.js";
+import { DelegatedProxyTimeoutError, DelegatedToolUnsupportedError, } from "../core/agent-core.js";
+import { readIntegrations } from "../db/integrations-store.js";
+import { proxyModelIsKnown, resolveCanonicalDelegatedModel, resolveProcessKeyModel, } from "../core/backends/proxy-model-registry.js";
+import { DELEGATED_PROXY_DEFAULTS } from "./delegated-proxy-config.js";
+import { buildRetryFollowup, buildTaskPrompt, classifyStructuredOutput, compileSchema, detectConfirmationEnvelope, detectErrorEnvelope, extractAndValidateResult, hashTaskArgs, resolveAllowedToolPatterns, resolveDestructiveToolPatterns, resolveRunWriteClassToolPatterns, resolveWriteClassToolPatterns, wrapSchemaForStructuredOutput, } from "./delegated-task-runtime.js";
+import { DelegatedTaskResultCache, execScope, integrationVersionFor, runScope, } from "./delegated-task-result-cache.js";
+import { DelegatedTaskSessionPool, SESSION_POOL_TEMPDIR_PREFIX, } from "./delegated-task-session-pool.js";
+import { readRuntimeState, writeRuntimeState, } from "../db/runtime-state.js";
+const logger = createLogger("delegated-proxy-invoker");
+export class DelegatedBackendInvoker {
+    deps;
+    defaults;
+    now;
+    /** Inflight permit count (acquired from `maxConcurrent`). */
+    inflight = 0;
+    /** FIFO waiters parked when `inflight === maxConcurrent`. */
+    waiters = [];
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §13 Phase 3.3 — result cache.
+     * Constructed lazily on first task() / run() so a daemon that never
+     * fires task mode does not hold the LRU map. `null` until the first
+     * call observes `delegatedTaskCacheEnabled === true`.
+     */
+    resultCache = null;
+    /**
+     * §13 Phase 3.2 — session-dir pool. Lazy-constructed for the same
+     * reason as `resultCache`. Pool is per-invoker so concurrent task
+     * runs see a coherent set of idle entries.
+     */
+    sessionPool = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.defaults = { ...DELEGATED_PROXY_DEFAULTS, ...(deps.defaults ?? {}) };
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * §13 Phase 3.3 — return the cache, instantiating it if missing or
+     * recreating it when the live config has flipped TTL or capacity.
+     * Returns null when caching is disabled, in which case callers MUST
+     * skip every cache code path (no insertions either, otherwise an
+     * emergency disable would still serve from a stale local map).
+     */
+    getResultCache() {
+        if (!this.deps.config.delegatedTaskCacheEnabled) {
+            if (this.resultCache) {
+                // Killing the cache mid-window: drop entries so they don't
+                // resurface if the flag flips back on.
+                this.resultCache.clear();
+                this.resultCache = null;
+            }
+            return null;
+        }
+        const ttlMs = Math.max(1, this.deps.config.delegatedTaskCacheTtlSeconds) * 1000;
+        const maxEntries = Math.max(1, this.deps.config.delegatedTaskCacheMaxEntries);
+        if (!this.resultCache
+            || this.resultCache.stats().ttlMs !== ttlMs
+            || this.resultCache.stats().maxEntries !== maxEntries) {
+            this.resultCache = new DelegatedTaskResultCache({
+                ttlMs,
+                maxEntries,
+                now: this.now,
+            });
+        }
+        return this.resultCache;
+    }
+    /**
+     * §13 Phase 3.2 — return the pool, instantiating if missing. Returns
+     * null when the kill switch is off; the caller falls through to the
+     * legacy `makeTempdir` + `cleanupTempdir` path.
+     */
+    getSessionPool() {
+        if (!this.deps.config.delegatedTaskSubprocessPoolEnabled) {
+            if (this.sessionPool) {
+                // Killing the pool mid-window: rm idle dirs so we don't strand
+                // them past the disable.
+                this.sessionPool.evictAll();
+                this.sessionPool = null;
+            }
+            return null;
+        }
+        const ttlMs = Math.max(1, this.deps.config.delegatedTaskSubprocessPoolTtlSeconds)
+            * 1000;
+        const maxIdle = this.maxConcurrent;
+        if (!this.sessionPool
+            || this.sessionPool.stats().ttlMs !== ttlMs
+            || this.sessionPool.stats().maxIdle !== maxIdle) {
+            // Pool config changed — drop the old one so its dirs get rm'd
+            // before we start handing out new leases under the new shape.
+            this.sessionPool?.evictAll();
+            this.sessionPool = new DelegatedTaskSessionPool({
+                ttlMs,
+                maxIdle,
+                materializer: (sessionDir, backendId) => this.materializeProxySession(sessionDir, backendId),
+                tempdirPrefix: SESSION_POOL_TEMPDIR_PREFIX,
+                sessionsRoot: this.sessionsRoot(),
+                now: this.now,
+            });
+        }
+        return this.sessionPool;
+    }
+    /**
+     * §13 Phase 3.2 — release-or-create wrapper. Returns either a pool
+     * lease (when pooling is on) or a one-shot synthetic lease (when
+     * pooling is off — preserves the legacy makeTempdir + cleanupTempdir
+     * flow). Either way the caller follows the lease's release/discard
+     * lifecycle.
+     *
+     * The legacy synthetic lease wraps `makeTempdir()` + the existing
+     * janitor cleanup so the rest of the task() / run() body doesn't have
+     * to branch on pooling state.
+     */
+    acquireSessionDir(args) {
+        const pool = this.getSessionPool();
+        if (pool) {
+            return pool.acquire({
+                backendId: args.backendId,
+                integrationKey: args.integrationKey,
+                modelId: args.modelId,
+            });
+        }
+        const sessionDir = this.makeTempdir();
+        try {
+            this.materializeProxySession(sessionDir, args.backendId);
+        }
+        catch (err) {
+            try {
+                rmSync(sessionDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+            throw err;
+        }
+        return new LegacyOneShotLease(sessionDir, () => this.cleanupTempdir(sessionDir));
+    }
+    /**
+     * Effective concurrency cap — read live so a runtime PATCH /api/config
+     * (Phase C5) takes effect on the next call without a daemon restart.
+     */
+    get maxConcurrent() {
+        const cfg = this.deps.config.delegatedProxyMaxConcurrent;
+        return typeof cfg === "number" && cfg > 0
+            ? cfg
+            : this.defaults.defaultMaxConcurrent;
+    }
+    /** Visibility for tests + future /health.metrics.delegatedProxy facet. */
+    get queueDepth() {
+        return this.waiters.length;
+    }
+    get inflightCount() {
+        return this.inflight;
+    }
+    async invoke(params) {
+        // Pre-permit fast path. Avoid spending one of the (default 4) permits —
+        // and a potential 60s queue wait — on a request that is obviously
+        // invalid right now. No `agent_actions` row is written: the request
+        // never held a slot, never spawned, never blocked anyone.
+        const fastCheck = this.resolvePreconditions(params.integrationKey, params.modelOverride);
+        if (!fastCheck.ok) {
+            return {
+                ok: false,
+                errorClass: "precondition",
+                message: fastCheck.message,
+                ...(fastCheck.backendId ? { backendId: fastCheck.backendId } : {}),
+            };
+        }
+        const acquired = await this.acquirePermit();
+        if (!acquired.ok) {
+            // Queue saturation — surfaces as 503 in the route handler. Don't
+            // create a tempdir, don't materialize anything. Cost row is still
+            // written (zero-cost) so the dashboard sees a saturation event.
+            this.recordAction({
+                backendId: fastCheck.backendId,
+                modelId: fastCheck.modelId,
+                params,
+                result: "failed",
+                errorClass: "delegated_proxy_busy",
+                cost: zeroCost(),
+                startedAt: new Date(this.now()).toISOString(),
+                completedAt: new Date(this.now()).toISOString(),
+                errorMessage: acquired.message,
+            });
+            return {
+                ok: false,
+                errorClass: "delegated_proxy_busy",
+                message: acquired.message,
+                backendId: fastCheck.backendId,
+                modelId: fastCheck.modelId,
+            };
+        }
+        // Post-permit re-check. Integration state may have been flipped (mode,
+        // delegatedBackend, or delegatedModel) while this request waited up to
+        // 60s in the FIFO queue. Running with stale state would materialize the
+        // wrong instruction file (e.g. CLAUDE.md against a freshly-switched
+        // codex backend) or invoke a core the user just unregistered. We DO
+        // record this row — unlike the pre-permit path it consumed a slot and
+        // blocked others, so the dashboard should surface the queue waste.
+        const liveCheck = this.resolvePreconditions(params.integrationKey, params.modelOverride);
+        if (!liveCheck.ok) {
+            this.releasePermit();
+            const nowIso = new Date(this.now()).toISOString();
+            const message = `integration state changed during queue wait: ${liveCheck.message}`;
+            this.recordAction({
+                backendId: liveCheck.backendId ?? fastCheck.backendId,
+                modelId: fastCheck.modelId,
+                params,
+                result: "failed",
+                errorClass: "precondition",
+                cost: zeroCost(),
+                startedAt: nowIso,
+                completedAt: nowIso,
+                errorMessage: message,
+            });
+            return {
+                ok: false,
+                errorClass: "precondition",
+                message,
+                backendId: liveCheck.backendId ?? fastCheck.backendId,
+                modelId: fastCheck.modelId,
+            };
+        }
+        const { state, backendId, core, modelId } = liveCheck;
+        const maxTurns = this.resolveMaxTurns(state);
+        const sessionDir = this.makeTempdir();
+        const startMs = this.now();
+        const startedAtIso = new Date(startMs).toISOString();
+        let toolResult = null;
+        let unimplemented = false;
+        let unhandledMessage = null;
+        // Default-classify any unhandled exception as a subprocess crash; the
+        // wall-clock timeout callback flips this to "timeout" before aborting
+        // so the route handler can map to 504 (vs 502/500). Distinct enums
+        // also keep failure-rate metrics honest.
+        let unhandledClass = "subprocess_crashed";
+        try {
+            this.materializeProxySession(sessionDir, backendId);
+            // Build the abort plumbing — combine caller's signal with our own
+            // wall-clock timeout so the core sees one signal. Backend-specific
+            // overrides (see `callTimeoutMsByBackend` in delegated-proxy-config.ts)
+            // win when present so gemini's slower CLI cold-start gets headroom.
+            const ac = new AbortController();
+            const callTimeoutMs = this.defaults.callTimeoutMsByBackend[backendId]
+                ?? this.defaults.callTimeoutMs;
+            const timeout = setTimeout(() => {
+                unhandledClass = "timeout";
+                ac.abort(new DelegatedProxyTimeoutError());
+            }, callTimeoutMs);
+            timeout.unref?.();
+            const callerListener = () => ac.abort(params.abortSignal?.reason);
+            if (params.abortSignal) {
+                if (params.abortSignal.aborted) {
+                    ac.abort(params.abortSignal.reason);
+                }
+                else {
+                    params.abortSignal.addEventListener("abort", callerListener, {
+                        once: true,
+                    });
+                }
+            }
+            try {
+                toolResult = await core.runDelegatedTool({
+                    integrationKey: params.integrationKey,
+                    toolName: params.toolName,
+                    toolArgs: params.toolArgs,
+                    modelId,
+                    maxTurns,
+                    maxBudgetUsd: this.defaults.maxBudgetUsd,
+                    sessionDir,
+                    abortSignal: ac.signal,
+                });
+            }
+            catch (err) {
+                if (err instanceof DelegatedToolUnsupportedError) {
+                    unimplemented = true;
+                }
+                else {
+                    unhandledMessage =
+                        err instanceof Error ? err.message : String(err);
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+                params.abortSignal?.removeEventListener("abort", callerListener);
+            }
+        }
+        finally {
+            this.cleanupTempdir(sessionDir);
+            this.releasePermit();
+        }
+        const completedAtIso = new Date(this.now()).toISOString();
+        if (unimplemented) {
+            this.recordAction({
+                backendId,
+                modelId,
+                params,
+                result: "failed",
+                errorClass: "unimplemented",
+                cost: zeroCost(),
+                startedAt: startedAtIso,
+                completedAt: completedAtIso,
+                errorMessage: "runDelegatedTool not implemented on this backend (Phase A stub)",
+            });
+            return {
+                ok: false,
+                errorClass: "unimplemented",
+                message: "delegated proxy backend has not been wired yet — Phase B will land per-backend stream extraction",
+                backendId,
+                modelId,
+            };
+        }
+        if (unhandledMessage !== null) {
+            this.recordAction({
+                backendId,
+                modelId,
+                params,
+                result: "failed",
+                errorClass: unhandledClass,
+                cost: zeroCost(),
+                startedAt: startedAtIso,
+                completedAt: completedAtIso,
+                errorMessage: unhandledMessage,
+            });
+            return {
+                ok: false,
+                errorClass: unhandledClass,
+                message: unhandledMessage,
+                backendId,
+                modelId,
+            };
+        }
+        if (!toolResult) {
+            // Defensive: should not happen unless runDelegatedTool resolved with
+            // null/undefined, which violates the contract.
+            this.recordAction({
+                backendId,
+                modelId,
+                params,
+                result: "failed",
+                errorClass: "parse_error",
+                cost: zeroCost(),
+                startedAt: startedAtIso,
+                completedAt: completedAtIso,
+                errorMessage: "core returned null DelegatedToolResult",
+            });
+            return {
+                ok: false,
+                errorClass: "parse_error",
+                message: "delegated proxy core returned null",
+                backendId,
+                modelId,
+            };
+        }
+        if (toolResult.ok) {
+            this.recordAction({
+                backendId,
+                modelId,
+                params,
+                result: "success",
+                cost: toolResult.cost,
+                startedAt: startedAtIso,
+                completedAt: completedAtIso,
+            });
+            return {
+                ok: true,
+                toolResult: toolResult.toolResult,
+                cost: toolResult.cost,
+                backendId,
+                modelId,
+            };
+        }
+        this.recordAction({
+            backendId,
+            modelId,
+            params,
+            result: "failed",
+            errorClass: toolResult.errorClass,
+            cost: toolResult.cost,
+            startedAt: startedAtIso,
+            completedAt: completedAtIso,
+            errorMessage: toolResult.message,
+        });
+        return {
+            ok: false,
+            errorClass: toolResult.errorClass,
+            message: toolResult.message,
+            cost: toolResult.cost,
+            backendId,
+            modelId,
+        };
+    }
+    // ── Preconditions ───────────────────────────────────────────────────────
+    /**
+     * Resolve the live integration state to a backend + core + model. Called
+     * twice per invocation: once before acquiring a permit (fast-fail without
+     * spending a slot) and again after the permit (defends against the user
+     * flipping mode/backend during a 60s queue wait — the post-permit re-check
+     * is the only place we'd notice).
+     */
+    resolvePreconditions(integrationKey, modelOverride) {
+        const state = readIntegrations(this.deps.db)[integrationKey];
+        if (!state || state.mode !== "delegated" || !state.delegatedBackend) {
+            return {
+                ok: false,
+                message: `integration '${integrationKey}' is not in delegated mode (mode=${state?.mode ?? "missing"}, delegatedBackend=${state?.delegatedBackend ?? "null"})`,
+            };
+        }
+        const backendId = state.delegatedBackend;
+        const core = this.deps.cores[backendId];
+        if (!core) {
+            return {
+                ok: false,
+                message: `no agent core registered for backend '${backendId}'`,
+                backendId,
+            };
+        }
+        const modelId = this.resolveModel(state, integrationKey, backendId, modelOverride);
+        return { ok: true, state, backendId, core, modelId };
+    }
+    // ── Concurrency primitives ──────────────────────────────────────────────
+    async acquirePermit() {
+        if (this.inflight < this.maxConcurrent) {
+            this.inflight++;
+            return { ok: true };
+        }
+        return new Promise((resolve) => {
+            const waiter = {
+                // Resolved by `releasePermit` when this waiter is at the head.
+                // Must INCREMENT inflight at resolve time (not queue time) so that
+                // concurrent acquires don't all see the same low inflight count.
+                wake: () => {
+                    if (waiter.settled)
+                        return;
+                    waiter.settled = true;
+                    clearTimeout(waiter.timer);
+                    this.inflight++;
+                    resolve({ ok: true });
+                },
+                timer: setTimeout(() => {
+                    if (waiter.settled)
+                        return;
+                    waiter.settled = true;
+                    // Remove from queue so releasePermit doesn't try to wake us.
+                    const idx = this.waiters.indexOf(waiter);
+                    if (idx >= 0)
+                        this.waiters.splice(idx, 1);
+                    resolve({
+                        ok: false,
+                        message: `delegated proxy queue wait exceeded ${this.defaults.queueWaitTimeoutMs}ms`,
+                    });
+                }, this.defaults.queueWaitTimeoutMs),
+                settled: false,
+            };
+            waiter.timer.unref?.();
+            this.waiters.push(waiter);
+        });
+    }
+    releasePermit() {
+        this.inflight--;
+        // Wake the head of the FIFO queue if any. The wake() handler
+        // re-increments inflight, so the net change is zero.
+        while (this.waiters.length > 0) {
+            const next = this.waiters.shift();
+            if (!next.settled) {
+                next.wake();
+                return;
+            }
+        }
+    }
+    // ── Tempdir + materialization ───────────────────────────────────────────
+    /**
+     * Path layout matches existing event sessions for filesystem locality —
+     * the DELEGATED-PROXY design says "same root as existing event-driven
+     * sessions" (§4.4); the actual root in this codebase is `agent-sessions/`.
+     */
+    sessionsRoot() {
+        return join(this.deps.config.dataDir, "agent-sessions");
+    }
+    makeTempdir() {
+        const dir = join(this.sessionsRoot(), `${this.defaults.tempdirPrefix}${randomUUID()}`);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return dir;
+    }
+    cleanupTempdir(sessionDir) {
+        try {
+            rmSync(sessionDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            logger.warn({ err, sessionDir }, "proxy tempdir cleanup failed");
+        }
+    }
+    /**
+     * Materialize the minimal proxy session: just the proxy profile rendered
+     * into the backend-specific instruction file (CLAUDE.md / AGENTS.md /
+     * GEMINI.md). No skills, no MCP config, no character block — the proxy
+     * profile itself is the entire instruction. Per-backend tool-listing
+     * for the connector is the core's responsibility (it knows its native
+     * MCP namespace).
+     */
+    materializeProxySession(sessionDir, backendId) {
+        const profilePath = join(this.deps.config.workspaceDir, "agent-assets", "agent-profiles", "proxy.md");
+        let body;
+        try {
+            body = readFileSyncIfExists(profilePath)
+                ?? FALLBACK_PROXY_PROFILE;
+        }
+        catch {
+            body = FALLBACK_PROXY_PROFILE;
+        }
+        const filename = backendId === "claude" ? "CLAUDE.md"
+            : backendId === "codex" ? "AGENTS.md"
+                : "GEMINI.md";
+        const target = join(sessionDir, filename);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, body, "utf-8");
+    }
+    // ── Cost / agent_actions persistence ────────────────────────────────────
+    recordAction(args) {
+        const detail = {
+            integrationKey: args.params.integrationKey,
+            toolName: args.params.toolName,
+            toolArgsHash: hashArgs(args.params.toolArgs),
+            ...(args.errorClass ? { errorClass: args.errorClass } : {}),
+        };
+        try {
+            this.deps.db
+                .prepare(
+            // datetime(@started_at) coerces ISO-8601 input into SQLite's
+            // canonical 'YYYY-MM-DD HH:MM:SS' so this row sorts correctly
+            // alongside rows written via datetime('now') elsewhere — without
+            // it, mixed formats break ORDER BY started_at.
+            `INSERT INTO agent_actions (
+             event_id, action_type, trigger, model_used,
+             cost_usd, tokens_input, tokens_output,
+             cache_creation_tokens, cache_read_tokens,
+             duration_ms, num_turns, result, detail,
+             started_at, completed_at, error, backend, cost_source
+           ) VALUES (
+             @event_id, 'delegated_proxy.invoke', @trigger, @model_used,
+             @cost_usd, @tokens_input, @tokens_output,
+             @cache_creation_tokens, @cache_read_tokens,
+             @duration_ms, @num_turns, @result, @detail,
+             datetime(@started_at), datetime(@completed_at), @error, @backend, 'sdk'
+           )`)
+                .run({
+                event_id: args.params.parentEventId ?? null,
+                trigger: args.params.parentProcessKey ?? null,
+                model_used: args.modelId,
+                cost_usd: args.cost.costUsd,
+                tokens_input: args.cost.tokensInput,
+                tokens_output: args.cost.tokensOutput,
+                cache_creation_tokens: args.cost.cacheCreationTokens,
+                cache_read_tokens: args.cost.cacheReadTokens,
+                duration_ms: args.cost.durationMs,
+                num_turns: args.cost.numTurns,
+                result: args.result,
+                detail: JSON.stringify(detail),
+                started_at: args.startedAt,
+                completed_at: args.completedAt,
+                error: args.errorMessage ?? null,
+                backend: args.backendId,
+            });
+        }
+        catch (err) {
+            logger.error({ err, integrationKey: args.params.integrationKey }, "failed to record delegated_proxy.invoke action");
+        }
+    }
+    // ── Model resolution ────────────────────────────────────────────────────
+    resolveModel(state, integrationKey, backendId, modelOverride) {
+        // Caller-side override (cadence path passes medium tier — see
+        // `delegated-sync-worker.ts`). Wins above the user pin so an operator
+        // who pinned Haiku for synchronous skill calls does not also force the
+        // cadence onto Haiku. Falls through to the standard cascade if the
+        // override is not registered for this backend (e.g. operator hand-edited
+        // an unknown model id).
+        if (modelOverride
+            && proxyModelIsKnown(this.deps.db, backendId, modelOverride)) {
+            return modelOverride;
+        }
+        if (this.deps.resolveProxyModel) {
+            return this.deps.resolveProxyModel(integrationKey, backendId);
+        }
+        // DELEGATED-PROXY-API-DESIGN.md §4.2 — user pin wins iff still
+        // resolvable for the current backend. After a `delegatedBackend`
+        // swap a leftover Claude model id silently falls through to the
+        // canonical light-tier pick; the dashboard surfaces the staleness
+        // with a "Reset to default" affordance.
+        const pinned = state.delegatedModel ?? null;
+        if (pinned && proxyModelIsKnown(this.deps.db, backendId, pinned)) {
+            return pinned;
+        }
+        const canonical = resolveCanonicalDelegatedModel(backendId, this.deps.db);
+        if (canonical)
+            return canonical;
+        // Registry has no lite-tier entry for this backend — fall back to the
+        // first model the live core advertises. Keeps the proxy callable when
+        // a backend's model registry is mid-redaction (e.g. a deprecated-only
+        // listing during a model rotation).
+        const core = this.deps.cores[backendId];
+        const models = core?.listModels?.() ?? [];
+        if (models.length > 0) {
+            const lite = models.find((m) => m.tier === "lite");
+            return (lite ?? models[0]).modelId;
+        }
+        return "auto";
+    }
+    /**
+     * Per-call maxTurns. Reads `state.delegatedMaxTurns` when set, otherwise
+     * the registry default (DELEGATED_PROXY_DEFAULTS.maxTurns = 2).
+     *
+     * v0.1 surfaces no dashboard UI for `delegatedMaxTurns` (DELEGATED-PROXY-
+     * API-DESIGN.md §4.2 / §13 Q3) but the daemon writes the integrations
+     * blob to `~/.personal-agent/integrations.md` for hand-edit, so a user
+     * who needs more turns for a connector that does a tool-list lookup
+     * before the call (e.g. `list_labels` then `apply_labels`) can edit the
+     * file and have it respected without waiting for UI to land.
+     *
+     * Schema bound is 1..10; defensively clamp here in case a hand-edit
+     * slipped through (the schema runs in withDefaults, but a future zod
+     * relaxation shouldn't silently let an unbounded value through to the
+     * subprocess core).
+     */
+    resolveMaxTurns(state) {
+        const pinned = state.delegatedMaxTurns;
+        if (typeof pinned !== "number" || !Number.isFinite(pinned)) {
+            return this.defaults.maxTurns;
+        }
+        if (pinned < 1)
+            return 1;
+        if (pinned > 10)
+            return 10;
+        return Math.floor(pinned);
+    }
+    // ── Task mode ─────────────────────────────────────────────────────────────
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §4.1 — task-mode chokepoint. Mirrors
+     * `invoke()`'s lifecycle (preconditions → permit → spawn → audit) but:
+     *   - resolves model + allowed tools via the runtime helpers
+     *   - writes a `delegated_task.exec` header row BEFORE spawning so step
+     *     rows can FK back to its `id`
+     *   - applies the §6.2 single-retry rule (only when no destructive /
+     *     write-class tool ran)
+     *   - returns a structured envelope (result OR confirmation OR error)
+     */
+    async task(params) {
+        if (!this.deps.config.delegatedTaskModeEnabled) {
+            return {
+                ok: false,
+                errorClass: "task_mode_disabled",
+                message: "Task mode is currently disabled (config.delegatedTaskModeEnabled=false). Re-enable via PATCH /api/config { delegatedTaskModeEnabled: true }, or flip an integration to delegated to auto-enable.",
+            };
+        }
+        // Daily quota check — pre-permit so a 429 doesn't burn a slot.
+        const today = getAgentDayDateStr(this.deps.config.timezone, this.deps.config.dayBoundaryHour);
+        const quotaCap = this.deps.config.delegatedTaskMaxPerDay;
+        const quotaCount = this.readTaskCount(today);
+        if (quotaCap > 0 && quotaCount >= quotaCap) {
+            return {
+                ok: false,
+                errorClass: "task_quota_exhausted",
+                message: `Daily task-mode quota reached (${quotaCount}/${quotaCap}); resets at the next agent-day boundary.`,
+            };
+        }
+        // Phase 1.5 landed Codex /exec — `runDelegatedTask` is now wired on
+        // CodexCore via daemon-side stream pre-emption. The previous
+        // `delegatedBackend === "codex"` short-circuit (501
+        // task_mode_unsupported) is gone; the same fastCheck below resolves
+        // the Codex core and lets the call flow through.
+        const fastCheck = this.resolvePreconditions(params.integrationKey);
+        if (!fastCheck.ok) {
+            return {
+                ok: false,
+                errorClass: "precondition",
+                message: fastCheck.message,
+                ...(fastCheck.backendId ? { backendId: fastCheck.backendId } : {}),
+            };
+        }
+        // §13 Phase 3.3 — opportunistic cache lookup BEFORE acquiring a permit.
+        // A cache hit completes in microseconds; making it queue behind in-flight
+        // tasks would defeat the latency win. We still write an audit row on
+        // hit (cost 0, detail.cacheHit=true) so dashboard accounting stays
+        // accurate. Only attempted when the caller opted in AND the operation
+        // is read-only by intent (`allowDestructive: false`) — destructive
+        // confirm flows must always re-plan.
+        if (params.cacheable === true
+            && params.allowDestructive === false) {
+            const cache = this.getResultCache();
+            if (cache) {
+                const cacheKey = {
+                    scope: execScope(params.integrationKey),
+                    task: params.task,
+                    outputSchema: params.outputSchema,
+                    modelId: fastCheck.modelId,
+                    backendId: fastCheck.backendId,
+                    allowDestructive: params.allowDestructive,
+                    integrationVersion: integrationVersionFor(fastCheck.state),
+                };
+                const hit = cache.get(cacheKey);
+                if (hit) {
+                    return this.buildCacheHitTaskResult({
+                        params,
+                        hit,
+                        backendId: fastCheck.backendId,
+                        modelId: fastCheck.modelId,
+                    });
+                }
+            }
+        }
+        const acquired = await this.acquirePermit();
+        if (!acquired.ok) {
+            return {
+                ok: false,
+                errorClass: "delegated_proxy_busy",
+                message: acquired.message,
+                backendId: fastCheck.backendId,
+            };
+        }
+        // Post-permit re-check (mirrors invoke()).
+        const liveCheck = this.resolvePreconditions(params.integrationKey);
+        if (!liveCheck.ok) {
+            this.releasePermit();
+            return {
+                ok: false,
+                errorClass: "precondition",
+                message: `integration state changed during queue wait: ${liveCheck.message}`,
+                backendId: liveCheck.backendId ?? fastCheck.backendId,
+            };
+        }
+        // Codex /exec is supported (Phase 1.5+); no backend-specific
+        // short-circuit is needed here. The post-permit re-check above
+        // already handles state changes that might have invalidated the
+        // resolved core.
+        const { state, backendId, core } = liveCheck;
+        // Resolve allowed + destructive tool patterns.
+        const denyPatterns = state.deniedTools ?? [];
+        const expandedDeny = filterDeniedToolsForBackend(params.integrationKey, backendId, denyPatterns).active;
+        const allowedTools = resolveAllowedToolPatterns({
+            integrationKey: params.integrationKey,
+            delegatedBackend: backendId,
+            allowDestructive: params.allowDestructive,
+            deniedTools: expandedDeny,
+        });
+        if (allowedTools.length === 0) {
+            this.releasePermit();
+            return {
+                ok: false,
+                errorClass: "denied_tool",
+                message: `Every tool in the ${params.integrationKey} connector is denied — task mode has no surface to plan against.`,
+                backendId,
+            };
+        }
+        const destructiveToolPatterns = resolveDestructiveToolPatterns(params.integrationKey, backendId);
+        // §6.2 / §7.4 — superset of destructiveTools used by the cores to
+        // detect write-class tool calls (e.g. `create_draft`, `update_draft`,
+        // `respond_to_event`) that should suppress the single retry. These
+        // are NOT removed from `allowedTools` even when allowDestructive=false
+        // because they are reversible — the user asked for the action — but
+        // a fresh subprocess re-running them on retry would create a second
+        // draft / second RSVP / etc.
+        const writeClassToolPatterns = resolveWriteClassToolPatterns(params.integrationKey, backendId);
+        // Resolve model. Heavy is opt-in via config; otherwise fall back to
+        // light (canonical proxy model). The §17 rationale is in the design
+        // doc — we never let the request body select the tier.
+        const heavy = !!params.heavy && this.deps.config.delegatedTaskHeavyEnabled;
+        const modelId = this.resolveTaskModel(backendId, heavy);
+        // Compile schema once; reused across the §6.2 retry.
+        const validator = compileSchema(params.outputSchema);
+        // §13 Phase 3.1 — schema bound to Claude SDK `outputFormat`. The
+        // wrap-helper currently returns the user schema verbatim (see
+        // `prepareStructuredOutputSchema` rationale in delegated-task-runtime.ts):
+        // top-level `oneOf` admitting confirmation/error envelopes is unverified
+        // against Anthropic's stricter validator, so we picked the conservative
+        // shape. When the SDK rejects the model's emission and exhausts its
+        // internal retries, the model's raw text fallback flows back through
+        // `rawAssistantText`, where `detectConfirmationEnvelope` /
+        // `detectErrorEnvelope` route it correctly. Cores that don't support
+        // structured output (Gemini, Codex) ignore the field.
+        const structuredOutputEnabled = this.deps.config.delegatedTaskStructuredOutputEnabled === true;
+        const wrappedSchema = structuredOutputEnabled
+            ? wrapSchemaForStructuredOutput(params.outputSchema)
+            : undefined;
+        // Render system prompt.
+        const systemPrompt = buildTaskPrompt({
+            task: params.task,
+            outputSchema: params.outputSchema,
+            allowedToolPatterns: allowedTools,
+            destructiveToolNamespaced: destructiveToolPatterns,
+            maxToolCalls: params.maxToolCalls,
+            timeoutMs: params.timeoutMs,
+            maxBudgetUsd: params.maxBudgetUsd,
+            allowDestructive: params.allowDestructive,
+        });
+        // §13 Phase 3.2 — acquire a session dir from the pool when enabled,
+        // else materialize a fresh tempdir. Either path returns a lease the
+        // task() loop releases (or discards on subprocess failure) in the
+        // outer `finally`.
+        let sessionLease;
+        try {
+            sessionLease = this.acquireSessionDir({
+                backendId,
+                integrationKey: params.integrationKey,
+                modelId,
+            });
+        }
+        catch (err) {
+            this.releasePermit();
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: `failed to materialize session directory: ${message}`,
+                backendId,
+                modelId,
+            };
+        }
+        const sessionDir = sessionLease.sessionDir;
+        const startMs = this.now();
+        const startedAtIso = new Date(startMs).toISOString();
+        const taskHash = hashTaskArgs(params.task);
+        const schemaHash = hashTaskArgs(params.outputSchema);
+        // §11.1 — write header row BEFORE spawn so step rows can FK to its id.
+        const headerId = this.recordTaskHeaderInProgress({
+            actionType: "delegated_task.exec",
+            backendId,
+            modelId,
+            ...(params.parentEventId !== undefined ? { parentEventId: params.parentEventId } : {}),
+            ...(params.parentProcessKey !== undefined
+                ? { parentProcessKey: params.parentProcessKey }
+                : {}),
+            startedAt: startedAtIso,
+            detail: {
+                integrationKey: params.integrationKey,
+                delegatedBackend: backendId,
+                taskHash,
+                schemaHash,
+            },
+        });
+        // Build abort plumbing — task mode uses the request-body timeout
+        // (clamped at hard cap) as the wall-clock; backend-specific
+        // overrides do not apply here.
+        const ac = new AbortController();
+        const timeout = setTimeout(() => {
+            ac.abort(new DelegatedProxyTimeoutError("delegated task wall-clock timeout"));
+        }, params.timeoutMs);
+        timeout.unref?.();
+        const callerListener = () => ac.abort(params.abortSignal?.reason);
+        if (params.abortSignal) {
+            if (params.abortSignal.aborted) {
+                ac.abort(params.abortSignal.reason);
+            }
+            else {
+                params.abortSignal.addEventListener("abort", callerListener, {
+                    once: true,
+                });
+            }
+        }
+        let attempt = 0;
+        const maxAttempts = 2;
+        let aggregatedTrace = [];
+        let aggregatedCost = zeroCost();
+        let writeClassToolFiredEver = false;
+        let lastRaw;
+        let outcome = null;
+        let retried = false;
+        try {
+            while (attempt < maxAttempts) {
+                attempt += 1;
+                let coreResult;
+                try {
+                    // §6.2 — on the retry, we must re-send the entire system
+                    // prompt (task + schema + tool list) AND the retry instruction.
+                    // Each `runDelegatedTask` spawns a fresh subprocess with no
+                    // session memory; sending only the retry follow-up would leave
+                    // the model without the original task or schema, guaranteeing
+                    // another validation failure. Append the retry instruction to
+                    // the original prompt so the model recovers from the same
+                    // context it had on attempt #1.
+                    const retryClass = outcome?.ok === false
+                        && (outcome.errorClass === "parse_error"
+                            || outcome.errorClass === "schema_violation")
+                        ? outcome.errorClass
+                        : "parse_error";
+                    const promptForAttempt = attempt === 1
+                        ? systemPrompt
+                        : `${systemPrompt}\n\n## Retry\n\n${buildRetryFollowup({
+                            errorClass: retryClass,
+                            message: outcome?.ok === false ? outcome.message : "",
+                        })}`;
+                    coreResult = await core.runDelegatedTask({
+                        integrationKey: params.integrationKey,
+                        systemPrompt: promptForAttempt,
+                        validate: validator,
+                        validatorErrorMessage: () => (validator.errors ?? [])
+                            .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`)
+                            .join("; "),
+                        allowedTools,
+                        destructiveTools: destructiveToolPatterns,
+                        writeClassTools: writeClassToolPatterns,
+                        modelId,
+                        maxToolCalls: params.maxToolCalls,
+                        maxBudgetUsd: params.maxBudgetUsd,
+                        timeoutMs: params.timeoutMs,
+                        allowDestructive: params.allowDestructive,
+                        sessionDir,
+                        abortSignal: ac.signal,
+                        // §13 Phase 3.1 — structured output. Cores that don't honor
+                        // the flag (Gemini, Codex) ignore both fields and fall back
+                        // to text emission, which the invoker then parses + validates.
+                        structuredOutputEnabled,
+                        ...(wrappedSchema ? { wrappedSchema } : {}),
+                        onToolStep: (step) => {
+                            this.recordTaskToolStep({
+                                parentTaskActionId: headerId,
+                                backendId,
+                                modelId,
+                                integrationKey: params.integrationKey,
+                                step,
+                            });
+                        },
+                    });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    coreResult = {
+                        ok: false,
+                        errorClass: "subprocess_crashed",
+                        message,
+                        cost: zeroCost(),
+                        trace: [],
+                        writeClassToolFired: false,
+                    };
+                }
+                aggregatedTrace = aggregatedTrace.concat(coreResult.trace);
+                aggregatedCost = mergeCost(aggregatedCost, coreResult.cost);
+                writeClassToolFiredEver =
+                    writeClassToolFiredEver || coreResult.writeClassToolFired;
+                if (!coreResult.ok) {
+                    outcome = {
+                        ok: false,
+                        errorClass: coreResult.errorClass,
+                        message: coreResult.message,
+                        ...(coreResult.rawAssistantText
+                            ? { raw: coreResult.rawAssistantText }
+                            : {}),
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                lastRaw = coreResult.rawAssistantText;
+                // §13 Phase 3.1 — when the core supplied a pre-validated
+                // `structuredOutput`, classify it directly and skip the text
+                // extraction path. The wrapper schema admits the §7.2 confirmation
+                // envelope and §5.1 error envelopes, so `classifyStructuredOutput`
+                // routes them to the same outcomes the text path would.
+                const classification = coreResult.structuredOutput !== undefined
+                    ? classifyStructuredOutput(coreResult.structuredOutput, validator)
+                    : null;
+                if (classification && classification.ok && "envelope" in classification) {
+                    if (classification.envelope === "confirmation") {
+                        const conf = detectConfirmationEnvelope(classification.value);
+                        outcome = {
+                            ok: true,
+                            result: classification.value,
+                            needsConfirmation: true,
+                            confirmationPlan: conf?.plan ?? "",
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    if (classification.envelope === "error") {
+                        const env = detectErrorEnvelope(classification.value);
+                        outcome = {
+                            ok: false,
+                            errorClass: env?.errorClass ?? "tool_failed",
+                            message: env?.message ?? "subprocess returned error envelope",
+                            raw: JSON.stringify(classification.value),
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    // envelope === "result" — happy path
+                    outcome = {
+                        ok: true,
+                        result: classification.value,
+                        needsConfirmation: false,
+                        confirmationPlan: null,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                if (classification && !classification.ok) {
+                    // SDK validated against wrapped schema but our narrower user
+                    // schema rejected — bias toward post-write failure when
+                    // applicable, otherwise fall through to retry path with the
+                    // SDK-supplied error class. We fall through to the existing
+                    // extraction path below by setting `parsed` so the same retry
+                    // / write-class logic applies.
+                    if (writeClassToolFiredEver) {
+                        outcome = {
+                            ok: false,
+                            errorClass: "post_write_format_failure",
+                            message: classification.message,
+                            raw: classification.raw,
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    if (attempt < maxAttempts) {
+                        retried = true;
+                        outcome = {
+                            ok: false,
+                            errorClass: classification.errorClass,
+                            message: classification.message,
+                            raw: classification.raw,
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        continue;
+                    }
+                    outcome = {
+                        ok: false,
+                        errorClass: classification.errorClass,
+                        message: classification.message,
+                        raw: classification.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                // §6.2 — extract + validate. On parse/schema failure, retry once
+                // ONLY if no write-class tool ran. Confirmation envelope and
+                // error envelope short-circuit before validation.
+                const stripped = coreResult.rawAssistantText;
+                let parsed;
+                try {
+                    parsed = JSON.parse(stripCodeFences(stripped));
+                }
+                catch {
+                    parsed = null;
+                }
+                const confirmation = parsed != null
+                    ? detectConfirmationEnvelope(parsed)
+                    : null;
+                if (confirmation) {
+                    outcome = {
+                        ok: true,
+                        result: parsed,
+                        needsConfirmation: true,
+                        confirmationPlan: confirmation.plan,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                const errorEnvelope = parsed != null
+                    ? detectErrorEnvelope(parsed)
+                    : null;
+                if (errorEnvelope) {
+                    outcome = {
+                        ok: false,
+                        errorClass: errorEnvelope.errorClass,
+                        message: errorEnvelope.message,
+                        raw: stripped,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                const extraction = extractAndValidateResult(stripped, validator);
+                if (extraction.ok) {
+                    outcome = {
+                        ok: true,
+                        result: extraction.value,
+                        needsConfirmation: false,
+                        confirmationPlan: null,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                // Validation failure path.
+                if (writeClassToolFiredEver) {
+                    // §7.4 idempotency rule — no retry after a write.
+                    outcome = {
+                        ok: false,
+                        errorClass: "post_write_format_failure",
+                        message: extraction.message,
+                        raw: extraction.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                if (attempt < maxAttempts) {
+                    retried = true;
+                    outcome = {
+                        ok: false,
+                        errorClass: extraction.errorClass,
+                        message: extraction.message,
+                        raw: extraction.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    // Loop again for the single retry.
+                    continue;
+                }
+                outcome = {
+                    ok: false,
+                    errorClass: extraction.errorClass,
+                    message: extraction.message,
+                    raw: extraction.raw,
+                    cost: aggregatedCost,
+                    trace: aggregatedTrace,
+                    backendId,
+                    modelId,
+                    retried,
+                };
+                break;
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            params.abortSignal?.removeEventListener("abort", callerListener);
+            // §13 Phase 3.2 — release the lease back to the pool when pooling
+            // is enabled (otherwise the synthetic lease cleans up its tempdir).
+            // We DISCARD instead of release when a write-class tool fired
+            // mid-task: the dir is fine to reuse, but if a future invariant
+            // change adds per-task state on disk (e.g. cached MCP tool
+            // listings keyed by allowDestructive), the discard path stays
+            // safe. Currently no per-task state lands on disk, so release
+            // would also be correct — but discard is the conservative choice.
+            if (writeClassToolFiredEver) {
+                sessionLease.discard();
+            }
+            else {
+                sessionLease.release();
+            }
+            this.releasePermit();
+        }
+        const completedAtIso = new Date(this.now()).toISOString();
+        // §8.3 — bump the per-day task quota counter on every settled task
+        // (success and failure both consumed the budget).
+        this.incrementTaskCount(today);
+        // §13 Phase 3.3 — write to cache when:
+        //   - caller opted in (`cacheable: true`)
+        //   - the cache is enabled live
+        //   - the outcome is a clean read-only success (no confirmation, no
+        //     write-class tool fired). Confirmation envelopes and write-class
+        //     touches MUST NOT be cached — see the §6.2/§7.4 idempotency rule.
+        if (params.cacheable === true
+            && params.allowDestructive === false
+            && outcome?.ok === true
+            && outcome.needsConfirmation === false
+            && writeClassToolFiredEver === false) {
+            const cache = this.getResultCache();
+            if (cache) {
+                const cacheKey = {
+                    scope: execScope(params.integrationKey),
+                    task: params.task,
+                    outputSchema: params.outputSchema,
+                    modelId,
+                    backendId,
+                    allowDestructive: params.allowDestructive,
+                    // Use the live state (post-permit) so a deniedTools mutation
+                    // mid-task invalidates the entry on the very next call.
+                    integrationVersion: integrationVersionFor(state),
+                };
+                const entry = {
+                    result: outcome.result,
+                    needsConfirmation: false,
+                    confirmationPlan: null,
+                    cost: aggregatedCost,
+                    trace: aggregatedTrace,
+                    backendId,
+                    modelId,
+                    retried: false,
+                };
+                cache.set(cacheKey, entry);
+            }
+        }
+        // §11.1 — finalise the header row.
+        this.completeTaskHeader({
+            headerId,
+            result: outcome?.ok ? "success" : "failed",
+            cost: aggregatedCost,
+            completedAt: completedAtIso,
+            errorClass: outcome?.ok === false ? outcome.errorClass : null,
+            errorMessage: outcome?.ok === false ? outcome.message : null,
+            retried,
+            toolCallCount: aggregatedTrace.length,
+            detail: {
+                integrationKey: params.integrationKey,
+                delegatedBackend: backendId,
+                taskHash,
+                schemaHash,
+                toolCallCount: aggregatedTrace.length,
+                retried,
+                // §11.2 metric `delegated_task_destructive_blocked` keys off this
+                // flag — true when allowDestructive=false and the subprocess
+                // returned a confirmation envelope instead of executing the
+                // destructive tool.
+                needsConfirmation: outcome?.ok === true && outcome.needsConfirmation === true,
+                ...(outcome?.ok === false ? { errorClass: outcome.errorClass } : {}),
+            },
+        });
+        // §11.3 — one INFO line per task summarizing the outcome.
+        logger.info({
+            integrationKey: params.integrationKey,
+            backendId,
+            modelId,
+            taskLen: params.task.length,
+            toolCallCount: aggregatedTrace.length,
+            costUsd: aggregatedCost.costUsd,
+            durationMs: aggregatedCost.durationMs,
+            result: outcome?.ok ? "success" : "failed",
+            ...(outcome?.ok === false ? { errorClass: outcome.errorClass } : {}),
+            ...(outcome?.ok === true && outcome.needsConfirmation === true
+                ? { needsConfirmation: true }
+                : {}),
+            retried,
+        }, "delegated task complete");
+        if (!outcome) {
+            // Defensive: should not happen.
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: "task settled without producing an outcome",
+                backendId,
+                modelId,
+                cost: aggregatedCost,
+                trace: aggregatedTrace,
+                retried,
+            };
+        }
+        if (lastRaw && outcome.ok && outcome.confirmationPlan === null) {
+            // Successful path — drop the raw text from the response.
+        }
+        return outcome;
+    }
+    /**
+     * §13 Phase 3.3 — synthesize a `TaskInvokeResult` from a cache hit and
+     * write the corresponding `delegated_task.exec` audit row with cost 0
+     * and `detail.cacheHit=true`. Cache hits do not consume the per-day
+     * quota (the quota counts subprocess invocations) and do not acquire a
+     * concurrency permit (looked up before `acquirePermit`).
+     */
+    buildCacheHitTaskResult(args) {
+        const nowIso = new Date(this.now()).toISOString();
+        const taskHash = hashTaskArgs(args.params.task);
+        const schemaHash = hashTaskArgs(args.params.outputSchema);
+        this.recordCacheHitAuditRow({
+            actionType: "delegated_task.exec",
+            backendId: args.backendId,
+            modelId: args.modelId,
+            ...(args.params.parentEventId !== undefined
+                ? { parentEventId: args.params.parentEventId }
+                : {}),
+            ...(args.params.parentProcessKey !== undefined
+                ? { parentProcessKey: args.params.parentProcessKey }
+                : {}),
+            timestamp: nowIso,
+            toolCallCount: args.hit.trace.length,
+            detail: {
+                integrationKey: args.params.integrationKey,
+                delegatedBackend: args.backendId,
+                taskHash,
+                schemaHash,
+                cacheHit: true,
+                toolCallCount: args.hit.trace.length,
+                retried: false,
+                // §11.2 — cache hits are gated on the original outcome being
+                // non-confirmation (see Phase 3.3 cache guard); record this
+                // explicitly so the metric aggregator's schema stays uniform
+                // across live + cache-hit rows.
+                needsConfirmation: false,
+            },
+        });
+        return {
+            ok: true,
+            result: args.hit.result,
+            needsConfirmation: false,
+            confirmationPlan: null,
+            cost: zeroCost(),
+            trace: args.hit.trace,
+            backendId: args.backendId,
+            modelId: args.modelId,
+            retried: false,
+        };
+    }
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §4.2 — Phase 2 generic task mode.
+     * Mirror of `task()` but with no `integrationKey`: the caller pins
+     * `delegatedBackend` and `allowedTools` patterns directly. Designed
+     * for unregistered MCPs the user installed via `gemini mcp add` /
+     * `claude mcp add` (etc.) that lack an `INTEGRATION_DESCRIPTORS` entry.
+     *
+     * Differences from `task()`:
+     *   - No registry / `INTEGRATION_DESCRIPTORS` lookup. The caller's
+     *     `allowedTools` is the only scoping signal.
+     *   - `destructiveTools = []` — the registry has no destructive list
+     *     to consult. Per §7.1 the caller takes responsibility for that
+     *     classification; the absolute-block layer is still applied at
+     *     the core.
+     *   - Write-class set is derived from `allowedTools` via
+     *     {@link resolveRunWriteClassToolPatterns} (verb-segment heuristic
+     *     biased toward false-positive write-class). Phase 2 keeps the
+     *     §6.2 retry rule honest without a connector descriptor.
+     *   - Model tier is fixed `light` server-side (§4.2 last bullet);
+     *     no `heavy` field on the request body.
+     *   - Action type is `'delegated_task.run'` so dashboard filters can
+     *     separate generic Phase 2 traffic from registered-integration
+     *     Phase 1 traffic.
+     *
+     * Risk tier (route-side): Approve. The route handler is the chokepoint
+     * that enforces Bearer auth — see §13 Phase 2 deliverables.
+     */
+    async run(params) {
+        if (!this.deps.config.delegatedTaskModeEnabled) {
+            return {
+                ok: false,
+                errorClass: "task_mode_disabled",
+                message: "Task mode is currently disabled (config.delegatedTaskModeEnabled=false). Re-enable via PATCH /api/config { delegatedTaskModeEnabled: true }, or flip an integration to delegated to auto-enable.",
+            };
+        }
+        // §8.3 — quota counter is shared across /exec + /run; both kinds of
+        // task consume the same per-day budget so a runaway /run loop cannot
+        // starve /exec or vice versa.
+        const today = getAgentDayDateStr(this.deps.config.timezone, this.deps.config.dayBoundaryHour);
+        const quotaCap = this.deps.config.delegatedTaskMaxPerDay;
+        const quotaCount = this.readTaskCount(today);
+        if (quotaCap > 0 && quotaCount >= quotaCap) {
+            return {
+                ok: false,
+                errorClass: "task_quota_exhausted",
+                message: `Daily task-mode quota reached (${quotaCount}/${quotaCap}); resets at the next agent-day boundary.`,
+            };
+        }
+        // Phase 1.5 landed Codex /run support — no backend-specific
+        // short-circuit needed. The core resolution below surfaces the
+        // backend-not-registered case as `subprocess_crashed`.
+        const backendId = params.delegatedBackend;
+        const core = this.deps.cores[backendId];
+        if (!core) {
+            // Boot ordering: the requested backend is not registered with this
+            // invoker (e.g. claude-only deployment). Surface as
+            // subprocess_crashed so the route returns 500 rather than a
+            // misleading auth_error. The dashboard surfaces the underlying
+            // backend wiring on /api/health.
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: `no agent core registered for backend '${backendId}'`,
+                backendId,
+            };
+        }
+        // §13 Phase 3.3 — opportunistic cache lookup BEFORE permit acquisition.
+        // The /run path uses `runScope(allowedTools)` so two callers with the
+        // same MCP allowedTools share a cache slot; different patterns force
+        // a miss. Same constraints as /exec: caller must opt in AND the
+        // operation must be read-only by intent (allowDestructive=false).
+        const runModelId = this.resolveTaskModel(backendId, /* heavy */ false);
+        if (params.cacheable === true && params.allowDestructive === false) {
+            const cache = this.getResultCache();
+            if (cache) {
+                const cacheKey = {
+                    scope: runScope(params.allowedTools),
+                    task: params.task,
+                    outputSchema: params.outputSchema,
+                    modelId: runModelId,
+                    backendId,
+                    allowDestructive: params.allowDestructive,
+                    // /run has no integration state — empty version stamps the
+                    // cache slot but never invalidates from external mutation.
+                    // Caller-controlled allowedTools changes already invalidate via
+                    // the `runScope` hash above.
+                    integrationVersion: "",
+                };
+                const hit = cache.get(cacheKey);
+                if (hit) {
+                    return this.buildCacheHitRunResult({
+                        params,
+                        hit,
+                        backendId,
+                        modelId: runModelId,
+                    });
+                }
+            }
+        }
+        const acquired = await this.acquirePermit();
+        if (!acquired.ok) {
+            return {
+                ok: false,
+                errorClass: "delegated_proxy_busy",
+                message: acquired.message,
+                backendId,
+            };
+        }
+        // No mid-flight precondition re-check — there is no integration
+        // state to flip during the queue wait. The kill switch is the only
+        // mutable gate, and we tolerate it silently because: (a) the §6.2
+        // retry would already be in-flight; (b) the boot janitor cleans up
+        // any orphan in-progress rows; (c) the cost is bounded by the
+        // wall-clock and budget caps the request already pinned.
+        // Caller-supplied allowedTools is the entire scoping surface. We
+        // do NOT subtract anything — there is no per-integration deniedTools
+        // to enforce. The absolute-block layer is applied at the core's
+        // `disallowedTools` (Claude SDK) or admin-policy TOML (Gemini).
+        const allowedTools = [...params.allowedTools];
+        // §7.1 — destructive set is empty by design (the caller owns that
+        // classification for unregistered MCPs). We still pass an array so
+        // the core's admin-policy / disallowedTools synthesis lands on a
+        // stable shape; an empty array is a no-op for both backends.
+        const destructiveToolPatterns = [];
+        // §6.2 / §7.4 — write-class derivation from the caller's allowedTools
+        // patterns. Verb-segment heuristic biased toward false-positive
+        // write-class; documented in `resolveRunWriteClassToolPatterns`.
+        const writeClassToolPatterns = resolveRunWriteClassToolPatterns(params.allowedTools);
+        // §4.2 last bullet — model tier is fixed `light` server-side.
+        // Heavy is intentionally not selectable per request to prevent a
+        // prompt-injected DM from escalating cost. Reuse the modelId
+        // resolved earlier for the cache lookup so a slow model resolver
+        // isn't called twice.
+        const modelId = runModelId;
+        // Compile schema once; reused across the §6.2 retry.
+        const validator = compileSchema(params.outputSchema);
+        // §13 Phase 3.1 — same structured-output bridge as task(): the helper
+        // returns the user schema verbatim today. Cores that don't honor the
+        // flag (Gemini, Codex) fall back to text emission, which the invoker
+        // parses + validates below.
+        const structuredOutputEnabled = this.deps.config.delegatedTaskStructuredOutputEnabled === true;
+        const wrappedSchema = structuredOutputEnabled
+            ? wrapSchemaForStructuredOutput(params.outputSchema)
+            : undefined;
+        const systemPrompt = buildTaskPrompt({
+            task: params.task,
+            outputSchema: params.outputSchema,
+            allowedToolPatterns: allowedTools,
+            // §5.1 — the destructive list is empty for /run; the prompt
+            // template renders a "(none)" sentinel and falls through to the
+            // generic destructive-confirmation prose when allowDestructive=false.
+            destructiveToolNamespaced: destructiveToolPatterns,
+            maxToolCalls: params.maxToolCalls,
+            timeoutMs: params.timeoutMs,
+            maxBudgetUsd: params.maxBudgetUsd,
+            allowDestructive: params.allowDestructive,
+        });
+        // §13 Phase 3.2 — pool acquisition with `integrationKey: null` since
+        // /run has no registered integration scope.
+        let sessionLease;
+        try {
+            sessionLease = this.acquireSessionDir({
+                backendId,
+                integrationKey: null,
+                modelId,
+            });
+        }
+        catch (err) {
+            this.releasePermit();
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: `failed to materialize session directory: ${message}`,
+                backendId,
+                modelId,
+            };
+        }
+        const sessionDir = sessionLease.sessionDir;
+        const startMs = this.now();
+        const startedAtIso = new Date(startMs).toISOString();
+        const taskHash = hashTaskArgs(params.task);
+        const schemaHash = hashTaskArgs(params.outputSchema);
+        const allowedToolsHash = hashTaskArgs(allowedTools);
+        // §11.1 — header row BEFORE spawn so step rows can FK to it.
+        const headerId = this.recordTaskHeaderInProgress({
+            actionType: "delegated_task.run",
+            backendId,
+            modelId,
+            ...(params.parentEventId !== undefined ? { parentEventId: params.parentEventId } : {}),
+            ...(params.parentProcessKey !== undefined
+                ? { parentProcessKey: params.parentProcessKey }
+                : {}),
+            startedAt: startedAtIso,
+            detail: {
+                delegatedBackend: backendId,
+                taskHash,
+                schemaHash,
+                allowedToolsHash,
+                allowedToolsCount: allowedTools.length,
+            },
+        });
+        const ac = new AbortController();
+        const timeout = setTimeout(() => {
+            ac.abort(new DelegatedProxyTimeoutError("delegated task wall-clock timeout"));
+        }, params.timeoutMs);
+        timeout.unref?.();
+        const callerListener = () => ac.abort(params.abortSignal?.reason);
+        if (params.abortSignal) {
+            if (params.abortSignal.aborted) {
+                ac.abort(params.abortSignal.reason);
+            }
+            else {
+                params.abortSignal.addEventListener("abort", callerListener, {
+                    once: true,
+                });
+            }
+        }
+        let attempt = 0;
+        const maxAttempts = 2;
+        let aggregatedTrace = [];
+        let aggregatedCost = zeroCost();
+        let writeClassToolFiredEver = false;
+        let outcome = null;
+        let retried = false;
+        try {
+            while (attempt < maxAttempts) {
+                attempt += 1;
+                let coreResult;
+                try {
+                    const retryClass = outcome?.ok === false
+                        && (outcome.errorClass === "parse_error"
+                            || outcome.errorClass === "schema_violation")
+                        ? outcome.errorClass
+                        : "parse_error";
+                    const promptForAttempt = attempt === 1
+                        ? systemPrompt
+                        : `${systemPrompt}\n\n## Retry\n\n${buildRetryFollowup({
+                            errorClass: retryClass,
+                            message: outcome?.ok === false ? outcome.message : "",
+                        })}`;
+                    coreResult = await core.runDelegatedTask({
+                        // No integrationKey — runtime helpers tolerate undefined; cores
+                        // do not consult this field.
+                        systemPrompt: promptForAttempt,
+                        validate: validator,
+                        validatorErrorMessage: () => (validator.errors ?? [])
+                            .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`)
+                            .join("; "),
+                        allowedTools,
+                        destructiveTools: destructiveToolPatterns,
+                        writeClassTools: writeClassToolPatterns,
+                        modelId,
+                        maxToolCalls: params.maxToolCalls,
+                        maxBudgetUsd: params.maxBudgetUsd,
+                        timeoutMs: params.timeoutMs,
+                        allowDestructive: params.allowDestructive,
+                        sessionDir,
+                        abortSignal: ac.signal,
+                        structuredOutputEnabled,
+                        ...(wrappedSchema ? { wrappedSchema } : {}),
+                        onToolStep: (step) => {
+                            this.recordTaskToolStep({
+                                parentTaskActionId: headerId,
+                                backendId,
+                                modelId,
+                                step,
+                            });
+                        },
+                    });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    coreResult = {
+                        ok: false,
+                        errorClass: "subprocess_crashed",
+                        message,
+                        cost: zeroCost(),
+                        trace: [],
+                        writeClassToolFired: false,
+                    };
+                }
+                aggregatedTrace = aggregatedTrace.concat(coreResult.trace);
+                aggregatedCost = mergeCost(aggregatedCost, coreResult.cost);
+                writeClassToolFiredEver =
+                    writeClassToolFiredEver || coreResult.writeClassToolFired;
+                if (!coreResult.ok) {
+                    outcome = {
+                        ok: false,
+                        errorClass: coreResult.errorClass,
+                        message: coreResult.message,
+                        ...(coreResult.rawAssistantText
+                            ? { raw: coreResult.rawAssistantText }
+                            : {}),
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                // §13 Phase 3.1 — structured-output-first path mirrors task().
+                const classification = coreResult.structuredOutput !== undefined
+                    ? classifyStructuredOutput(coreResult.structuredOutput, validator)
+                    : null;
+                if (classification && classification.ok && "envelope" in classification) {
+                    if (classification.envelope === "confirmation") {
+                        const conf = detectConfirmationEnvelope(classification.value);
+                        outcome = {
+                            ok: true,
+                            result: classification.value,
+                            needsConfirmation: true,
+                            confirmationPlan: conf?.plan ?? "",
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    if (classification.envelope === "error") {
+                        const env = detectErrorEnvelope(classification.value);
+                        outcome = {
+                            ok: false,
+                            errorClass: env?.errorClass ?? "tool_failed",
+                            message: env?.message ?? "subprocess returned error envelope",
+                            raw: JSON.stringify(classification.value),
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    outcome = {
+                        ok: true,
+                        result: classification.value,
+                        needsConfirmation: false,
+                        confirmationPlan: null,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                if (classification && !classification.ok) {
+                    if (writeClassToolFiredEver) {
+                        outcome = {
+                            ok: false,
+                            errorClass: "post_write_format_failure",
+                            message: classification.message,
+                            raw: classification.raw,
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        break;
+                    }
+                    if (attempt < maxAttempts) {
+                        retried = true;
+                        outcome = {
+                            ok: false,
+                            errorClass: classification.errorClass,
+                            message: classification.message,
+                            raw: classification.raw,
+                            cost: aggregatedCost,
+                            trace: aggregatedTrace,
+                            backendId,
+                            modelId,
+                            retried,
+                        };
+                        continue;
+                    }
+                    outcome = {
+                        ok: false,
+                        errorClass: classification.errorClass,
+                        message: classification.message,
+                        raw: classification.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                // Text-extraction fallback (Gemini, or Claude with structured
+                // output disabled).
+                const stripped = coreResult.rawAssistantText;
+                let parsed;
+                try {
+                    parsed = JSON.parse(stripCodeFences(stripped));
+                }
+                catch {
+                    parsed = null;
+                }
+                const confirmation = parsed != null
+                    ? detectConfirmationEnvelope(parsed)
+                    : null;
+                if (confirmation) {
+                    outcome = {
+                        ok: true,
+                        result: parsed,
+                        needsConfirmation: true,
+                        confirmationPlan: confirmation.plan,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                const errorEnvelope = parsed != null
+                    ? detectErrorEnvelope(parsed)
+                    : null;
+                if (errorEnvelope) {
+                    outcome = {
+                        ok: false,
+                        errorClass: errorEnvelope.errorClass,
+                        message: errorEnvelope.message,
+                        raw: stripped,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                const extraction = extractAndValidateResult(stripped, validator);
+                if (extraction.ok) {
+                    outcome = {
+                        ok: true,
+                        result: extraction.value,
+                        needsConfirmation: false,
+                        confirmationPlan: null,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                if (writeClassToolFiredEver) {
+                    outcome = {
+                        ok: false,
+                        errorClass: "post_write_format_failure",
+                        message: extraction.message,
+                        raw: extraction.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    break;
+                }
+                if (attempt < maxAttempts) {
+                    retried = true;
+                    outcome = {
+                        ok: false,
+                        errorClass: extraction.errorClass,
+                        message: extraction.message,
+                        raw: extraction.raw,
+                        cost: aggregatedCost,
+                        trace: aggregatedTrace,
+                        backendId,
+                        modelId,
+                        retried,
+                    };
+                    continue;
+                }
+                outcome = {
+                    ok: false,
+                    errorClass: extraction.errorClass,
+                    message: extraction.message,
+                    raw: extraction.raw,
+                    cost: aggregatedCost,
+                    trace: aggregatedTrace,
+                    backendId,
+                    modelId,
+                    retried,
+                };
+                break;
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            params.abortSignal?.removeEventListener("abort", callerListener);
+            // §13 Phase 3.2 — same release/discard rule as task().
+            if (writeClassToolFiredEver) {
+                sessionLease.discard();
+            }
+            else {
+                sessionLease.release();
+            }
+            this.releasePermit();
+        }
+        const completedAtIso = new Date(this.now()).toISOString();
+        // §8.3 — bump the shared per-day quota counter.
+        this.incrementTaskCount(today);
+        // §13 Phase 3.3 — cache write mirrors task(), with `runScope` keyed
+        // off the caller's allowedTools.
+        if (params.cacheable === true
+            && params.allowDestructive === false
+            && outcome?.ok === true
+            && outcome.needsConfirmation === false
+            && writeClassToolFiredEver === false) {
+            const cache = this.getResultCache();
+            if (cache) {
+                const cacheKey = {
+                    scope: runScope(params.allowedTools),
+                    task: params.task,
+                    outputSchema: params.outputSchema,
+                    modelId,
+                    backendId,
+                    allowDestructive: params.allowDestructive,
+                    integrationVersion: "",
+                };
+                cache.set(cacheKey, {
+                    result: outcome.result,
+                    needsConfirmation: false,
+                    confirmationPlan: null,
+                    cost: aggregatedCost,
+                    trace: aggregatedTrace,
+                    backendId,
+                    modelId,
+                    retried: false,
+                });
+            }
+        }
+        // §11.1 — finalise the header row.
+        this.completeTaskHeader({
+            headerId,
+            result: outcome?.ok ? "success" : "failed",
+            cost: aggregatedCost,
+            completedAt: completedAtIso,
+            errorClass: outcome?.ok === false ? outcome.errorClass : null,
+            errorMessage: outcome?.ok === false ? outcome.message : null,
+            retried,
+            toolCallCount: aggregatedTrace.length,
+            detail: {
+                delegatedBackend: backendId,
+                taskHash,
+                schemaHash,
+                allowedToolsHash,
+                allowedToolsCount: allowedTools.length,
+                toolCallCount: aggregatedTrace.length,
+                retried,
+                // §11.2 — see /exec equivalent above.
+                needsConfirmation: outcome?.ok === true && outcome.needsConfirmation === true,
+                ...(outcome?.ok === false ? { errorClass: outcome.errorClass } : {}),
+            },
+        });
+        // §11.3 — one INFO line per /run task.
+        logger.info({
+            backendId,
+            modelId,
+            taskLen: params.task.length,
+            toolCallCount: aggregatedTrace.length,
+            costUsd: aggregatedCost.costUsd,
+            durationMs: aggregatedCost.durationMs,
+            allowedToolsCount: allowedTools.length,
+            result: outcome?.ok ? "success" : "failed",
+            ...(outcome?.ok === false ? { errorClass: outcome.errorClass } : {}),
+            ...(outcome?.ok === true && outcome.needsConfirmation === true
+                ? { needsConfirmation: true }
+                : {}),
+            retried,
+        }, "delegated run task complete");
+        if (!outcome) {
+            return {
+                ok: false,
+                errorClass: "subprocess_crashed",
+                message: "task settled without producing an outcome",
+                backendId,
+                modelId,
+                cost: aggregatedCost,
+                trace: aggregatedTrace,
+                retried,
+            };
+        }
+        return outcome;
+    }
+    /**
+     * §13 Phase 3.3 — cache-hit synthesizer for `/run`. Same shape as
+     * `buildCacheHitTaskResult` but writes a `delegated_task.run` audit row.
+     */
+    buildCacheHitRunResult(args) {
+        const nowIso = new Date(this.now()).toISOString();
+        const taskHash = hashTaskArgs(args.params.task);
+        const schemaHash = hashTaskArgs(args.params.outputSchema);
+        const allowedToolsHash = hashTaskArgs(args.params.allowedTools);
+        this.recordCacheHitAuditRow({
+            actionType: "delegated_task.run",
+            backendId: args.backendId,
+            modelId: args.modelId,
+            ...(args.params.parentEventId !== undefined
+                ? { parentEventId: args.params.parentEventId }
+                : {}),
+            ...(args.params.parentProcessKey !== undefined
+                ? { parentProcessKey: args.params.parentProcessKey }
+                : {}),
+            timestamp: nowIso,
+            toolCallCount: args.hit.trace.length,
+            detail: {
+                delegatedBackend: args.backendId,
+                taskHash,
+                schemaHash,
+                allowedToolsHash,
+                allowedToolsCount: args.params.allowedTools.length,
+                cacheHit: true,
+                toolCallCount: args.hit.trace.length,
+                retried: false,
+                // §11.2 — see /exec equivalent.
+                needsConfirmation: false,
+            },
+        });
+        return {
+            ok: true,
+            result: args.hit.result,
+            needsConfirmation: false,
+            confirmationPlan: null,
+            cost: zeroCost(),
+            trace: args.hit.trace,
+            backendId: args.backendId,
+            modelId: args.modelId,
+            retried: false,
+        };
+    }
+    /**
+     * Resolve the model for a task-mode call.
+     *
+     * §8.1 resolution order — first match wins:
+     *   1. `process_backend_config(delegated_task | delegated_task_heavy)`
+     *      with `main_backend == backendId` — honors dashboard-configured
+     *      per-process model pins (e.g. user pins Haiku 4.5 for
+     *      `delegated_task` on Claude). The ProcessKey constants
+     *      `delegated_task` / `delegated_task_heavy` exist in
+     *      `packages/shared/src/process-key.ts:51-52` precisely so the
+     *      dashboard's process-config surface can target them.
+     *   2. Heavy: first registered heavy-tier model for the backend.
+     *      Light: canonical proxy model (`backend_global_defaults` →
+     *      registry default).
+     *   3. First registered model on the live core (`auto` if none — keeps
+     *      the call alive when a backend's registry is mid-rotation).
+     *
+     * Heavy is opt-in via `config.delegatedTaskHeavyEnabled`; when the
+     * config flag is `false` the heavy ProcessKey falls through to light.
+     */
+    resolveTaskModel(backendId, heavy) {
+        const useHeavy = heavy && this.deps.config.delegatedTaskHeavyEnabled;
+        const processKey = useHeavy ? "delegated_task_heavy" : "delegated_task";
+        // Step 1: dashboard / process_backend_config override.
+        const pinned = resolveProcessKeyModel(this.deps.db, processKey, backendId);
+        if (pinned)
+            return pinned;
+        // Step 2: heavy-task fallback to first registered high-tier model.
+        if (useHeavy) {
+            const core = this.deps.cores[backendId];
+            const models = core?.listModels?.() ?? [];
+            const highModel = models.find((m) => m.tier === "high");
+            if (highModel)
+                return highModel.modelId;
+        }
+        // Step 3: canonical lite-tier delegated model (registry + global default).
+        const canonical = resolveCanonicalDelegatedModel(backendId, this.deps.db);
+        if (canonical)
+            return canonical;
+        // Step 4: live-core fallback.
+        const core = this.deps.cores[backendId];
+        const models = core?.listModels?.() ?? [];
+        if (models.length > 0) {
+            const lite = models.find((m) => m.tier === "lite");
+            return (lite ?? models[0]).modelId;
+        }
+        return "auto";
+    }
+    // ── Per-day task-mode quota counter ───────────────────────────────────────
+    readTaskCount(today) {
+        const state = readRuntimeState(this.deps.db, DELEGATED_TASK_COUNT_STATE_KEY);
+        if (!state || state.date !== today)
+            return 0;
+        return state.count;
+    }
+    incrementTaskCount(today) {
+        try {
+            const state = readRuntimeState(this.deps.db, DELEGATED_TASK_COUNT_STATE_KEY);
+            const nextCount = state && state.date === today ? state.count + 1 : 1;
+            writeRuntimeState(this.deps.db, DELEGATED_TASK_COUNT_STATE_KEY, {
+                date: today,
+                count: nextCount,
+            });
+        }
+        catch (err) {
+            logger.warn({ err }, "failed to increment delegated task quota counter");
+        }
+    }
+    // ── agent_actions header / step persistence ───────────────────────────────
+    /**
+     * §13 Phase 3.3 — single-shot INSERT for cache-hit audit rows. Cache
+     * hits don't go through the in-progress → complete two-step lifecycle
+     * (the outcome is known synchronously), so this writes one row with
+     * `result='success'`, `cost_usd=0`, `cost_source='cache'` for clean
+     * dashboard cost-source filtering.
+     */
+    recordCacheHitAuditRow(args) {
+        try {
+            const result = this.deps.db
+                .prepare(`INSERT INTO agent_actions (
+             event_id, action_type, trigger, model_used,
+             cost_usd, tokens_input, tokens_output,
+             cache_creation_tokens, cache_read_tokens,
+             duration_ms, num_turns, result, detail,
+             started_at, completed_at, error, backend, cost_source
+           ) VALUES (
+             @event_id, @action_type, @trigger, @model_used,
+             0, 0, 0, 0, 0,
+             0, @num_turns, 'success', @detail,
+             datetime(@ts), datetime(@ts), NULL, @backend, 'cache'
+           )`)
+                .run({
+                event_id: args.parentEventId ?? null,
+                action_type: args.actionType,
+                trigger: args.parentProcessKey ?? null,
+                model_used: args.modelId,
+                num_turns: args.toolCallCount,
+                detail: JSON.stringify(args.detail),
+                ts: args.timestamp,
+                backend: args.backendId,
+            });
+            return Number(result.lastInsertRowid);
+        }
+        catch (err) {
+            logger.error({ err, actionType: args.actionType, detail: args.detail }, "failed to write delegated_task cache-hit audit row");
+            return -1;
+        }
+    }
+    recordTaskHeaderInProgress(args) {
+        try {
+            const result = this.deps.db
+                .prepare(`INSERT INTO agent_actions (
+             event_id, action_type, trigger, model_used,
+             cost_usd, tokens_input, tokens_output,
+             cache_creation_tokens, cache_read_tokens,
+             duration_ms, num_turns, result, detail,
+             started_at, completed_at, error, backend, cost_source
+           ) VALUES (
+             @event_id, @action_type, @trigger, @model_used,
+             0, 0, 0, 0, 0,
+             0, 0, 'in_progress', @detail,
+             datetime(@started_at), NULL, NULL, @backend, 'sdk'
+           )`)
+                .run({
+                event_id: args.parentEventId ?? null,
+                action_type: args.actionType,
+                trigger: args.parentProcessKey ?? null,
+                model_used: args.modelId,
+                detail: JSON.stringify(args.detail),
+                started_at: args.startedAt,
+                backend: args.backendId,
+            });
+            return Number(result.lastInsertRowid);
+        }
+        catch (err) {
+            logger.error({ err, actionType: args.actionType, detail: args.detail }, "failed to write delegated_task header row");
+            return -1;
+        }
+    }
+    completeTaskHeader(args) {
+        if (args.headerId < 0)
+            return;
+        try {
+            this.deps.db
+                .prepare(`UPDATE agent_actions SET
+             result = @result,
+             cost_usd = @cost_usd,
+             tokens_input = @tokens_input,
+             tokens_output = @tokens_output,
+             cache_creation_tokens = @cache_creation_tokens,
+             cache_read_tokens = @cache_read_tokens,
+             duration_ms = @duration_ms,
+             num_turns = @num_turns,
+             completed_at = datetime(@completed_at),
+             error = @error,
+             detail = @detail
+           WHERE id = @id`)
+                .run({
+                id: args.headerId,
+                result: args.result,
+                cost_usd: args.cost.costUsd,
+                tokens_input: args.cost.tokensInput,
+                tokens_output: args.cost.tokensOutput,
+                cache_creation_tokens: args.cost.cacheCreationTokens,
+                cache_read_tokens: args.cost.cacheReadTokens,
+                duration_ms: args.cost.durationMs,
+                num_turns: args.cost.numTurns,
+                completed_at: args.completedAt,
+                error: args.errorMessage,
+                detail: JSON.stringify(args.detail),
+            });
+        }
+        catch (err) {
+            logger.error({ err, headerId: args.headerId }, "failed to update delegated_task.exec header row");
+        }
+    }
+    recordTaskToolStep(args) {
+        try {
+            this.deps.db
+                .prepare(`INSERT INTO agent_actions (
+             action_type, trigger, model_used,
+             cost_usd, tokens_input, tokens_output,
+             cache_creation_tokens, cache_read_tokens,
+             duration_ms, num_turns, result, detail,
+             started_at, completed_at, error, backend, cost_source
+           ) VALUES (
+             'delegated_task.tool_step', NULL, @model_used,
+             @cost_usd, @tokens_input, @tokens_output,
+             0, 0,
+             @duration_ms, 1, @result, @detail,
+             datetime('now'), datetime('now'), @error, @backend, 'sdk'
+           )`)
+                .run({
+                model_used: args.modelId,
+                cost_usd: args.step.costUsd,
+                tokens_input: args.step.tokensInput,
+                tokens_output: args.step.tokensOutput,
+                duration_ms: args.step.durationMs,
+                result: args.step.status === "ok" ? "success" : "failed",
+                detail: JSON.stringify({
+                    ...(args.integrationKey ? { integrationKey: args.integrationKey } : {}),
+                    toolName: args.step.toolName,
+                    toolArgsHash: hashTaskArgs(args.step.toolArgs),
+                    toolStatus: args.step.status,
+                    parentTaskActionId: args.parentTaskActionId,
+                }),
+                error: args.step.status === "error" ? "tool_step_error" : null,
+                backend: args.backendId,
+            });
+        }
+        catch (err) {
+            logger.warn({ err, parentTaskActionId: args.parentTaskActionId }, "failed to write delegated_task.tool_step row");
+        }
+    }
+}
+/**
+ * §13 Phase 3.2 — synthetic lease used when pooling is disabled. Implements
+ * the same `release()` / `discard()` shape as `SessionPoolLease` so the
+ * task() / run() loop doesn't have to branch on whether pooling is active.
+ * Both methods clean up the tempdir (no TTL semantics — there's no pool
+ * to return to).
+ */
+class LegacyOneShotLease {
+    sessionDir;
+    cleanup;
+    fromPool = false;
+    released = false;
+    constructor(sessionDir, cleanup) {
+        this.sessionDir = sessionDir;
+        this.cleanup = cleanup;
+    }
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.cleanup();
+    }
+    discard() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.cleanup();
+    }
+}
+const FALLBACK_PROXY_PROFILE = `# Delegated Proxy
+
+Call the named tool exactly once with the JSON arguments given verbatim.
+Do not narrate, do not summarize, do not call any other tool — with one
+exception: if the named tool's schema is not yet loaded, call ToolSearch
+to load it, then immediately call the named tool. Do not browse other
+tools. If the tool errors, return the error verbatim.
+`;
+function readFileSyncIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf-8");
+}
+function hashArgs(args) {
+    try {
+        const serialized = JSON.stringify(args ?? null);
+        return createHash("sha256")
+            .update(serialized)
+            .digest("hex")
+            .slice(0, 16);
+    }
+    catch {
+        return "unhashable";
+    }
+}
+function zeroCost() {
+    return {
+        tokensInput: 0,
+        tokensOutput: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        costUsd: 0,
+        durationMs: 0,
+        numTurns: 0,
+    };
+}
+function mergeCost(a, b) {
+    return {
+        tokensInput: a.tokensInput + b.tokensInput,
+        tokensOutput: a.tokensOutput + b.tokensOutput,
+        cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        costUsd: a.costUsd + b.costUsd,
+        durationMs: a.durationMs + b.durationMs,
+        numTurns: a.numTurns + b.numTurns,
+    };
+}
+/**
+ * Local copy of the runtime helper's fence stripper to avoid cycle —
+ * `delegated-task-runtime.ts` already exports the canonical version, but
+ * importing it here would cycle (the runtime imports types from this
+ * file's `agent-core.ts` chain). Tiny duplication is the cleanest fix.
+ */
+function stripCodeFences(input) {
+    let s = input.trim();
+    const fenceRe = /^```(?:json|JSON|jsonc|JSONC)?\s*\r?\n([\s\S]*?)\r?\n```$/;
+    const m = s.match(fenceRe);
+    if (m)
+        return m[1];
+    s = s.replace(/^```(?:json|JSON|jsonc|JSONC)?\s*\r?\n/, "");
+    s = s.replace(/\r?\n```\s*$/, "");
+    return s;
+}
+/**
+ * DELEGATED-TASK-MODE-DESIGN.md §8.3 — runtime_state key for the per-day
+ * task-mode quota counter. Resets at the agent-day boundary; mirrors the
+ * Gemini per-day request counter shape.
+ */
+const DELEGATED_TASK_COUNT_STATE_KEY = "delegated_task_count_today";
+/**
+ * DELEGATED-TASK-MODE-DESIGN.md §11.1 crash safety — boot-time janitor
+ * that flips orphaned `delegated_task.exec` rows older than `maxAgeMs`
+ * (default 5 min) from `result='in_progress'` to `result='failed'` with
+ * `error='subprocess_orphaned'`. Without this, a daemon crash mid-task
+ * leaves the row in flight forever and poisons the dashboard's "in-flight
+ * task" counter.
+ *
+ * Returns the number of rows updated.
+ */
+export function runDelegatedTaskOrphanJanitor(db, options = {}) {
+    const maxAgeMs = options.maxAgeMs ?? DELEGATED_PROXY_DEFAULTS.janitorMaxAgeMs;
+    const cutoffMs = (options.now?.() ?? Date.now()) - maxAgeMs;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    try {
+        const result = db
+            .prepare(`UPDATE agent_actions SET
+           result = 'failed',
+           error = 'subprocess_orphaned',
+           completed_at = datetime('now')
+         WHERE action_type IN ('delegated_task.exec', 'delegated_task.run', 'delegated_task.tool_step')
+           AND result = 'in_progress'
+           AND started_at < datetime(?)`)
+            .run(cutoffIso);
+        if (result.changes > 0) {
+            logger.info({ changes: result.changes }, "delegated task janitor: closed orphaned in-progress rows");
+        }
+        return result.changes;
+    }
+    catch (err) {
+        logger.warn({ err }, "delegated task janitor: SQL update failed");
+        return 0;
+    }
+}
+/**
+ * Boot-time janitor — scans the sessions root for orphan `proxy-*` dirs
+ * older than the configured threshold and removes them. Covers the SIGKILL
+ * mid-call case the per-call `finally` cannot. Safe to call before any
+ * invocations have happened.
+ *
+ * Returns the number of directories removed (for logging at startup).
+ */
+export function runProxyTempdirJanitor(dataDir, options = {}) {
+    const now = options.now ?? Date.now;
+    const maxAgeMs = options.maxAgeMs ?? DELEGATED_PROXY_DEFAULTS.janitorMaxAgeMs;
+    const root = join(dataDir, "agent-sessions");
+    if (!existsSync(root))
+        return 0;
+    let removed = 0;
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch (err) {
+        logger.warn({ err, root }, "proxy janitor: readdir failed");
+        return 0;
+    }
+    for (const entry of entries) {
+        if (!entry.startsWith(DELEGATED_PROXY_DEFAULTS.tempdirPrefix))
+            continue;
+        const path = join(root, entry);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        if (now() - stat.mtimeMs < maxAgeMs)
+            continue;
+        try {
+            rmSync(path, { recursive: true, force: true });
+            removed++;
+        }
+        catch (err) {
+            logger.warn({ err, path }, "proxy janitor: rm failed");
+        }
+    }
+    if (removed > 0) {
+        logger.info({ removed }, "proxy janitor: removed orphan tempdirs");
+    }
+    return removed;
+}
+//# sourceMappingURL=delegated-backend-invoker.js.map