@tea-agent/loop-agent 0.35.0-beta.2 → 0.35.1-beta.0

package/dist/commands/pi-reuse-benchmark.js

@@ -106,22 +106,22 @@ export function parsePiReuseBenchmarkArgs(args) {
     };
 }
 export function printPiReuseBenchmarkUsage() {
-    console.log(`usage: pi-reuse-benchmark [options]
-
-Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
-
-Options:
-  --report <path>         Benchmark report markdown (approval status)
-  --approval <path>       Explicit approval JSON artifact
-  --off-executor <path>   Baseline executor.jsonl (reuse off)
-  --on-executor <path>    Treatment executor.jsonl (reuse on)
-  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
-  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
-  --json                  Emit JSON (default when no format flag is set)
-  --markdown              Emit Markdown summary
-  -h, --help              Show this help
-
-Recommendations: defer | maintain-opt-in | eligible-for-human-review
+    console.log(`usage: pi-reuse-benchmark [options]
+
+Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
+
+Options:
+  --report <path>         Benchmark report markdown (approval status)
+  --approval <path>       Explicit approval JSON artifact
+  --off-executor <path>   Baseline executor.jsonl (reuse off)
+  --on-executor <path>    Treatment executor.jsonl (reuse on)
+  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
+  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
+  --json                  Emit JSON (default when no format flag is set)
+  --markdown              Emit Markdown summary
+  -h, --help              Show this help
+
+Recommendations: defer | maintain-opt-in | eligible-for-human-review
 Never changes CODE_AGENT_PI_REUSE_RUNTIME default (off).`);
 }
 function resolveRepoRelative(repoRoot, filePath) {

package/dist/commands/run-dag-progress.js

@@ -1,4 +1,18 @@
 export const DEFAULT_RUN_DAG_PROGRESS_INTERVAL_MS = 30_000;
+/**
+ * Contract floor for periodic progress output. Values below this are rejected
+ * at CLI parse time (aligned with `dag execute`'s parseProgressIntervalMs).
+ * Lives here (not src/application/dag/args.ts) because task-advance shares it
+ * and src/application/dag/args.ts is outside the task-advance write boundary.
+ */
+export const MIN_RUN_DAG_PROGRESS_INTERVAL_MS = 1_000;
+/** Validate a progress interval; throws with the dag execute error contract. */
+export function validateRunDagProgressIntervalMs(value) {
+    if (!Number.isInteger(value) || value < MIN_RUN_DAG_PROGRESS_INTERVAL_MS) {
+        throw new Error("progress-interval-ms must be an integer >= 1000");
+    }
+    return value;
+}
 function formatDuration(durationMs) {
     const totalSeconds = Math.max(0, Math.floor(durationMs / 1_000));
     const hours = Math.floor(totalSeconds / 3_600);

package/dist/commands/task-advance.js

@@ -1,5 +1,6 @@
 import { advanceTaskLifecycle, } from "../application/task-lifecycle/index.js";
 import { buildOperatorResult, operatorFailed, processExitCodeForOutcome, writeOperatorJson, } from "../shared/operator/index.js";
+import { createRunDagProgressObserver, validateRunDagProgressIntervalMs, } from "./run-dag-progress.js";
 const COMMAND = "task advance";
 const USAGE = `usage:
   task advance <task-id> [title]
@@ -24,6 +25,8 @@ const USAGE = `usage:
     [--dag-output <path>]
     [--skip-finalize]
     [--no-strict-models]
+    [--quiet]
+    [--progress-interval-ms <ms>]
     [--dry-run]
     [--json]`;
 function pushList(target, value) {
@@ -170,6 +173,19 @@ export function parseTaskAdvanceArgs(args) {
             options.strictModels = false;
             continue;
         }
+        if (token === "--quiet") {
+            options.quiet = true;
+            continue;
+        }
+        if (token === "--progress-interval-ms") {
+            const raw = next();
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed)) {
+                throw new Error(`progress-interval-ms must be an integer >= 1000\n${USAGE}`);
+            }
+            options.progressIntervalMs = validateRunDagProgressIntervalMs(parsed);
+            continue;
+        }
         if (token === "--help" || token === "-h") {
             throw new Error(USAGE);
         }
@@ -208,7 +224,7 @@ function mapOutcome(result) {
         return "blocked";
     return "succeeded";
 }
-function toUseCaseInput(repoRoot, taskId, options) {
+export function toUseCaseInput(repoRoot, taskId, options, observer) {
     const timeouts = new Map((options.verifyTimeout ?? []).map((entry) => {
         const parsed = parseVerifyTimeout(entry);
         return [parsed.label, parsed.timeoutMs];
@@ -270,7 +286,8 @@ function toUseCaseInput(repoRoot, taskId, options) {
         dagOutputPath: options.dagOutputPath,
         skipFinalize: options.skipFinalize,
         strictModels: options.strictModels,
-        onProgress: options.json
+        ...(observer ? { observer } : {}),
+        onProgress: options.quiet
             ? undefined
             : (message) => {
                 process.stderr.write(`[task advance] ${message}\n`);
@@ -295,8 +312,18 @@ export async function runTaskAdvance(repoRoot, args) {
         process.exitCode = processExitCodeForOutcome(envelope.outcome);
         return;
     }
+    let progress;
     try {
-        const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options));
+        // AC-006/AC-007: periodic DAG progress goes to stderr only (stdout stays
+        // the single final OperatorCommandResultV1 JSON). The observer is created
+        // ONLY for the approve-gate execution path and disposed on every exit;
+        // its timer starts only after onRunStart (double guard, no stray timer).
+        if (options.approveGate && !options.dryRun && !options.quiet) {
+            progress = createRunDagProgressObserver({
+                intervalMs: options.progressIntervalMs,
+            });
+        }
+        const result = await advanceTaskLifecycle(toUseCaseInput(repoRoot, taskId, options, progress?.observer));
         const outcome = mapOutcome(result);
         const gateStop = result.lifecycleState === "awaiting-write-set-approval" &&
             result.blockers.length === 0;
@@ -332,4 +359,7 @@ export async function runTaskAdvance(repoRoot, args) {
         writeOperatorJson(envelope);
         process.exitCode = processExitCodeForOutcome(envelope.outcome);
     }
+    finally {
+        progress?.dispose();
+    }
 }

package/dist/shared/operator/capabilities.js

@@ -445,6 +445,43 @@ export function buildOperatorCapabilitiesDocument() {
             modelCallable: "always",
             humanConfirmation: "none",
         },
+        {
+            action: "operationWait",
+            cli: "console canonical operation wait (read-only event-driven long poll)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            resultPolicy: { readOnly: true, bounded: true, redacted: true },
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "NOT_FOUND",
+                "INVALID_INPUT",
+                "EVENT_CURSOR_EXPIRED",
+            ],
+            description: "Read-only event-driven wait on the canonical operation event ring. Returns immediately on existing events, terminal state or needs-reconcile; otherwise resolves on the first new event/state change or after maxWaitMs with timedOut:true (a success summary, not a command failure).",
+            inputParams: [
+                {
+                    name: "operationId",
+                    type: "string",
+                    required: true,
+                    description: "canonical operation id",
+                },
+                {
+                    name: "afterSeq",
+                    type: "number",
+                    required: false,
+                    description: "event cursor; only events with seq > afterSeq count (default 0, >= 0)",
+                },
+                {
+                    name: "maxWaitMs",
+                    type: "number",
+                    required: false,
+                    description: "bounded wait budget; clamped server-side (default 180000, floor 60000)",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
         {
             action: "contractShow",
             cli: "loop-agent task status <taskId> --json",
@@ -965,7 +1002,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "CONTROLLER_MISMATCH",
                 "INVALID_INPUT",
             ],
-            description: "Consume a single-use execution receipt and execute the reviewed DAG (prefer task advance --approve-gate when gate token present). accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor.",
+            description: "Consume a single-use execution receipt and execute the reviewed DAG (prefer task advance --approve-gate when gate token present). accepted/queued/running/operationId are NOT completion — supervise via operationGet/status/dagReport/dagDoctor/operationWait.",
             inputParams: [
                 {
                     name: "executionId",

package/dist/sidecars/cursor-prompt/executor.js

@@ -29,7 +29,7 @@ export function resolveArtifactWriteDir(options) {
 }
 export function buildArtifactPathPrompt(writeDir) {
     if (!writeDir)
-        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
+        return `After changes, write artifacts/修改记录.md and artifacts/验证结果.md with verification evidence.
 ${ARTIFACT_INSTRUCTIONS}`;
     return [
         `After changes, write the following files:`,

package/dist/worker/console/chat/pi-runtime.js

@@ -58,11 +58,11 @@ import { RUNTIME_CONTEXT_TEXT_MAX, redactRuntimeText, } from "./runtime-context.
  */
 export const OPERATOR_CHAT_SYSTEM_PROMPT_BASE = [
     "You are the General Operator Chat for loop-agent / agent-worker.",
-    "Operate through operator_* tools first. Pi read/write/edit/bash/grep/find/ls are available, but obey the loaded repository AGENTS.md. apply_patch, full-tools, shell, and coding-chat are denied alternate runtimes. Prefer safe-read/safe-grep for sensitive probes.",
-    "If a repository has no loop-agent harness and the user requests initialization, run `loop-agent init instructions --repo-root .` then `loop-agent init --repo-root . --profile full --merge`; finish the generated setup, init doctor, inspect, docs audit, and quick verification. For updates use `loop-agent init upgrade --repo-root . --json` until stable; use init check-update only for an explicitly read-only request.",
-    "After a DAG is started or accepted, do not end on accepted/queued/running or an operationId. Supervise it to a terminal outcome. Poll operationGet, task status, dagReport, and dagDoctor after about 15 seconds on start/change, every 30 seconds during progress, and every 60 seconds after 3 minutes unchanged. Report only meaningful node/rank changes, review/verify/closeout, recovery, liveness concerns, and terminal outcomes.",
-    "On failure read primaryFailure, primaryRecovery, and doctor evidence. If meaningful progress exists, wait. Otherwise use a fresh eligible dagRerunPlan and rerun its safe node; when ineligible follow AGENTS.md/runtime recovery for same-task rerun/advance, resume, or Worker retry. Auto-approve only a bounded writeSet inside allowedPaths, outside forbiddenPaths, without broad/destructive risk, and with structured verification.",
-    "Continue until success, user stop, or no safe eligible recovery remains because limits, bindings, auth/quota recovery, or required external authorization are exhausted. Never create a new task for a transient failure or replace repair-pi with direct edits.",
+    "Operate through operator_* tools first. Pi read/write/edit/bash/grep/find/ls are available; obey the loaded repository AGENTS.md. apply_patch, full-tools, shell, coding-chat are denied. Prefer safe-read/safe-grep for sensitive probes.",
+    "If a repository has no loop-agent harness and the user requests initialization, run `loop-agent init instructions --repo-root .` then `loop-agent init --repo-root . --profile full --merge`; finish with init doctor, inspect, docs audit, quick verification. For updates use `loop-agent init upgrade --repo-root . --json` until stable; init check-update only for explicitly read-only requests.",
+    "Long-running DAGs must run via prepareDagExecution → runDag → operationId held by a Console operation; never foreground-Bash `task advance --approve-gate`, no tail/head pipes, no hand-rolled nohup/Start-Process/start; do not end on accepted/queued/running or an operationId — NOT completion. Supervise via operationGet/status/dagReport/dagDoctor/operationWait: 60s → 90s → 120s → 180s backoff; reset to 60s on state change; 30-60s re-checks when stall suspected. Report only meaningful node/rank changes, review/verify/closeout, recovery, liveness, terminal outcomes.",
+    "On failure read primaryFailure, primaryRecovery, doctor evidence. If meaningful progress exists, wait. Else use a fresh eligible dagRerunPlan and rerun its safe node; when ineligible follow AGENTS.md/runtime recovery for same-task rerun/advance, resume, or Worker retry. Auto-approve only a bounded writeSet inside allowedPaths, outside forbiddenPaths, without broad/destructive risk, with structured verification.",
+    "Continue until success, user stop, or no safe eligible recovery remains (limits, bindings, auth/quota, external authorization exhausted). Never create a new task for a transient failure or replace repair-pi with direct edits.",
 ].join("\n");
 /** Compose the inspectable system prompt actually injected into Operator Chat. */
 export function composeOperatorChatSystemPrompt(input) {
@@ -1280,6 +1280,7 @@ export class ConsolePiRuntime {
      * session is not active — callers fail closed instead of fabricating data.
      */
     /**
+     * ConsolePiRuntime.listSlashCommands
      * Browser-safe slash command projection for UI-11.
      * Sources: current Session extension commands, prompt templates, skills.
      * Never returns prompt/skill file bodies.
@@ -1292,29 +1293,36 @@ export class ConsolePiRuntime {
                 .replace(/[A-Za-z]:\\Users\\[^\s]+/gi, "~")
                 .slice(0, 240);
         };
-        try {
-            await this.ensureSessionReady(sessionId);
-        }
-        catch {
-            return [];
-        }
+        // Fail soft at the HTTP layer: bubble readiness errors so routes can attach
+        // a compact warning while the UI keeps local Operator/Pi Web commands.
+        await this.ensureSessionReady(sessionId);
         const session = this.sessions.get(sessionId);
         if (!session)
-            return [];
-        const out = [];
-        const seen = new Set();
+            return { commands: [] };
+        // Same-name conflict priority (AC-3): extension > skill > prompt.
+        // Enum order must not decide the winner — prompt-before-skill still loses.
+        const SOURCE_RANK = {
+            extension: 0,
+            skill: 1,
+            prompt: 2,
+        };
+        const byKey = new Map();
+        const sourceWarnings = [];
         const push = (command, label, description, source) => {
             const name = command.startsWith("/") ? command : `/${command}`;
             const key = name.toLowerCase();
-            if (!key || key === "/" || seen.has(key))
+            if (!key || key === "/")
                 return;
-            seen.add(key);
-            out.push({
+            const next = {
                 command: name,
                 label: (label || name).slice(0, 80),
                 description: scrub(description),
                 source,
-            });
+            };
+            const existing = byKey.get(key);
+            if (!existing || SOURCE_RANK[source] < SOURCE_RANK[existing.source]) {
+                byKey.set(key, next);
+            }
         };
         try {
             const cmds = session.extensionRunner?.getRegisteredCommands?.() ?? [];
@@ -1325,18 +1333,20 @@ export class ConsolePiRuntime {
                 push(String(name), String(cmd.name || name), String(cmd.description || ""), "extension");
             }
         }
-        catch {
-            // non-blocking
+        catch (error) {
+            // Source isolation: keep other sources; surface compact warning (AC-3).
+            sourceWarnings.push(`extension: ${scrub(error instanceof Error ? error.message : String(error))}`);
         }
         try {
+            // Enumerate prompts before skills on purpose: priority must still let skill win.
             for (const tpl of session.promptTemplates ?? []) {
                 if (!tpl?.name)
                     continue;
                 push(String(tpl.name), String(tpl.name), String(tpl.description || ""), "prompt");
             }
         }
-        catch {
-            // non-blocking
+        catch (error) {
+            sourceWarnings.push(`prompt: ${scrub(error instanceof Error ? error.message : String(error))}`);
         }
         try {
             const services = this.serviceScopes.get(sessionId);
@@ -1351,10 +1361,16 @@ export class ConsolePiRuntime {
                 push(command, skill.name, String(skill.description || ""), "skill");
             }
         }
-        catch {
-            // non-blocking
+        catch (error) {
+            sourceWarnings.push(`skill: ${scrub(error instanceof Error ? error.message : String(error))}`);
         }
-        return out;
+        const warning = sourceWarnings.length > 0
+            ? sourceWarnings.join("; ").slice(0, 160)
+            : undefined;
+        return {
+            commands: [...byKey.values()],
+            ...(warning ? { warning } : {}),
+        };
     }
     async getRuntimeSnapshot(sessionId, options) {
         try {

package/dist/worker/console/chat/routes.js

@@ -1645,14 +1645,24 @@ async function handleChatFiles(res, deps, sessionId, query) {
 }
 export async function handleChatCommands(res, deps, sessionId) {
     try {
-        const commands = typeof deps.runtime.listSlashCommands === "function"
+        const listed = typeof deps.runtime.listSlashCommands === "function"
             ? await deps.runtime.listSlashCommands(sessionId)
-            : [];
+            : { commands: [] };
+        // Partial single-source failures keep successful commands + compact warning (AC-3).
+        const commands = listed.commands ?? [];
+        const warning = typeof listed.warning === "string" && listed.warning.trim()
+            ? listed.warning.trim().slice(0, 160)
+            : undefined;
         res.statusCode = 200;
         res.setHeader("content-type", "application/json; charset=utf-8");
-        res.end(JSON.stringify({ ok: true, commands }));
+        res.end(JSON.stringify({
+            ok: true,
+            commands,
+            ...(warning ? { warning } : {}),
+        }));
     }
     catch (error) {
+        // Whole-list / readiness failures stay fail-soft with empty commands + warning.
         res.statusCode = 200;
         res.setHeader("content-type", "application/json; charset=utf-8");
         res.end(JSON.stringify({
@@ -2799,8 +2809,21 @@ export async function handleChatCompact(req, res, deps, sessionId) {
             return;
         }
     }
+    let body = {};
+    try {
+        body = await readJsonBody(req);
+    }
+    catch {
+        sendJson(res, 400, {
+            ok: false,
+            error: { code: "INVALID_INPUT", message: "invalid json body" },
+        });
+        return;
+    }
+    const rawInstructions = typeof body.instructions === "string" ? body.instructions : undefined;
+    const customInstructions = rawInstructions?.trim() || undefined;
     try {
-        const snapshot = await deps.runtime.compact(sessionId);
+        const snapshot = await deps.runtime.compact(sessionId, customInstructions);
         const event = deps.events.append(sessionId, deps.events.latestTurnId(sessionId) ?? `${sessionId}:compact`, { kind: "compact", data: snapshot });
         sendJson(res, 200, { ok: true, snapshot, eventId: event.eventId });
     }

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

@@ -74,6 +74,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);

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

@@ -0,0 +1,241 @@
+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";
+    }
+}
+function isFocusedOperation(operation) {
+    return (isTerminalOperationState(operation.state) ||
+        operation.state === "needs-reconcile");
+}
+function settledSummary(input) {
+    const projectedEvents = input.newEvents.length > 0
+        ? input.newEvents.map(projectOperationEventSummary)
+        : [];
+    const nextSeq = input.newEvents.length > 0
+        ? input.newEvents[input.newEvents.length - 1].seq
+        : input.afterSeq;
+    return {
+        operationId: input.operationId,
+        state: input.operation.state,
+        changed: input.changed,
+        timedOut: input.timedOut,
+        events: projectedEvents,
+        nextSeq,
+        operation: projectOperationForChat(input.operation),
+    };
+}
+/**
+ * Deterministic read-only wait over the canonical operation event stream
+ * (AC-003 / AC-004). Completion paths:
+ *  - existing events (seq > afterSeq) → immediate (changed: true);
+ *  - operation terminal/needs-reconcile with unconsumed events → immediate summary (changed: true);
+ *  - operation terminal/needs-reconcile with no new events → immediate summary (changed: false);
+ *  - EVENT_CURSOR_EXPIRED when the cursor fell out of the retained ring;
+ *  - first subscribed event/state change → immediate settle;
+ *  - maxWaitMs elapsed with no change → timedOut: true summary (not a failure).
+ *
+ * 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 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;
+    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 (AC-002): the
+        // caller's cursor must advance past every retained canonical event.
+        const listed = events.listFrom(operationId, afterSeq);
+        if ("error" in listed) {
+            throw new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot");
+        }
+        if (listed.events.length > 0) {
+            return settledSummary({
+                operationId,
+                operation,
+                afterSeq,
+                changed: true,
+                timedOut: false,
+                newEvents: listed.events,
+            });
+        }
+        return settledSummary({
+            operationId,
+            operation,
+            afterSeq,
+            changed: false,
+            timedOut: false,
+            newEvents: [],
+        });
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let unsubscribe;
+        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 (AC-003): events at or below the caller's
+            // afterSeq are already consumed and must not settle this wait.
+            if (event.seq <= afterSeq)
+                return;
+            // 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],
+                    }));
+                }
+                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 (AC-002): 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;
+                    }
+                    if (listed.events.length > 0) {
+                        finish(settledSummary({
+                            operationId,
+                            operation: current,
+                            afterSeq,
+                            changed: true,
+                            timedOut: false,
+                            newEvents: listed.events,
+                        }));
+                        return;
+                    }
+                    finish(settledSummary({
+                        operationId,
+                        operation: current,
+                        afterSeq,
+                        changed: false,
+                        timedOut: false,
+                        newEvents: [],
+                    }));
+                    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;
+                }
+                if (listed.events.length > 0) {
+                    finish(settledSummary({
+                        operationId,
+                        operation: current ?? operation,
+                        afterSeq,
+                        changed: true,
+                        timedOut: false,
+                        newEvents: listed.events,
+                    }));
+                    return;
+                }
+                // No events: arm the bounded wait; the listener settles on the
+                // first new event/state change, the timer settles on timeout.
+                timer = setTimeout(() => {
+                    void (async () => {
+                        try {
+                            const latest = await input.operations.get(operationId);
+                            finish(settledSummary({
+                                operationId,
+                                operation: latest ?? operation,
+                                afterSeq,
+                                changed: false,
+                                timedOut: true,
+                                newEvents: [],
+                            }));
+                        }
+                        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)));
+            }
+        })();
+    });
+}