visionclaw 0.1.219-dev.codex-issue-2805-worker-runtime.2 → 0.1.219-dev.codex-fix-2941-activity-foreground.1

package/dist/threads/thread-task-runtime.js

@@ -0,0 +1,896 @@
+/**
+ * ThreadTaskRuntime (issue #1996, PR 3): the one object the live loop talks
+ * to. It owns this process's {@link ThreadTaskStore} and
+ * {@link ThreadTaskController} for the thread it serves — the default thread
+ * in the main process, a business thread in its worker.
+ *
+ * Hot-path rule: every method is fail-safe. A store, controller or model
+ * error is logged and swallowed; it must never break message handling, a
+ * wake or a reply. The cost of a failure is a missed task update that the
+ * next run can still recover from the persisted events, never a lost message.
+ */
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { getConfigDir } from "../config/index.js";
+import { DEFAULT_THREAD_ID } from "../channels/interface.js";
+import { getMessageDedupKey } from "../channels/message-dedup.js";
+import { EXTERNAL_WAKE_KIND } from "../channels/queue.js";
+import { logger } from "../logger.js";
+import { OPEN_TASK_STATUSES } from "./task-contracts.js";
+import { createSidecarModel } from "./task-sidecar.js";
+import { ThreadTaskStore, messageEventKey } from "./task-store.js";
+import { ThreadTaskController } from "./thread-task-controller.js";
+import { renderThreadTaskContext } from "./thread-task-context.js";
+import { taskContinuationRouting } from "../agent/reply-target.js";
+/** Execution events are batched harder than owner messages; each run is a model call. */
+const LIVE_CONTROLLER_DEFAULTS = {
+    batchDelayMs: 30_000,
+    maxBatchEvents: 40,
+    callTimeoutMs: 60_000,
+    budget: { maxCalls: 12, windowMs: 10 * 60_000 },
+    // Execution events alone never use the last 4 calls of the window, so an
+    // owner message still gets a run during a long busy wake.
+    ownerReserve: 4,
+};
+/**
+ * How long a fast reply waits for the sidecar before it settles for
+ * "received". Added in front of the fast responder's own 5 s budget.
+ */
+export const REGISTRATION_WAIT_MS = 6_000;
+/**
+ * How long a lifecycle boundary waits for the sidecar to catch up (#1996 PR 4).
+ * Wake end is short because the next message waits behind it; compaction
+ * and refresh are already slow.
+ */
+export const RECONCILE_WAIT_MS = { wakeEnd: 5_000, boundary: 10_000 };
+/** Newest unfolded events read for the context block. */
+const UNFOLDED_CONTEXT_EVENTS = 200;
+/** `meta.kind` of a queued resume (PR 5). A system row: no fast reply, watchdog or gate reply. */
+export const TASK_RESUME_KIND = "thread-task-resume";
+const RESUME_SENDER = "thread-task-resume";
+/**
+ * At most this many resumes are queued per pass. One wake works one task at
+ * a time; the next pass after it queues the next one.
+ */
+const RESUMES_PER_PASS = 1;
+/** Unfolded events read at `/stop` to tell pre-stop tasks from later ones. */
+const STOP_EVENTS = 1_000;
+/** A resume pass waits for the sidecar to catch up; if it cannot, it retries after this. */
+export const RESUME_RETRY_MS = 60_000;
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class ThreadTaskRuntime {
+    threadId;
+    store;
+    controller;
+    /**
+     * Latest event seq when this process started. A task whose last committed
+     * change came from events up to here was moved by a previous process.
+     */
+    startSeq;
+    /** Resumes this process accepted, by task id: a resume runs once per task per process. Released when its message goes back on the queue. */
+    resumesAccepted = new Set();
+    closed = false;
+    resumeHooks = null;
+    resumeRetry = null;
+    resumeRunning = false;
+    constructor(threadId, store, controller, startSeq, inProgressAtStart) {
+        this.threadId = threadId;
+        this.store = store;
+        this.controller = controller;
+        this.startSeq = startSeq;
+        if (inProgressAtStart > 0) {
+            logger.system(`[thread-tasks] thread=${threadId}: ${inProgressAtStart} task(s) were in progress when the previous process stopped`);
+        }
+    }
+    /**
+     * Open the thread's store next to its queue.db, take the writer slot and
+     * start the controller (which picks up events a previous process left).
+     * Returns null instead of throwing: without a runtime the agent runs
+     * exactly as before.
+     */
+    static start(options) {
+        let store;
+        try {
+            store = new ThreadTaskStore({
+                threadId: options.threadId,
+                writerId: options.writerId,
+                // Same file the MessageQueue owner opens, whichever process this is.
+                dbPath: options.dbPath ?? path.join(getConfigDir(), "queue.db"),
+                claimWriter: true,
+            });
+            // Read before the controller starts: it may move these tasks on, and
+            // nothing after start() may throw and leave its timer running.
+            const startSeq = store.latestSeq();
+            const inProgressAtStart = store.listTasks(["in_progress"]).length;
+            const controller = new ThreadTaskController({
+                store,
+                model: options.model ?? createSidecarModel(options.config),
+                ...LIVE_CONTROLLER_DEFAULTS,
+                ...options.controller,
+            });
+            const runtime = new ThreadTaskRuntime(options.threadId, store, controller, startSeq, inProgressAtStart);
+            controller.start();
+            return runtime;
+        }
+        catch (error) {
+            logger.err(`[thread-tasks] disabled for thread=${options.threadId}: ${errorMessage(error)}`);
+            try {
+                store?.close();
+            }
+            catch {
+                // Already closed or never opened.
+            }
+            return null;
+        }
+    }
+    /**
+     * Persist owner messages as events. Idempotent per message (queue dedup
+     * key), so a redelivered message, the watchdog and the wake path can all
+     * call it. Returns false if any message could not be recorded.
+     */
+    recordMessages(messages, options = {}) {
+        if (this.closed || messages.length === 0)
+            return !this.closed;
+        let ok = true;
+        let appended = false;
+        for (const msg of messages) {
+            try {
+                appended = this.store.appendMessageEvent(msg).appended || appended;
+            }
+            catch (error) {
+                ok = false;
+                logger.err(`[thread-tasks] could not record message ${msg.id} thread=${this.threadId}: ${errorMessage(error)}`);
+            }
+        }
+        if (appended && options.notify !== false)
+            this.safeNotify(true);
+        return ok;
+    }
+    /** Persist an execution event (response, tool result, todo update, status report). */
+    recordExecution(input) {
+        if (this.closed)
+            return;
+        try {
+            if (this.store.appendEvent(input).appended)
+                this.safeNotify(false);
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] could not record ${input.kind} thread=${this.threadId}: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * Record the messages, then wait up to `waitMs` for the sidecar to consume
+     * them. `registered` lists the open tasks the commit tied to these messages;
+     * empty means a reply may only acknowledge receipt.
+     *
+     * A run that started before these events cannot commit them (it snapshotted
+     * its batch), and a batch is a contiguous prefix, so the message may need
+     * more than one run: an execution-event backlog in front of it is folded
+     * first. The loop therefore waits for this message's events to be consumed,
+     * not for a single run, and stops as soon as the deadline passes or a run
+     * fails (the controller keeps retrying those events on its own schedule).
+     */
+    async registerMessages(messages, waitMs = REGISTRATION_WAIT_MS) {
+        const recorded = this.recordMessages(messages, { notify: false });
+        if (!recorded || this.closed)
+            return { recorded, registered: [] };
+        try {
+            const target = this.store.latestSeq();
+            const deadline = Date.now() + waitMs;
+            while (!this.isClosed() && this.store.getPosition() < target) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                let timer;
+                const timeout = new Promise((resolve) => { timer = setTimeout(() => { resolve("timeout"); }, remaining); });
+                const outcome = await Promise.race([this.controller.runOnce(), timeout]).finally(() => { clearTimeout(timer); });
+                // Only a commit or a conflict re-read is worth another pass; anything
+                // else (deadline, budget, fence, failure) is retried by the controller.
+                if (outcome === "timeout" || (outcome.status !== "committed" && outcome.status !== "conflict"))
+                    break;
+            }
+            return { recorded, registered: this.tasksForMessages(messages) };
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] registration run failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { recorded, registered: [] };
+        }
+    }
+    /** `close()` may run while a wait awaits; a method read is not narrowed away. */
+    isClosed() {
+        return this.closed;
+    }
+    /** Open tasks already tied to any of these messages (no model call). */
+    tasksForMessages(messages) {
+        try {
+            const eventIds = new Set();
+            for (const msg of messages) {
+                const event = this.store.getEventByKey(messageEventKey(getMessageDedupKey(msg)));
+                if (event)
+                    eventIds.add(event.id);
+            }
+            if (eventIds.size === 0)
+                return [];
+            return this.store.listOpenTasks().filter((task) => task.sourceEventIds.some((id) => eventIds.has(id)));
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] lookup failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return [];
+        }
+    }
+    /** Tasks of this thread for the query tool; `[]` on error. */
+    listTasks(statuses = OPEN_TASK_STATUSES) {
+        try {
+            return this.store.listTasks(statuses);
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] list failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return [];
+        }
+    }
+    /**
+     * Let the sidecar fold every event up to the latest one (the explicit
+     * position of this boundary), waiting at most `waitMs`. No events past the
+     * position means no model call. On timeout, budget exhaustion or failure
+     * the events simply stay unconsumed: the controller keeps retrying them,
+     * and {@link contextBlock} shows them raw to the next recovery.
+     */
+    async reconcile(phase, waitMs) {
+        let target = 0;
+        let position = 0;
+        try {
+            target = this.store.latestSeq();
+            position = this.store.getPosition();
+            const deadline = Date.now() + waitMs;
+            while (!this.closed && position < target) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                let timer;
+                const timeout = new Promise((resolve) => { timer = setTimeout(() => { resolve("timeout"); }, remaining); });
+                const outcome = await Promise.race([this.controller.runOnce(), timeout]).finally(() => { clearTimeout(timer); });
+                position = this.store.getPosition();
+                // Only a commit or a conflict re-read is worth another pass; anything
+                // else (timeout, budget, failure, fence) is retried by the controller.
+                if (outcome === "timeout" || (outcome.status !== "committed" && outcome.status !== "conflict"))
+                    break;
+            }
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] ${phase} reconcile failed thread=${this.threadId}: ${errorMessage(error)}`);
+        }
+        if (position < target) {
+            logger.info(`[thread-tasks] ${phase} reconcile left ${target - position} event seq(s) unfolded thread=${this.threadId}`);
+        }
+        return { reached: position >= target, target, position };
+    }
+    /**
+     * Tasks a previous process left `in_progress`: their last change came from
+     * events recorded before this process started. That includes a task those
+     * events only move to `in_progress` when this process folds them at
+     * startup (the sidecar batches, so a crash usually leaves some). Once this
+     * process's own events move the task, it is no longer interrupted.
+     * TODO: a startup fold whose batch also holds events of this process
+     * stamps the task with the later seq and drops the flag early.
+     */
+    interruptedTaskIds() {
+        return new Set(this.store.listTasks(["in_progress"])
+            .filter((task) => task.lastEventSeq <= this.startSeq)
+            .map((task) => task.id));
+    }
+    /** The recovery context for this thread, or null when it owes nothing. Never throws. */
+    contextBlock() {
+        try {
+            const position = this.store.getPosition();
+            return renderThreadTaskContext({
+                openTasks: this.store.listOpenTasks(),
+                unfoldedEvents: this.store.readLatestEventsAfter(position, UNFOLDED_CONTEXT_EVENTS),
+                unfoldedTotal: this.store.latestSeq() - position,
+                interruptedTaskIds: this.interruptedTaskIds(),
+            });
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] context unavailable thread=${this.threadId}: ${errorMessage(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Queue a resume for the next runnable task (PR 5), so the thread keeps
+     * working without a new owner message. Crash-safe in three steps:
+     * reserve the delivery record (`recovery:<task>:v<version>`), enqueue a
+     * system message whose id is that key, then mark it delivered. A crash
+     * before the enqueue leaves a reservation that the next pass re-sends; a
+     * crash after it is harmless because the queue dedups the id. A resume
+     * that was already delivered is never queued again for the same version.
+     *
+     * Never throws. Returns what it queued.
+     */
+    deliverResumes(queue, now = Date.now()) {
+        if (this.closed)
+            return { queued: [] };
+        const queued = [];
+        try {
+            // Re-send reservations a previous pass made but did not deliver.
+            for (const record of this.store.listUndeliveredRecoveries()) {
+                const task = this.store.getTask(record.taskId);
+                if (this.enqueueResume(queue, record.idempotencyKey, task, record.taskVersion))
+                    queued.push(record.idempotencyKey);
+            }
+            if (queued.length < RESUMES_PER_PASS) {
+                // Work the previous process left in progress comes first. Its resume
+                // may have been replayed already (then it is accepted and skipped).
+                const interrupted = [...this.interruptedTaskIds()]
+                    .filter((id) => !this.resumesAccepted.has(id))
+                    .map((id) => this.store.getTask(id))
+                    .filter((task) => task !== undefined);
+                for (const task of [...interrupted, ...this.store.listRunnableTasks(now)]) {
+                    if (queued.length >= RESUMES_PER_PASS)
+                        break;
+                    if (hasNoRemainingWork(task))
+                        continue;
+                    const reservation = this.store.reserveRecoveryDelivery({ taskId: task.id, taskVersion: task.version });
+                    if (!reservation.ok) {
+                        logger.warn(`[thread-tasks] resume not reserved thread=${this.threadId}: ${reservation.reason}`);
+                        break;
+                    }
+                    // Already delivered for this version: a wake took it and made no
+                    // recorded progress. Do not loop on it; progress bumps the version.
+                    if (!reservation.value.reserved)
+                        continue;
+                    if (this.enqueueResume(queue, reservation.value.record.idempotencyKey, task, task.version)) {
+                        queued.push(reservation.value.record.idempotencyKey);
+                    }
+                }
+            }
+            return { queued };
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] resume pass failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { queued };
+        }
+    }
+    /**
+     * Whether a dequeued resume may still run (the re-check before execution).
+     * Yes when its task is still pending at the version it was queued for and
+     * is due: a cancel, modification, wait or block since then makes it stale.
+     * Also yes, once per task per process, when a previous process left the
+     * task `in_progress` ({@link interruptedTaskIds}): that is a resume replayed
+     * after a crash, or one queued for the interrupted task. Its version is not
+     * compared, because folding the previous process's last events at startup
+     * bumps it.
+     *
+     * The "once" test is against {@link resumesAccepted}, which a requeue
+     * releases ({@link releaseResume}): an accepted resume whose message went
+     * back on the queue must still run when it is dequeued again, or the
+     * interrupted task keeps its only recovery row forever.
+     * Fail-closed: any error means no.
+     */
+    isResumeRunnable(msg, now = Date.now()) {
+        try {
+            const taskId = msg.meta?.taskId;
+            const taskVersion = msg.meta?.taskVersion;
+            if (typeof taskId !== "string" || typeof taskVersion !== "number")
+                return false;
+            const task = this.store.getTask(taskId);
+            if (!task || hasNoRemainingWork(task))
+                return false;
+            // Left in progress by a previous process: once, whatever the version.
+            if (task.status === "in_progress" && this.interruptedTaskIds().has(task.id)) {
+                return !this.resumesAccepted.has(task.id);
+            }
+            // Pending, or unfinished by an earlier wake of this process: unchanged
+            // since it was queued. Any progress, wait, block or cancel bumps the version.
+            return (task.status === "pending" || task.status === "in_progress")
+                && task.version === taskVersion
+                && (task.runAfter === undefined || task.runAfter <= now);
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] resume check failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return false;
+        }
+    }
+    /**
+     * The re-check at dequeue: {@link isResumeRunnable}, and if yes, record
+     * that this process is now working on the task so a second copy of its
+     * resume is stale.
+     */
+    acceptResume(msg, now = Date.now()) {
+        if (!this.isResumeRunnable(msg, now))
+            return false;
+        this.resumesAccepted.add(msg.meta?.taskId);
+        return true;
+    }
+    /**
+     * The resume was accepted but its message went back on the queue (a failed
+     * inject, an orphaned injection, a failed wake). Takes the acceptance back
+     * so the next dequeue may run it. Safe for any message: not a resume, or
+     * never accepted, does nothing. #2664 review P1-B.
+     */
+    releaseResume(messages) {
+        for (const msg of messages) {
+            const taskId = msg.meta?.taskId;
+            if (!isTaskResumeMessage(msg) || typeof taskId !== "string")
+                continue;
+            if (this.resumesAccepted.delete(taskId)) {
+                logger.info(`[thread-tasks] resume released back to the queue thread=${this.threadId} task=${taskId}`);
+            }
+        }
+    }
+    /** Install the loop's hooks. Resumes are only queued once this is set. */
+    enableResumes(hooks) {
+        this.resumeHooks = hooks;
+    }
+    /**
+     * The owner sent `/stop` (option B, owner 10-04): cancel every unfinished
+     * task of this thread. Cancelled is a stored status, so nothing queued
+     * starts on its own, a restart cannot bring it back, and resumes already
+     * queued are retired at dequeue.
+     *
+     * The open tasks are cancelled at once. A message sent just before
+     * `/stop` may not be folded yet: the sidecar then folds up to the stop
+     * (bounded by `waitMs`) and the tasks those events created are cancelled
+     * too. Tasks from messages after the `/stop` are kept. Returns every
+     * cancelled task, for the reply. Never throws.
+     * TODO: a fold that misses `waitMs` (or more than {@link STOP_EVENTS}
+     * unfolded events) can still create a task from a pre-stop message later.
+     */
+    async cancelOpenTasks(waitMs = RECONCILE_WAIT_MS.wakeEnd, queue) {
+        if (this.closed)
+            return { cancelled: [], droppedQueued: 0 };
+        let beforeStop;
+        let cancelled;
+        let droppedQueued = 0;
+        try {
+            // Queue rows first, at this boundary: a message the interrupt debounce
+            // has not recorded yet is not an event and owns no task, so nothing
+            // below would ever see it. Left in place, the next wake reads it as a
+            // new request and runs it (#2664 review P1-A).
+            droppedQueued = this.dropQueuedMessages(queue);
+            beforeStop = new Set(this.store.readUnconsumedEvents(STOP_EVENTS).map((event) => event.id));
+            cancelled = this.cancelTasks(this.store.listOpenTasks());
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] /stop cancel failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { cancelled: [], droppedQueued };
+        }
+        if (beforeStop.size === 0)
+            return { cancelled, droppedQueued };
+        await this.reconcile("stop", waitMs);
+        if (this.isClosed())
+            return { cancelled, droppedQueued };
+        try {
+            // A task's first source event is the one that created it.
+            const late = this.store.listOpenTasks().filter((task) => beforeStop.has(task.sourceEventIds[0] ?? ""));
+            return { cancelled: [...cancelled, ...this.cancelTasks(late)], droppedQueued };
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] /stop cancel failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { cancelled, droppedQueued };
+        }
+    }
+    /**
+     * Drop queued owner messages: rows not claimed by a wake, that are not
+     * system rows (a resume, or the stop command itself) and that the task
+     * sidecar would read as owner input. Returns how many were dropped.
+     * Fail-safe: a row that cannot be read is left alone.
+     */
+    dropQueuedMessages(queue) {
+        if (!queue)
+            return 0;
+        let dropped = 0;
+        for (const msg of queue.snapshot()) {
+            if (msg.channel === "system" || !isTaskRelevantMessage(msg))
+                continue;
+            try {
+                // Handled, not just removed: a provider retry of the same message
+                // would otherwise be accepted again as a request after the stop.
+                if (queue.remove(msg.id)) {
+                    queue.markHandled(msg);
+                    dropped += 1;
+                }
+            }
+            catch (error) {
+                logger.warn(`[thread-tasks] could not drop queued message ${msg.id} thread=${this.threadId}: ${errorMessage(error)}`);
+            }
+        }
+        if (dropped > 0)
+            logger.system(`[thread-tasks] /stop dropped ${dropped} queued message(s) thread=${this.threadId}`);
+        return dropped;
+    }
+    /**
+     * Commit `cancelled` for these tasks without consuming any event, so the
+     * sidecar still folds everything. Read and commit run in one synchronous
+     * stretch, so no sidecar commit lands between them; a sidecar call in
+     * flight hits a version conflict and re-reads.
+     */
+    cancelTasks(tasks) {
+        if (tasks.length === 0)
+            return [];
+        const position = this.store.getPosition();
+        const result = this.store.commit({
+            expectedPosition: position,
+            throughSeq: position,
+            changes: tasks.map((task) => ({ op: "update", taskId: task.id, expectedVersion: task.version, patch: { status: "cancelled" } })),
+        });
+        if (!result.ok) {
+            logger.warn(`[thread-tasks] /stop cancel rejected thread=${this.threadId}: ${result.reason} ${result.detail}`);
+            return [];
+        }
+        logger.system(`[thread-tasks] /stop cancelled ${tasks.length} task(s) thread=${this.threadId}`);
+        return [...tasks];
+    }
+    /**
+     * Close one open task of this thread for the agent's `close_thread_task`
+     * tool (#2822). The sidecar completes a task only with evidence from the
+     * batch it folds, so finished work it missed stayed open and kept being
+     * resumed; this is the explicit way out. Commits like {@link cancelTasks}:
+     * no event is consumed, and a sidecar call in flight hits a version
+     * conflict and re-reads. Never throws.
+     */
+    closeTask(input) {
+        if (this.closed)
+            return { ok: false, reason: "The task list is closed." };
+        try {
+            // Scoped to this thread: another thread's id is not found.
+            const task = this.store.getTask(input.taskId);
+            if (!task)
+                return { ok: false, reason: `No task with id ${input.taskId} in this thread.` };
+            if (task.status === "completed" || task.status === "cancelled") {
+                return { ok: false, reason: `Task ${task.id} is already ${task.status}.` };
+            }
+            const position = this.store.getPosition();
+            const result = this.store.commit({
+                expectedPosition: position,
+                throughSeq: position,
+                changes: [{ op: "update", taskId: task.id, expectedVersion: task.version, patch: {
+                            status: input.status,
+                            result: { summary: input.summary, evidence: [input.evidenceRef] },
+                            resumeCondition: null,
+                        } }],
+            });
+            if (!result.ok)
+                return { ok: false, reason: `Not closed: ${result.reason} ${result.detail}` };
+            logger.system(`[thread-tasks] agent closed task=${task.id} as ${input.status} thread=${this.threadId}`);
+            const closed = this.store.getTask(task.id);
+            return closed ? { ok: true, task: closed } : { ok: false, reason: `Task ${task.id} vanished after closing.` };
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] close failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { ok: false, reason: `Not closed: ${errorMessage(error)}` };
+        }
+    }
+    /**
+     * Fold the events up to now, then queue the next runnable task. Called at
+     * wake end and at startup; never throws and never blocks the caller's
+     * loop. Without the fold a task the wake just finished could still look
+     * pending, so a pass that cannot catch up delivers nothing and retries
+     * after {@link RESUME_RETRY_MS} instead. A fold that needs a slow sidecar
+     * call therefore starts the next task about a minute later, not at once.
+     */
+    async requestResume(waitMs = RECONCILE_WAIT_MS.wakeEnd) {
+        const hooks = this.resumeHooks;
+        if (!hooks || this.closed || this.resumeRunning)
+            return { queued: [] };
+        this.resumeRunning = true;
+        this.clearResumeRetry();
+        try {
+            const reconciled = await this.reconcile("wake_end", waitMs);
+            if (this.isClosed())
+                return { queued: [] };
+            // Events that arrived during the fold (another wake ran and ended; its
+            // own pass was dropped because this one was running) may cancel or
+            // finish the task this pass would queue: fold them first.
+            if (!reconciled.reached || this.store.latestSeq() > reconciled.target) {
+                this.scheduleResumeRetry();
+                return { queued: [] };
+            }
+            // Busy: usually a wake, whose end starts the next pass; but nightly
+            // maintenance is busy too and has no wake end, so retry either way.
+            if (hooks.isBusy() || hooks.isGated()) {
+                this.scheduleResumeRetry();
+                return { queued: [] };
+            }
+            const outcome = this.deliverResumes(hooks.queue);
+            if (outcome.queued.length > 0)
+                hooks.wake();
+            // By design (owner 10-03): a not-yet-due task waits; its due or
+            // unblock wake comes from the existing calendar / event-trigger
+            // messages to this thread. Thread tasks never schedule wakes.
+            return outcome;
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] resume request failed thread=${this.threadId}: ${errorMessage(error)}`);
+            return { queued: [] };
+        }
+        finally {
+            this.resumeRunning = false;
+        }
+    }
+    scheduleResumeRetry() {
+        if (this.closed || this.resumeRetry)
+            return;
+        this.resumeRetry = setTimeout(() => {
+            this.resumeRetry = null;
+            void this.requestResume();
+        }, RESUME_RETRY_MS);
+        this.resumeRetry.unref();
+    }
+    clearResumeRetry() {
+        if (this.resumeRetry)
+            clearTimeout(this.resumeRetry);
+        this.resumeRetry = null;
+    }
+    /** Enqueue one reserved resume and mark it delivered. False when nothing was handed over. */
+    enqueueResume(queue, key, task, version) {
+        if (!task) {
+            // TODO: a reservation whose task row is gone stays reserved; harmless,
+            // the next pass skips it again.
+            return false;
+        }
+        // `enqueue` returns false for an id it already holds or handled: that
+        // resume reached the queue before a crash, so marking it is still right.
+        queue.enqueue(resumeMessage(this.threadId, key, task, version));
+        const marked = this.store.markRecoveryDelivered(key);
+        if (!marked.ok) {
+            logger.warn(`[thread-tasks] resume ${key} queued but not marked thread=${this.threadId}: ${marked.reason}`);
+            return false;
+        }
+        this.recordExecution({
+            idempotencyKey: key,
+            kind: "recovery",
+            payload: { text: `Resumed: ${task.title}`, data: { taskId: task.id, taskVersion: version } },
+        });
+        logger.system(`[thread-tasks] queued resume thread=${this.threadId} task=${task.id} v${version}`);
+        return true;
+    }
+    /** Events not yet folded into tasks (the sidecar is behind or failing). */
+    pendingEventCount() {
+        try {
+            return this.store.readUnconsumedEvents(1_000).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async close(graceMs) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.clearResumeRetry();
+        try {
+            await this.controller.close(graceMs);
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] controller close failed thread=${this.threadId}: ${errorMessage(error)}`);
+        }
+        try {
+            this.store.close();
+        }
+        catch {
+            // Closing twice or after a failed open is harmless.
+        }
+    }
+    safeNotify(immediate) {
+        try {
+            this.controller.notify({ immediate });
+        }
+        catch (error) {
+            logger.warn(`[thread-tasks] notify failed thread=${this.threadId}: ${errorMessage(error)}`);
+        }
+    }
+}
+/**
+ * A task whose checkpoint lists nothing remaining and no blockers: the work
+ * is done but the sidecar did not complete it (no evidence in its batch).
+ * Resuming it only wakes the agent to find nothing to do (#2822). A task
+ * with no checkpoint yet has not been worked on, so it still resumes.
+ * TODO: a checkpoint that empties `remaining` too early stops auto-resume;
+ * the task stays open and visible in the context block.
+ */
+export function hasNoRemainingWork(task) {
+    return task.checkpoint?.remaining.length === 0 && task.checkpoint.blockers.length === 0;
+}
+/**
+ * The queue row for a resume. Its id is the delivery key, so the queue's
+ * own dedup refuses a second copy. `system` keeps it out of fast replies,
+ * the watchdog, activity cards and gate replies; the reply target travels
+ * with the task, not with this row.
+ */
+function resumeMessage(threadId, key, task, version) {
+    // Replies go where the task came from, like any task continuation.
+    const routing = task.replyTarget
+        ? taskContinuationRouting({ sender: RESUME_SENDER, delivery: task.replyTarget })
+        : { meta: {} };
+    return {
+        id: key,
+        channel: "system",
+        sender: RESUME_SENDER,
+        text: `[Thread task resume] Continue the queued task "${task.title}" (id ${task.id}). ` +
+            "Its requirements and checkpoint are in the Thread Tasks block. Check the checkpoint and results first; never redo a step listed as done. " +
+            "If it is no longer wanted or cannot start yet, report that instead of doing it.",
+        attachments: [],
+        timestamp: new Date().toISOString(),
+        ...routing,
+        meta: { ...routing.meta, kind: TASK_RESUME_KIND, taskId: task.id, taskVersion: version },
+        ...(threadId !== DEFAULT_THREAD_ID ? { threadId } : {}),
+    };
+}
+/** True for a queued thread-task resume row. */
+export function isTaskResumeMessage(msg) {
+    return msg.channel === "system" && msg.meta?.kind === TASK_RESUME_KIND;
+}
+/**
+ * The re-check before execution, at every place a wake takes rows off the
+ * queue: a resume whose task was cancelled, changed, put on hold or already
+ * started since it was queued is retired unexecuted. Without a runtime (the
+ * switch was turned off) every resume is stale. Returns true when retired.
+ */
+export function retireStaleResume(queue, runtime, msg) {
+    if (!isTaskResumeMessage(msg) || runtime?.acceptResume(msg) === true)
+        return false;
+    logger.system(`[thread-tasks] dropping stale resume ${msg.id}`);
+    queue.markHandled(msg);
+    return true;
+}
+/**
+ * Messages the task store tracks: anything from a real channel. System
+ * messages (heartbeats, internal continuations) and external-wake markers
+ * carry no owner request. Email and group chats are included; the sidecar
+ * decides whether they hold a request.
+ */
+export function isTaskRelevantMessage(msg) {
+    return msg.channel !== "system" && msg.meta?.kind !== EXTERNAL_WAKE_KIND;
+}
+/**
+ * The end-of-wake handoff (issue #1996 PR 1 rule): a claim is released as
+ * handled only after its message is a durable task event, so the follow-up
+ * belongs to the task store instead of vanishing with the queue row.
+ *
+ * Fail-safe: if recording fails the claims are still released. The agent
+ * already processed them in this wake; replaying them would redo the work.
+ * The error is logged. `handled` never means a task is completed.
+ */
+export function releaseClaimsAfterRecording(queue, runtime) {
+    if (runtime) {
+        try {
+            runtime.recordMessages(queue.currentCycleClaims().filter(isTaskRelevantMessage));
+        }
+        catch (error) {
+            logger.err(`[thread-tasks] could not record claims before release: ${errorMessage(error)}`);
+        }
+    }
+    queue.markAllInFlightHandled();
+}
+/**
+ * Wake end. A wake cut short by an engine failover restart leaves its claims
+ * in flight for the replacement process (issue #2519) and folds nothing.
+ * Otherwise release the claims, fold this wake's events into the
+ * checkpoints and queue the next runnable task (PR 5). Not awaited: the
+ * session keeps its transcript, so the loop need not hold the next message
+ * for it. Bounded; leftovers stay unconsumed and the next wake's context
+ * shows them raw.
+ */
+export function endWakeThreadTasks(queue, runtime, options) {
+    if (options.failoverRestartPending)
+        return;
+    releaseClaimsAfterRecording(queue, runtime);
+    void runtime?.requestResume();
+}
+/** Per-event caps; the sidecar clips again, this keeps the event log small. */
+const EXECUTION_TEXT_CHARS = 1_500;
+const TOOL_OUTPUT_CHARS = 400;
+function clipText(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}… [${text.length - max} more chars]`;
+}
+/**
+ * Provider tool-call ids are not unique for the life of a thread: some
+ * providers number them per response (`functions.notify_user:0`). A stream
+ * emits each result once, so the key only has to be unique; a process nonce
+ * plus a counter makes it so.
+ */
+const EXECUTION_KEY_NONCE = randomUUID().slice(0, 8);
+let executionKeySeq = 0;
+function executionKey(prefix, toolUseId) {
+    executionKeySeq += 1;
+    return `${prefix}:${toolUseId}:${EXECUTION_KEY_NONCE}-${executionKeySeq}`;
+}
+/** Tools whose results say nothing about task progress. */
+const NOISE_TOOLS = new Set(["wait", "finish", "TodoWrite", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]);
+function baseToolName(name) {
+    return name.replace(/^mcp__[^_]+(?:_[^_]+)*__/, "");
+}
+/**
+ * Engine-neutral execution events. Both engines feed the same stream
+ * handler, so these are called from there. Each id is unique per call, so
+ * keys never collide across wakes or retries.
+ */
+export const executionEvents = {
+    toolResult(toolUseId, toolName, output, isError) {
+        const name = baseToolName(toolName);
+        // Some providers stream tool calls without an id; a shared empty key
+        // would dedup every later one away, so those results are not recorded.
+        if (NOISE_TOOLS.has(name) || !toolUseId)
+            return null;
+        return {
+            idempotencyKey: executionKey("tool", toolUseId),
+            kind: "tool_result",
+            payload: { data: { tool: name, ok: !isError, output: clipText(output, TOOL_OUTPUT_CHARS) } },
+        };
+    },
+    todos(toolUseId, todos) {
+        if (!toolUseId)
+            return null;
+        return {
+            idempotencyKey: executionKey("todo", toolUseId),
+            kind: "todo_update",
+            payload: { data: { todos: todos.map((todo) => ({ content: clipText(todo.content, 200), status: todo.status })) } },
+        };
+    },
+    response(turnId, text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return null;
+        return { idempotencyKey: `response:${turnId}`, kind: "assistant_response", payload: { text: clipText(trimmed, EXECUTION_TEXT_CHARS) } };
+    },
+    /** What the agent told the owner through notify_user: an explicit status report. */
+    statusReport(toolUseId, message) {
+        const trimmed = message.trim();
+        if (!trimmed || !toolUseId)
+            return null;
+        return { idempotencyKey: executionKey("report", toolUseId), kind: "status_report", payload: { text: clipText(trimmed, EXECUTION_TEXT_CHARS) } };
+    },
+};
+/**
+ * The fast responder's reading of a batch, as one candidate event. It shares
+ * the message's dedup key, so the sidecar's origin key matches the message's
+ * and the same task is never created twice. Only for a single-message batch:
+ * a brief over several messages cannot be keyed to the right one, and the
+ * messages themselves are already events.
+ */
+export function fastResponderCandidate(messages, brief) {
+    const relevant = messages.filter(isTaskRelevantMessage);
+    const first = relevant.length === 1 ? relevant[0] : undefined;
+    const text = typeof brief === "string" ? brief.trim() : "";
+    if (!first || !text)
+        return null;
+    const dedupKey = getMessageDedupKey(first);
+    return {
+        idempotencyKey: `candidate:${dedupKey}`,
+        kind: "fast_responder_candidate",
+        source: { channel: first.channel, sender: first.sender, messageId: first.id, dedupKey },
+        payload: { text: clipText(text, EXECUTION_TEXT_CHARS) },
+    };
+}
+/** Record the fast responder's brief as a candidate event. Never throws. */
+export function recordFastResponderCandidate(messages, brief) {
+    try {
+        recordExecutionEvent(fastResponderCandidate(messages, brief));
+    }
+    catch (error) {
+        logger.warn(`[thread-tasks] could not record fast-responder candidate: ${errorMessage(error)}`);
+    }
+}
+/** Record an execution event on the process runtime, if there is one. Never throws. */
+export function recordExecutionEvent(input) {
+    if (input)
+        current?.recordExecution(input);
+}
+/** The process runtime's recovery context, or null without a runtime (then nothing is injected). */
+export function buildThreadTaskContext() {
+    return current?.contextBlock() ?? null;
+}
+/** Bounded reconcile on the process runtime; resolves immediately without one. */
+export async function reconcileThreadTasks(phase, waitMs = RECONCILE_WAIT_MS.boundary) {
+    await current?.reconcile(phase, waitMs);
+}
+/** The runtime for this process, set once by the loop. Tools and hooks read it. */
+let current = null;
+export function setThreadTaskRuntime(runtime) {
+    current = runtime;
+}
+export function getThreadTaskRuntime() {
+    return current;
+}
+//# sourceMappingURL=thread-task-runtime.js.map