@sema-agent/core 7.11.1 → 7.12.0

package/dist/core/runner/run-leg.js

@@ -0,0 +1,462 @@
+import { snapshotActorAssertion } from "../../internal/llm.js";
+import { redactThenCut } from "../../agents/subagent-steps.js";
+import { readPendingSteerQueue } from "../checkpoint-store.js";
+import { formatHookFeedback, hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { buildHumanInputEvent, projectHumanInput } from "../human-input-projection.js";
+import { computeCostMicroUsd } from "../pricing.js";
+import { mintSystemReminder } from "../reminder-mint.js";
+import { hasDestroy } from "../remote-env.js";
+import { deliverEngineNotice } from "../types.js";
+import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
+import { errorCodeOf } from "./assemble-result.js";
+import { DEFAULT_PRECALL_OUTPUT_TOKENS, platformLimitTerminal } from "./clock-and-limits.js";
+import { resumeContinuation } from "./decide-continuation.js";
+import { resolveGitLegDelivery, wrapGitFrame } from "./git-leg-delivery.js";
+import { GIT_STATUS_ECHO_PREVIEW } from "./git-status-frame.js";
+import { toImageContent } from "./image.js";
+import { nextHumanInputSeq } from "./steer-admission.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
+import { attachmentEnvelopeTags, commitAgentListing, commitSkillsListing, reduceToolEnd, renderAgentListingDelta, renderOrphanedBackgroundTasks, renderSkillsListingDelta, stampWriteAnchor } from "./turn-attachments.js";
+export async function runLeg(input) {
+    const { spec, queue, prepared, resume, rs, entryActor, effectiveTimeoutMs, timeout, pushContent, ident, emitCommitted, writeFamilyOf, startedToolCallIds, announceWorkspaceMove, withBrainSinks, flushGitMirror, loopLatch, notificationLane, unsubscribeTaskNotifications, unsubGitRetry, unsubBoundary, unsub, runner, applyResumeDecision, next } = input;
+    let final;
+    let threw;
+    let abortedLive = false;
+    let userInterruptedLive = false;
+    let strandedHumanAnswers = [];
+    try {
+        if (prepared.abortController.signal.aborted) {
+            const e = new Error("run aborted");
+            e.name = "AbortError";
+            throw e;
+        }
+        if (resume) {
+            const walltimeExhaustedResume = effectiveTimeoutMs !== undefined && effectiveTimeoutMs <= 0;
+            const resumeWindowRetryAfterMs = !walltimeExhaustedResume && prepared.usageGovernance !== undefined ? await prepared.usageGovernance.check(Date.now()) : undefined;
+            if (resumeWindowRetryAfterMs !== undefined) {
+                const owesNothing = resume.outcome.gate === "resource_limit" &&
+                    readPendingSteerQueue(resume.cp.state).length === 0 &&
+                    (resume.cp.state.runningBackgroundTasks?.length ?? 0) === 0;
+                const committed = owesNothing &&
+                    prepared.suspendForPlatformLimit !== undefined &&
+                    (await prepared.suspendForPlatformLimit("usage_window", { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) }, { resumeAfterMs: resumeWindowRetryAfterMs }));
+                if (committed) {
+                    rs.limits.turnsExceeded = false;
+                    rs.limits.budgetHit = undefined;
+                }
+                else {
+                    const terminal = platformLimitTerminal("usage_window", resumeWindowRetryAfterMs, "resume");
+                    rs.limits.platformTerminal = terminal;
+                    try {
+                        runner.deps.onError?.(terminal, { phase: "config", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+            if (resumeWindowRetryAfterMs === undefined && !walltimeExhaustedResume && resume.outcome.gate !== "wake") {
+                await applyResumeDecision(prepared, resume, (e) => pushContent({ ...e, ...ident() }), emitCommitted, (toolName, details) => {
+                    if (rs.attach.attachState === undefined)
+                        return;
+                    const family = writeFamilyOf(toolName);
+                    if (family !== undefined)
+                        stampWriteAnchor(rs.attach.attachState, family, rs.counters.cadenceTurns);
+                    if (details !== undefined)
+                        reduceToolEnd(rs.attach.attachState, details);
+                }, (toolCallId) => {
+                    startedToolCallIds.add(toolCallId);
+                    if (resume !== undefined && resume.cp.pendingAction.kind === "tool_approval" && toolCallId === resume.cp.pendingAction.toolCallId) {
+                        resume.pendingActionStarted = true;
+                    }
+                });
+                if (resume.outcome.gate === "policy_ask")
+                    resume.decisionDelivered = true;
+                announceWorkspaceMove();
+            }
+            if (resumeWindowRetryAfterMs !== undefined) {
+            }
+            else if (walltimeExhaustedResume) {
+                timeout.fired = true;
+                timeout.clear();
+                void prepared.harness.abort();
+                prepared.abortController.abort();
+            }
+            else if (rs.budget.maxTokensWindow !== undefined && rs.budget.maxTokensWindow <= 0) {
+                rs.limits.budgetHit = "exceeded";
+                rs.limits.budgetAxis = "tokens";
+            }
+            else if (rs.budget.maxCostMicroUsd !== undefined && rs.budget.maxCostMicroUsd <= 0) {
+                rs.limits.budgetHit = "exceeded";
+                rs.limits.budgetAxis = "cost";
+            }
+            else {
+                let continuation = resumeContinuation(resume, prepared.reminderMark);
+                const bgSnapshot = resume.cp.state.runningBackgroundTasks;
+                if (bgSnapshot !== undefined && bgSnapshot.length > 0) {
+                    const alive = new Set(prepared.listBackgroundTasks().map((t) => t.id));
+                    const orphans = bgSnapshot.filter((t) => !alive.has(t.id));
+                    if (orphans.length > 0) {
+                        continuation += "\n\n" + formatHookFeedback(renderOrphanedBackgroundTasks(orphans), prepared.reminderMark);
+                    }
+                }
+                let gitResumeDelivered;
+                {
+                    const gitBody = await resolveGitLegDelivery(prepared, resume.cp.state.gitAnnouncement, (err) => {
+                        try {
+                            runner.deps.onError?.(new Error(`git announcement ladder unreadable (conservative re-announce): ${err.message}`), { phase: "degraded", sessionId: prepared.sessionId });
+                        }
+                        catch {
+                        }
+                    });
+                    const gitFrame = prepared.gitStatusRef.frame;
+                    if (gitBody !== undefined && gitFrame !== undefined) {
+                        const wrappedGit = wrapGitFrame(gitBody, prepared.reminderMark);
+                        continuation += "\n\n" + wrappedGit;
+                        gitResumeDelivered = { kind: gitFrame.kind, hash: gitFrame.hash, wrapped: wrappedGit };
+                        if (gitFrame.kind === "full" && gitFrame.shrunk !== undefined) {
+                            prepared.gitStatusRef.wrappedShrink = { find: wrappedGit, replace: wrapGitFrame(gitFrame.shrunk.body, prepared.reminderMark) };
+                        }
+                    }
+                }
+                const engineSegments = continuation.length > 0 ? [{ start: 0, end: continuation.length }] : [];
+                const resumeFrames = [
+                    ...readPendingSteerQueue(resume.cp.state).map((entry) => ({ entry, source: "steer" })),
+                    ...(resume.wakeMessage !== undefined ? [{ entry: resume.wakeMessage, source: "wake" }] : []),
+                ];
+                for (const { entry: steer, source } of resumeFrames) {
+                    if (source === "wake" && resume.wakeMessageHookContext !== undefined) {
+                        const hookStart = continuation.length;
+                        continuation += "\n\n" + formatHookFeedback(resume.wakeMessageHookContext, prepared.reminderMark);
+                        engineSegments.push({ start: hookStart, end: continuation.length });
+                    }
+                    if (source === "steer") {
+                        const parkedScreen = (spec.hooks ?? runner.deps.hooks)?.userPromptSubmit;
+                        if (parkedScreen !== undefined) {
+                            let outcome;
+                            try {
+                                const seat = await runHookSeat("userPromptSubmit", { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal, abortEnds: true }, (sig) => parkedScreen(steer.text, {
+                                    identity: prepared.hookIdentity,
+                                    signal: sig,
+                                    source: "parked_redelivery",
+                                    ...(steer.inputId !== undefined ? { inputId: steer.inputId } : {}),
+                                    ...(steer.actor !== undefined ? { actor: snapshotActorAssertion(steer.actor) } : {}),
+                                }));
+                                outcome = seat.expired
+                                    ? { blocked: seat.cause === "timeout" ? `the screen did not answer within its ${prepared.hookTimeoutMs}ms bound (fail-closed)` : "the run was cancelled while the screen was still deciding (fail-closed)" }
+                                    : seat.value?.block !== undefined && seat.value.block !== ""
+                                        ? { blocked: inlineUntrusted(seat.value.block) }
+                                        : { ...(seat.value?.additionalContext !== undefined && seat.value.additionalContext !== "" ? { context: seat.value.additionalContext } : {}) };
+                            }
+                            catch (hookErr) {
+                                const err = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+                                try {
+                                    runner.deps.onError?.(err, { phase: "hook", sessionId: prepared.sessionId });
+                                }
+                                catch {
+                                }
+                                outcome = { blocked: `the screen crashed (${inlineUntrusted(err.message)}; fail-closed)` };
+                            }
+                            if ("blocked" in outcome) {
+                                deliverEngineNotice(runner.deps.onNotice, {
+                                    code: "steering.parked_input_blocked",
+                                    message: "a parked steering input was withheld by the deployment's userPromptSubmit screen when this resume redelivered it: " +
+                                        `${outcome.blocked}. The parked row was consumed with the checkpoint; the instruction never reached the model — ` +
+                                        "re-issue it if it still applies.",
+                                    detail: {
+                                        ...(steer.inputId !== undefined ? { inputId: steer.inputId } : {}),
+                                        sessionId: prepared.sessionId,
+                                        runId: prepared.runId,
+                                        ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
+                                    },
+                                });
+                                queue.push({
+                                    ...buildHumanInputEvent({
+                                        carrier: source,
+                                        source,
+                                        delivery: "blocked",
+                                        sessionSeq: nextHumanInputSeq(prepared.harness),
+                                        ...(steer.inputId !== undefined ? { inputId: steer.inputId } : {}),
+                                        ...(steer.actor !== undefined ? { actor: steer.actor } : {}),
+                                        ...(steer.actor?.issuer !== undefined ? { issuer: steer.actor.issuer } : {}),
+                                        ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                                    }),
+                                    ...ident(),
+                                });
+                                continue;
+                            }
+                            if ("context" in outcome && outcome.context !== undefined) {
+                                const hookStart = continuation.length;
+                                continuation += "\n\n" + formatHookFeedback(outcome.context, prepared.reminderMark);
+                                engineSegments.push({ start: hookStart, end: continuation.length });
+                            }
+                        }
+                    }
+                    const start = continuation.length;
+                    const projected = projectHumanInput({ text: steer.text, actor: steer.actor, source });
+                    continuation +=
+                        "\n\n" +
+                            (steer.trusted ? formatHookFeedback(projected, prepared.reminderMark) : delimitUntrusted("supervisor steering message", projected));
+                    if (steer.trusted)
+                        engineSegments.push({ start, end: continuation.length });
+                    queue.push({
+                        ...buildHumanInputEvent({
+                            carrier: source,
+                            source,
+                            delivery: "applied",
+                            sessionSeq: nextHumanInputSeq(prepared.harness),
+                            inputId: steer.inputId,
+                            ...(steer.actor !== undefined ? { actor: steer.actor } : {}),
+                            ...(steer.actor?.issuer !== undefined ? { issuer: steer.actor.issuer } : {}),
+                            ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                        }),
+                        ...ident(),
+                    });
+                }
+                if (resume !== undefined)
+                    resume.decisionDelivered = true;
+                if (gitResumeDelivered !== undefined) {
+                    const delivered = gitResumeDelivered;
+                    prepared.gitStatusRef.protectedText = delivered.wrapped;
+                    prepared.gitStatusRef.pendingReceipt = {
+                        text: continuation,
+                        commit: (entryId) => {
+                            prepared.gitStatusRef.announced = { kind: delivered.kind, hash: delivered.hash, entryId };
+                            queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[delivered.kind], ...ident() });
+                            rs.attach.attachmentsInjected += 1;
+                            prepared.gitStatusRef.mirrorOwed = { kind: delivered.kind, hash: delivered.hash, entryId };
+                        },
+                    };
+                }
+                final = await withBrainSinks(() => prepared.harness.prompt(continuation, { engineSegments }));
+                await flushGitMirror();
+                if (prepared.gitStatusRef.announced?.pending === true)
+                    await prepared.gitStatusRef.reassert?.();
+            }
+        }
+        else {
+            const objectiveActor = entryActor;
+            const projectedObjective = projectHumanInput({ text: spec.objective, actor: objectiveActor, source: "objective" });
+            let effectiveObjective = projectedObjective;
+            let promptBlocked = false;
+            const userPromptSubmit = (spec.hooks ?? runner.deps.hooks)?.userPromptSubmit;
+            if (userPromptSubmit) {
+                try {
+                    const promptSeat = await runHookSeat("userPromptSubmit", { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal, abortEnds: true }, (sig) => userPromptSubmit(spec.objective, { identity: prepared.hookIdentity, signal: sig, source: "objective", ...(objectiveActor !== undefined ? { actor: snapshotActorAssertion(objectiveActor) } : {}) }));
+                    if (promptSeat.expired) {
+                        if (promptSeat.cause === "timeout") {
+                            try {
+                                runner.deps.onError?.(hookSeatExpiredError("userPromptSubmit", prepared.hookTimeoutMs, promptSeat.cause, "the prompt was NOT submitted (fail-closed) and the task ends blocked"), { phase: "hook", sessionId: prepared.sessionId });
+                            }
+                            catch {
+                            }
+                        }
+                        prepared.blockedRef.reason = formatHookFeedback(promptSeat.cause === "timeout"
+                            ? `the deployment's userPromptSubmit hook did not answer within its ${prepared.hookTimeoutMs}ms bound while screening this prompt; ` +
+                                `the prompt was NOT submitted (fail-closed)`
+                            : `the task was cancelled while the deployment's userPromptSubmit hook was still screening this prompt; ` +
+                                `the prompt was NOT submitted (fail-closed)`, prepared.reminderMark);
+                        promptBlocked = true;
+                    }
+                    const decision = promptSeat.expired ? undefined : promptSeat.value;
+                    if (decision?.block) {
+                        prepared.blockedRef.reason = formatHookFeedback(decision.block, prepared.reminderMark);
+                        promptBlocked = true;
+                    }
+                    else if (decision?.additionalContext) {
+                        effectiveObjective = `${formatHookFeedback(decision.additionalContext, prepared.reminderMark)}\n\n${projectedObjective}`;
+                    }
+                }
+                catch (hookErr) {
+                    const err = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+                    try {
+                        runner.deps.onError?.(err, { phase: "hook", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                    prepared.blockedRef.reason = formatHookFeedback(`the deployment's userPromptSubmit hook crashed while screening this prompt (${err.message}); ` +
+                        `the prompt was NOT submitted (fail-closed)`, prepared.reminderMark);
+                    promptBlocked = true;
+                }
+            }
+            let gitLegDelivered;
+            if (!promptBlocked) {
+                const gitBody = await resolveGitLegDelivery(prepared, undefined, (err) => {
+                    try {
+                        runner.deps.onError?.(new Error(`git announcement ladder unreadable (conservative re-announce): ${err.message}`), { phase: "degraded", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                });
+                const gitFrame = prepared.gitStatusRef.frame;
+                if (gitBody !== undefined && gitFrame !== undefined) {
+                    const wrappedGit = wrapGitFrame(gitBody, prepared.reminderMark);
+                    const standalone = spec.images !== undefined && spec.images.length > 0;
+                    if (!standalone)
+                        effectiveObjective = `${wrappedGit}\n${effectiveObjective}`;
+                    gitLegDelivered = { kind: gitFrame.kind, hash: gitFrame.hash, standalone, wrapped: wrappedGit };
+                    if (gitFrame.kind === "full" && gitFrame.shrunk !== undefined) {
+                        prepared.gitStatusRef.wrappedShrink = { find: wrappedGit, replace: wrapGitFrame(gitFrame.shrunk.body, prepared.reminderMark) };
+                    }
+                }
+            }
+            const firstFrames = [];
+            if (rs.attach.attachState !== undefined) {
+                const attach = rs.attach.attachState;
+                if (rs.attach.agentListingOn && prepared.agentListing !== undefined) {
+                    const listing = prepared.agentListing;
+                    const body = renderAgentListingDelta(attach, listing.entries, listing.toolName, listing.models);
+                    if (body !== undefined) {
+                        firstFrames.push({
+                            source: "agent_listing",
+                            body,
+                            commit: () => {
+                                commitAgentListing(attach, listing.entries, listing.models);
+                                prepared.announcedListingsRef.agents = listing.entries.map((e) => e.name);
+                                if (listing.models !== undefined)
+                                    prepared.announcedListingsRef.models = [...listing.models];
+                            },
+                        });
+                    }
+                }
+                if (rs.attach.skillsListingOn && prepared.skillsListing !== undefined) {
+                    const listing = prepared.skillsListing;
+                    const body = renderSkillsListingDelta(attach, listing.entries);
+                    if (body !== undefined) {
+                        firstFrames.push({
+                            source: "skills_listing",
+                            body,
+                            commit: () => {
+                                commitSkillsListing(attach, listing.entries);
+                                prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
+                            },
+                        });
+                    }
+                }
+                if (firstFrames.length > 0) {
+                    effectiveObjective = `${firstFrames.map((f) => mintSystemReminder(sanitizeUntrustedText(f.body, attachmentEnvelopeTags(f.source)), prepared.reminderMark)).join("\n")}\n${effectiveObjective}`;
+                }
+            }
+            const gitQueuedChars = gitLegDelivered !== undefined && gitLegDelivered.standalone ? gitLegDelivered.wrapped.length : 0;
+            const precallMicroUsd = rs.budget.maxCostMicroUsd === undefined
+                ? 0
+                : computeCostMicroUsd({
+                    totalInputTokens: Math.ceil((effectiveObjective.length + gitQueuedChars) / 4),
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    cacheWriteTokensLong: 0,
+                    outputTokens: prepared.model.maxTokens ?? DEFAULT_PRECALL_OUTPUT_TOKENS,
+                }, rs.telemetry.pricing);
+            const precallCeilingMicroUsd = prepared.suspendForResource !== undefined ? rs.budget.remainingMicroUsd : rs.budget.maxCostMicroUsd;
+            const precallTokens = Math.ceil((effectiveObjective.length + gitQueuedChars) / 4) + (prepared.model.maxTokens ?? DEFAULT_PRECALL_OUTPUT_TOKENS);
+            const precallCeilingTokens = prepared.suspendForResource !== undefined ? rs.budget.remainingTokens : rs.budget.maxTokensWindow;
+            const entryUsageRetryAfterMs = prepared.usageGovernance !== undefined ? await prepared.usageGovernance.check(Date.now()) : undefined;
+            if (promptBlocked) {
+            }
+            else if (entryUsageRetryAfterMs !== undefined) {
+                const terminal = platformLimitTerminal("usage_window", entryUsageRetryAfterMs, "entry");
+                rs.limits.platformTerminal = terminal;
+                try {
+                    runner.deps.onError?.(terminal, { phase: "config", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+            else if (precallCeilingTokens !== undefined && precallTokens > precallCeilingTokens) {
+                rs.limits.budgetHit = "precall";
+                rs.limits.budgetAxis = "tokens";
+            }
+            else if (precallCeilingMicroUsd !== undefined && precallMicroUsd > precallCeilingMicroUsd) {
+                rs.limits.budgetHit = "precall";
+                rs.limits.budgetAxis = "cost";
+            }
+            else if (effectiveTimeoutMs !== undefined && effectiveTimeoutMs <= 0) {
+                timeout.fired = true;
+                timeout.clear();
+                void prepared.harness.abort();
+                prepared.abortController.abort();
+            }
+            else {
+                const images = spec.images
+                    ? await Promise.all(spec.images.map((img) => toImageContent(img, runner.deps.allowImageUrl)))
+                    : undefined;
+                if (gitLegDelivered !== undefined) {
+                    const delivered = gitLegDelivered;
+                    if (delivered.standalone)
+                        await prepared.harness.nextTurn(delivered.wrapped, { engineMinted: true });
+                    prepared.gitStatusRef.protectedText = delivered.wrapped;
+                    prepared.gitStatusRef.pendingReceipt = {
+                        text: delivered.standalone ? delivered.wrapped : effectiveObjective,
+                        commit: (entryId) => {
+                            prepared.gitStatusRef.announced = { kind: delivered.kind, hash: delivered.hash, entryId };
+                            queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[delivered.kind], ...ident() });
+                            rs.attach.attachmentsInjected += 1;
+                            prepared.gitStatusRef.mirrorOwed = { kind: delivered.kind, hash: delivered.hash, entryId };
+                        },
+                    };
+                }
+                for (const f of firstFrames) {
+                    f.commit();
+                    queue.push({ type: "steering_injected", source: f.source, preview: redactThenCut(f.body, 220), ...ident() });
+                }
+                rs.attach.attachmentsInjected += firstFrames.length;
+                if (firstFrames.length > 0 && prepared.announcedSnapshotRecovered)
+                    await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                const enginePrefixChars = effectiveObjective.length - projectedObjective.length;
+                queue.push({
+                    ...buildHumanInputEvent({
+                        carrier: "objective",
+                        source: "objective",
+                        delivery: "applied",
+                        sessionSeq: nextHumanInputSeq(prepared.harness),
+                        ...(objectiveActor !== undefined ? { actor: objectiveActor } : {}),
+                        ...(objectiveActor?.issuer !== undefined ? { issuer: objectiveActor.issuer } : {}),
+                        ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+                    }),
+                    ...ident(),
+                });
+                final = await withBrainSinks(() => prepared.harness.prompt(effectiveObjective, {
+                    ...(images && images.length > 0 ? { images } : {}),
+                    ...(enginePrefixChars > 0 ? { enginePrefixChars } : {}),
+                    ...(objectiveActor !== undefined ? { actor: objectiveActor } : {}),
+                }));
+                await flushGitMirror();
+                if (prepared.gitStatusRef.announced?.pending === true)
+                    await prepared.gitStatusRef.reassert?.();
+            }
+        }
+        loopLatch.ended = true;
+        abortedLive = prepared.abortController.signal.aborted;
+        userInterruptedLive = loopLatch.userInterrupted;
+    }
+    catch (err) {
+        loopLatch.ended = true;
+        if (errorCodeOf(err) === "resume.tool_unavailable" || errorCodeOf(err) === "resume.tool_contract_mismatch") {
+            await settleTeardownLeg(() => prepared.mcp.dispose(), "mcp.dispose (tool_unavailable leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+            await settleTeardownLeg(() => prepared.a2a?.dispose(), "a2a.dispose (tool_unavailable leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+            await settleTeardownLeg(() => (prepared.ownedEnv && hasDestroy(prepared.ownedEnv) ? prepared.ownedEnv.destroy() : undefined), "ownedEnv.destroy (tool_unavailable leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+            throw err;
+        }
+        threw = err;
+        abortedLive = prepared.abortController.signal.aborted;
+        userInterruptedLive = loopLatch.userInterrupted;
+    }
+    finally {
+        timeout.clear();
+        prepared.lspDiagnostics?.registry.releaseRun(prepared.lspDiagnostics.runIdent);
+        prepared.abortController.abort();
+        prepared.releaseSignal();
+        strandedHumanAnswers = prepared.settleContentAskBindings();
+        try {
+            prepared.harness.recoverUndrainedEngineNotes();
+        }
+        catch {
+        }
+        notificationLane.live = false;
+        unsubscribeTaskNotifications();
+        prepared.toolRosterDeltas.unsubscribe();
+        unsubGitRetry();
+        unsubBoundary();
+        unsub();
+    }
+    return await next({ final, threw, abortedLive, userInterruptedLive, strandedHumanAnswers });
+}

package/dist/core/runner/run-notification-lane.d.ts

@@ -0,0 +1,55 @@
+import { type PeerInboundChainRef } from "../../agents/peer-admission.js";
+import type { PushQueue } from "../push-queue.js";
+import type { SessionStore } from "../session.js";
+import { type PendingSessionNotifications, type SystemInjectionPriority, type TaskNotificationPayload } from "../task-notification.js";
+import type { RunnerDeps, TaskEvent, TaskSpec } from "../types.js";
+import type { SessionReadFileStates } from "./prepare-hands-readface.js";
+import type { NotificationLaneBindings, Prepared, PrepareResume, ResumeRun, RunInternals, RunnerDepsSeat, RunnerSelfSeat, TaskIdRef } from "./contracts.js";
+export interface RunNotificationLaneInput<R> {
+    /** borrowed-readonly — the task spec: prepare's input, and the principal the peer scope is minted from. */
+    spec: TaskSpec;
+    /** borrowed-mutable — the run's event queue: the routed `task_notification` frames are pushed here. */
+    queue: PushQueue<TaskEvent>;
+    /** borrowed-readonly — the resume plan when this leg resumes a checkpoint (prepare's resume seed is derived from it). */
+    resume: ResumeRun | undefined;
+    /** borrowed-readonly — the trusted run-scoped channel: the detach hub, the uplink, the root / parent anchors, the peer refs, the upstream notification observer. */
+    internals: RunInternals | undefined;
+    /** borrowed-mutable — the stream layer's backstop carrier, handed to prepare so a prepare THROW still names its run. */
+    taskIdRef: TaskIdRef | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError` in the park closure — after the run, on a swapped
+     *  catalog it is still the CURRENT sink; `models` and prepare's `deps` at the natural-snapshot pin); the one home of why it
+     *  is a seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the TRUSTED Runner self-reference prepare mounts the `run_workflow` tool over (never a TaskSpec field). */
+    self: RunnerSelfSeat;
+    /** borrowed-readonly — the session store prepare acquires / creates the leg's session through. */
+    sessions: SessionStore;
+    /** borrowed-mutable — the Runner's own per-session read-state seat, ALWAYS this Runner's (a caller-supplied one is overridden). */
+    sessionReadStates: SessionReadFileStates;
+    /** borrowed-mutable — the Runner's per-session parked-notification store: the torn-down lane and the escalation pend here. */
+    pendingSessionNotifications: PendingSessionNotifications;
+    /** borrowed-readonly — the orchestrator's entry (a lane may not name the orchestrator; the driver hands it in). */
+    prepareTask: (spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume: PrepareResume | undefined, internals: RunInternals, runnerSelf: RunnerSelfSeat, taskIdRef: TaskIdRef | undefined) => Promise<Prepared>;
+    /** borrowed-readonly — the lanes after this one, entered in this lane's last continuation with what it prepared and bound. */
+    next: (lane: RunNotificationLaneResult) => Promise<R>;
+}
+/** What the lane prepared and bound — the seats every lane after it reads. */
+export interface RunNotificationLaneResult {
+    /** The leg's prepared seat. */
+    prepared: Prepared;
+    /** The ONE injection entry every notification producer rides (the identity lane binds the notify() bridge to it). */
+    injectTaskNotification: (notification: TaskNotificationPayload, opts?: {
+        priority?: SystemInjectionPriority;
+    }) => Promise<"queued" | "parked" | "dropped_duplicate">;
+    /** The turn-open dedup set (the cross-layer double-park dedup): the identity lane registers a redelivered frame's key here. */
+    deliveredAtTurnOpen: Set<string>;
+    /** design/176: the peer inbound chain ref this run carries (the spawn chain's, or a fresh one). */
+    peerInboundChainRef: PeerInboundChainRef;
+    /** The model catalog pinned BEFORE prepare (the natural-snapshot closure for swapDeps): the budget seats resolve against it. */
+    modelCatalog: RunnerDeps["models"];
+    /** The lane's bindings as one seat over its own variables — see {@link NotificationLaneBindings}. */
+    notificationLane: NotificationLaneBindings;
+    /** The queue subscription's release; the leg lane's finally calls it right after flipping `live`. */
+    unsubscribeTaskNotifications: () => void;
+}
+export declare function runNotificationLane<R>(input: RunNotificationLaneInput<R>): Promise<R>;

package/dist/core/runner/run-notification-lane.js

@@ -0,0 +1,128 @@
+import { createPeerInboundChainRef, createPeerSelfRef } from "../../agents/peer-admission.js";
+import { boundInputHashOf } from "../canonical-json.js";
+import { isDelegatedAgentTerminal, isTerminalTaskNotification, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
+import { ToolDetachHub } from "../tool-detach.js";
+import { pendingContentAskCallId } from "./decide-continuation.js";
+export async function runNotificationLane(input) {
+    const { spec, queue, resume, internals, taskIdRef, runner, self, sessions, sessionReadStates, pendingSessionNotifications, prepareTask, next } = input;
+    const prepareResume = resume
+        ? {
+            leafId: resume.cp.leafId,
+            suspendedBatch: new Set(resume.cp.pendingAction.kind === "tool_approval" ? resume.cp.pendingAction.batchToolCallIds : []),
+            seed: resume.cp.state,
+            priorSuspendCount: resume.cp.suspendCount,
+            priorLedger: resume.cp.resourceLedger,
+            priorHumanReview: resume.cp.humanReview,
+            workspaceHandle: resume.cp.state.workspaceHandle,
+            executesApprovedAction: resume.cp.pendingAction.kind === "tool_approval" &&
+                resume.outcome.gate !== "wake" &&
+                resume.outcome.decision === "allow",
+            ...(resume.outcome.gate !== "wake" && resume.outcome.decision === "allow" && pendingContentAskCallId(resume.cp) !== undefined
+                ? {
+                    redeemedContentAskCallId: pendingContentAskCallId(resume.cp),
+                    redeemedContentAskQuestionsHash: boundInputHashOf(resume.cp.pendingAction.args?.questions),
+                }
+                : {}),
+        }
+        : undefined;
+    const taskNotificationQueue = new SystemInjectionQueue();
+    const detachHub = internals?.detachHub ?? new ToolDetachHub();
+    let notificationHarness;
+    let notificationIdent = () => ({});
+    let notificationLaneLive = true;
+    let notificationSessionId;
+    let descendantAnchorDisclosed = false;
+    const parkTaskNotification = (payload, priority) => {
+        if (notificationSessionId !== undefined)
+            pendingSessionNotifications.pend(notificationSessionId, payload, priority);
+        if (!isDelegatedAgentTerminal(payload))
+            return;
+        const uplink = internals?.parentNotify;
+        if (uplink !== undefined) {
+            try {
+                uplink(payload, { priority });
+            }
+            catch (e) {
+                runner.deps.onError?.(e, { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-uplink" });
+            }
+            return;
+        }
+        const rootAnchor = internals?.rootSessionId;
+        if (rootAnchor !== undefined && rootAnchor !== notificationSessionId) {
+            pendingSessionNotifications.pend(rootAnchor, payload, priority);
+            return;
+        }
+        if (internals?.parentSessionId !== undefined && !descendantAnchorDisclosed) {
+            descendantAnchorDisclosed = true;
+            runner.deps.onError?.(new Error(`background-agent terminal ${payload.task_id} parked on this run's own session — the delegation tree's root session is not reachable from this run (no uplink, no root anchor)`), { phase: "degraded", sessionId: notificationSessionId ?? "", classification: "descendant-terminal-unrouted" });
+        }
+    };
+    const unsubscribeTaskNotifications = taskNotificationQueue.subscribe((item) => {
+        queue.push({ type: "task_notification", notification: item.payload, priority: item.priority, ...notificationIdent() });
+        if (notificationHarness && prepared.batchHaltRef.current === undefined) {
+            const xml = renderTaskNotificationXml(item.payload);
+            const noteOptions = {
+                provenance: "engine-note",
+                enginePayload: item.payload,
+                ...(item.payload.task_type !== "external" && isTerminalTaskNotification(item.payload) ? { capPreferred: true } : {}),
+            };
+            const deliver = item.priority === "later"
+                ? notificationHarness.followUp(xml, noteOptions)
+                : notificationHarness.steer(xml, { ...noteOptions, ...(item.priority === "now" ? { immediate: true } : {}) });
+            void deliver.then(() => item.onDisposition?.("queued"), () => {
+                parkTaskNotification(item.payload, item.priority);
+                item.onDisposition?.("parked");
+            });
+        }
+        else {
+            parkTaskNotification(item.payload, item.priority);
+            item.onDisposition?.("parked");
+        }
+    });
+    const upstreamTaskNotification = internals?.onTaskNotification;
+    const deliveredAtTurnOpen = new Set();
+    const injectTaskNotification = (notification, opts) => {
+        if (deliveredAtTurnOpen.has(taskNotificationDedupKey(notification)))
+            return Promise.resolve("dropped_duplicate");
+        if (!notificationLaneLive) {
+            parkTaskNotification(notification, opts?.priority ?? "later");
+            return Promise.resolve("parked");
+        }
+        return new Promise((resolve) => {
+            const accepted = taskNotificationQueue.enqueue({
+                kind: "task_notification",
+                priority: opts?.priority ?? "later",
+                dedupKey: taskNotificationDedupKey(notification),
+                payload: notification,
+                onDisposition: resolve,
+            });
+            if (!accepted)
+                resolve("queued");
+        });
+    };
+    const peerSelfRef = internals?.peerSelfRef ?? createPeerSelfRef(internals?.registryScope ?? spec.principal ?? "default");
+    const peerInboundChainRef = internals?.peerInboundChainRef ?? createPeerInboundChainRef();
+    const modelCatalog = runner.deps.models;
+    const prepared = await prepareTask(spec, runner.deps, sessions, prepareResume, {
+        ...(internals ?? {}),
+        peerSelfRef,
+        peerInboundChainRef,
+        detachHub,
+        sessionReadStates,
+        onTaskNotification: (notification, opts) => {
+            try {
+                upstreamTaskNotification?.(notification, opts);
+            }
+            catch {
+            }
+            injectTaskNotification(notification, opts);
+        },
+    }, self, taskIdRef);
+    const notificationLane = {
+        get harness() { return notificationHarness; }, set harness(h) { notificationHarness = h; },
+        get sessionId() { return notificationSessionId; }, set sessionId(s) { notificationSessionId = s; },
+        get ident() { return notificationIdent; }, set ident(f) { notificationIdent = f; },
+        get live() { return notificationLaneLive; }, set live(v) { notificationLaneLive = v; },
+    };
+    return await next({ prepared, injectTaskNotification, deliveredAtTurnOpen, peerInboundChainRef, modelCatalog, notificationLane, unsubscribeTaskNotifications });
+}