@aron98/load-lock 1.3.0 → 1.4.0

package/dist/adapters/opencode/plugin.d.ts

@@ -4,7 +4,8 @@
  * Installed to ~/.config/opencode/plugins/load-lock/ (see cli/install.ts).
  * Provides:
  *  - native tools in the `load_lock` namespace (acquire/claim/release/...)
- *  - run_with_permit / job_status / job_stop: full execution lifecycle
+ *  - run_with_permit / job_status / job_stop / wait_for_completion:
+ *    full execution lifecycle incl. honest execution-phase sleeping
  *  - automatic policy injection on every model call via the session
  *    "context" hook (compaction-proof by construction)
  *  - idle wakeup: daemon watch -> ctx.session.synthetic when an offer

package/dist/adapters/opencode/plugin.js

@@ -4,7 +4,8 @@
  * Installed to ~/.config/opencode/plugins/load-lock/ (see cli/install.ts).
  * Provides:
  *  - native tools in the `load_lock` namespace (acquire/claim/release/...)
- *  - run_with_permit / job_status / job_stop: full execution lifecycle
+ *  - run_with_permit / job_status / job_stop / wait_for_completion:
+ *    full execution lifecycle incl. honest execution-phase sleeping
  *  - automatic policy injection on every model call via the session
  *    "context" hook (compaction-proof by construction)
  *  - idle wakeup: daemon watch -> ctx.session.synthetic when an offer
@@ -21,6 +22,7 @@ import path from "node:path";
 import { LLClient } from "../../shared/client.js";
 import { POLICY_BRIEF } from "../../policy/text.js";
 import { waitForTurn, WaitAbortedError } from "../../shared/wait-turn.js";
+import { waitForLocalJob, waitForTrackedJob } from "../../shared/wait-completion.js";
 import { killProcessGroup } from "../../shared/transport.js";
 const client = new LLClient();
 const knownSessions = new Set();
@@ -156,10 +158,12 @@ export default Plugin.define({
                 reason: input.reason,
                 author: "opencode:" + context.sessionID,
             }));
