@sema-agent/core 1.451.0 → 2.0.0

package/dist/core/task-registry-agent.js

@@ -0,0 +1,1163 @@
+import { randomBytes } from "node:crypto";
+import { uuidv7 } from "../internal/harness.js";
+import { canAccessAgentRecord, BackgroundAgentStoreError, } from "./background-agent-store.js";
+import { shutdownDebug } from "./shutdown-debug.js";
+import { delimitUntrusted } from "./untrusted-text.js";
+import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
+export function ensureDurableHeartbeatLane(core) {
+    if (core.durableHeartbeatTimer !== undefined)
+        return;
+    const t = setInterval(() => {
+        let liveLanes = 0;
+        for (const h of core.handles.values()) {
+            if (h.type !== "background_agent")
+                continue;
+            const bh = h;
+            if (!bh.durable || bh.durable.poisoned)
+                continue;
+            if (bh.status === "running") {
+                liveLanes++;
+                durableAgentWriteLane(bh, {});
+            }
+            else if (bh.durable.flushFailed) {
+                if ((bh.durable.redrives = (bh.durable.redrives ?? 0) + 1) > 60) {
+                    bh.durable.poisoned = true;
+                    process.emitWarning(`sema durable-agents: terminal flush for ${bh.durable.record.handle} unrecoverable after 60 heartbeat re-drives — durable writes for this row stop here`);
+                    continue;
+                }
+                liveLanes++;
+                durableAgentWriteLane(bh, {});
+            }
+        }
+        if (liveLanes === 0) {
+            clearInterval(t);
+            core.durableHeartbeatTimer = undefined;
+        }
+    }, DURABLE_AGENT_HEARTBEAT_MS);
+    t.unref?.();
+    core.durableHeartbeatTimer = t;
+}
+export function durableAgentWriteLane(handle, patch, clear) {
+    const lane = handle.durable;
+    if (!lane || lane.poisoned)
+        return;
+    lane.chain = lane.chain.then(async () => {
+        if (lane.poisoned)
+            return;
+        Object.assign(lane.record, patch);
+        if (clear !== undefined)
+            for (const k of clear)
+                delete lane.record[k];
+        lane.record.updatedAt = Date.now();
+        const poison = (why) => {
+            lane.poisoned = true;
+            process.emitWarning(`sema durable-agents: ${why} for ${lane.record.handle} — durable writes for this row stop here`);
+        };
+        const adoptOwnRow = async () => {
+            try {
+                const live = await lane.store.get(lane.record.handle, lane.record.scope);
+                if (!live)
+                    return "gone";
+                if (live.writerId !== lane.record.writerId)
+                    return "foreign";
+                if (live.writerEpoch !== lane.record.writerEpoch)
+                    return "foreign";
+                lane.record.rev = live.rev;
+                lane.written = true;
+                return "adopted";
+            }
+            catch {
+                return "unreadable";
+            }
+        };
+        for (let attempt = 0; attempt < 3; attempt++) {
+            if (lane.poisoned)
+                return;
+            if (attempt > 0) {
+                await new Promise((r) => {
+                    const t = setTimeout(r, 50 * attempt);
+                    t.unref?.();
+                });
+            }
+            try {
+                if (!lane.written) {
+                    await lane.store.put(structuredClone(lane.record));
+                    lane.written = true;
+                    lane.flushFailed = false;
+                    lane.redrives = 0;
+                    return;
+                }
+                const ok = await lane.store.update(lane.record.handle, lane.record.scope, structuredClone(lane.record), {
+                    rev: lane.record.rev,
+                });
+                if (ok) {
+                    lane.record.rev += 1;
+                    lane.flushFailed = false;
+                    lane.redrives = 0;
+                    return;
+                }
+                const verdict = await adoptOwnRow();
+                if (lane.poisoned)
+                    return;
+                if (verdict === "adopted")
+                    continue;
+                if (verdict === "unreadable")
+                    continue;
+                poison(verdict === "gone" ? "row reaped mid-write" : "CAS lost to a foreign writer");
+                return;
+            }
+            catch (e) {
+                if (e instanceof BackgroundAgentStoreError && e.code === "agent_record.already_exists") {
+                    const verdict = await adoptOwnRow();
+                    if (lane.poisoned)
+                        return;
+                    if (verdict === "adopted")
+                        continue;
+                    if (verdict === "unreadable")
+                        continue;
+                    if (verdict === "gone")
+                        continue;
+                    poison("handle collision (foreign durable row left untouched)");
+                    return;
+                }
+                shutdownDebug(`durable-agents write failed for ${lane.record.handle} (attempt ${attempt + 1}/3)`, { error: String(e) });
+            }
+        }
+        lane.flushFailed = true;
+    });
+}
+export function durableAgentArmedLane(core, id) {
+    const h = core.handles.get(id);
+    if (!h || h.type !== "background_agent")
+        return false;
+    const lane = h.durable;
+    return lane !== undefined && !lane.poisoned;
+}
+export function durableAgentRowProbeLane(core, id) {
+    const h = core.handles.get(id);
+    if (!h || h.type !== "background_agent")
+        return undefined;
+    const lane = h.durable;
+    if (!lane)
+        return undefined;
+    return async () => {
+        await lane.chain.catch(() => undefined);
+        return lane.written && !lane.poisoned && !lane.flushFailed;
+    };
+}
+export function beginDurableClaimLane(core, id) {
+    const live = core.handles.get(id);
+    if (live !== undefined && (live.status === "running" || live.status === "pending"))
+        return false;
+    if (core.reapingHandles.has(id) || core.claimingHandles.has(id))
+        return false;
+    core.claimingHandles.add(id);
+    return true;
+}
+export function endDurableClaimLane(core, id) {
+    core.claimingHandles.delete(id);
+}
+export async function reapDurableAgentsLane(core, scope, deps, policy) {
+    const now = policy.now ?? Date.now();
+    if (policy.staleRunningMaxAgeMs !== undefined) {
+        await deps.store.reap(scope, now, { staleRunningMaxAgeMs: policy.staleRunningMaxAgeMs });
+    }
+    if (policy.maxAgeMs === undefined && policy.keep === undefined)
+        return { rowsReaped: 0, sessionsReleased: 0, skippedNoSessions: 0 };
+    const terminal = (await deps.store.listByScope(scope)).filter((r) => r.status !== "running" && r.status !== "parked");
+    terminal.sort((a, b) => b.spawnedAt - a.spawnedAt);
+    const doomed = new Map();
+    if (policy.maxAgeMs !== undefined) {
+        for (const r of terminal) {
+            if ((r.settledAt ?? r.spawnedAt) < now - policy.maxAgeMs)
+                doomed.set(r.handle, r);
+        }
+    }
+    if (policy.keep !== undefined) {
+        for (const r of terminal.slice(Math.max(0, policy.keep)))
+            doomed.set(r.handle, r);
+    }
+    let rowsReaped = 0;
+    let sessionsReleased = 0;
+    let skippedNoSessions = 0;
+    for (const r of doomed.values()) {
+        if (core.claimingHandles.has(r.handle))
+            continue;
+        core.reapingHandles.add(r.handle);
+        try {
+            let live;
+            try {
+                live = await deps.store.get(r.handle, scope);
+            }
+            catch {
+                continue;
+            }
+            if (!live || live.status === "running" || live.status === "parked")
+                continue;
+            const inProc = core.handles.get(r.handle);
+            if (inProc !== undefined && (inProc.status === "running" || inProc.status === "pending" || inProc.status === "parked"))
+                continue;
+            if (live.sessionId !== undefined && deps.sessions === undefined) {
+                skippedNoSessions++;
+                continue;
+            }
+            try {
+                if (!(await deps.store.delete(r.handle, scope, { rev: live.rev })))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            rowsReaped++;
+            if (deps.mailbox !== undefined) {
+                try {
+                    await deps.mailbox.drop(scope, r.handle);
+                }
+                catch {
+                }
+            }
+            if (live.sessionId !== undefined && deps.sessions !== undefined) {
+                try {
+                    await deps.sessions.unpin?.(live.sessionId);
+                    await deps.sessions.release(live.sessionId);
+                    sessionsReleased++;
+                }
+                catch {
+                }
+            }
+        }
+        finally {
+            core.reapingHandles.delete(r.handle);
+        }
+    }
+    return { rowsReaped, sessionsReleased, skippedNoSessions };
+}
+export function releaseDurableTranscriptAnchorLane(core, id) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return;
+    durableAgentWriteLane(handle, {}, ["sessionId"]);
+}
+export function bindBackgroundAgentSessionLane(core, id, sessionId) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return;
+    handle.sessionId = sessionId;
+    durableAgentWriteLane(handle, { sessionId });
+}
+export function registerBackgroundAgentLane(core, input) {
+    assertOwnership(input, "registerBackgroundAgent");
+    if (input.id !== undefined && !DURABLE_AGENT_HANDLE_RE.test(input.id)) {
+        throw new Error(`TaskRegistry: background-agent id ${JSON.stringify(input.id)} does not match the a<hex> handle form`);
+    }
+    const id = input.id ?? core.mintTaskId("background_agent");
+    if (input.durableSeed !== undefined) {
+        const prior = core.handles.get(id);
+        if (prior !== undefined) {
+            const parkedHandoff = prior.status === "parked" && input.initialStatus === "parked";
+            if (prior.type !== "background_agent" || prior.status === "running" || prior.status === "pending" || (prior.status === "parked" && !parkedHandoff)) {
+                throw new Error(`TaskRegistry: task id already registered: ${id}`);
+            }
+            const priorLane = prior.durable;
+            if (priorLane !== undefined)
+                priorLane.poisoned = true;
+            core.handles.delete(id);
+        }
+    }
+    if (core.handles.has(id))
+        throw new Error(`TaskRegistry: task id already registered: ${id}`);
+    const now = input.now ?? Date.now();
+    core.handles.set(id, {
+        id,
+        type: "background_agent",
+        status: input.initialStatus ?? "running",
+        ...(input.parkedCheckpointToken !== undefined ? { parkedCheckpointToken: input.parkedCheckpointToken } : {}),
+        ...(input.resolveParkedStop !== undefined ? { resolveParkedStop: input.resolveParkedStop } : {}),
+        ...(input.sessionScoped ? { sessionScoped: true } : {}),
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
+        ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
+        ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
+        ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
+        ...(input.deliveryChannel !== undefined ? { channelState: input.deliveryChannel } : {}),
+        ...(input.retainedContinuation !== undefined ? { retainedContinuation: input.retainedContinuation } : {}),
+        ...(input.owner !== undefined ? { owner: input.owner } : {}),
+        ...(input.scope !== undefined ? { scope: input.scope } : {}),
+        ...(input.toolUseId !== undefined ? { toolUseId: input.toolUseId } : {}),
+        cycleSeq: input.durableSeed !== undefined ? (input.durableSeed.record.seq ?? 1) : 1,
+        createdAt: now,
+        updatedAt: now,
+        abort: input.abort,
+    });
+    if (input.store) {
+        const handle = core.handles.get(id);
+        if (input.durableSeed !== undefined) {
+            const seeded = structuredClone(input.durableSeed.record);
+            seeded.rev = input.durableSeed.rev;
+            handle.durable = {
+                store: input.store,
+                record: seeded,
+                chain: Promise.resolve(),
+                written: true,
+                poisoned: false,
+                flushFailed: false,
+            };
+            ensureDurableHeartbeatLane(core);
+            return id;
+        }
+        handle.durable = {
+            store: input.store,
+            record: {
+                handle: id,
+                scope: input.scope,
+                owner: input.owner,
+                sessionScoped: input.sessionScoped === true,
+                ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
+                ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
+                ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
+                ...(input.name !== undefined ? { name: input.name } : {}),
+                ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
+                ...(input.description !== undefined ? { description: input.description } : {}),
+                ...(input.model !== undefined ? { model: input.model } : {}),
+                ...(input.teamName !== undefined ? { teamName: input.teamName } : {}),
+                writerId: core.writerId,
+                writerEpoch: 1,
+                spawnedAt: now,
+                updatedAt: now,
+                status: "running",
+                rev: 0,
+            },
+            chain: Promise.resolve(),
+            written: false,
+            poisoned: false,
+            flushFailed: false,
+        };
+        durableAgentWriteLane(handle, {});
+        ensureDurableHeartbeatLane(core);
+    }
+    return id;
+}
+export function parkBackgroundAgentLane(core, id, park) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return undefined;
+    if (handle.status !== "running")
+        return undefined;
+    handle.status = "parked";
+    handle.parkedCheckpointToken = park.checkpointToken;
+    handle.resolveParkedStop = park.resolveStop;
+    handle.notify = undefined;
+    for (const [, , qResolve] of handle.preAttachQueue ?? [])
+        qResolve?.({ ok: false, reason: "not_running" });
+    handle.preAttachQueue = undefined;
+    for (const r of [...(handle.inFlightDirect ?? [])])
+        r({ ok: false, reason: "not_running" });
+    handle.inFlightDirect = undefined;
+    handle.updatedAt = Date.now();
+    if (park.seq !== undefined)
+        handle.cycleSeq = park.seq;
+    core.pokeBgQuiescence(handle.owner);
+    durableAgentWriteLane(handle, {
+        status: "parked",
+        parkedCheckpointToken: park.checkpointToken,
+        parkedAt: Date.now(),
+        ...(park.seq !== undefined ? { seq: park.seq } : {}),
+    }, ["parkClaimId"]);
+    return "parked";
+}
+export async function reconcileParkedAgentsLane(core, stores, scope, now, opts) {
+    let liveFailed = 0;
+    for (const handle of core.handles.values()) {
+        if (handle.type !== "background_agent" || handle.status !== "parked")
+            continue;
+        if (handle.scope !== undefined && handle.scope !== scope)
+            continue;
+        const token = handle.parkedCheckpointToken;
+        let state;
+        if (token === undefined)
+            state = "missing";
+        else {
+            try {
+                const cp = await stores.checkpointStore.get(token);
+                state = cp === null ? "missing" : cp.status;
+            }
+            catch {
+                state = "unreadable";
+            }
+        }
+        if (state !== "expired" && state !== "missing")
+            continue;
+        if (handle.status !== "parked")
+            continue;
+        handle.status = "failed";
+        handle.error = `approval checkpoint ${state} while parked (reconciled)`;
+        handle.parkedCheckpointToken = undefined;
+        handle.resolveParkedStop = undefined;
+        handle.updatedAt = now;
+        mintCompletionId(handle);
+        core.pokeBgQuiescence(handle.owner);
+        durableAgentWriteLane(handle, { status: "failed", error: handle.error, settledAt: now, stoppedBy: "system", completionId: handle.completionId }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
+        liveFailed++;
+    }
+    const { reconcileParkedAgents: storeReconcile } = await import("./background-agent-store.js");
+    const liveHandles = new Set();
+    for (const h of core.handles.values())
+        if (h.type === "background_agent")
+            liveHandles.add(h.id);
+    const storeHalf = await storeReconcile(stores, scope, now, {
+        ...(opts?.staleClaimMaxAgeMs !== undefined ? { staleClaimMaxAgeMs: opts.staleClaimMaxAgeMs } : {}),
+        excludeHandles: liveHandles,
+    });
+    return { failed: storeHalf.failed + liveFailed, rolledBack: storeHalf.rolledBack };
+}
+export async function claimParkedAgentLane(stores, handle, access) {
+    if (access.scope === undefined)
+        return { ok: false, reason: "not_found" };
+    let row;
+    try {
+        row = await stores.agentStore.get(handle, access.scope);
+    }
+    catch {
+        return { ok: false, reason: "store_unreachable" };
+    }
+    if (!row || !canAccessAgentRecord(row, access))
+        return { ok: false, reason: "not_found" };
+    if (row.status !== "parked")
+        return { ok: false, reason: "not_parked" };
+    const token = row.parkedCheckpointToken;
+    if (token === undefined || row.sessionId === undefined)
+        return { ok: false, reason: "binding_broken" };
+    let cp;
+    try {
+        cp = (await stores.checkpointStore.get(token));
+    }
+    catch {
+        return { ok: false, reason: "store_unreachable" };
+    }
+    if (cp === null || cp.sessionId !== row.sessionId)
+        return { ok: false, reason: "binding_broken" };
+    if (cp.status !== "pending")
+        return { ok: false, reason: "checkpoint_not_pending" };
+    const claimId = randomBytes(8).toString("hex");
+    const reserved = structuredClone(row);
+    reserved.parkClaimId = claimId;
+    reserved.updatedAt = Date.now();
+    let won;
+    try {
+        won = await stores.agentStore.updateIf(handle, access.scope, reserved, {
+            rev: row.rev,
+            status: "parked",
+            parkedCheckpointToken: token,
+            parkClaimId: null,
+        });
+    }
+    catch {
+        return { ok: false, reason: "store_unreachable" };
+    }
+    if (!won)
+        return { ok: false, reason: "claim_lost" };
+    return {
+        ok: true,
+        ticket: { handle, scope: access.scope, token, claimId, reservedRev: row.rev + 1, row: structuredClone(row) },
+    };
+}
+export async function rollbackParkedClaimLane(core, stores, ticket) {
+    let cpStatus;
+    try {
+        const cp = (await stores.checkpointStore.get(ticket.token));
+        cpStatus = cp === null ? "missing" : cp.status;
+    }
+    catch {
+        return "retry";
+    }
+    const now = Date.now();
+    const rollbackCompletionIdCandidate = uuidv7();
+    const settleLocalParkedHandle = (error) => {
+        const h = core.handles.get(ticket.handle);
+        if (h !== undefined && h.type === "background_agent" && h.status === "parked") {
+            h.status = "failed";
+            h.error = error;
+            h.parkedCheckpointToken = undefined;
+            h.resolveParkedStop = undefined;
+            h.updatedAt = now;
+            commitCompletionIdIfEmpty(h, rollbackCompletionIdCandidate);
+            core.pokeBgQuiescence(h.owner);
+        }
+    };
+    let liveRow;
+    try {
+        liveRow = await stores.agentStore.get(ticket.handle, ticket.scope);
+    }
+    catch {
+        return "retry";
+    }
+    if (!liveRow || liveRow.parkClaimId !== ticket.claimId)
+        return "lost";
+    if (cpStatus === "pending") {
+        const restored = structuredClone(liveRow);
+        delete restored.parkClaimId;
+        restored.updatedAt = now;
+        restored.writerEpoch = (liveRow.writerEpoch ?? 0) + 1;
+        const liveHandle = core.handles.get(ticket.handle);
+        if (liveHandle?.type === "background_agent" &&
+            liveHandle.durable !== undefined &&
+            liveHandle.durable.record.writerId === liveRow.writerId &&
+            (liveHandle.durable.record.writerEpoch ?? 0) === (liveRow.writerEpoch ?? 0)) {
+            liveHandle.durable.record.writerEpoch = restored.writerEpoch;
+        }
+        try {
+            const won = await stores.agentStore.updateIf(ticket.handle, ticket.scope, restored, {
+                rev: liveRow.rev,
+                status: "parked",
+                parkedCheckpointToken: ticket.token,
+                parkClaimId: ticket.claimId,
+            });
+            if (!won)
+                return "lost";
+            try {
+                const cp2 = (await stores.checkpointStore.get(ticket.token));
+                if (cp2 !== null && cp2.status === "pending")
+                    return "rolled_back";
+                const post = await stores.agentStore.get(ticket.handle, ticket.scope);
+                if (post && post.status === "parked") {
+                    const term = structuredClone(post);
+                    term.status = "failed";
+                    term.error = `approval checkpoint ${cp2 === null ? "missing" : cp2.status} under the resume claim (claim rollback)`;
+                    term.stoppedBy = "system";
+                    term.settledAt = now;
+                    term.updatedAt = now;
+                    term.completionId = rollbackCompletionIdCandidate;
+                    delete term.parkedCheckpointToken;
+                    delete term.parkClaimId;
+                    delete term.parkedAt;
+                    if (await stores.agentStore.updateIf(ticket.handle, ticket.scope, term, { rev: post.rev, status: "parked" })) {
+                        settleLocalParkedHandle(term.error);
+                        return "failed";
+                    }
+                }
+                return "lost";
+            }
+            catch {
+                return "rolled_back";
+            }
+        }
+        catch {
+            return "retry";
+        }
+    }
+    const error = cpStatus === "resolved"
+        ? "approval consumed but the resume could not proceed — outcome unknown (claim rollback)"
+        : `approval checkpoint ${cpStatus} under the resume claim (claim rollback)`;
+    if (liveRow.status !== "parked")
+        return "lost";
+    const failed = structuredClone(liveRow);
+    failed.status = "failed";
+    failed.error = error;
+    failed.stoppedBy = "system";
+    failed.settledAt = now;
+    failed.updatedAt = now;
+    failed.completionId = rollbackCompletionIdCandidate;
+    delete failed.parkedCheckpointToken;
+    delete failed.parkClaimId;
+    delete failed.parkedAt;
+    try {
+        const won = await stores.agentStore.updateIf(ticket.handle, ticket.scope, failed, {
+            rev: liveRow.rev,
+            status: "parked",
+            parkClaimId: ticket.claimId,
+        });
+        if (won)
+            settleLocalParkedHandle(error);
+        return won ? "failed" : "lost";
+    }
+    catch {
+        return "retry";
+    }
+}
+export async function consumeParkedFlipLane(core, id, stores, ticket) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent" || handle.status !== "parked")
+        return false;
+    const lane = handle.durable;
+    const doFlip = async () => {
+        let live;
+        try {
+            live = await stores.agentStore.get(ticket.handle, ticket.scope);
+        }
+        catch {
+            return undefined;
+        }
+        if (!live || live.status !== "parked" || live.parkClaimId !== ticket.claimId || live.parkedCheckpointToken !== ticket.token)
+            return undefined;
+        const flipped = structuredClone(live);
+        flipped.status = "running";
+        flipped.writerId = core.writerId;
+        flipped.writerEpoch = (live.writerEpoch ?? 0) + 1;
+        flipped.updatedAt = Date.now();
+        flipped.seq = (live.seq ?? 1) + 1;
+        delete flipped.parkedCheckpointToken;
+        delete flipped.parkedAt;
+        try {
+            const won = await stores.agentStore.updateIf(ticket.handle, ticket.scope, flipped, {
+                rev: live.rev,
+                status: "parked",
+                parkedCheckpointToken: ticket.token,
+                parkClaimId: ticket.claimId,
+            });
+            if (!won)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        flipped.rev = live.rev + 1;
+        return flipped;
+    };
+    let flipped;
+    if (lane !== undefined && !lane.poisoned) {
+        const p = lane.chain.then(doFlip, doFlip);
+        lane.chain = p.then((f) => {
+            if (f !== undefined) {
+                lane.record = structuredClone(f);
+                lane.written = true;
+            }
+        });
+        flipped = await p;
+    }
+    else {
+        flipped = await doFlip();
+    }
+    if (flipped === undefined)
+        return false;
+    handle.status = "running";
+    handle.parkedCheckpointToken = undefined;
+    handle.resolveParkedStop = undefined;
+    handle.updatedAt = Date.now();
+    handle.completionId = undefined;
+    if (flipped.seq !== undefined)
+        handle.cycleSeq = flipped.seq;
+    return true;
+}
+export function finalizeParkedResumeLane(core, id) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return;
+    durableAgentWriteLane(handle, {}, ["parkClaimId"]);
+}
+export function settleBackgroundAgentLane(core, id, outcome) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return undefined;
+    if (handle.status !== "running") {
+        if (handle.status === "killed") {
+            mintCompletionId(handle);
+            let backfilled = false;
+            if (handle.result === undefined && outcome.result !== undefined && outcome.result !== "") {
+                handle.result = outcome.result;
+                handle.resultIsPartial = true;
+                backfilled = true;
+                if (outcome.resultFull !== undefined)
+                    handle.resultFull = outcome.resultFull;
+            }
+            if (handle.error === undefined && outcome.error !== undefined && outcome.error !== BG_AGENT_REAP_STOP_ERROR) {
+                handle.error = outcome.error;
+                backfilled = true;
+            }
+            if (backfilled) {
+                handle.updatedAt = Date.now();
+                durableAgentWriteLane(handle, {
+                    ...(handle.result !== undefined ? { finalOutput: handle.result } : {}),
+                    ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
+                    ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
+                    ...(handle.error !== undefined ? { error: handle.error } : {}),
+                    ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+                });
+            }
+        }
+        return handle.status === "completed" || handle.status === "failed" || handle.status === "killed" ? handle.status : undefined;
+    }
+    handle.status = outcome.status;
+    mintCompletionId(handle);
+    handle.notify = undefined;
+    for (const [, , qResolve] of handle.preAttachQueue ?? [])
+        qResolve?.({ ok: false, reason: "not_running" });
+    handle.preAttachQueue = undefined;
+    for (const r of [...(handle.inFlightDirect ?? [])])
+        r({ ok: false, reason: "not_running" });
+    handle.inFlightDirect = undefined;
+    if (outcome.status === "killed" && handle.stoppedBy === undefined) {
+        handle.stoppedBy = outcome.stoppedBy ?? handle.stopSource ?? "system";
+    }
+    if (outcome.result !== undefined)
+        handle.result = outcome.result;
+    if (outcome.resultFull !== undefined)
+        handle.resultFull = outcome.resultFull;
+    if (outcome.status === "killed" && outcome.result !== undefined && outcome.result !== "") {
+        handle.resultIsPartial = true;
+    }
+    if (outcome.error !== undefined && !(outcome.status === "killed" && outcome.error === BG_AGENT_REAP_STOP_ERROR)) {
+        handle.error = outcome.error;
+    }
+    handle.updatedAt = Date.now();
+    if (outcome.seq !== undefined)
+        handle.cycleSeq = outcome.seq;
+    core.pokeBgQuiescence(handle.owner);
+    durableAgentWriteLane(handle, {
+        status: outcome.status,
+        ...(outcome.seq !== undefined ? { seq: outcome.seq } : {}),
+        settledAt: Date.now(),
+        ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+        ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        ...(handle.result !== undefined ? { finalOutput: handle.result } : {}),
+        ...(handle.resultFull !== undefined ? { finalOutputFull: handle.resultFull } : {}),
+        ...(handle.resultIsPartial ? { resultIsPartial: true } : {}),
+        ...(handle.error !== undefined ? { error: handle.error } : {}),
+    }, ["parkedCheckpointToken", "parkClaimId", "parkedAt"]);
+    return outcome.status;
+}
+export function abortBackgroundAgentsForOwnerLane(core, access, opts) {
+    let aborted = 0;
+    for (const handle of core.handles.values()) {
+        if (handle.type !== "background_agent" || handle.status !== "running" || !canAccess(handle, access))
+            continue;
+        if (opts?.skipSessionScoped && handle.sessionScoped)
+            continue;
+        if (opts?.sessionScopedOnly && !handle.sessionScoped)
+            continue;
+        core.markStopSource(handle.id, "parent");
+        handle.abort.abort();
+        aborted++;
+    }
+    return aborted;
+}
+export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
+    const key = normalizeAgentName(name);
+    if (key === "")
+        return { status: "not_found" };
+    const latestOf = (pool) => {
+        let best;
+        for (const h of pool)
+            if (best === undefined || h.createdAt >= best.createdAt)
+                best = h;
+        return best;
+    };
+    const named = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || h.name === undefined || !canAccess(h, access))
+            continue;
+        if (h.name === name || normalizeAgentName(h.name) === key)
+            named.push(h);
+    }
+    if (opts?.preferRunning === true) {
+        const namedRunning = named.filter((h) => h.status === "running");
+        if (namedRunning.length > 1) {
+            return {
+                status: "ambiguous",
+                message: `Multiple RUNNING background agents match "${name}": ${namedRunning.map((h) => `${h.id} (${h.name ?? h.description ?? "unnamed"})`).join(", ")}. Use the task ID.`,
+            };
+        }
+        if (namedRunning.length === 1)
+            return { status: "found", handle: namedRunning[0] };
+    }
+    const namedWinner = latestOf(named);
+    if (namedWinner !== undefined)
+        return { status: "found", handle: namedWinner };
+    const exact = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || !canAccess(h, access))
+            continue;
+        if (h.description === name)
+            exact.push(h);
+    }
+    const exactRunning = exact.filter((h) => h.status === "running");
+    const exactPool = exactRunning.length > 0 ? exactRunning : exact;
+    if (exactPool.length === 1)
+        return { status: "found", handle: exactPool[0] };
+    if (exactPool.length > 1) {
+        return {
+            status: "ambiguous",
+            message: `Multiple background agents match "${name}": ${exactPool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+        };
+    }
+    const matches = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || !canAccess(h, access))
+            continue;
+        if (h.description !== undefined && normalizeAgentName(h.description) === key)
+            matches.push(h);
+    }
+    const running = matches.filter((h) => h.status === "running");
+    const pool = running.length > 0 ? running : matches;
+    if (pool.length === 1)
+        return { status: "found", handle: pool[0] };
+    if (pool.length > 1) {
+        return {
+            status: "ambiguous",
+            message: `Multiple background agents match "${name}": ${pool.map((h) => (h.description ? `${h.id} (${h.description})` : h.id)).join(", ")}. Use the task ID.`,
+        };
+    }
+    const byKey = new Map();
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+            continue;
+        for (const label of [h.name, h.description]) {
+            if (label === undefined)
+                continue;
+            const k = normalizeAgentName(label);
+            if (k !== "" && !byKey.has(k))
+                byKey.set(k, label);
+        }
+    }
+    const closest = closestName(key, byKey.keys());
+    return { status: "not_found", ...(closest !== undefined ? { suggestion: byKey.get(closest) } : {}) };
+}
+export function markRetainedContinuationLane(core, id) {
+    const handle = core.handles.get(id);
+    if (handle && handle.type === "background_agent")
+        handle.retainedContinuation = true;
+}
+export function reviveBackgroundAgentLane(core, id, access, abort) {
+    if (core.reapingHandles.has(id) || core.claimingHandles.has(id))
+        return { ok: false, reason: "not_found" };
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent" || !canAccess(handle, access))
+        return { ok: false, reason: "not_found" };
+    if (handle.status === "running" || handle.status === "pending")
+        return { ok: false, reason: "still_running" };
+    if (handle.status === "parked")
+        return { ok: false, reason: "still_running" };
+    handle.status = "running";
+    handle.channelState = "attaching";
+    handle.notify = undefined;
+    if (abort !== undefined)
+        handle.abort = abort;
+    handle.result = undefined;
+    handle.resultFull = undefined;
+    handle.error = undefined;
+    handle.resultIsPartial = undefined;
+    handle.stopSource = undefined;
+    handle.completionId = undefined;
+    handle.reviveCycle = (handle.reviveCycle ?? 0) + 1;
+    handle.cycleSeq = (handle.cycleSeq ?? 1) + 1;
+    handle.updatedAt = Date.now();
+    durableAgentWriteLane(handle, { status: "running" }, ["settledAt", "stoppedBy", "finalOutput", "finalOutputFull", "error", "resultIsPartial", "completionId", "summary", "recentSteps", "editedFiles", "usage"]);
+    return { ok: true, cycle: handle.reviveCycle };
+}
+export function settleRevivedAgentLane(core, id, cycle, outcome) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent")
+        return undefined;
+    if ((handle.reviveCycle ?? 0) !== cycle)
+        return undefined;
+    return settleBackgroundAgentLane(core, id, outcome);
+}
+export function unmarkRetainedContinuationLane(core, id) {
+    const handle = core.handles.get(id);
+    if (handle && handle.type === "background_agent")
+        handle.retainedContinuation = false;
+}
+export function attachAgentNotifyLane(core, id, notify, cycle) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent" || handle.status !== "running")
+        return;
+    if (cycle !== undefined && (handle.reviveCycle ?? 0) !== cycle)
+        return;
+    handle.notify = notify;
+    handle.channelState = "attaching";
+    const live = handle.preAttachQueue;
+    if (live !== undefined && live.length > 0) {
+        void (async () => {
+            while (handle.preAttachQueue === live && live.length > 0) {
+                const [qPayload, qOpts, qResolve] = live[0];
+                let result;
+                try {
+                    const d = await notify(qPayload, qOpts);
+                    result =
+                        d === "parked" && handle.retainedContinuation !== true
+                            ? { ok: false, reason: "not_running" }
+                            : d === "parked"
+                                ? { ok: true, disposition: "parked" }
+                                : { ok: true, disposition: "queued" };
+                }
+                catch {
+                    result = { ok: false, reason: "not_running" };
+                }
+                if (handle.preAttachQueue !== live)
+                    return;
+                live.shift();
+                qResolve?.(result);
+            }
+            if (handle.preAttachQueue === live) {
+                handle.preAttachQueue = undefined;
+                handle.channelState = "attached";
+            }
+        })();
+    }
+    else {
+        handle.preAttachQueue = undefined;
+        handle.channelState = "attached";
+    }
+}
+export async function deliverToRunningAgentLane(core, id, access, notification, opts) {
+    const handle = core.handles.get(id);
+    if (!handle || handle.type !== "background_agent" || !canAccess(handle, access))
+        return { ok: false, reason: "not_found" };
+    if (handle.status !== "running")
+        return { ok: false, reason: "not_running" };
+    const bounded = (p, fallback, onTimeout) => new Promise((resolve) => {
+        const t = setTimeout(() => {
+            try {
+                onTimeout?.();
+            }
+            catch {
+            }
+            resolve(fallback);
+        }, core.deliverConfirmTimeoutMs);
+        t.unref?.();
+        void p.then((v) => {
+            clearTimeout(t);
+            resolve(v);
+        }, () => {
+            clearTimeout(t);
+            resolve(fallback);
+        });
+    });
+    if (handle.notify === undefined || handle.channelState === "attaching") {
+        if (handle.channelState !== "attaching")
+            return { ok: false, reason: "no_channel" };
+        const q = (handle.preAttachQueue ??= []);
+        if (q.length >= 8)
+            return { ok: false, reason: "no_channel" };
+        return bounded(new Promise((resolve) => {
+            q.push([notification, opts, resolve]);
+        }), { ok: true, disposition: "pending" });
+    }
+    let detachOnTimeout;
+    return await bounded(new Promise((resolve) => {
+        const inflight = (handle.inFlightDirect ??= new Set());
+        const settleOnce = (r) => {
+            if (!inflight.has(settleOnce))
+                return;
+            inflight.delete(settleOnce);
+            resolve(r);
+        };
+        inflight.add(settleOnce);
+        detachOnTimeout = () => inflight.delete(settleOnce);
+        void (async () => {
+            let result;
+            try {
+                const d = await handle.notify?.(notification, opts);
+                if (d === "parked") {
+                    result = handle.retainedContinuation === true ? { ok: true, disposition: "parked" } : { ok: false, reason: "not_running" };
+                }
+                else {
+                    result = { ok: true, disposition: "queued" };
+                }
+            }
+            catch {
+                result = { ok: false, reason: "not_running" };
+            }
+            settleOnce(result);
+        })();
+    }), { ok: true, disposition: "pending" }, () => detachOnTimeout?.());
+}
+export function runningBackgroundAgentLabelsLane(core, access) {
+    const out = [];
+    for (const h of core.handles.values()) {
+        if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
+            continue;
+        const label = h.name ?? h.description;
+        out.push(label ? `${h.id} (${label})` : h.id);
+    }
+    return out;
+}
+export function serveDurableAgentRowLane(row) {
+    if (row.status === "parked") {
+        return {
+            content: delimitUntrusted(`TaskOutput ${row.handle}`, `status: parked
+The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
+            details: {
+                task_id: row.handle,
+                type: "background_agent",
+                status: "parked",
+                retrieval_status: "success",
+                ...(row.seq !== undefined ? { seq: row.seq } : {}),
+            },
+        };
+    }
+    const body = `status: ${row.status}
+${row.error ? `error: ${row.error}
+` : ""}${row.finalOutput ? `--- result${row.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
+${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
+    return {
+        content: delimitUntrusted(`TaskOutput ${row.handle}`, body),
+        details: {
+            task_id: row.handle,
+            type: "background_agent",
+            status: row.status,
+            retrieval_status: "success",
+            ...(row.status === "killed" && row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}),
+            ...(row.seq !== undefined ? { seq: row.seq } : {}),
+            ...(row.resultIsPartial ? { partial_result: true } : {}),
+            ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
+        },
+    };
+}
+export async function pollBackgroundAgentLane(handle, deadline, signal) {
+    while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
+        await sleepPollStep(deadline, signal);
+    }
+    const running = handle.status === "running";
+    const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
+    if (handle.status === "parked") {
+        return {
+            content: delimitUntrusted(`TaskOutput ${handle.id}`, `status: parked
+The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
+            details: {
+                task_id: handle.id,
+                type: "background_agent",
+                status: "parked",
+                retrieval_status: "success",
+                ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
+            },
+        };
+    }
+    const body = running
+        ? `status: running
+The agent is still working — you will be notified when it completes.`
+        : `status: ${handle.status}
+${handle.error ? `error: ${handle.error}
+` : ""}${handle.result ? `--- result${handle.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
+${clipTaskOutput(handle.resultFull ?? handle.result, handle.outputFile)}` : "(no result text)"}`;
+    return {
+        content: delimitUntrusted(`TaskOutput ${handle.id}`, body),
+        details: {
+            task_id: handle.id,
+            type: "background_agent",
+            status: handle.status,
+            retrieval_status: retrieval,
+            ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
+            ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.resultIsPartial ? { partial_result: true } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        },
+    };
+}
+export async function stopBackgroundAgentLane(core, handle) {
+    const entryStatus = handle.status;
+    if (handle.status === "parked") {
+        const arbiter = handle.resolveParkedStop;
+        if (arbiter === undefined) {
+            return {
+                content: `${handle.id} is parked on a pending approval — stop it by deciding (deny/expire) the pending approval in the durable approval inbox.`,
+                details: { task_id: handle.id, type: "background_agent", status: "parked", retrieval_status: "not_ready", error: "parked_pending_approval" },
+            };
+        }
+        let stopWon = false;
+        let arbiterUnreachable = false;
+        try {
+            stopWon = await arbiter();
+        }
+        catch {
+            stopWon = false;
+            arbiterUnreachable = true;
+        }
+        if (stopWon && handle.status === "parked") {
+            core.markStopSource(handle.id, "parent");
+            handle.status = "killed";
+            handle.stoppedBy = handle.stopSource ?? "parent";
+            handle.updatedAt = Date.now();
+            mintCompletionId(handle);
+            handle.parkedCheckpointToken = undefined;
+            handle.resolveParkedStop = undefined;
+            core.pokeBgQuiescence(handle.owner);
+            {
+                const lane = handle.durable;
+                if (lane !== undefined) {
+                    try {
+                        const live = await lane.store.get(handle.id, lane.record.scope);
+                        if (live && (live.status === "parked" || live.status === "running")) {
+                            const term = structuredClone(live);
+                            term.status = "killed";
+                            if (handle.stoppedBy !== undefined)
+                                term.stoppedBy = handle.stoppedBy;
+                            term.settledAt = Date.now();
+                            term.updatedAt = Date.now();
+                            delete term.parkedCheckpointToken;
+                            delete term.parkClaimId;
+                            delete term.parkedAt;
+                            await lane.store.update(handle.id, lane.record.scope, term, { rev: live.rev });
+                        }
+                    }
+                    catch {
+                    }
+                }
+            }
+            durableAgentWriteLane(handle, {
+                status: "killed",
+                settledAt: Date.now(),
+                ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+            }, ["parkedCheckpointToken", "parkClaimId"]);
+            return {
+                content: `Terminated ${handle.id} (pending approval expired).`,
+                details: {
+                    task_id: handle.id,
+                    type: "background_agent",
+                    status: "killed",
+                    retrieval_status: "success",
+                    ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
+                    ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+                    ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+                },
+            };
+        }
+        if (arbiterUnreachable) {
+            return {
+                content: `${handle.id} was not stopped: the approval arbitration store was unreachable — the row stays parked; retry the stop.`,
+                details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_arbiter_unreachable" },
+                isError: true,
+            };
+        }
+        return {
+            content: `${handle.id} was not stopped: its pending approval was already consumed (a resume won the arbitration).`,
+            details: { task_id: handle.id, type: "background_agent", status: handle.status, retrieval_status: "not_ready", error: "park_resume_won" },
+            isError: true,
+        };
+    }
+    if (handle.status === "running") {
+        core.markStopSource(handle.id, "parent");
+        handle.abort.abort();
+        handle.status = "killed";
+        handle.stoppedBy = handle.stopSource ?? "parent";
+        handle.updatedAt = Date.now();
+        mintCompletionId(handle);
+        handle.notify = undefined;
+        for (const [, , qResolve] of handle.preAttachQueue ?? [])
+            qResolve?.({ ok: false, reason: "not_running" });
+        handle.preAttachQueue = undefined;
+        for (const r of [...(handle.inFlightDirect ?? [])])
+            r({ ok: false, reason: "not_running" });
+        handle.inFlightDirect = undefined;
+        core.pokeBgQuiescence(handle.owner);
+        durableAgentWriteLane(handle, {
+            status: "killed",
+            settledAt: Date.now(),
+            ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        });
+    }
+    return {
+        content: entryStatus === "running" ? `Terminated ${handle.id}.` : alreadyTerminalStopNote(handle.id, handle.status),
+        details: {
+            task_id: handle.id,
+            type: "background_agent",
+            status: handle.status,
+            retrieval_status: "success",
+            ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
+            ...(handle.status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
+            ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
+        },
+    };
+}