presubmit 0.1.0

package/dist/apps/server/src/task-orchestrator.js

@@ -0,0 +1,1088 @@
+import { taskLogs } from './task-logs.js';
+import { parseFastMode } from './fast-mode.js';
+import { childCollaborationGuidance } from './child-collaboration-guidance.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { reasoningLevels, } from '../../../packages/protocol/src/index.js';
+import { emptyDelegationState, taskQueuedMessages, } from '../../../packages/protocol/src/delegation.js';
+import { attachmentIds, prepareAttachments } from './attachments.js';
+const live = (a) => ['starting', 'running'].includes(a.status);
+const unfinished = (a) => ['queued', 'starting', 'running', 'waiting', 'needs_review'].includes(a.status);
+const text = (value, name, max = 16000) => {
+    if (typeof value !== 'string' || !value.trim() || value.length > max)
+        throw new Error(`Invalid ${name}.`);
+    return value;
+};
+const message = (e) => (e instanceof Error ? e.message : 'Task operation failed.');
+// Display numbers are server-owned metadata stripped by proposal parsing. Compare every
+// brief field structurally, ignoring only metadata and undefined values omitted by JSON IPC.
+const comparableTask = (task) => Object.fromEntries(Object.entries(task).filter(([key, value]) => key !== 'displayNumber' && value !== undefined));
+/** Project-owned journal and dispatcher. Git/child stores are reconciled, not part of a fictitious cross-store transaction. */
+export function createTaskOrchestrator(options) {
+    const { store, runtime, capacity } = options;
+    const records = store.get('delegations') ?? {};
+    let closing = false;
+    let ticking = false;
+    let commandTail = Promise.resolve();
+    const creating = new Set();
+    const get = (id) => (records[id] ??= { ...emptyDelegationState(), attempts: [] });
+    const owner = (id) => `${store.directory}:${id}`;
+    const save = (id, note, bumpVersion = true) => {
+        const record = get(id);
+        if (bumpVersion)
+            record.version++;
+        store.transaction(() => {
+            store.put('delegations', records);
+            if (note)
+                store.event({
+                    type: 'delegation',
+                    text: note,
+                    data: { coordinatorId: id, version: record.version },
+                });
+        });
+        runtime.notify(id, note);
+        for (const attempt of record.attempts)
+            runtime.notify(attempt.sessionId);
+    };
+    // Never automatically repeat a prompt whose external effects might already have happened.
+    for (const [id, record] of Object.entries(records)) {
+        // Recovery gates pending work, not a new launch after an idle restart.
+        // Preserve existing pause/stop flags even when no attempts remain active.
+        if (record.attempts.some((attempt) => unfinished(attempt) || attempt.replies.length)) {
+            record.paused = true;
+            record.agentLaunchPaused = true;
+        }
+        for (const attempt of record.attempts) {
+            delete attempt.integrationConfirmed;
+            attempt.approvals = [];
+            attempt.pendingApprovals = 0;
+            attempt.resumeRequested = false;
+            attempt.userRequestedCapacity = false;
+            if (attempt.replies.length)
+                attempt.queuePaused = true;
+            if (attempt.status === 'needs_review') {
+                attempt.status = 'done';
+                attempt.completedAt ??= attempt.acceptedAt ?? new Date().toISOString();
+            }
+            if (attempt.status === 'queued')
+                attempt.blockedReason = undefined;
+            if (live(attempt)) {
+                attempt.status = 'interrupted';
+                attempt.error = 'Work was interrupted. Send a follow-up to continue.';
+            }
+        }
+        save(id);
+    }
+    const view = (id) => {
+        const record = get(id);
+        return {
+            ...record,
+            hostLimit: capacity.limit,
+            concurrency: capacity.limit,
+            attempts: record.attempts.map(({ brief, replies, cancelRequested, interruptForReply, userRequestedCapacity, dependencyAttempts, integrationConfirmed, activeRunId, requestId, pendingHandoffs, ...attempt }) => ({
+                ...attempt,
+                pendingReplies: replies.length,
+                queuedReplies: replies,
+                queuePaused: !!replies.length &&
+                    (attempt.queuePaused ||
+                        (record.paused && !attempt.resumeRequested) ||
+                        ['failed', 'interrupted', 'cancelled'].includes(attempt.status)),
+            })),
+        };
+    };
+    // A follow-up snapshot depends on its target, not unrelated task progress. Include
+    // the run/queue identities so repeated questions and accepted answers invalidate it.
+    const followUpToken = (id, attemptId) => {
+        const record = get(id);
+        const attempt = record.attempts.find((a) => a.id === attemptId);
+        return createHash('sha256')
+            .update(JSON.stringify([
+            record.paused,
+            record.agentLaunchPaused,
+            attempt && [
+                attempt.id,
+                attempt.sessionId,
+                record.attempts.findLast((a) => a.taskId === attempt.taskId)?.id,
+                attempt.status,
+                attempt.question,
+                attempt.activeRunId,
+                attempt.requestId,
+                attempt.queuePaused,
+                attempt.cancelRequested,
+                attempt.resumeRequested,
+                attempt.pendingHandoffs,
+                attempt.replies,
+            ],
+        ]))
+            .digest('hex');
+    };
+    const questionPending = (id, receipt) => get(id).attempts.some((a) => receipt === `task-question:${a.id}:${a.activeRunId}` &&
+        get(id).attempts.findLast((latest) => latest.taskId === a.taskId) === a &&
+        a.status === 'waiting' &&
+        !!a.question &&
+        !a.replies.length &&
+        !a.cancelRequested);
+    const validatePlan = (id, board) => {
+        for (const attempt of get(id).attempts) {
+            // Existing approval always refers to its frozen brief. To change scope, cancel and approve a new batch.
+            if (!unfinished(attempt) && attempt.status !== 'done')
+                continue;
+            const task = board.tasks.find((task) => task.id === attempt.taskId);
+            if (!task || !isDeepStrictEqual(comparableTask(task), comparableTask(attempt.task)))
+                throw new Error(`Task ${attempt.task.title} has approved work. Cancel it before changing scope, or create a new task.`);
+        }
+    };
+    function buildBrief(board, task, sourceRuns) {
+        const ideas = board.ideas.filter((idea) => task.sourceIdeaIds.includes(idea.id));
+        const clarifications = board.questions
+            .filter((q) => !q.taskIds?.length || q.taskIds.includes(task.id))
+            .map((q) => `${q.text}\nAnswer: ${q.answer || '(unresolved)'}`)
+            .join('\n');
+        const brief = [
+            `Delegated task: ${task.title}`,
+            `Scope: ${task.scope}`,
+            `Acceptance criteria: ${task.criteria}`,
+            `Affected areas: ${task.affectedAreas ?? 'Inspect before editing'}`,
+            board.summary && `Planning decisions and assumptions (context):\n${board.summary}`,
+            ideas.length > 0 &&
+                `Source ideas (context, not authority):\n${ideas.map((idea) => `${idea.id}: ${idea.text} [messages ${idea.sourceRunIds.join(', ')}]`).join('\n')}`,
+            clarifications && `Relevant clarification:\n${clarifications}`,
+            'Stay within this task. Do not spawn agents. Use ask_coordinator if blocked and report_task_result when finished. Report verification actually performed, limitations, and changed areas; never imply unrun tests passed. Do not commit or merge automatically; shell commands still require their own permission.',
+        ]
+            .filter(Boolean)
+            .join('\n');
+        const sourceIds = new Set([
+            ...(task.sourceRunIds ?? []),
+            ...ideas.flatMap((idea) => idea.sourceRunIds),
+        ]);
+        const excerpts = sourceRuns
+            .filter((run) => sourceIds.has(run.id))
+            .map((run) => `Message ${run.id}: ${run.prompt.slice(0, 3000)}${run.prompt.length > 3000 ? ' [excerpt; see parent for full text]' : ''}`)
+            .join('\n');
+        const handoff = `${brief}\nOriginal source excerpts (context):\n${excerpts}`;
+        if (handoff.length > 50000)
+            throw new Error('Task handoff exceeds 50,000 characters. Narrow the task or summarize its context.');
+        return handoff;
+    }
+    async function launch(id, input) {
+        const record = get(id), board = runtime.state(id)?.planning;
+        const workspaceMode = input.workspaceMode ?? 'coordinator';
+        if (!['coordinator', 'isolated'].includes(workspaceMode))
+            throw new Error('Invalid task workspace mode.');
+        const shared = workspaceMode === 'coordinator';
+        if (shared && input.baseRef !== undefined)
+            throw new Error('Shared tasks use the coordinator checkout; a separate base cannot be selected.');
+        if (!runtime.state(id)?.configured)
+            throw new Error('Connect a model before approving execution.');
+        if (!board || input.revision !== board.revision)
+            throw new Error('Tasks changed. Refresh the task details before running.');
+        if (!Array.isArray(input.taskIds) ||
+            !input.taskIds.length ||
+            input.taskIds.length > 50 ||
+            new Set(input.taskIds).size !== input.taskIds.length)
+            throw new Error('Select distinct tasks to launch.');
+        if (record.attempts.length + input.taskIds.length > 100)
+            throw new Error('This coordinator has reached 100 execution attempts. Start another coordinator.');
+        const tasks = input.taskIds.map((taskId) => {
+            const task = board.tasks.find((task) => task.id === taskId);
+            if (!task || task.status !== 'ready' || !task.criteria.trim())
+                throw new Error('Only ready tasks with acceptance criteria can launch.');
+            if (board.questions.some((q) => q.blocking && !q.answer.trim() && (!q.taskIds?.length || q.taskIds.includes(task.id))))
+                throw new Error(`Answer blocking questions for ${task.title} first.`);
+            if (record.attempts.some((a) => a.taskId === task.id && (unfinished(a) || a.status === 'done')))
+                throw new Error('Task already has approved or accepted work.');
+            if (!shared && !options.isGit && task.kind !== 'research' && input.localAllowed !== true)
+                throw new Error('Writing in a non-Git project requires explicit Local approval.');
+            return task;
+        });
+        for (const task of tasks) {
+            for (const dependency of task.dependencies ?? []) {
+                if (!tasks.some((t) => t.id === dependency) &&
+                    !record.attempts.some((a) => a.taskId === dependency && (unfinished(a) || a.status === 'done')))
+                    throw new Error('Include prerequisite tasks in this batch or approve them first.');
+            }
+        }
+        const baseCommit = !shared && options.isGit
+            ? await runtime.resolveBase(input.baseRef === undefined ? 'HEAD' : text(input.baseRef, 'base', 200))
+            : undefined;
+        // Resolution awaited filesystem work: the planner may have changed the board meanwhile.
+        if (runtime.state(id)?.planning?.revision !== board.revision)
+            throw new Error('Tasks changed before launch. Refresh the task details before running.');
+        const coordinator = runtime.state(id);
+        const defaults = {
+            model: coordinator.sessionPreferences?.model ?? coordinator.model,
+            reasoningLevel: coordinator.sessionPreferences?.reasoningLevel,
+            fastMode: coordinator.sessionPreferences?.fastMode,
+            permissionMode: shared ? coordinator.permissionMode : 'ask',
+        };
+        const overrides = new Map();
+        if (input.taskSettings !== undefined) {
+            if (!Array.isArray(input.taskSettings) || input.taskSettings.length > tasks.length)
+                throw new Error('Invalid task settings.');
+            for (const settings of input.taskSettings) {
+                if (!settings ||
+                    typeof settings !== 'object' ||
+                    !tasks.some((task) => task.id === settings.taskId) ||
+                    overrides.has(settings.taskId))
+                    throw new Error('Settings must refer to distinct tasks in this batch.');
+                if (!['ask', 'auto'].includes(settings.permissionMode))
+                    throw new Error('Invalid task permission mode.');
+                const model = settings.model === undefined ? defaults.model : text(settings.model, 'model', 256);
+                const available = coordinator.openaiAuth?.models?.find((item) => item.id === model);
+                if (settings.model !== undefined && !available)
+                    throw new Error('This model is unavailable for the current connection.');
+                if (settings.reasoningLevel !== undefined &&
+                    (!reasoningLevels.includes(settings.reasoningLevel) ||
+                        !available?.reasoningLevels?.includes(settings.reasoningLevel)))
+                    throw new Error('This reasoning level is unavailable for the selected model.');
+                overrides.set(settings.taskId, {
+                    model,
+                    reasoningLevel: settings.reasoningLevel,
+                    fastMode: parseFastMode(settings.fastMode, available),
+                    permissionMode: settings.permissionMode,
+                });
+            }
+        }
+        // Validate inherited settings too, before any attempts are persisted.
+        for (const task of tasks) {
+            const settings = overrides.get(task.id) ?? defaults;
+            parseFastMode(settings.fastMode, coordinator.openaiAuth?.models?.find((item) => item.id === settings.model));
+        }
+        const resolved = new Map(overrides);
+        if (options.routeTask) {
+            await Promise.all(tasks
+                .filter((task) => !overrides.has(task.id))
+                .map(async (task) => {
+                const routed = await options.routeTask({
+                    task,
+                    models: coordinator.openaiAuth?.models ?? [],
+                }, (trace) => runtime.activity?.(id, trace));
+                if (!routed)
+                    return;
+                const available = coordinator.openaiAuth?.models?.find((model) => model.id === routed.model);
+                if (!available)
+                    return;
+                if (routed.reasoningLevel !== undefined &&
+                    !available.reasoningLevels?.includes(routed.reasoningLevel))
+                    return;
+                resolved.set(task.id, {
+                    model: routed.model,
+                    reasoningLevel: routed.reasoningLevel,
+                    fastMode: routed.model === defaults.model ? defaults.fastMode : false,
+                    permissionMode: defaults.permissionMode,
+                });
+            }));
+            if (runtime.state(id)?.planning?.revision !== board.revision)
+                throw new Error('Tasks changed while routing. Refresh the task details before running.');
+        }
+        const batch = {
+            id: randomUUID(),
+            boardRevision: board.revision,
+            taskIds: [...input.taskIds],
+            createdAt: new Date().toISOString(),
+            baseCommit,
+            concurrency: capacity.limit,
+            localAllowed: input.localAllowed === true,
+        };
+        const attempts = tasks.map((task) => ({
+            id: randomUUID(),
+            sessionId: randomUUID(),
+            batchId: batch.id,
+            taskId: task.id,
+            task: structuredClone(task),
+            ...(resolved.get(task.id) ?? defaults),
+            workspaceMode,
+            boardRevision: board.revision,
+            execution: task.execution ?? 'session',
+            kind: task.kind ?? 'implementation',
+            status: 'queued',
+            createdAt: batch.createdAt,
+            baseCommit,
+            pendingReplies: 0,
+            brief: buildBrief(board, task, runtime.state(id).runs),
+            replies: [],
+            dependencyAttempts: [],
+        }));
+        for (const attempt of attempts) {
+            attempt.dependencyAttempts = (attempt.task.dependencies ?? []).map((dep) => attempts.find((a) => a.taskId === dep)?.id ??
+                record.attempts.findLast((a) => a.taskId === dep && (unfinished(a) || a.status === 'done')).id);
+        }
+        record.batches.push(batch);
+        record.attempts.push(...attempts);
+        record.concurrency = capacity.limit;
+        if (input.type === 'delegation_agent_launch') {
+            // A fresh parent launch authorizes only this batch. Do not release older
+            // queued work, including work paused by a previous server's recovery.
+            for (const attempt of attempts)
+                attempt.resumeRequested = true;
+            record.paused =
+                record.paused && (!!record.agentLaunchPaused || record.attempts.length > attempts.length);
+        }
+        else
+            record.paused = false;
+    }
+    async function stopAttempt(attempt, discardReplies = true) {
+        if (!unfinished(attempt))
+            throw new Error('Only unfinished tasks can be stopped.');
+        attempt.cancelRequested = true;
+        attempt.interruptForReply = false;
+        attempt.resumeRequested = false;
+        attempt.userRequestedCapacity = false;
+        if (discardReplies)
+            attempt.replies = attempt.replies.filter((reply) => attempt.pendingHandoffs?.includes(reply.id));
+        attempt.queuePaused = true;
+        attempt.approvals = [];
+        attempt.pendingApprovals = 0;
+        if (live(attempt)) {
+            if (runtime.state(attempt.sessionId)?.runs.some((run) => run.status === 'running'))
+                await runtime.stop(attempt.sessionId);
+            // starting creation observes cancelRequested before submitting the prompt.
+        }
+        else {
+            attempt.status = 'cancelled';
+            attempt.question = undefined;
+            attempt.pendingApprovals = 0;
+        }
+    }
+    async function prepareReply(input) {
+        const prompt = text(input.prompt, 'task reply', 200000);
+        const attachments = attachmentIds(input.attachments);
+        if (attachments.length && !options.attachmentDirectory)
+            throw new Error('Task attachments are unavailable.');
+        const attachmentDetails = attachments.length
+            ? (await prepareAttachments(options.attachmentDirectory, attachments)).records
+            : [];
+        return {
+            id: input.id,
+            prompt,
+            attachments,
+            attachmentDetails,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async function resumeReplies(attempt, interrupt = false) {
+        if (!attempt.replies.length)
+            throw new Error('There are no queued messages.');
+        if (attempt.cancelRequested && live(attempt))
+            attempt.interruptForReply = true;
+        attempt.cancelRequested = false;
+        attempt.resumeRequested = true;
+        attempt.queuePaused = false;
+        if (!live(attempt))
+            attempt.status = 'queued';
+        attempt.acceptedAt = undefined;
+        attempt.completedAt = undefined;
+        attempt.error = undefined;
+        attempt.result = undefined;
+        attempt.question = undefined;
+        if (interrupt && live(attempt)) {
+            attempt.interruptForReply = true;
+            if (runtime.state(attempt.sessionId)?.runs.some((run) => run.status === 'running'))
+                await runtime.stop(attempt.sessionId);
+        }
+    }
+    async function executeCommand(id, input, validate) {
+        validate?.();
+        if (closing)
+            throw new Error('Server is stopping.');
+        const requestId = text(input.id, 'request ID', 128);
+        const key = `delegation:${id}:${requestId}`;
+        const digest = JSON.stringify({ ...input, version: undefined, followUpToken: undefined });
+        const cached = store.get(key);
+        if (cached) {
+            if (cached.digest !== digest)
+                throw new Error('Request ID already used for a different task action.');
+            return cached.response;
+        }
+        const record = get(id);
+        const validateFollowUp = () => {
+            const attempt = record.attempts.find((a) => a.id === input.attemptId);
+            if (!attempt || record.attempts.findLast((a) => a.taskId === attempt.taskId) !== attempt)
+                throw new Error('Child attempt not found or has a newer attempt. Refresh child sessions.');
+            if (record.paused ||
+                attempt.queuePaused ||
+                attempt.cancelRequested ||
+                ['cancelled', 'failed', 'interrupted'].includes(attempt.status))
+                throw new Error('This task is paused or stopped. The user must resume it before coordinator follow-ups.');
+            if (input.followUpToken !== undefined
+                ? input.followUpToken !== followUpToken(id, attempt.id)
+                : input.version !== record.version)
+                throw new Error('Task state changed. Refresh before taking this action.');
+        };
+        if (input.type === 'delegation_reply' && input.coordinatorFollowUp === true)
+            validateFollowUp();
+        else if (input.version !== record.version)
+            throw new Error('Task state changed. Refresh before taking this action.');
+        if (!runtime.state(id)?.planning)
+            throw new Error('Task delegation is available in standalone sessions.');
+        let launchAcceptance;
+        if (input.type === 'delegation_task_settings') {
+            const state = runtime.state(id);
+            if (input.revision !== state.planning.revision)
+                throw new Error('Tasks changed. Refresh before changing settings.');
+            if (!state.planning.tasks.some((task) => task.id === input.taskId))
+                throw new Error('Task not found.');
+            if (record.attempts.some((a) => a.taskId === input.taskId))
+                throw new Error('Task already launched; its settings are frozen.');
+            const settings = input.settings;
+            if (settings !== null) {
+                if (!settings ||
+                    Object.keys(settings).some((key) => !['model', 'reasoningLevel', 'fastMode', 'permissionMode'].includes(key)) ||
+                    !['ask', 'auto'].includes(settings.permissionMode))
+                    throw new Error('Invalid task settings.');
+                const model = settings.model === undefined ? undefined : text(settings.model, 'model', 256);
+                const available = state.openaiAuth?.models?.find((item) => item.id === (model ?? state.model));
+                if (model !== undefined && !available)
+                    throw new Error('This model is unavailable for the current connection.');
+                if (settings.reasoningLevel !== undefined &&
+                    !available?.reasoningLevels?.includes(settings.reasoningLevel))
+                    throw new Error('This reasoning level is unavailable for the selected model.');
+                record.taskSettings = {
+                    ...record.taskSettings,
+                    [input.taskId]: {
+                        model,
+                        reasoningLevel: settings.reasoningLevel,
+                        fastMode: parseFastMode(settings.fastMode, available),
+                        permissionMode: settings.permissionMode,
+                    },
+                };
+            }
+            else if (record.taskSettings)
+                delete record.taskSettings[input.taskId];
+        }
+        else if (input.type === 'delegation_agent_launch') {
+            const board = runtime.state(id).planning;
+            if (input.revision !== board.revision)
+                throw new Error('Tasks changed. Read get_tasks again and preserve current edits.');
+            const selected = new Map();
+            const visiting = new Set();
+            const visit = (taskId, prerequisite = false) => {
+                if (selected.has(taskId))
+                    return;
+                if (visiting.has(taskId))
+                    throw new Error('Task prerequisites contain a cycle. Update tasks first.');
+                const task = board.tasks.find((task) => task.id === taskId);
+                if (!task || task.status !== 'ready' || !task.criteria.trim())
+                    throw new Error(`Task ${taskId} is missing, deferred, or not ready. Read get_tasks and resolve its scope first.`);
+                if (board.questions.some((q) => q.blocking && !q.answer.trim() && (!q.taskIds?.length || q.taskIds.includes(taskId))))
+                    throw new Error(`Answer blocking questions for ${task.title} first.`);
+                const previous = record.attempts.findLast((attempt) => attempt.taskId === taskId);
+                if (previous) {
+                    if (prerequisite &&
+                        (!record.paused ||
+                            previous.resumeRequested ||
+                            previous.status === 'done' ||
+                            live(previous)) &&
+                        !previous.queuePaused &&
+                        !previous.cancelRequested &&
+                        (unfinished(previous) || previous.status === 'done'))
+                        return;
+                    throw new Error(`Task ${taskId} already has attempt ${previous.id} (${previous.status}). Inspect progress; stopped work requires explicit user action, and completed work is not rerun.`);
+                }
+                visiting.add(taskId);
+                for (const dependency of task.dependencies ?? [])
+                    visit(dependency, true);
+                visiting.delete(taskId);
+                selected.set(taskId, task);
+            };
+            for (const taskId of input.taskIds)
+                visit(taskId);
+            if (record.attempts.length + selected.size > 100)
+                throw new Error('Attempt capacity reached (100). Start another coordinator.');
+            const before = record.attempts.length;
+            await launch(id, {
+                ...input,
+                taskIds: [...selected.keys()],
+                workspaceMode: 'coordinator',
+                concurrency: capacity.limit,
+                taskSettings: [...selected.keys()]
+                    .filter((taskId) => record.taskSettings?.[taskId])
+                    .map((taskId) => ({ taskId, ...record.taskSettings[taskId] })),
+            });
+            launchAcceptance = {
+                acceptance: 'queued',
+                requestKey: input.requestKey,
+                attempts: record.attempts
+                    .slice(before)
+                    .map((a) => ({ taskId: a.taskId, attemptId: a.id, sessionId: a.sessionId })),
+            };
+        }
+        else if (input.type === 'delegation_launch') {
+            await launch(id, input);
+            record.agentLaunchPaused = false;
+        }
+        else if (input.type === 'delegation_pause') {
+            record.agentLaunchPaused = true;
+            record.paused = true;
+            for (const attempt of record.attempts) {
+                attempt.resumeRequested = false;
+                attempt.userRequestedCapacity = false;
+            }
+        }
+        else if (input.type === 'delegation_resume') {
+            if (!runtime.state(id)?.configured)
+                throw new Error('Reconnect a model before resuming dispatch.');
+            record.paused = false;
+            record.agentLaunchPaused = false;
+            for (const attempt of record.attempts.filter((item) => item.status === 'queued'))
+                attempt.queuePaused = false;
+        }
+        else if (input.type === 'delegation_stop_all') {
+            record.agentLaunchPaused = true;
+            record.paused = true;
+            for (const attempt of record.attempts.filter(unfinished))
+                await stopAttempt(attempt);
+        }
+        else {
+            const attempt = record.attempts.find((a) => a.id === input.attemptId);
+            if (!attempt)
+                throw new Error('Task attempt not found in this coordinator.');
+            if (attempt.pendingHandoffs?.length &&
+                ([
+                    'delegation_reply',
+                    'delegation_resume_replies',
+                    'delegation_discard_replies',
+                    'delegation_retry',
+                ].includes(input.type) ||
+                    ([
+                        'delegation_edit_reply',
+                        'delegation_reorder_reply',
+                        'delegation_remove_reply',
+                        'delegation_send_reply',
+                    ].includes(input.type) &&
+                        attempt.pendingHandoffs.includes(input.messageId))))
+                throw new Error('Retry the pending session handoff from its message menu first.');
+            if ([
+                'delegation_reply',
+                'delegation_retry',
+                'delegation_edit_reply',
+                'delegation_reorder_reply',
+                'delegation_remove_reply',
+                'delegation_send_reply',
+                'delegation_resume_replies',
+            ].includes(input.type) &&
+                record.attempts.findLast((a) => a.taskId === attempt.taskId) !== attempt)
+                throw new Error('This task has a newer attempt. Continue in its conversation.');
+            if (input.type === 'delegation_stop')
+                await stopAttempt(attempt, false);
+            else if (input.type === 'delegation_reply') {
+                const reply = await prepareReply(input);
+                validate?.();
+                if (input.coordinatorFollowUp === true)
+                    validateFollowUp();
+                if (attempt.replies.length >= 20)
+                    throw new Error('Queue is full (20 messages per task).');
+                if (input.interrupt === true)
+                    attempt.replies.unshift(reply);
+                else
+                    attempt.replies.push(reply);
+                await resumeReplies(attempt, input.interrupt === true);
+                if (input.userRequested === true)
+                    attempt.userRequestedCapacity = true;
+            }
+            else if (input.type === 'delegation_edit_reply') {
+                const reply = attempt.replies.find((item) => item.id === input.messageId);
+                if (!reply)
+                    throw new Error('Queued message no longer exists.');
+                if (input.expectedPrompt !== reply.prompt)
+                    throw new Error('Queued message changed. Reopen it to edit the latest version.');
+                if (input.attachments !== undefined &&
+                    JSON.stringify(input.expectedAttachments) !== JSON.stringify(reply.attachments ?? []))
+                    throw new Error('Queued attachments changed. Reopen the message to edit the latest version.');
+                const updated = await prepareReply({
+                    ...input,
+                    attachments: input.attachments ?? reply.attachments,
+                });
+                // A child may finish preparing its first turn while attachment validation awaits IO.
+                if (!attempt.replies.includes(reply))
+                    throw new Error('Queued message no longer exists.');
+                Object.assign(reply, updated, { id: reply.id, createdAt: reply.createdAt });
+            }
+            else if (input.type === 'delegation_reorder_reply') {
+                const expectedIds = input.expectedIds;
+                if (!Array.isArray(expectedIds) ||
+                    expectedIds.length !== attempt.replies.length ||
+                    expectedIds.some((id, index) => id !== attempt.replies[index]?.id))
+                    throw new Error('Queue order changed. Reopen the queue before moving this message.');
+                const fromIndex = attempt.replies.findIndex((item) => item.id === input.messageId);
+                if (fromIndex < 0)
+                    throw new Error('Queued message no longer exists.');
+                if (!Number.isInteger(input.toIndex) ||
+                    input.toIndex < 0 ||
+                    input.toIndex >= attempt.replies.length)
+                    throw new Error('Invalid queue position.');
+                const [reply] = attempt.replies.splice(fromIndex, 1);
+                attempt.replies.splice(input.toIndex, 0, reply);
+            }
+            else if (input.type === 'delegation_remove_reply' ||
+                input.type === 'delegation_send_reply') {
+                const index = attempt.replies.findIndex((item) => item.id === input.messageId);
+                if (index < 0)
+                    throw new Error('Queued message no longer exists.');
+                const [reply] = attempt.replies.splice(index, 1);
+                if (input.type === 'delegation_remove_reply')
+                    attempt.userRequestedCapacity = false;
+                if (input.type === 'delegation_send_reply') {
+                    attempt.replies.unshift(reply);
+                    await resumeReplies(attempt, true);
+                    if (input.userRequested === true)
+                        attempt.userRequestedCapacity = true;
+                }
+            }
+            else if (input.type === 'delegation_resume_replies') {
+                if (!runtime.state(id)?.configured)
+                    throw new Error('Reconnect a model before resuming this task.');
+                await resumeReplies(attempt);
+                if (input.userRequested === true)
+                    attempt.userRequestedCapacity = true;
+            }
+            else if (input.type === 'delegation_discard_replies') {
+                if (!['failed', 'interrupted', 'cancelled'].includes(attempt.status))
+                    throw new Error('Only terminal attempts can discard unexecuted replies.');
+                store.put(`discarded-replies:${attempt.id}:${record.version}`, attempt.replies);
+                attempt.replies = [];
+            }
+            else if (input.type === 'delegation_accept') {
+                // Older clients may still acknowledge an already completed task.
+                if (attempt.status !== 'done')
+                    throw new Error('Task has not completed.');
+            }
+            else if (input.type === 'delegation_retry') {
+                if (!['failed', 'interrupted', 'cancelled'].includes(attempt.status))
+                    throw new Error('Only failed, interrupted, or cancelled tasks can be retried.');
+                if (runtime.state(attempt.sessionId)?.runs.some((r) => r.status === 'running') ||
+                    live(attempt))
+                    throw new Error('Stop the previous worker before retrying.');
+                if (record.attempts.length >= 100)
+                    throw new Error('Attempt limit reached.');
+                const retry = {
+                    ...structuredClone(attempt),
+                    id: randomUUID(),
+                    sessionId: randomUUID(),
+                    status: 'queued',
+                    createdAt: new Date().toISOString(),
+                    cancelRequested: false,
+                    replies: [],
+                    pendingHandoffs: [],
+                    resumeRequested: false,
+                    userRequestedCapacity: false,
+                    activeRunId: undefined,
+                    requestId: undefined,
+                    error: undefined,
+                    result: undefined,
+                    question: undefined,
+                    branch: undefined,
+                    workspace: undefined,
+                    outputCommit: undefined,
+                    dirty: undefined,
+                    usage: undefined,
+                    latestActivity: undefined,
+                    logs: undefined,
+                    logsTruncated: undefined,
+                    completedAt: undefined,
+                    queuePaused: false,
+                    pendingApprovals: 0,
+                    approvals: [],
+                    acceptedAt: undefined,
+                };
+                record.attempts.push(retry);
+                for (const pending of record.attempts.filter((a) => a.status === 'queued'))
+                    pending.dependencyAttempts = pending.dependencyAttempts.map((dep) => dep === attempt.id ? retry.id : dep);
+            }
+            else if (input.type === 'delegation_reconcile') {
+                if (attempt.status !== 'interrupted')
+                    throw new Error('Only interrupted attempts need reconciliation.');
+                const state = runtime.state(attempt.sessionId), run = state?.runs.at(-1);
+                if (!confirmedCompletion(attempt, state))
+                    throw new Error('No confirmed completed run. Inspect external effects and use explicit Retry if appropriate.');
+                attempt.activeRunId = run.id;
+                await finish(attempt, state);
+            }
+            else if (input.type === 'delegation_base') {
+                if (attempt.workspaceMode === 'coordinator')
+                    throw new Error('Shared tasks use the coordinator checkout; a separate base cannot be selected.');
+                if (attempt.status !== 'queued' || attempt.workspace || !options.isGit)
+                    throw new Error('Choose a committed base before the child workspace is created.');
+                // Optional explicit override. Otherwise dispatch uses the commit pinned at approval,
+                // regardless of uncommitted or unmerged prerequisite changes.
+                attempt.baseCommit = await runtime.resolveBase(text(input.baseRef, 'base', 200));
+            }
+            else
+                throw new Error('Unknown delegation command.');
+        }
+        const response = launchAcceptance ?? { ok: true };
+        store.transaction(() => {
+            record.version++;
+            store.put('delegations', records);
+            store.put(key, { digest, response });
+            store.event({
+                type: 'delegation',
+                text: input.type,
+                data: { coordinatorId: id, version: record.version },
+            });
+        });
+        runtime.notify(id, input.type.replace('delegation_', 'Task action: '));
+        for (const attempt of record.attempts)
+            runtime.notify(attempt.sessionId);
+        return response;
+    }
+    function confirmedCompletion(attempt, state) {
+        const run = state?.runs.at(-1);
+        return (run?.status === 'completed' && !!attempt.requestId && run.taskRequestId === attempt.requestId);
+    }
+    async function finish(attempt, state) {
+        const run = state.runs.at(-1);
+        if (!run || run.status === 'running')
+            return;
+        if (run.status === 'completed')
+            attempt.error = undefined;
+        if (attempt.cancelRequested)
+            attempt.status = 'cancelled';
+        else if (attempt.replies.length &&
+            (run.status === 'completed' || (!attempt.queuePaused && attempt.interruptForReply))) {
+            attempt.status = 'queued';
+            attempt.interruptForReply = false;
+            attempt.question = undefined;
+            attempt.result = undefined;
+        }
+        else if (run.status === 'completed') {
+            attempt.result = run.taskResult ?? {
+                summary: state.events
+                    .filter((e) => e.runId === run.id && e.type === 'text')
+                    .map((e) => e.text ?? '')
+                    .join('')
+                    .slice(-8000) || 'Run completed without a structured result.',
+                changedAreas: 'Inspect the child workspace.',
+                verification: 'No structured verification report was provided.',
+                unresolved: 'Review against the acceptance criteria.',
+            };
+            attempt.question = run.taskQuestion;
+            attempt.status = run.taskQuestion ? 'waiting' : 'done';
+            if (attempt.status === 'done')
+                attempt.completedAt = new Date().toISOString();
+            try {
+                const info = await runtime.inspect(attempt.sessionId);
+                attempt.outputCommit = info.commit;
+                attempt.dirty = info.dirty;
+            }
+            catch {
+                /* Workspace may have been removed. The child remains inspectable as unavailable. */
+            }
+        }
+        else {
+            attempt.status =
+                run.status === 'stopped'
+                    ? 'cancelled'
+                    : run.status === 'interrupted'
+                        ? 'interrupted'
+                        : 'failed';
+            attempt.error = run.error;
+        }
+        if (['failed', 'interrupted', 'cancelled'].includes(attempt.status)) {
+            attempt.queuePaused = true;
+            attempt.question = undefined;
+            attempt.pendingApprovals = 0;
+        }
+        attempt.approvals = [];
+        attempt.pendingApprovals = 0;
+        if (attempt.status !== 'queued')
+            attempt.resumeRequested = false;
+        capacity.release(owner(attempt.sessionId));
+    }
+    async function dispatch(id, attempt) {
+        const record = get(id);
+        attempt.status = 'starting';
+        attempt.blockedReason = undefined;
+        save(id, `Starting ${attempt.task.title}`);
+        try {
+            if (!attempt.workspace) {
+                const created = await runtime.create(attempt.sessionId, attempt.task.title, {
+                    coordinatorId: id,
+                    taskId: attempt.taskId,
+                    attemptId: attempt.id,
+                    execution: attempt.execution,
+                    kind: attempt.kind,
+                    baseCommit: attempt.baseCommit,
+                    model: attempt.model,
+                    reasoningLevel: attempt.reasoningLevel,
+                    fastMode: attempt.fastMode,
+                    workspaceMode: attempt.workspaceMode,
+                    permissionMode: attempt.permissionMode,
+                });
+                const child = runtime.state(attempt.sessionId);
+                if (!child)
+                    throw new Error('Created child is unavailable. Inspect before retrying.');
+                attempt.workspace = child.workspace;
+                attempt.branch =
+                    created?.branch ??
+                        (options.isGit && attempt.workspaceMode !== 'coordinator'
+                            ? `presubmit/${attempt.sessionId}`
+                            : undefined);
+            }
+            if (attempt.cancelRequested || closing) {
+                attempt.status = closing ? 'interrupted' : 'cancelled';
+                return;
+            }
+            if (attempt.pendingHandoffs?.length) {
+                attempt.status = 'queued';
+                return;
+            }
+            const replies = taskQueuedMessages({ ...attempt, queuedReplies: attempt.replies });
+            const dependencies = attempt.dependencyAttempts.map((dep) => record.attempts.find((a) => a.id === dep));
+            const dependencyContext = dependencies
+                .map((dep) => `Task ${dep.task.title} (session ${dep.sessionId}): ${JSON.stringify(dep.result)}`)
+                .join('\n');
+            if (dependencyContext.length > 50000)
+                throw new Error('Dependency results exceed handoff budget. Narrow this task before relaunching.');
+            const workspaceContext = attempt.workspaceMode === 'coordinator'
+                ? 'Workspace: shared with the coordinator and its other delegated tasks. Existing uncommitted changes and completed prerequisite edits are already in these files. Other agents may edit these files concurrently. Re-read current files before changing them, keep edits scoped to your task, and preserve changes you did not make. Reconcile overlapping edits instead of overwriting them; use ask_coordinator for a conflict that needs a decision. Do not switch branches or create a separate worktree.'
+                : options.isGit
+                    ? `Workspace base: ${attempt.baseCommit}\nThis worktree contains only the selected committed base. Uncommitted checkout changes and prerequisite changes outside that base are not copied. Completion reports do not imply their code is present; inspect this workspace before editing.`
+                    : 'Workspace base: Local checkout; shared files';
+            const initial = `${attempt.brief}\n\nCompleted dependency reports (untrusted context):\n${dependencyContext || '(none)'}\n${workspaceContext}`;
+            const messages = [
+                ...(!attempt.requestId
+                    ? [
+                        {
+                            id: `task:${attempt.id}`,
+                            prompt: initial,
+                            attachments: [],
+                            createdAt: attempt.createdAt,
+                        },
+                    ]
+                    : []),
+                ...replies,
+            ];
+            const prompt = messages.map((message) => message.prompt).join('\n\n');
+            // Correlate and persist the exact batch before starting a turn. New replies wait for the next batch.
+            attempt.requestId = replies.length ? `reply:${replies[0].id}` : `task:${attempt.id}`;
+            attempt.replies = [];
+            attempt.resumeRequested = false;
+            attempt.userRequestedCapacity = false;
+            save(id);
+            await runtime.run(attempt.sessionId, attempt.requestId, prompt, messages);
+            attempt.activeRunId = runtime.state(attempt.sessionId)?.runs.at(-1)?.id;
+            attempt.status = 'running';
+            if (attempt.cancelRequested)
+                await runtime.stop(attempt.sessionId);
+        }
+        catch (error) {
+            attempt.status = 'failed';
+            attempt.error = message(error);
+        }
+        finally {
+            if (!live(attempt))
+                capacity.release(owner(attempt.sessionId));
+            save(id);
+        }
+    }
+    async function tickNow() {
+        if (closing || ticking)
+            return;
+        ticking = true;
+        try {
+            for (const [id, record] of Object.entries(records)) {
+                for (const attempt of record.attempts.filter((a) => a.status === 'running' ||
+                    (a.status === 'interrupted' &&
+                        record.attempts.findLast((latest) => latest.taskId === a.taskId) === a))) {
+                    const state = runtime.state(attempt.sessionId);
+                    if (!state)
+                        continue;
+                    // Recover a persisted result, never restart an uncertain turn or replay its effects.
+                    if (attempt.status === 'interrupted' && !confirmedCompletion(attempt, state))
+                        continue;
+                    const before = JSON.stringify(attempt);
+                    const next = structuredClone(attempt);
+                    const run = state.runs.at(-1);
+                    if (attempt.status === 'interrupted')
+                        next.activeRunId = run.id;
+                    next.approvals = state.approvals
+                        .filter((a) => run?.status === 'running' && a.status === 'pending' && a.runId === run.id)
+                        .map((approval) => ({ ...approval }));
+                    next.pendingApprovals = next.approvals.length;
+                    next.usage = state.runs.reduce((sum, r) => ({
+                        input: sum.input + (r.usage?.input ?? 0),
+                        output: sum.output + (r.usage?.output ?? 0),
+                        cacheRead: sum.cacheRead + (r.usage?.cacheRead ?? 0),
+                        cacheWrite: sum.cacheWrite + (r.usage?.cacheWrite ?? 0),
+                    }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+                    next.logs = taskLogs(state.events);
+                    next.logsTruncated =
+                        state.events.length >= 500 ||
+                            state.events.filter((event) => (event.text || event.toolName || event.type.startsWith('tool_')) &&
+                                !['command', 'task_progress'].includes(event.type)).length > next.logs.length ||
+                            next.logs.some((event) => !!event.data?.textTruncated);
+                    next.latestActivity = state.events
+                        .filter((e) => e.text && e.type !== 'command' && e.type !== 'reasoning')
+                        .at(-1)
+                        ?.text?.slice(-500);
+                    next.question = run?.taskQuestion;
+                    await finish(next, state);
+                    if (before !== JSON.stringify(next)) {
+                        const semantic = next.status !== attempt.status || next.question !== attempt.question;
+                        Object.assign(attempt, next);
+                        save(id, next.status !== 'running' ? `${next.task.title}: ${next.status}` : undefined, semantic);
+                    }
+                }
+                // A progress broadcast updates browsers but cannot wake an idle coordinator.
+                // Use the parent's durable, idempotent queue after the child finishes asking.
+                for (const attempt of record.attempts) {
+                    if (!runtime.report ||
+                        record.paused ||
+                        attempt.queuePaused ||
+                        attempt.status !== 'waiting' ||
+                        !attempt.question ||
+                        !attempt.activeRunId)
+                        continue;
+                    const receipt = `task-question:${attempt.id}:${attempt.activeRunId}`;
+                    if (store.get(receipt))
+                        continue;
+                    try {
+                        await runtime.report(id, receipt, `Task ${attempt.task.title} is waiting for an answer (attemptId: ${attempt.id}, sessionId: ${attempt.sessionId}).\n` +
+                            `${childCollaborationGuidance}\nAttributed child question:\n${attempt.question}\n\n` +
+                            'Inspect get_child_sessions for current status, version and followUpToken; re-evaluate whether this question is still unresolved and the target eligible. Resolve routine questions within authorized scope yourself; ask the user only for essential missing intent. Use send_child_message with a stable requestKey to queue the answer. Reuse the key after uncertain responses; never resend an accepted reply for an old notification. Accepted/queued is not running/done and does not prove delivery or execution. Do not resume explicitly paused/stopped/failed/interrupted work.');
+                        store.put(receipt, true);
+                    }
+                    catch {
+                        // Keep the waiting question pending when the parent is unavailable or full.
+                    }
+                }
+                for (const attempt of record.attempts.filter((a) => a.status === 'queued')) {
+                    if (attempt.pendingHandoffs?.length ||
+                        attempt.queuePaused ||
+                        (record.paused && !attempt.resumeRequested))
+                        continue;
+                    // Removing the last follow-up must not create an empty turn or repeat the old brief.
+                    if (attempt.requestId && !attempt.replies.length) {
+                        const child = runtime.state(attempt.sessionId);
+                        if (child?.runs.at(-1)?.status === 'running')
+                            continue;
+                        if (child?.runs.length)
+                            await finish(attempt, child);
+                        else {
+                            attempt.status = 'interrupted';
+                            attempt.error = 'The previous task run is unavailable.';
+                        }
+                        save(id);
+                        continue;
+                    }
+                    const dependencies = attempt.dependencyAttempts.map((dep) => record.attempts.find((a) => a.id === dep));
+                    const reason = runtime
+                        .state(attempt.sessionId)
+                        ?.runs.some((run) => run.status === 'running')
+                        ? 'Waiting for the previous turn to finish.'
+                        : dependencies.some((a) => a?.status !== 'done')
+                            ? 'Waiting for dependencies to finish.'
+                            : undefined;
+                    if (reason) {
+                        if (attempt.blockedReason !== reason) {
+                            attempt.blockedReason = reason;
+                            save(id);
+                        }
+                        continue;
+                    }
+                    if (!capacity.acquire(owner(attempt.sessionId), owner(id), attempt.userRequestedCapacity)) {
+                        const reason = capacity.blockedReason(owner(attempt.sessionId), owner(id));
+                        if (attempt.blockedReason !== reason) {
+                            attempt.blockedReason = reason;
+                            save(id);
+                        }
+                        continue;
+                    }
+                    const promise = dispatch(id, attempt);
+                    creating.add(promise);
+                    void promise.finally(() => creating.delete(promise));
+                }
+            }
+        }
+        finally {
+            ticking = false;
+        }
+    }
+    const tick = () => {
+        const operation = commandTail.then(tickNow);
+        commandTail = operation.catch(() => { });
+        return operation;
+    };
+    async function handoffQueued(id, input, send) {
+        if (closing)
+            throw new Error('Server is stopping.');
+        const key = `task-handoff:${id}:${text(input.id, 'request ID', 128)}`;
+        const digest = JSON.stringify(input);
+        const receipt = store.get(key);
+        if (receipt) {
+            if (receipt !== digest)
+                throw new Error('Request ID already used for a different handoff.');
+            return;
+        }
+        const record = get(id);
+        const attempt = record.attempts.find((item) => item.id === input.attemptId);
+        if (!attempt || record.attempts.findLast((item) => item.taskId === attempt.taskId) !== attempt)
+            throw new Error('This task has a newer attempt. Continue in its conversation.');
+        const message = taskQueuedMessages({ ...attempt, queuedReplies: attempt.replies }).find((item) => item.id === input.launch.message.id);
+        if (!message)
+            throw new Error('Queued message no longer exists; check its destination session.');
+        if (JSON.stringify(message) !== JSON.stringify(input.launch.message))
+            throw new Error('Queued message changed. Reopen its menu to launch the latest version.');
+        attempt.pendingHandoffs = [...new Set([...(attempt.pendingHandoffs ?? []), message.id])];
+        save(id);
+        try {
+            await send();
+        }
+        catch (error) {
+            attempt.queuePaused = true;
+            save(id);
+            throw error;
+        }
+        attempt.replies = attempt.replies.filter((reply) => reply.id !== message.id);
+        attempt.pendingHandoffs = attempt.pendingHandoffs.filter((item) => item !== message.id);
+        record.version++;
+        store.transaction(() => {
+            store.put(key, digest);
+            store.put('delegations', records);
+        });
+        runtime.notify(id);
+        for (const child of record.attempts)
+            runtime.notify(child.sessionId);
+    }
+    const timer = setInterval(() => {
+        void tick().catch(() => {
+            /* Durable intents stay visible; the next tick reconciles state. */
+        });
+    }, 250);
+    timer.unref();
+    return {
+        bridge(id) {
+            return {
+                view: () => view(id),
+                followUpToken: (attemptId) => followUpToken(id, attemptId),
+                questionPending: (receipt) => questionPending(id, receipt),
+                validatePlan: (board) => validatePlan(id, board),
+                command: (input, validate) => {
+                    const next = commandTail.then(() => executeCommand(id, input, validate));
+                    commandTail = next.catch(() => { });
+                    return next;
+                },
+                handoffQueued: (input, send) => {
+                    const next = commandTail.then(() => handoffQueued(id, input, send));
+                    commandTail = next.catch(() => { });
+                    return next;
+                },
+            };
+        },
+        view,
+        active: () => Object.values(records).some((record) => record.attempts.some((a) => live(a) || ((!record.paused || a.resumeRequested) && a.status === 'queued'))),
+        busy: (id) => Object.entries(records).some(([key, record]) => record.attempts.some((a) => (!id || key === id || a.sessionId === id) &&
+            ['queued', 'starting', 'running', 'waiting'].includes(a.status))),
+        tick,
+        async close() {
+            closing = true;
+            clearInterval(timer);
+            await commandTail;
+            await Promise.allSettled(creating);
+            for (const record of Object.values(records))
+                for (const attempt of record.attempts)
+                    capacity.release(owner(attempt.sessionId));
+        },
+    };
+}