-            add("run_with_permit", "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns it in its own process group, atomically associates it with the permit, returns a job_id immediately (background), and auto-releases the permit when the job exits. Do NOT release manually for these jobs. Poll job_status.", {
+            add("run_with_permit", "Run the heavy command you hold a permit for, with full lifecycle ownership: spawns it in its own process group, atomically associates it with the permit, returns a job_id immediately (background), and auto-releases the permit when the job exits. Do NOT release manually for these jobs. Set wait:true to sleep through execution in this one call; otherwise sleep via wait_for_completion(job_id), quick-check via job_status.", {
                 permit_token: { type: "string" },
                 command: { type: "string", description: "The heavy shell command (not unrelated light commands)" },
                 cwd: { type: "string" },
+                wait: { type: "boolean", description: "true = sleep through execution in this one call; wake promptly when the job finishes (bounded by wait_timeout_ms)" },
+                wait_timeout_ms: { type: "number", description: "Bounded sleep for wait:true (ms, default 600000); still_running checkpoint on timeout" },
             }, async (input, context) => {
                 const child = spawn(input.command, {
                     shell: true,
@@ -168,15 +172,20 @@ export default Plugin.define({
                     env: process.env,
                     stdio: ["ignore", "pipe", "pipe"],
                 });
+                let resolveExit;
                 const job = {
                     id: "job_" + child.pid + "_" + Math.random().toString(36).slice(2, 8),
                     child,
                     permitToken: input.permit_token,
                     command: input.command,
                     sessionID: context.sessionID,
+                    startedAt: Date.now(),
                     exited: false,
                     exitCode: null,
                     output: [],
+                    exitPromise: new Promise((resolve) => {
+                        resolveExit = resolve;
+                    }),
                 };
                 const push = (b) => {
                     job.output.push(b.toString("utf8"));
@@ -190,18 +199,43 @@ export default Plugin.define({
                 // round-trip to the daemon, or the permit would never auto-release.
                 child.on("exit", (code) => {
                     job.exited = true;
+                    job.exitedAt = Date.now();
                     job.exitCode = code;
-                    void client.request("release", { permitToken: job.permitToken, outcome: code === 0 ? "success" : "failure" }).catch(() => { });
+                    // releasePromise is assigned BEFORE resolveExit so a woken waiter
+                    // sees the release round-trip in flight (see waitForLocalJob).
+                    job.releasePromise = client
+                        .request("release", { permitToken: job.permitToken, outcome: code === 0 ? "success" : "failure" })
+                        .then(() => {
+                        job.permitReleased = true;
+                    }, () => { });
+                    resolveExit(code);
                 });
                 try {
-                    await client.request("start_job", { permitToken: input.permit_token, pid: child.pid, pgid: child.pid });
+                    const res = await client.request("start_job", { permitToken: input.permit_token, pid: child.pid, pgid: child.pid });
+                    job.requestId = res.entry?.requestId;
                 }
                 catch (err) {
                     killProcessGroup(child.pid, "SIGKILL");
                     return { error: `permit no longer startable (${err.message}); job killed before doing work; acquire again` };
                 }
                 jobs.set(job.id, job);
-                return { job_id: job.id, pid: child.pid, state: "running", note: "auto-releases when the job exits; poll job_status" };
+                if (!input.wait) {
+                    return { job_id: job.id, pid: child.pid, state: "running", note: "auto-releases when the job exits; sleep via wait_for_completion(job_id), quick-check via job_status" };
+                }
+                const r = await waitForLocalJob(job, { timeoutMs: input.wait_timeout_ms, signal: context.signal });
+                return {
+                    job_id: job.id,
+                    pid: child.pid,
+                    command: job.command,
+                    state: r.state,
+                    exit_code: r.exitCode,
+                    output_tail: r.outputTail,
+                    duration_ms: r.durationMs,
+                    permit_released: r.permitReleased,
+                    waited_ms: r.waitedMs,
+                    next_action: r.nextAction,
+                    detail: r.detail,
+                };
             });
             add("job_status", "Poll a run_with_permit job: running/exited, exit code, output tail.", { job_id: { type: "string" } }, (input) => {
                 const job = jobs.get(input.job_id);
@@ -220,6 +254,7 @@ export default Plugin.define({
                 if (!job)
                     return { error: "unknown job_id" };
                 if (!job.exited) {
+                    job.stopRequested = true;
                     killProcessGroup(job.child.pid, "SIGTERM");
                     setTimeout(() => {
                         if (!job.exited) {
@@ -229,6 +264,51 @@ export default Plugin.define({
                 }
                 return { job_id: job.id, stopping: true };
             });
+            add("wait_for_completion", "Sleep honestly through the EXECUTION phase (replaces sleep-and-poll): bounded blocking wait that wakes promptly when the heavy job finishes. Pass job_id (run_with_permit job; exact exit-code wake) or request_id (daemon-tracked permit; liveness-sweep wake, permit released before you are woken). Structured result on every path: finished (exit_code/output_tail/duration/permit_released), still_running (checkpoint — call again), timeout (wait aborted, job untouched), job_unknown, stopped_by_request. timeout_ms bounds one call (default 600000; 0 = check-only).", {
+                job_id: { type: "string", description: "A run_with_permit job_id" },
+                request_id: { type: "string", description: "A daemon-tracked permit's request_id" },
+                timeout_ms: { type: "number", description: "Bounded sleep (ms, default 600000); still_running checkpoint on timeout — re-call" },
+            }, async (input, context) => {
+                if (!input.job_id && !input.request_id) {
+                    return {
+                        state: "job_unknown",
+                        waited_ms: 0,
+                        next_action: "Pass job_id (a run_with_permit job) or request_id (a daemon-tracked permit).",
+                        detail: "no identifier given",
+                    };
+                }
+                if (input.job_id && jobs.has(input.job_id)) {
+                    const job = jobs.get(input.job_id);
+                    const r = await waitForLocalJob(job, { timeoutMs: input.timeout_ms, signal: context.signal });
+                    return {
+                        state: r.state,
+                        job_id: job.id,
+                        request_id: job.requestId,
+                        exit_code: r.exitCode,
+                        output_tail: r.outputTail,
+                        duration_ms: r.durationMs,
+                        permit_released: r.permitReleased,
+                        waited_ms: r.waitedMs,
+                        started_at: r.startedAt,
+                        next_action: r.nextAction,
+                        detail: r.detail,
+                    };
+                }
+                const requestId = input.request_id ?? input.job_id;
+                const r = await waitForTrackedJob({ client, requestId, timeoutMs: input.timeout_ms, signal: context.signal });
+                return {
+                    state: r.state,
+                    request_id: r.requestId ?? requestId,
+                    exit_code: r.exitCode,
+                    duration_ms: r.durationMs,
+                    permit_released: r.permitReleased,
+                    waited_ms: r.waitedMs,
+                    effective_wait_ms: r.effectiveWaitMs,
+                    started_at: r.startedAt,
+                    next_action: r.nextAction,
+                    detail: r.detail,
+                };
+            });
             add("attach_pid", "Associate a process you already started (e.g. a background shell task) with your claimed permit. Atomic; auto-releases when the process group exits.", { permit_token: { type: "string" }, pid: { type: "number" } }, (input) => client.request("attach_pid", { permitToken: input.permit_token, pid: input.pid }));
             add("mark_started", "Tell load-lock you started the work when no process can be associated. Weaker guarantee: heartbeat lease applies (see docs). Prefer run_with_permit.", { permit_token: { type: "string" } }, (input) => client.request("mark_started", { permitToken: input.permit_token }));
         });

package/dist/cli/main.js

@@ -13,6 +13,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { LLClient, withClient } from "../shared/client.js";
 import { ProtocolError } from "../shared/protocol.js";
 import { waitForTurn } from "../shared/wait-turn.js";
+import { waitForTrackedJob } from "../shared/wait-completion.js";
 import { stateDir, socketPath } from "../core/persist.js";
 import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
 import { packageVersion, compareVersions } from "../shared/version.js";
@@ -162,7 +163,7 @@ const HELP_GROUPS = [
     {
         title: "waiting & running",
         items: [
-            { names: ["wait"], desc: "sleep until a queued request's turn, then auto-claim the offer: --id <request-id> [--timeout <ms>]" },
+            { names: ["wait"], desc: "sleep until a queued request's turn (--id <request-id>), auto-claiming the offer — or until a heavy job finishes (--job <request-id>): [--timeout <ms>]" },
             { names: ["run"], desc: "acquire (or reuse) a permit and run a command under it: run [--permit <token> | acquire flags] -- <cmd>" },
         ],
     },
@@ -388,19 +389,43 @@ async function main() {
             out(await withClient((c) => c.request("attach_pid", { permitToken: token, pid })));
             return;
         }
-        // ------------------------------------------------------- wait (offer -> permit)
+        // ------------------------------------------------------- wait (offer -> permit / job -> done)
         case "wait": {
-            // Watches a queued request; auto-claims the offer when capacity is
-            // handed to it and prints the permit token. Honest bounded blocking
-            // for scriptable flows (aider, plain shell scripts). Shares the exact
-            // implementation with the MCP wait_for_turn tool and the OpenCode
-            // plugin (src/shared/wait-turn.ts).
-            const id = S("id") || fail("wait: --id <request-id> required");
+            // Two honest bounded sleeps sharing one command:
+            //   --id  : queue phase — watches a queued request, auto-claims the
+            //           offer when capacity reaches it, prints the permit token.
+            //   --job : execution phase — sleeps until the daemon-tracked job for
+            //           that request-id finishes (liveness sweep wake; the permit
+            //           is released before you are woken). Structured result on
+            //           every path; still_running = checkpoint, call again.
+            // Both share the exact implementations with the MCP tools and the
+            // OpenCode plugin (src/shared/wait-turn.ts / wait-completion.ts).
             const timeoutMs = N("timeout", 600_000);
-            const agent = S("agent", defaultAgent());
             const c = new LLClient();
             await c.connect();
             try {
+                const job = S("job");
+                if (job) {
+                    const r = await waitForTrackedJob({ client: c, requestId: job, timeoutMs });
+                    out({
+                        state: r.state,
+                        request_id: r.requestId ?? job,
+                        exit_code: r.exitCode,
+                        duration_ms: r.durationMs,
+                        permit_released: r.permitReleased,
+                        waited_ms: r.waitedMs,
+                        effective_wait_ms: r.effectiveWaitMs,
+                        started_at: r.startedAt,
+                        detail: r.detail ?? r.nextAction,
+                    });
+                    if (r.state === "finished")
+                        return;
+                    if (r.state === "still_running")
+                        fail(`wait: job still running after ${r.waitedMs}ms (checkpoint — call again)`, 68);
+                    fail(`wait: job is ${r.state.replace(/_/g, " ")} — ${r.nextAction}`, 69);
+                }
+                const id = S("id") || fail("wait: --id <request-id> (queue wait) or --job <request-id> (job wait) required");
+                const agent = S("agent", defaultAgent());
                 const r = await waitForTurn({ client: c, agentId: agent, requestId: id, timeoutMs });
                 if (r.state === "granted" && r.entry?.permitToken) {
                     out({ permit_token: r.entry.permitToken, state: r.state, request_id: r.requestId, auto_claimed: r.autoClaimed ?? false });

package/dist/core/daemon.d.ts

@@ -27,6 +27,8 @@ export declare class Daemon {
      *  restart via the event cursor) and the process can exit promptly. */
     private conns;
     private waiters;
+    /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
+    private completionWaiters;
     private sentEventId;
     private stateDirPath;
     private socketPath;
@@ -77,6 +79,28 @@ export declare class Daemon {
      * push notifications — no model-authored busy-polling required.
      */
     private waitForAdmission;
+    /**
+     * Bounded blocking wait for a daemon-tracked job's completion. Mirrors
+     * waitForAdmission: the call is held server-side and woken by
+     * resolveCompletionWaiters() when the job is observed done — which always
+     * happens AFTER the permit has been released (finish() frees capacity
+     * before the event is emitted, and waiters are resolved after that).
+     * timeoutMs 0 is check-only. Never blocks unbounded.
+     */
+    private waitForJobCompletion;
+    /**
+     * Classify a request whose entry is no longer held (released, reclaimed,
+     * cancelled, or never started) into a structured completion result, using
+     * the most recent event for the request.
+     */
+    private classifyEntryCompletion;
+    /**
+     * Wake blocked wait_for_completion calls whose tracked job has ended.
+     * Called after every machine transition (afterOp, sweep, expiry timer) —
+     * always AFTER finish() has freed capacity and after the event flush, so
+     * a woken agent observes the pool as free. Entries still held are skipped.
+     */
+    private resolveCompletionWaiters;
     /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
     private afterOp;
     private armExpiryTimer;

package/dist/core/daemon.js

@@ -44,6 +44,8 @@ export class Daemon {
      *  restart via the event cursor) and the process can exit promptly. */
     conns = new Set();
     waiters = new Map();
+    /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
+    completionWaiters = new Map();
     sentEventId;
     stateDirPath;
     socketPath;
@@ -115,6 +117,22 @@ export class Daemon {
         if (this.stopped)
             return;
         this.stopped = true;
+        // Resolve blocked wait_for_completion calls first so no promise dangles.
+        // Responses may not make it out (conns are destroyed below) — that is
+        // fine: clients see the disconnect, reconnect, and re-issue the wait.
+        for (const [, waiters] of this.completionWaiters) {
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve({
+                    state: "job_unknown",
+                    requestId: w.requestId,
+                    waitedMs: this.machine.now() - w.registeredAt,
+                    nextAction: "daemon is stopping — call wait_for_completion again after it is back",
+                    detail: "daemon stopping",
+                });
+            }
+        }
+        this.completionWaiters.clear();
         if (this.sweepTimer)
             clearInterval(this.sweepTimer);
         if (this.expiryTimer)
@@ -395,6 +413,24 @@ export class Daemon {
                 m.adminRelease(String(p.requestId));
                 return [{ ok: true }, undefined];
             }
+            case "wait_for_completion": {
+                // Bounded "sleep until the job finishes" for a daemon-tracked job
+                // (issue #36) — the execution-phase counterpart of wait_for_turn.
+                const requestId = String(p.requestId ?? "");
+                if (!requestId)
+                    throw new ProtocolError("invalid", "wait_for_completion: requestId is required");
+                const requested = Number(p.timeoutMs ?? 0);
+                if (!Number.isFinite(requested) || requested < 0) {
+                    throw new ProtocolError("invalid", "wait_for_completion: timeoutMs must be a non-negative number of milliseconds");
+                }
+                // Same bounded-sleep contract as wait_for_turn: one call is capped by
+                // maxTurnWaitMs; longer waits are checkpointed (still_running) and re-issued.
+                const timeoutMs = Math.min(requested, m.config.maxTurnWaitMs);
+                const res = await this.waitForJobCompletion(requestId, timeoutMs);
+                if (timeoutMs !== requested)
+                    res.effectiveWaitMs = timeoutMs;
+                return [res, undefined];
+            }
             default:
                 throw new ProtocolError("invalid", `unknown method "${method}"`);
         }
@@ -414,6 +450,181 @@ export class Daemon {
             this.waiters.set(requestId, { requestId, resolve, timer });
         });
     }
+    // ---------------------------------------------- wait_for_completion (issue #36)
+    /**
+     * Bounded blocking wait for a daemon-tracked job's completion. Mirrors
+     * waitForAdmission: the call is held server-side and woken by
+     * resolveCompletionWaiters() when the job is observed done — which always
+     * happens AFTER the permit has been released (finish() frees capacity
+     * before the event is emitted, and waiters are resolved after that).
+     * timeoutMs 0 is check-only. Never blocks unbounded.
+     */
+    async waitForJobCompletion(requestId, timeoutMs) {
+        const m = this.machine;
+        let entry;
+        try {
+            entry = m.entryById(requestId);
+        }
+        catch {
+            return {
+                state: "job_unknown",
+                requestId,
+                waitedMs: 0,
+                nextAction: "no request with this id exists (yet) — check the id, or acquire first",
+                detail: "unknown request id",
+            };
+        }
+        if (entry.state === "held") {
+            if (entry.phase !== "running_tracked") {
+                const why = entry.phase === "claimed"
+                    ? "permit is held but no process is attached yet — start the job (run_with_permit / attach_pid / start_job) first"
+                    : "permit is running untracked (no process association) — completion is not observable; attach a pid or poll your job directly";
+                return { state: "job_unknown", requestId, waitedMs: 0, startedAt: entry.startedAt, nextAction: why, detail: `held permit in phase "${entry.phase}"` };
+            }
+            if (timeoutMs === 0) {
+                return {
+                    state: "still_running",
+                    requestId,
+                    waitedMs: 0,
+                    startedAt: entry.startedAt,
+                    nextAction: "job still running — call wait_for_completion again (with a timeout) to sleep until it finishes",
+                    detail: "check-only",
+                };
+            }
+            // Register a completion waiter; woken by resolveCompletionWaiters()
+            // when the job ends, or checkpointed by the bounded timer below.
+            return await new Promise((resolve) => {
+                const registeredAt = m.now();
+                const waiter = {
+                    requestId,
+                    resolve,
+                    timer: null,
+                    registeredAt,
+                };
+                waiter.timer = setTimeout(() => {
+                    const arr = this.completionWaiters.get(requestId);
+                    if (arr) {
+                        const idx = arr.indexOf(waiter);
+                        if (idx >= 0)
+                            arr.splice(idx, 1);
+                        if (arr.length === 0)
+                            this.completionWaiters.delete(requestId);
+                    }
+                    resolve({
+                        state: "still_running",
+                        requestId,
+                        waitedMs: m.now() - registeredAt,
+                        startedAt: entry.startedAt,
+                        nextAction: "job still running — call wait_for_completion again to keep sleeping honestly",
+                        detail: "wait budget elapsed",
+                    });
+                }, timeoutMs);
+                waiter.timer.unref?.();
+                const arr = this.completionWaiters.get(requestId) ?? [];
+                arr.push(waiter);
+                this.completionWaiters.set(requestId, arr);
+            });
+        }
+        // Terminal or pre-execution states: classify from the entry's last event.
+        return this.classifyEntryCompletion(requestId, 0);
+    }
+    /**
+     * Classify a request whose entry is no longer held (released, reclaimed,
+     * cancelled, or never started) into a structured completion result, using
+     * the most recent event for the request.
+     */
+    classifyEntryCompletion(requestId, waitedMs) {
+        const m = this.machine;
+        const ev = m.lastEventForRequest(requestId, 0);
+        const startedAt = ev?.entry?.startedAt;
+        if (!ev) {
+            return {
+                state: "job_unknown",
+                requestId,
+                waitedMs,
+                nextAction: "no completion is observable for this request id — verify the id or re-acquire",
+                detail: "entry is no longer held and no matching event was found",
+            };
+        }
+        switch (ev.type) {
+            case "released":
+            case "auto_released":
+                return {
+                    state: "finished",
+                    requestId,
+                    durationMs: startedAt !== undefined ? ev.ts - startedAt : undefined,
+                    permitReleased: true,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "job finished and the permit is released — capacity is free; proceed with the next step",
+                    detail: ev.detail,
+                };
+            case "reclaimed":
+                if ((ev.detail ?? "").includes("admin")) {
+                    return {
+                        state: "stopped_by_request",
+                        requestId,
+                        waitedMs,
+                        startedAt,
+                        nextAction: "the permit was force-released by an admin while you were waiting — re-acquire before running more heavy work",
+                        detail: ev.detail,
+                    };
+                }
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "the permit was reclaimed before completion could be observed — re-acquire before running more heavy work",
+                    detail: ev.detail,
+                };
+            case "cancelled":
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "the request was cancelled — re-acquire before running more heavy work",
+                    detail: ev.detail,
+                };
+            default:
+                return {
+                    state: "job_unknown",
+                    requestId,
+                    waitedMs,
+                    startedAt,
+                    nextAction: "no completion is observable for this request id — verify the id or re-acquire",
+                    detail: `entry is in state "${ev.entry?.state ?? "unknown"}" (last event: ${ev.type})`,
+                };
+        }
+    }
+    /**
+     * Wake blocked wait_for_completion calls whose tracked job has ended.
+     * Called after every machine transition (afterOp, sweep, expiry timer) —
+     * always AFTER finish() has freed capacity and after the event flush, so
+     * a woken agent observes the pool as free. Entries still held are skipped.
+     */
+    resolveCompletionWaiters() {
+        if (this.completionWaiters.size === 0)
+            return;
+        const m = this.machine;
+        for (const [requestId, waiters] of [...this.completionWaiters]) {
+            let entry;
+            try {
+                entry = m.entryById(requestId);
+            }
+            catch {
+                entry = undefined;
+            }
+            if (entry && entry.state === "held")
+                continue; // job still running
+            this.completionWaiters.delete(requestId);
+            for (const w of waiters) {
+                clearTimeout(w.timer);
+                w.resolve(this.classifyEntryCompletion(requestId, m.now() - w.registeredAt));
+            }
+        }
+    }
     // ------------------------------------------------------------- post-op pass
     /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
     afterOp() {
@@ -448,6 +659,10 @@ export class Daemon {
             for (const ev of fresh)
                 this.broadcast(ev);
         }
+        // Wake completion waiters whose job ended in this op — after the events
+        // flushed, i.e. after finish() already freed the capacity (ordering
+        // guarantee: a woken agent sees the pool as free).
+        this.resolveCompletionWaiters();
         // Persist held permits for restart reconciliation.
         try {
             saveJournal(this.stateDirPath, m.journalEntries());
@@ -474,6 +689,8 @@ export class Daemon {
                 for (const ev of fresh)
                     this.broadcast(ev);
             }
+            // Reclaims performed by the tick above must also wake waiters.
+            this.resolveCompletionWaiters();
             try {
                 saveJournal(this.stateDirPath, this.machine.journalEntries());
             }
@@ -533,6 +750,10 @@ export class Daemon {
             for (const ev of fresh)
                 this.broadcast(ev);
         }
+        // Wake completion waiters woken by this sweep (tracked job confirmed
+        // dead => auto-released above) — after capacity was freed and events
+        // flushed, per the wake ordering guarantee.
+        this.resolveCompletionWaiters();
     }
 }
 // --------------------------------------------------------------------- helpers

package/dist/core/state.d.ts

@@ -75,6 +75,11 @@ export declare class Machine {
     /** Events with id > since, newest last. */
     eventsSince(since: number, agentId?: string, limit?: number): MachineEvent[];
     latestEventId(): number;
+    /**
+     * Newest event with id > `since` whose entry is the given request, or null.
+     * Scans backwards, so the first match is the most recent one.
+     */
+    lastEventForRequest(requestId: string, since: number): MachineEvent | null;
     private emit;
     snapshot(e: Entry): EntrySnapshot;
     private ownerSnapshot;

package/dist/core/state.js

@@ -87,6 +87,20 @@ export class Machine {
     latestEventId() {
         return this.nextEventId - 1;
     }
+    /**
+     * Newest event with id > `since` whose entry is the given request, or null.
+     * Scans backwards, so the first match is the most recent one.
+     */
+    lastEventForRequest(requestId, since) {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.id <= since)
+                break;
+            if (ev.entry?.requestId === requestId)
+                return ev;
+        }
+        return null;
+    }
     emit(type, entry, extra) {
         const targetAgent = entry ? entry.agentId : "*";
         const ev = {
@@ -134,6 +148,8 @@ export class Machine {
             s.leaseDeadline = e.leaseDeadline;
         if (e.lastSeen)
             s.lastSeen = e.lastSeen;
+        if (e.startedAt !== undefined)
+            s.startedAt = e.startedAt;
         return s;
     }
     ownerSnapshot(e) {