@tea-agent/loop-agent 0.35.4-beta.0 → 0.36.1-beta.0

package/dist/worker/console/operation-run-facts.js

@@ -0,0 +1,190 @@
+/**
+ * Trusted run-facts extraction + safe run summary projection
+ * (2026-08-14 Operator Chat DAG recovery P0).
+ *
+ * Invariants:
+ * - Only deterministic structured sources are trusted: the standard
+ *   `OperatorCommandResultV1.result.runSummary` envelope, a structured CLI
+ *   `runSummary` object, or the rerun standard `newRunId`. Free-text stdout /
+ *   non-standard JSON is NEVER scanned or guessed for run ids.
+ * - The projection uses an independent allowlist with bounded fields/arrays
+ *   and redacted text; it must never leak raw results, actionParams, CLI
+ *   args, absolute artifact paths or secrets.
+ * - A run summary is a projection only: it can never change the terminal
+ *   operation state decided by the command envelope/exit facts.
+ */
+import { scrubSecrets } from "./chat/explore-tools.js";
+const RUN_SUMMARY_MAX_NODES = 20;
+const RUN_SUMMARY_MAX_TEXT_CHARS = 600;
+const ABSOLUTE_PATH_REDACTION = "[REDACTED-ABS-PATH]";
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function redactAbsolutePathSubstrings(value) {
+    let redacted = "";
+    let cursor = 0;
+    while (cursor < value.length) {
+        const current = value[cursor] ?? "";
+        const next = value[cursor + 1] ?? "";
+        const previous = value[cursor - 1] ?? "";
+        const windowsDrive = /[A-Za-z]/.test(current) &&
+            next === ":" &&
+            /[\\/]/.test(value[cursor + 2] ?? "") &&
+            (cursor === 0 || !/[A-Za-z0-9_]/.test(previous));
+        const uncPath = current === "\\" && next === "\\";
+        const posixPath = current === "/" &&
+            next !== "/" &&
+            (cursor === 0 || (!/[A-Za-z0-9_]/.test(previous) && previous !== "/"));
+        if (!windowsDrive && !uncPath && !posixPath) {
+            redacted += current;
+            cursor += 1;
+            continue;
+        }
+        const quote = previous === '"' || previous === "'" ? previous : undefined;
+        let end = cursor;
+        while (end < value.length) {
+            const char = value[end] ?? "";
+            if (quote ? char === quote : /["'<>()[\]{},;]/.test(char))
+                break;
+            end += 1;
+        }
+        redacted += ABSOLUTE_PATH_REDACTION;
+        cursor = end;
+    }
+    return redacted;
+}
+function boundedRedactedText(value, maxChars = RUN_SUMMARY_MAX_TEXT_CHARS) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const { scrubbed } = scrubSecrets(value);
+    const pathRedacted = redactAbsolutePathSubstrings(scrubbed);
+    return pathRedacted.length <= maxChars
+        ? pathRedacted
+        : `${pathRedacted.slice(0, maxChars)}…[truncated]`;
+}
+function safeNode(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return undefined;
+    const id = boundedRedactedText(rec.id, 200);
+    const status = boundedRedactedText(rec.status, 100);
+    if (!id || !status)
+        return undefined;
+    return { id, status };
+}
+/** Independent allowlist projection of a structured run summary. */
+export function safeRunSummaryForProjection(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return undefined;
+    const runId = boundedRedactedText(rec.runId, 200);
+    if (!runId)
+        return undefined;
+    const status = boundedRedactedText(rec.status, 100);
+    if (!status)
+        return undefined;
+    const nodes = [];
+    if (Array.isArray(rec.nodes)) {
+        for (const raw of rec.nodes) {
+            if (nodes.length >= RUN_SUMMARY_MAX_NODES)
+                break;
+            const node = safeNode(raw);
+            if (node)
+                nodes.push(node);
+        }
+    }
+    const outOfBounds = [];
+    if (Array.isArray(rec.outOfBounds)) {
+        for (const raw of rec.outOfBounds.slice(0, RUN_SUMMARY_MAX_NODES)) {
+            const entry = asRecord(raw);
+            if (!entry)
+                continue;
+            const nodeId = boundedRedactedText(entry.nodeId, 200);
+            const failureCategory = boundedRedactedText(entry.failureCategory, 200);
+            if (nodeId && failureCategory)
+                outOfBounds.push({ nodeId, failureCategory });
+        }
+    }
+    let next;
+    const nextRec = asRecord(rec.next);
+    if (nextRec) {
+        const kind = boundedRedactedText(nextRec.kind, 100);
+        if (kind) {
+            const description = boundedRedactedText(nextRec.description);
+            next = { kind, ...(description ? { description } : {}) };
+        }
+    }
+    const verdict = boundedRedactedText(rec.verdict);
+    const failureCategory = boundedRedactedText(rec.failureCategory);
+    return {
+        runId,
+        status,
+        nodes,
+        ...(verdict !== undefined ? { verdict } : {}),
+        ...(failureCategory !== undefined ? { failureCategory } : {}),
+        ...(outOfBounds.length > 0 ? { outOfBounds } : {}),
+        ...(next ? { next } : {}),
+    };
+}
+/**
+ * Deterministic trusted-source extraction:
+ * 1. `OperatorCommandResultV1.result.runSummary` (schemaVersion=1 envelope);
+ * 2. structured CLI JSON `runSummary` object (task advance / report shapes);
+ * 3. rerun standard `newRunId` (optionally with its own `runSummary`).
+ *
+ * Candidates are checked in order; a rerun `newRunId` that disagrees with the
+ * accompanying `runSummary.runId` is rejected (no guessing). Free text is
+ * never scanned.
+ */
+export function extractTrustedRunFacts(result) {
+    const root = asRecord(result.json);
+    if (!root)
+        return undefined;
+    // Envelope: { schemaVersion: 1, ok, result: { runSummary } }
+    if (root.schemaVersion === 1 && typeof root.ok === "boolean") {
+        const payload = asRecord(root.result);
+        const runSummaryRaw = payload ? asRecord(payload.runSummary) : null;
+        if (runSummaryRaw) {
+            const summary = safeRunSummaryForProjection(runSummaryRaw);
+            if (summary)
+                return { runId: summary.runId, runSummary: summary };
+        }
+        // Rerun standard newRunId inside the envelope result.
+        if (payload && typeof payload.newRunId === "string" && payload.newRunId.trim()) {
+            const runId = payload.newRunId.trim();
+            const inner = asRecord(payload.runSummary);
+            const summary = inner ? safeRunSummaryForProjection(inner) : undefined;
+            if (summary && summary.runId !== runId)
+                return undefined;
+            return summary ? { runId, runSummary: summary } : { runId };
+        }
+        return undefined;
+    }
+    // Structured CLI JSON with a top-level runSummary object.
+    const directSummary = asRecord(root.runSummary);
+    if (directSummary) {
+        const summary = safeRunSummaryForProjection(directSummary);
+        if (summary) {
+            // A rerun newRunId must agree with the summary runId.
+            if (typeof root.newRunId === "string" &&
+                root.newRunId.trim() &&
+                root.newRunId.trim() !== summary.runId) {
+                return undefined;
+            }
+            return { runId: summary.runId, runSummary: summary };
+        }
+        return undefined;
+    }
+    // Rerun standard newRunId (top level, non-envelope).
+    if (typeof root.newRunId === "string" && root.newRunId.trim()) {
+        const runId = root.newRunId.trim();
+        const inner = asRecord(root.runSummary);
+        const summary = inner ? safeRunSummaryForProjection(inner) : undefined;
+        if (summary && summary.runId !== runId)
+            return undefined;
+        return summary ? { runId, runSummary: summary } : { runId };
+    }
+    return undefined;
+}

package/dist/worker/console/operation-runner.js

@@ -1,5 +1,6 @@
 import { clipPreview, } from "./operation-store.js";
 import { stateEvent } from "./operation-sse.js";
+import { extractTrustedRunFacts } from "./operation-run-facts.js";
 /**
  * Execute a queued operation via LoopAgentClient (or inject).
  * Timeout without proven exit → needs-reconcile (never Cancel).
@@ -74,6 +75,30 @@ export async function runOperation(operationId, deps) {
                     message: chunk,
                 });
             },
+            onHeartbeat: (info) => {
+                // P1 (2026-08-13): project sibling CLI heartbeats into canonical
+                // operation events so operationWait/operationEventSummary can consume
+                // them. The projection is best-effort: a failed append must never
+                // terminate the sibling CLI execution (AC-002). The injected test
+                // runCommand path has no LoopAgentClient callback guard, so the
+                // runner protects itself here.
+                try {
+                    deps.events.append(operationId, {
+                        at: info.at,
+                        kind: "heartbeat",
+                        message: `heartbeat elapsedMs=${info.elapsedMs}`,
+                        data: {
+                            elapsedMs: info.elapsedMs,
+                            action: op.action,
+                            ...(op.taskId ? { taskId: op.taskId } : {}),
+                            ...(op.dagRunId ? { dagRunId: op.dagRunId } : {}),
+                        },
+                    });
+                }
+                catch {
+                    // Heartbeat is derived telemetry; ignore projection failures.
+                }
+            },
         });
         await spawnUpdate;
         finished = await finalizeFromWorkerResult(operationId, result, deps);
@@ -97,6 +122,38 @@ export async function runOperation(operationId, deps) {
     }
     return finished;
 }
+function taskAdvanceBusinessBlock(operation, envelope) {
+    if (!operation || !envelope)
+        return undefined;
+    if (operation.action !== "taskAdvance" && operation.action !== "dagRunTask") {
+        return undefined;
+    }
+    const result = envelope.result && typeof envelope.result === "object"
+        ? envelope.result
+        : undefined;
+    const lifecycleState = typeof result?.lifecycleState === "string"
+        ? result.lifecycleState
+        : undefined;
+    const blockers = Array.isArray(result?.blockers)
+        ? result.blockers
+        : [];
+    const expectedGateStop = lifecycleState === "awaiting-write-set-approval" && blockers.length === 0;
+    if (expectedGateStop)
+        return undefined;
+    if (lifecycleState !== "intake-incomplete" &&
+        blockers.length === 0 &&
+        envelope.outcome !== "blocked") {
+        return undefined;
+    }
+    const firstBlocker = blockers[0];
+    const code = typeof firstBlocker?.code === "string"
+        ? firstBlocker.code
+        : "TASK_ADVANCE_BLOCKED";
+    const message = typeof firstBlocker?.message === "string"
+        ? firstBlocker.message
+        : `task advance stopped before runnable DAG completion (lifecycleState=${lifecycleState ?? "unknown"})`;
+    return { code, message };
+}
 async function finalizeFromWorkerResult(operationId, result, deps) {
     const previewStdout = clipPreview(result.stdout ?? "");
     const previewStderr = clipPreview(result.stderr ?? "");
@@ -106,6 +163,8 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
         resultPath: result.artifacts.resultPath,
         dir: result.artifacts.dir,
     };
+    // Trusted structured run facts only (AC-003): never scanned from free text.
+    const runFacts = extractTrustedRunFacts(result);
     if (result.timedOut) {
         // Supervisory timeout without classified CLI timeout → needs-reconcile
         // Only mark timed-out when we have a machine timeout result after exit.
@@ -121,12 +180,35 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
                 ? "CLI timed out with process exit"
                 : "timeout reached without proven process exit; needs reconcile (not cancelled)",
             result: coerceEnvelope(result),
+            ...(runFacts
+                ? {
+                    dagRunId: runFacts.runId,
+                    ...(runFacts.runSummary ? { runSummary: runFacts.runSummary } : {}),
+                }
+                : {}),
         });
         stateEvent(deps.events, updated, state, updated.errorMessage);
+        if (runFacts) {
+            appendSafeResultEvent(deps, operationId, state, {
+                ok: false,
+                exitCode: result.exitCode,
+            }, runFacts);
+        }
+        else {
+            deps.events.append(operationId, {
+                at: new Date().toISOString(),
+                kind: "result",
+                state,
+                data: { ok: false, exitCode: result.exitCode },
+            });
+        }
         return updated;
     }
     const envelope = coerceEnvelope(result);
-    const ok = envelope?.ok === true || (result.ok && result.exitCode === 0);
+    const operation = await deps.store.get(operationId);
+    const businessBlock = taskAdvanceBusinessBlock(operation, envelope);
+    const processOk = envelope?.ok === true || (result.ok && result.exitCode === 0);
+    const ok = processOk && !businessBlock;
     const state = ok ? "succeeded" : "failed";
     const updated = await deps.store.update(operationId, {
         state,
@@ -138,21 +220,40 @@ async function finalizeFromWorkerResult(operationId, result, deps) {
             stdout: previewStdout,
             stderr: previewStderr,
         }),
-        errorCode: ok ? undefined : (envelope?.error?.code ?? "INTERNAL_ERROR"),
+        errorCode: ok
+            ? undefined
+            : (businessBlock?.code ?? envelope?.error?.code ?? "INTERNAL_ERROR"),
         errorMessage: ok
             ? undefined
-            : (envelope?.error?.message ??
+            : (businessBlock?.message ??
+                envelope?.error?.message ??
                 (previewStderr.trim() ||
                     `command failed with exit ${result.exitCode}`)),
+        // Atomic final patch: state/result + trusted dagRunId + safe runSummary
+        // in a single per-op write-locked update (AC-004). The runSummary is a
+        // projection and never launders the envelope/exit-decided state.
+        ...(runFacts
+            ? {
+                dagRunId: runFacts.runId,
+                ...(runFacts.runSummary ? { runSummary: runFacts.runSummary } : {}),
+            }
+            : {}),
     });
-    stateEvent(deps.events, updated, state);
+    stateEvent(deps.events, updated, state, updated.errorMessage);
+    appendSafeResultEvent(deps, operationId, state, { ok, exitCode: result.exitCode }, runFacts);
+    return updated;
+}
+/** Result event carries the same safe summary persisted on the record. */
+function appendSafeResultEvent(deps, operationId, state, base, runFacts) {
     deps.events.append(operationId, {
         at: new Date().toISOString(),
         kind: "result",
         state,
-        data: { ok, exitCode: result.exitCode },
+        data: {
+            ...base,
+            ...(runFacts?.runSummary ? { runSummary: runFacts.runSummary } : {}),
+        },
     });
-    return updated;
 }
 function coerceEnvelope(result) {
     const json = result.json;

package/dist/worker/console/operation-wait.js

@@ -0,0 +1,314 @@
+import { projectOperationEventSummary, projectOperationForChat, } from "./chat/chat-event-store.js";
+import { isTerminalOperationState, } from "./operation-store.js";
+/**
+ * P2: read-only event-driven long poll on the canonical operation event ring
+ * (2026-08-13 Operator Chat long-run supervision). Server contract bounds:
+ * the model-facing `maxWaitMs` is clamped to [minWaitMs, maxWaitMsBound];
+ * defaults allow the 60–180s model supervision cadence and tests may inject
+ * short bounds.
+ */
+export const DEFAULT_OPERATION_WAIT_MIN_MS = 60_000;
+export const DEFAULT_OPERATION_WAIT_MAX_MS = 180_000;
+export class OperationWaitError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OperationWaitError";
+    }
+}
+/**
+ * Pure wake classification: heartbeats are liveness telemetry, not progress.
+ * Everything else (state/result/stdout/stderr/error/reconcile) is meaningful.
+ *
+ * Exception (2026-08-15): stderr/stdout events whose payload is a DAG-runner
+ * telemetry log line (`[dag execute] heartbeat ...` / `[task advance] heartbeat
+ * ...` / bare `heartbeat ...`) are also liveness, not progress. Without this,
+ * a long run's periodic stderr heartbeat logs settle every operationWait
+ * immediately (55/55 observed instant returns) and force the model back into
+ * high-frequency bash polling — defeating the 60-180s backoff contract.
+ */
+const RUNNER_TELEMETRY_LOG = /^\s*\[?(?:dag execute|task advance|run-dag)\]?\s*heartbeat\b/i;
+const BARE_HEARTBEAT_LOG = /^\s*heartbeat\b/i;
+export function isMeaningfulOperationEvent(event) {
+    if (event.kind === "heartbeat")
+        return false;
+    if (event.kind === "stderr" || event.kind === "stdout") {
+        const message = typeof event.message === "string"
+            ? event.message
+            : "";
+        // Multi-line chunks: only telemetry-only chunks are classified liveness.
+        const lines = message.split("\n").filter((line) => line.trim() !== "");
+        if (lines.length > 0 && lines.every((line) => RUNNER_TELEMETRY_LOG.test(line) || BARE_HEARTBEAT_LOG.test(line))) {
+            return false;
+        }
+    }
+    return true;
+}
+function isFocusedOperation(operation) {
+    return (isTerminalOperationState(operation.state) ||
+        operation.state === "needs-reconcile");
+}
+function settledSummary(input) {
+    const projectedEvents = input.newEvents.length > 0
+        ? input.newEvents.map(projectOperationEventSummary)
+        : [];
+    // Cursor safety: nextSeq always covers every observed seq so heartbeats
+    // filtered out of the payload are never replayed on the next round.
+    const nextSeq = Math.max(input.afterSeq, input.observedSeq);
+    return {
+        operationId: input.operationId,
+        state: input.operation.state,
+        changed: input.changed,
+        timedOut: input.timedOut,
+        events: projectedEvents,
+        nextSeq,
+        recommendedNextCall: {
+            operationId: input.operationId,
+            afterSeq: nextSeq,
+            wakeOn: "meaningful",
+        },
+        operation: projectOperationForChat(input.operation),
+    };
+}
+/**
+ * Deterministic read-only wait over the canonical operation event stream
+ * (AC-003 / AC-004). Completion paths (wakeOn=meaningful default):
+ *  - existing meaningful events (seq > afterSeq) → immediate (changed: true);
+ *  - operation terminal/needs-reconcile → immediate flush of meaningful events;
+ *  - first subscribed meaningful event → immediate settle;
+ *  - maxWaitMs elapsed without meaningful change → timedOut summary whose
+ *    nextSeq still covers every observed (heartbeat) seq.
+ *
+ * wakeOn=all preserves the legacy diagnostic semantics: any first event,
+ * heartbeat included, settles and is returned.
+ *
+ * Race safety: the listener is registered BEFORE listFrom, closing the
+ * listFrom/subscribe gap; every path settles exactly once through a guarded
+ * `finish`, and listener + timer are always cleaned up on settle.
+ */
+export async function waitForOperationChange(input) {
+    const operationId = input.operationId?.trim();
+    if (!operationId) {
+        throw new OperationWaitError("INVALID_INPUT", "operationId is required");
+    }
+    if (!Number.isInteger(input.afterSeq) || input.afterSeq < 0) {
+        throw new OperationWaitError("INVALID_INPUT", "afterSeq must be a non-negative integer");
+    }
+    const wakeOn = input.wakeOn ?? "meaningful";
+    if (wakeOn !== "meaningful" && wakeOn !== "all") {
+        throw new OperationWaitError("INVALID_INPUT", "wakeOn must be 'meaningful' or 'all'");
+    }
+    const minWaitMs = input.minWaitMs ?? DEFAULT_OPERATION_WAIT_MIN_MS;
+    const maxWaitMsBound = input.maxWaitMsBound ?? DEFAULT_OPERATION_WAIT_MAX_MS;
+    if (!Number.isFinite(minWaitMs) ||
+        !Number.isFinite(maxWaitMsBound) ||
+        minWaitMs < 0 ||
+        maxWaitMsBound < minWaitMs) {
+        throw new OperationWaitError("INVALID_INPUT", "invalid wait bounds");
+    }
+    const rawMaxWaitMs = input.maxWaitMs ?? maxWaitMsBound;
+    if (!Number.isFinite(rawMaxWaitMs) || rawMaxWaitMs < 0) {
+        throw new OperationWaitError("INVALID_INPUT", "maxWaitMs must be a non-negative number");
+    }
+    const maxWaitMs = Math.max(minWaitMs, Math.min(maxWaitMsBound, Math.floor(rawMaxWaitMs)));
+    const afterSeq = input.afterSeq;
+    /** Wake filter per policy: meaningful drops heartbeat payload entirely. */
+    const wakeFilter = (events) => wakeOn === "meaningful"
+        ? events.filter((event) => isMeaningfulOperationEvent(event))
+        : events;
+    const operation = await input.operations.get(operationId);
+    if (!operation) {
+        throw new OperationWaitError("NOT_FOUND", `operation not found: ${operationId}`);
+    }
+    const events = input.events;
+    if (isFocusedOperation(operation)) {
+        // Flush unconsumed events before the terminal summary: the caller's
+        // cursor must advance past every retained canonical event (observed
+        // seq includes heartbeats even when their payload is filtered out).
+        const listed = events.listFrom(operationId, afterSeq);
+        if ("error" in listed) {
+            throw new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot");
+        }
+        const wake = wakeFilter(listed.events);
+        const observedSeq = listed.events.length > 0
+            ? listed.events[listed.events.length - 1].seq
+            : afterSeq;
+        if (wake.length > 0) {
+            return settledSummary({
+                operationId,
+                operation,
+                afterSeq,
+                changed: true,
+                timedOut: false,
+                newEvents: wake,
+                observedSeq,
+            });
+        }
+        return settledSummary({
+            operationId,
+            operation,
+            afterSeq,
+            changed: false,
+            timedOut: false,
+            newEvents: [],
+            observedSeq,
+        });
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let unsubscribe;
+        /** Highest seq observed via listener/listFrom during this wait. */
+        let observedSeq = afterSeq;
+        const cleanup = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (unsubscribe) {
+                unsubscribe();
+                unsubscribe = undefined;
+            }
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (result instanceof OperationWaitError)
+                reject(result);
+            else
+                resolve(result);
+        };
+        const settleWithEvent = (event) => {
+            // Future-cursor guard: events at or below the caller's afterSeq are
+            // already consumed and must not settle this wait.
+            if (event.seq <= afterSeq)
+                return;
+            // Heartbeats only advance the observed cursor in meaningful mode.
+            if (wakeOn === "meaningful" && !isMeaningfulOperationEvent(event)) {
+                observedSeq = Math.max(observedSeq, event.seq);
+                return;
+            }
+            observedSeq = Math.max(observedSeq, event.seq);
+            // Listener path: async re-read of the operation for a fresh summary.
+            void (async () => {
+                try {
+                    const current = await input.operations.get(operationId);
+                    finish(settledSummary({
+                        operationId,
+                        operation: current ?? operation,
+                        afterSeq,
+                        changed: true,
+                        timedOut: false,
+                        newEvents: [event],
+                        observedSeq,
+                    }));
+                }
+                catch (error) {
+                    finish(error instanceof OperationWaitError
+                        ? error
+                        : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+                }
+            })();
+        };
+        // Terminal recheck before subscribing: events landing during this await
+        // are still in the ring and are caught by listFrom below.
+        void (async () => {
+            try {
+                const current = await input.operations.get(operationId);
+                if (current && isFocusedOperation(current)) {
+                    // Same terminal flush as the initial path: events landing during
+                    // the await are still in the retained ring.
+                    const listed = events.listFrom(operationId, afterSeq);
+                    if ("error" in listed) {
+                        finish(new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot"));
+                        return;
+                    }
+                    const wake = wakeFilter(listed.events);
+                    observedSeq = Math.max(observedSeq, listed.events.length > 0
+                        ? listed.events[listed.events.length - 1].seq
+                        : afterSeq);
+                    if (wake.length > 0) {
+                        finish(settledSummary({
+                            operationId,
+                            operation: current,
+                            afterSeq,
+                            changed: true,
+                            timedOut: false,
+                            newEvents: wake,
+                            observedSeq,
+                        }));
+                        return;
+                    }
+                    finish(settledSummary({
+                        operationId,
+                        operation: current,
+                        afterSeq,
+                        changed: false,
+                        timedOut: false,
+                        newEvents: [],
+                        observedSeq,
+                    }));
+                    return;
+                }
+                // Subscribe BEFORE listFrom: any event appended after this point
+                // reaches the listener, closing the listFrom/subscribe race.
+                unsubscribe = events.subscribe(operationId, settleWithEvent);
+                const listed = events.listFrom(operationId, afterSeq);
+                if ("error" in listed) {
+                    finish(new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot"));
+                    return;
+                }
+                observedSeq = Math.max(observedSeq, listed.events.length > 0
+                    ? listed.events[listed.events.length - 1].seq
+                    : afterSeq);
+                const wake = wakeFilter(listed.events);
+                if (wake.length > 0) {
+                    finish(settledSummary({
+                        operationId,
+                        operation: current ?? operation,
+                        afterSeq,
+                        changed: true,
+                        timedOut: false,
+                        newEvents: wake,
+                        observedSeq,
+                    }));
+                    return;
+                }
+                // No wake events: arm the bounded wait; the listener settles on
+                // the first new wake event, the timer settles on timeout. The
+                // timeout summary returns observedSeq so heartbeat-only progress
+                // advances the cursor without replaying heartbeat payloads.
+                timer = setTimeout(() => {
+                    void (async () => {
+                        try {
+                            const latest = await input.operations.get(operationId);
+                            finish(settledSummary({
+                                operationId,
+                                operation: latest ?? operation,
+                                afterSeq,
+                                changed: false,
+                                timedOut: true,
+                                newEvents: [],
+                                observedSeq,
+                            }));
+                        }
+                        catch (error) {
+                            finish(error instanceof OperationWaitError
+                                ? error
+                                : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+                        }
+                    })();
+                }, maxWaitMs);
+                timer.unref?.();
+            }
+            catch (error) {
+                finish(error instanceof OperationWaitError
+                    ? error
+                    : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+            }
+        })();
+    });
+}