@sema-agent/core 7.12.0 → 7.13.0

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

@@ -1,24 +1,33 @@
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { redactThenCut } from "../../agents/subagent-steps.js";
-import { readPendingSteerQueue } from "../checkpoint-store.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
+import { CheckpointError, readPendingSteerQueue, realApprovalOrgFact, remainingBudgetMicroUsd } from "../checkpoint-store.js";
+import { normalizePersistedRuleHit } from "../gate-lanes.js";
 import { formatHookFeedback, hookSeatExpiredError, runHookSeat } from "../hooks.js";
 import { buildHumanInputEvent, projectHumanInput } from "../human-input-projection.js";
+import { ORG_ADJUDICATION_TIMEOUT_MS, settleOrgVerdictWithin } from "../permission-rule-org.js";
+import { applyPersistedTightening, disclosedRuleSet } from "../persisted-rule-arms.js";
 import { computeCostMicroUsd } from "../pricing.js";
 import { mintSystemReminder } from "../reminder-mint.js";
 import { hasDestroy } from "../remote-env.js";
+import { refuseOutOfContractDecision } from "../tool-policy.js";
+import { callFaceSeat, judgeParkedToolIdentity, rosterEntryNamed, toolCallFaceOf } from "../tool-roster.js";
 import { deliverEngineNotice } from "../types.js";
-import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
+import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, 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 { deepJsonEqual, DEFERRED_REISSUE, resumeContinuation } from "./decide-continuation.js";
+import { settleExecutionRecord } from "./execution-record.js";
+import { mintGateOutcome } from "./gate-exit.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 { toolEndBodyFrom, toolResultMsg } from "./tool-end-body.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;
+    const { spec, queue, prepared, resume, rs, entryActor, effectiveTimeoutMs, timeout, pushContent, ident, emitCommitted, writeFamilyOf, startedToolCallIds, announceWorkspaceMove, withBrainSinks, flushGitMirror, loopLatch, notificationLane, unsubscribeTaskNotifications, unsubGitRetry, unsubBoundary, unsub, runner, next } = input;
     let final;
     let threw;
     let abortedLive = false;
@@ -55,7 +64,7 @@ export async function runLeg(input) {
                 }
             }
             if (resumeWindowRetryAfterMs === undefined && !walltimeExhaustedResume && resume.outcome.gate !== "wake") {
-                await applyResumeDecision(prepared, resume, (e) => pushContent({ ...e, ...ident() }), emitCommitted, (toolName, details) => {
+                await applyResumeDecision(runner, prepared, resume, (e) => pushContent({ ...e, ...ident() }), emitCommitted, (toolName, details) => {
                     if (rs.attach.attachState === undefined)
                         return;
                     const family = writeFamilyOf(toolName);
@@ -460,3 +469,245 @@ export async function runLeg(input) {
     }
     return await next({ final, threw, abortedLive, userInterruptedLive, strandedHumanAnswers });
 }
+const ORG_DISCLOSURE_MAX_CHARS = 600;
+async function applyResumeDecision(runner, prepared, resume, emit, emitCommitted, onResolvedToolSuccess, onExecuteStart) {
+    const { pendingAction } = resume.cp;
+    if (resume.outcome.gate === "dry_run_review")
+        return;
+    if (resume.outcome.gate === "plan_review")
+        return;
+    if (pendingAction.kind !== "tool_approval")
+        return;
+    if (resume.outcome.gate === "policy_ask" &&
+        resume.outcome.decision === "allow" &&
+        !prepared.tools.some((t) => t.name === pendingAction.toolName)) {
+        const e = new Error(`the approved tool "${pendingAction.toolName}" is no longer available on resume — refusing to continue as if it ran; the checkpoint is reopened for a retry with the tool present`);
+        e.code = "resume.tool_unavailable";
+        throw e;
+    }
+    const liveRoster = prepared.toolRosterDeltas.current;
+    if (pendingAction.kind === "tool_approval" && liveRoster !== undefined && judgeParkedToolIdentity(pendingAction, rosterEntryNamed(liveRoster, pendingAction.toolName)) === "mismatch") {
+        const e = new Error(`the approved tool "${pendingAction.toolName}" on this leg is not the tool the approval was minted against (its contract / shape / revision differ) — refusing to execute a replacement wearing the name; the checkpoint is reopened for a retry with the original tool present`);
+        e.code = "resume.tool_contract_mismatch";
+        throw e;
+    }
+    const completed = new Set(pendingAction.completedCallIds);
+    const deferredIds = pendingAction.batchToolCallIds.filter((id) => id !== pendingAction.toolCallId && !completed.has(id));
+    const names = new Map();
+    const deferredArgs = new Map();
+    if (deferredIds.length > 0) {
+        const { messages } = await prepared.session.buildContext();
+        for (const m of messages) {
+            if (m.role === "assistant") {
+                for (const c of m.content) {
+                    if (c.type === "toolCall") {
+                        names.set(c.id, c.name);
+                        deferredArgs.set(c.id, c.arguments);
+                    }
+                }
+            }
+        }
+    }
+    for (const id of pendingAction.batchToolCallIds) {
+        if (id === pendingAction.toolCallId) {
+            await resolvePendingCall(runner, prepared, resume, emit, emitCommitted, onResolvedToolSuccess, onExecuteStart);
+        }
+        else if (!completed.has(id)) {
+            const name = names.get(id) ?? "unknown";
+            const displayLabel = (() => {
+                const l = prepared.tools.find((t) => t.name === name)?.label;
+                return l !== undefined && l !== name ? { label: l } : {};
+            })();
+            emit({ type: "tool_start", toolCallId: id, toolName: name, ...displayLabel, args: deferredArgs.get(id) ?? {} });
+            emit({ type: "tool_end", toolCallId: id, toolName: name, ...displayLabel, isError: true, ...toolEndBodyFrom({ content: formatHookFeedback(DEFERRED_REISSUE, prepared.reminderMark) }, true, prepared.structuredProjector) });
+            const eid = await prepared.session.appendMessage(toolResultMsg(id, name, formatHookFeedback(DEFERRED_REISSUE, prepared.reminderMark), true));
+            emitCommitted(eid, "toolResult", id);
+        }
+    }
+}
+async function resolvePendingCall(runner, prepared, resume, emit, emitCommitted, onResolvedToolSuccess, onExecuteStart) {
+    const { pendingAction } = resume.cp;
+    const { outcome } = resume;
+    if (pendingAction.kind !== "tool_approval" || outcome.gate !== "policy_ask")
+        return;
+    const decidedGate = outcome.gateOutcome;
+    if (decidedGate === undefined) {
+        throw new CheckpointError("checkpoint.invalid_outcome", "pending action reached the resolver with no settlement record on its decision (gateOutcome) — refusing to execute or settle a decision that carries no record");
+    }
+    const resolvedArgs = pendingAction.toolName === ASK_USER_QUESTION_TOOL_NAME ? pendingAction.args : (outcome.updatedInput !== undefined ? outcome.updatedInput : pendingAction.args);
+    const pendingLabel = (() => { const l = prepared.tools.find((t) => t.name === pendingAction.toolName)?.label; return l !== undefined && l !== pendingAction.toolName ? { label: l } : {}; })();
+    emit({ type: "tool_start", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, args: resolvedArgs });
+    const settleEnd = async (isError, result, gate = decidedGate) => {
+        emit({ type: "tool_end", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, isError, ...toolEndBodyFrom(result, isError, prepared.structuredProjector, gate) });
+        const word = await resume.recordExecutionOutcome(gate);
+        settleExecutionRecord(runner.deps.onNotice, word, { toolName: pendingAction.toolName, gate, sessionId: prepared.sessionId, runId: prepared.runId, scope: resume.cp.scope, ...(resume.cp.checkpointId !== undefined ? { checkpointId: resume.cp.checkpointId } : {}) });
+    };
+    const vetoed = (layer) => mintGateOutcome({
+        deniedBy: layer,
+        ...(outcome.gateOutcome?.settlement !== undefined && outcome.gateOutcome.origin !== undefined ? { settled: { settlement: outcome.gateOutcome.settlement, origin: outcome.gateOutcome.origin } } : {}),
+    });
+    if (outcome.decision === "deny") {
+        const defaultDenial = outcome.gateOutcome?.settlement?.kind === "park_sla_expired"
+            ? `No one answered the approval request for the pending tool call "${pendingAction.toolName}" — the approval window elapsed with no answer, so it was not executed.`
+            : `The pending tool call "${pendingAction.toolName}" was denied by an approver.`;
+        const reason = outcome.reason ? delimitUntrusted("reviewer note", outcome.reason, REVIEWER_NOTE_MAX_BODY) : defaultDenial;
+        await settleEnd(true, { content: formatHookFeedback(reason, prepared.reminderMark) });
+        const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, formatHookFeedback(reason, prepared.reminderMark), true));
+        emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+        return;
+    }
+    if (outcome.decision !== "allow") {
+        throw new CheckpointError("checkpoint.invalid_outcome", `pending action reached the resolver with decision "${String(outcome.decision)}" — only "allow" executes and only "deny" injects a denial; refusing to execute`);
+    }
+    const beltBudget = {
+        resourceRemainingMicroUsd: remainingBudgetMicroUsd(prepared.resourceLedger),
+        resourceSpentMicroUsd: prepared.resourceLedger?.spentMicroUsd ?? 0,
+        suspendCount: resume.cp.suspendCount ?? 0,
+    };
+    if (outcome.decision === "allow" && outcome.updatedInput !== undefined && prepared.basePolicyForResumeEdit) {
+        const rechecked = refuseOutOfContractDecision(await prepared.basePolicyForResumeEdit.check({
+            toolName: pendingAction.toolName,
+            args: resolvedArgs,
+            toolCallId: pendingAction.toolCallId,
+            budget: beltBudget,
+            ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+            ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
+        }, prepared.abortController.signal));
+        const beltUnsafe = rechecked.action === "deny" ||
+            (rechecked.updatedInput !== undefined && !deepJsonEqual(rechecked.updatedInput, resolvedArgs));
+        if (beltUnsafe) {
+            const editedDenial = formatHookFeedback(`The approver EDITED this call's input; the edited call is refused by the deployment's tool policy and was not executed${rechecked.action === "deny" && rechecked.message ? `: ${rechecked.message}` : " (the policy rewrote the edit to a value that was not approved)"}.`, prepared.reminderMark);
+            await settleEnd(true, { content: editedDenial }, vetoed("policy"));
+            const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, editedDenial, true));
+            emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+            return;
+        }
+    }
+    const gateRealApproval = resume.cp.gate.kind === "irreversible_ask" ? resume.cp.gate.realApproval : undefined;
+    const gateOrgGoverned = realApprovalOrgFact(gateRealApproval) !== undefined;
+    if (gateOrgGoverned && prepared.permissionRuleOrg === undefined) {
+        const unwiredDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: its approval was minted under organization governance (${gateRealApproval.origin}), and this worker has no org adjudication wiring — a governed approval may only be redeemed where governance can be enforced. This approval is spent; re-issue the call on an org-wired worker.`, prepared.reminderMark);
+        await settleEnd(true, { content: unwiredDenial }, vetoed("org"));
+        const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, unwiredDenial, true));
+        emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+        return;
+    }
+    if (prepared.permissionRuleOrg !== undefined) {
+        const orgVerdict = prepared.permissionRuleOrg
+            .adjudicate({ toolName: pendingAction.toolName, args: resolvedArgs, toolCallId: pendingAction.toolCallId })
+            .catch(() => ({ status: "unavailable", disclosures: ["the org adjudication face threw on resume"] }));
+        let orgWaitCancelled = false;
+        const org = await settleOrgVerdictWithin(orgVerdict, { status: "unavailable", disclosures: [`the org adjudication face did not answer within ${ORG_ADJUDICATION_TIMEOUT_MS}ms (or the task ended first)`] }, {
+            signal: prepared.abortController.signal,
+            timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS,
+            onFallback: (cause) => {
+                orgWaitCancelled = cause === "aborted";
+            },
+        });
+        const blocked = org.status === "unavailable"
+            ? realApprovalOrgFact(gateRealApproval) === "unavailable"
+                ? undefined
+                : orgWaitCancelled
+                    ? "this deployment is org-governed and the task was cancelled before the organization policy snapshot could be adjudicated"
+                    : "this deployment is org-governed and cannot currently adjudicate against an organization policy snapshot"
+            : org.verdict?.behavior === "deny"
+                ? `an organization policy rule (${org.verdict.rule}) denies it`
+                : undefined;
+        if (blocked !== undefined) {
+            const orgDisclosures = org.status === "unavailable" && org.disclosures.length > 0
+                ? ` Governance disclosures: ${inlineUntrusted(org.disclosures.join("; "), ORG_DISCLOSURE_MAX_CHARS)}.`
+                : "";
+            const orgDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${blocked}.${orgDisclosures} This approval is spent — the call has to be re-issued and approved again once organization policy permits it.`, prepared.reminderMark);
+            await settleEnd(true, { content: orgDenial }, vetoed("org"));
+            const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, orgDenial, true));
+            emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+            return;
+        }
+    }
+    if (prepared.denyNarrowingPolicy) {
+        const narrowed = refuseOutOfContractDecision(await prepared.denyNarrowingPolicy.check({
+            toolName: pendingAction.toolName,
+            args: resolvedArgs,
+            toolCallId: pendingAction.toolCallId,
+            ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
+            budget: beltBudget,
+            ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+        }, prepared.abortController.signal));
+        if (narrowed.action === "deny") {
+            const narrowedDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" is now denied by a session rule and was not executed${narrowed.message ? `: ${narrowed.message}` : ""}.`, prepared.reminderMark);
+            await settleEnd(true, { content: narrowedDenial }, vetoed("policy"));
+            const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, narrowedDenial, true));
+            emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+            return;
+        }
+    }
+    if (prepared.persistedRuleLane !== undefined) {
+        const unreadable = { unreadable: true };
+        const read = await settleOrgVerdictWithin(Promise.resolve()
+            .then(() => prepared.persistedRuleLane.adjudicate({
+            toolName: pendingAction.toolName,
+            args: resolvedArgs,
+            toolCallId: pendingAction.toolCallId,
+            ...callFaceSeat(toolCallFaceOf(prepared.toolRosterDeltas.current, pendingAction.toolName)),
+            budget: beltBudget,
+            ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
+        }))
+            .then((answer) => normalizePersistedRuleHit(answer)), unreadable, { signal: prepared.abortController.signal, timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
+        const tightened = applyPersistedTightening({ action: "allow" }, read);
+        if (tightened.tightened === "deny" || tightened.tightened === "unreadable") {
+            const why = tightened.tightened === "deny"
+                ? `a standing deny rule of yours (${disclosedRuleSet(read.hit?.rules ?? [])}) now refuses it`
+                : "your persisted permission rules could not be read on this leg";
+            const ruleDenial = formatHookFeedback(`The approved tool call "${pendingAction.toolName}" was not executed: ${why}. This approval is spent — the call has to be re-issued and approved again.`, prepared.reminderMark);
+            await settleEnd(true, { content: ruleDenial }, vetoed("persisted_rule"));
+            const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, ruleDenial, true));
+            emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+            return;
+        }
+    }
+    const tool = prepared.tools.find((t) => t.name === pendingAction.toolName);
+    if (!tool) {
+        const e = new Error(`the approved tool "${pendingAction.toolName}" is no longer available on resume`);
+        e.code = "resume.tool_unavailable";
+        throw e;
+    }
+    const args = resolvedArgs;
+    onExecuteStart?.(pendingAction.toolCallId);
+    prepared.suspendProgressRef.executedApproved = true;
+    let res;
+    try {
+        res = await tool.execute(pendingAction.toolCallId, args, prepared.abortController.signal);
+    }
+    catch (err) {
+        const execError = `Error: ${err instanceof Error ? err.message : String(err)}`;
+        const marks = (() => {
+            if (err === null || typeof err !== "object")
+                return undefined;
+            const src = err;
+            let d;
+            if (src.details !== null && typeof src.details === "object" && !Array.isArray(src.details)) {
+                d = { ...src.details };
+            }
+            if (typeof src.errorKind === "string")
+                d = { ...(d ?? {}), errorKind: src.errorKind };
+            return d;
+        })();
+        await settleEnd(true, { content: execError, ...(marks !== undefined ? { details: marks } : {}) });
+        const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, execError, true));
+        emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+        return;
+    }
+    const executedIsError = res.isError === true;
+    await settleEnd(executedIsError, res);
+    onResolvedToolSuccess?.(pendingAction.toolName, executedIsError ? undefined : res.details);
+    const eid = await prepared.session.appendMessage({
+        role: "toolResult",
+        toolCallId: pendingAction.toolCallId,
+        toolName: pendingAction.toolName,
+        content: res.content,
+        details: res.details,
+        isError: executedIsError,
+        timestamp: Date.now(),
+    });
+    emitCommitted(eid, "toolResult", pendingAction.toolCallId);
+}

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

@@ -4,7 +4,7 @@ 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";
+import type { NotificationLaneBindings, Prepared, PrepareTaskFn, 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;
@@ -28,8 +28,9 @@ export interface RunNotificationLaneInput<R> {
     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 orchestrator's entry (a lane may not name the orchestrator; the driver hands it in), as the ONE
+     *  contract the orchestrator's own declaration is pinned to ({@link PrepareTaskFn}, contracts.ts — design/393 S7, #675). */
+    prepareTask: PrepareTaskFn;
     /** 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>;
 }

package/dist/core/runner/run-recovery-lanes.d.ts

@@ -1,9 +1,8 @@
 import type { Model } from "../../internal/llm.js";
 import { type MaybeCompactOptions } from "../auto-compaction.js";
-import type { HookInvocationIdentity } from "../hooks.js";
 import type { PushQueue } from "../push-queue.js";
 import type { Brain, TaskEvent, TaskSpec } from "../types.js";
-import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+import type { InstallingPhaseResult, Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
 export interface RunRecoveryLanesInput {
     /** borrowed-readonly — the task spec: the compaction settings / instructions and the key-and-headers seat. */
     spec: TaskSpec;
@@ -31,24 +30,12 @@ export interface RunRecoveryLanesInput {
     };
     /** borrowed-readonly — the window-safety option builder (the compaction-machinery lane's), per pass. */
     windowSafetyOptions: (mainModel: Model) => Pick<MaybeCompactOptions, "fallbackBudget" | "onWindowSafety">;
-    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`). */
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`; the compaction seams the pass reaches down
+     *  for — compaction-seams.ts — read the summary provider and the hooks slot through it on every pass). */
     runner: RunnerDepsSeat;
-    /** borrowed-readonly — the Runner's three compaction methods as delegates: the Seam C reuse options, the hook
-     *  option wrapper and the reuse counter. The method bodies stay the Runner's; the pass calls them as the run body did. */
-    compactionSeats: {
-        seamCCompactionOptions: (prepared: Prepared) => Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse"> | undefined;
-        compactionHookOptions: (spec: TaskSpec, sessionId: string, trigger: "auto" | "manual" | "forced", identity?: HookInvocationIdentity, seatBound?: {
-            timeoutMs: number;
-            signal?: AbortSignal;
-        }) => Pick<MaybeCompactOptions, "trigger" | "preCompact" | "postCompact">;
-        recordCompactionReuse: (prepared: Prepared, comp: {
-            compacted: boolean;
-            reused?: boolean;
-        }) => void;
-    };
 }
 /** Nothing comes back: the lane's products are INSTALLED on the seats it borrowed — the harness's loop recovery
  *  chain and the microCompact arm-B seat — and the shared pass is read by those two installations alone. */
-export interface RunRecoveryLanesResult {
+export interface RunRecoveryLanesResult extends InstallingPhaseResult {
 }
 export declare function runRecoveryLanes(input: RunRecoveryLanesInput): RunRecoveryLanesResult;

package/dist/core/runner/run-recovery-lanes.js

@@ -7,8 +7,9 @@ import { rebaseCadenceWindows } from "./turn-attachments.js";
 import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
 import { gitRestateOption } from "./git-leg-delivery.js";
 import { COMPACTION_FREED_EPSILON, COMPACTION_REGROWTH_FACTOR, MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
+import { compactionHookOptions, recordCompactionReuse, seamCCompactionOptions } from "./compaction-seams.js";
 export function runRecoveryLanes(input) {
-    const { spec, prepared, queue, rs, ident, compactionBrain, compactionBreaker, windowSafetyOptions, runner, compactionSeats } = input;
+    const { spec, prepared, queue, rs, ident, compactionBrain, compactionBreaker, windowSafetyOptions, runner } = input;
     const runForcedCompactionPass = async (lane, turnSignal) => {
         if (!(spec.compaction?.enabled ?? true))
             return false;
@@ -37,14 +38,14 @@ export function runRecoveryLanes(input) {
                 workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
                 ...contextInstructionFilesOption(prepared),
                 ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
-                ...compactionSeats.seamCCompactionOptions(prepared),
+                ...seamCCompactionOptions(runner, prepared),
                 ...gitRestateOption(prepared),
                 ...windowSafetyOptions(prepared.harness.getModel()),
-                ...compactionSeats.compactionHookOptions(spec, prepared.sessionId, "forced", prepared.hookIdentity, { timeoutMs: prepared.hookTimeoutMs, signal: passSignal }),
+                ...compactionHookOptions(runner, spec, prepared.sessionId, "forced", prepared.hookIdentity, { timeoutMs: prepared.hookTimeoutMs, signal: passSignal }),
             });
             if (comp.compacted) {
                 compactionBreaker.failures = 0;
-                compactionSeats.recordCompactionReuse(prepared, comp);
+                recordCompactionReuse(runner, prepared, comp);
                 if ((comp.freedTokens ?? 0) >= COMPACTION_FREED_EPSILON) {
                     const postSize = comp.postTriggerTokens ?? Math.max(0, (comp.triggerTokens ?? comp.tokensBefore ?? 0) - (comp.freedTokens ?? 0));
                     rs.counters.compactionFloor = Math.ceil(postSize * COMPACTION_REGROWTH_FACTOR);

package/dist/core/runner/run-settle-and-teardown.d.ts

@@ -9,7 +9,9 @@
  * compaction, the forwarded-frame drain and the queue's `done` + close, the file-history boundary settle and the
  * prompt-suggestion kickoff — then, in its finally, the four teardown legs in the order they were: the shell-lane
  * children settle, the background-shell sweep, the registry clears / the background-agent abort / the retained
- * child sessions, and the owned env's teardown.
+ * child sessions, and the owned env's teardown. The suggestion pass (`suggestNextPrompts`, with its four bounds) and the
+ * owned-env teardown (`teardownOwnedEnv`) are the lane's own module-private functions since design/393 S7, verbatim from
+ * the Runner's private methods: each has this one caller, and a sibling file would be a lane-to-lane reach (the S6 legs' reading).
  *
  * Async (eleven first-level awaits, all of them the same awaits at the same positions). The `queue.push("done")` and
  * the teardown legs' order are contract (the forwarded-frame drain lands before `done`; the env is torn down after
@@ -21,9 +23,9 @@ import type { AssistantMessage } from "../../internal/llm.js";
 import type { ResolvedReasoning } from "../../brain/reasoning.js";
 import type { PushQueue } from "../push-queue.js";
 import type { SessionStore } from "../session.js";
-import type { CompactOutcome, DelegationLifecycleEvent, TaskEvent, TaskResult, TaskSpec } from "../types.js";
+import { type CompactOutcome, type DelegationLifecycleEvent, type TaskEvent, type TaskResult, type TaskSpec } from "../types.js";
 import { type Stats } from "./assemble-result.js";
-import type { EndOfTaskCompaction, ManualCompactRef, Prepared, ResumeRun, RunInternals, RunnerDepsSeat, RunState, SuspendReap, TaskIdRef } from "./contracts.js";
+import type { EndOfTaskCompaction, InstallingPhaseResult, ManualCompactRef, Prepared, ResumeRun, RunInternals, RunnerDepsSeat, RunState, SuspendReap, TaskIdRef } from "./contracts.js";
 export interface RunSettleAndTeardownInput {
     /** borrowed-readonly — the task spec: the hooks slot, the suggestion opt-in, the retain / forward flags, the task id and principal. */
     spec: TaskSpec;
@@ -76,6 +78,11 @@ export interface RunSettleAndTeardownInput {
     threw: unknown;
     /** borrowed-readonly — the live-abort flag captured before the leg's release-abort. */
     abortedLive: boolean;
+    /** borrowed-readonly — the leg's snapshot of `loopLatch.userInterrupted`: names the origin of a stop that landed after the answer settled. */
+    userInterruptedLive: boolean;
+    /** borrowed-readonly — #677: the terminal-adoption lane's ONE evaluation of `answerSettled` (a clean `"stop"` final, no continuation
+     *  lost). Read by the arbitration (`ResultFlags.answerSettled`), the teardown's stop-source attribution and the notice. */
+    answerSettled: boolean;
     /** borrowed-readonly — design/174: the answered-but-never-collected deliveries the leg's finally settled. */
     strandedHumanAnswers: ReadonlyArray<{
         deliveryId: string;
@@ -93,17 +100,14 @@ export interface RunSettleAndTeardownInput {
     onSuggestions: (p: Promise<string[]>) => void;
     /** borrowed-readonly — the stream's reap-stash for a committed pause (what `destroy()` reaps when the run SUSPENDED). */
     onSuspend: (reap: SuspendReap) => void;
-    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`, `hooks`, `checkpointStore`, `executionEnv`, `onNotice`);
-     *  the one home of why it is a seat and not a captured object is {@link RunnerDepsSeat}. */
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE (`onError`, `hooks`, `checkpointStore`, `executionEnv`, `onNotice`; the
+     *  suggestion pass reads `brain` / `pricing` / `roles` and the owned-env teardown `onError` through it too); the one home of why it
+     *  is a seat and not a captured object is {@link RunnerDepsSeat}. */
     runner: RunnerDepsSeat;
     /** borrowed-readonly — the session store: the resumed-terminal leg unpins the checkpoint's session through it. */
     sessions: SessionStore;
-    /** borrowed-readonly — the Runner's post-completion prompt-suggestion pass (its private method, as a delegate). */
-    suggestNextPrompts: (spec: TaskSpec, prepared: Prepared, result: TaskResult) => Promise<string[]>;
-    /** borrowed-readonly — the Runner's owned-env teardown (its private method, as a delegate; its gate mirrors the reap-stash's). */
-    teardownOwnedEnv: (prepared: Prepared) => Promise<void>;
 }
 /** Nothing comes back: the result is published through `setResult`, the queue is closed, the teardown legs ran. */
-export interface RunSettleAndTeardownResult {
+export interface RunSettleAndTeardownResult extends InstallingPhaseResult {
 }
 export declare function runSettleAndTeardown(input: RunSettleAndTeardownInput): Promise<RunSettleAndTeardownResult>;

package/dist/core/runner/run-settle-and-teardown.js

@@ -1,18 +1,24 @@
+import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
+import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { modelCostToPricing } from "../pricing.js";
 import { hasDestroy, isIsolated } from "../remote-env.js";
+import { resolveTaskModel } from "../roles.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../types.js";
 import { assembleResult } from "./assemble-result.js";
 import { TIMER_LATENESS_REPORT_MS } from "./clock-and-limits.js";
 import { resumeDecisionWasNegative } from "./decide-continuation.js";
 import { drainForwardedFramesBeforeDone, forwardsSubagentEvents } from "./prepare-run-refs.js";
+import { generatePromptSuggestions } from "./prompt-suggestions.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { amendTerminal, terminalProjection } from "./terminal-projection.js";
 export async function runSettleAndTeardown(input) {
-    const { spec, queue, prepared, resume, internals, rs, stats, ident, parentToolCallId, subagentName, loopLatch, timeout, ownCommittedTailRef, emitDelegationLifecycle, taskIdRef, manualCompactRef, drainManualCompact, final, threw, abortedLive, strandedHumanAnswers, reasoningResolution, comp, setResult, onSuggestions, onSuspend, runner, sessions, suggestNextPrompts, teardownOwnedEnv } = input;
+    const { spec, queue, prepared, resume, internals, rs, stats, ident, parentToolCallId, subagentName, loopLatch, timeout, ownCommittedTailRef, emitDelegationLifecycle, taskIdRef, manualCompactRef, drainManualCompact, final, threw, abortedLive, userInterruptedLive, answerSettled, strandedHumanAnswers, reasoningResolution, comp, setResult, onSuggestions, onSuspend, runner, sessions } = input;
     try {
         if (comp?.compacted) {
             queue.push({
@@ -107,6 +113,7 @@ export async function runSettleAndTeardown(input) {
             abortedForTimeout: timeout.fired,
             abortedForTurns: rs.limits.turnsExceeded,
             abortedLive,
+            answerSettled,
             budgetHit: rs.limits.budgetHit,
             budgetAxis: rs.limits.budgetAxis,
             blockedReason: prepared.blockedRef.reason,
@@ -116,6 +123,19 @@ export async function runSettleAndTeardown(input) {
             suspendLoop: prepared.suspendLoopRef.hit,
             ...(prepared.pausedRef.current !== undefined ? { paused: prepared.pausedRef.current.cause } : {}),
         });
+        if (abortedLive && answerSettled && result.terminal.kind === "completed") {
+            deliverEngineNotice(runner.deps.onNotice, {
+                code: "task.interrupt_unconsumed",
+                message: "a stop arrived after the run had already given its answer: nothing was cut or stopped by it — the answer stands " +
+                    "as the result, the run ends completed, and no interruption marker or limit code records the stop.",
+                detail: {
+                    sessionId: prepared.sessionId,
+                    runId: rs.telemetry.runId,
+                    ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
+                    origin: userInterruptedLive ? "interrupt" : timeout.fired ? "walltime" : rs.limits.turnsExceeded ? "turns" : "signal",
+                },
+            });
+        }
         if (resume !== undefined &&
             resume.pendingActionStarted !== true &&
             result.terminal.kind !== "completed" &&
@@ -269,8 +289,8 @@ export async function runSettleAndTeardown(input) {
         queue.push({ type: "done", result });
         queue.close();
         await prepared.fileHistoryBoundary?.settle();
-        if (spec.suggestNextPrompts && result.terminal.kind === "completed") {
-            onSuggestions(suggestNextPrompts(spec, prepared, result));
+        if (spec.suggestNextPrompts && result.terminal.kind === "completed" && !abortedLive) {
+            onSuggestions(suggestNextPrompts(spec, prepared, result, runner));
         }
     }
     finally {
@@ -280,6 +300,7 @@ export async function runSettleAndTeardown(input) {
             prepared.pausedRef.current === undefined;
         await settleTeardownLeg(() => defaultTaskRegistry.settleKilledForOwner({ owner: spec.taskId ?? prepared.sessionId, scope: spec.principal ?? "default", sessionId: prepared.sessionId }, {
             source: abortedLive &&
+                !answerSettled &&
                 !timeout.fired &&
                 !rs.limits.turnsExceeded &&
                 rs.limits.budgetHit === undefined &&
@@ -318,7 +339,94 @@ export async function runSettleAndTeardown(input) {
         if (prepared.subagentRetain) {
             await settleTeardownLeg(() => prepared.subagentRetain.disposeAll(), "subagentRetain.disposeAll", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
         }
-        await settleTeardownLeg(() => teardownOwnedEnv(prepared), "teardownOwnedEnv", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+        await settleTeardownLeg(() => teardownOwnedEnv(prepared, runner), "teardownOwnedEnv", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
     }
     return {};
 }
+const SUGGESTIONS_DEFAULT_COUNT = 3;
+const SUGGESTIONS_MAX_COUNT = 8;
+const SUGGESTIONS_TIMEOUT_MS = 30_000;
+const SUGGESTIONS_TRANSCRIPT_MESSAGES = 12;
+async function suggestNextPrompts(spec, prepared, result, runner) {
+    const cfg = typeof spec.suggestNextPrompts === "object" ? spec.suggestNextPrompts : {};
+    const count = cfg.count && cfg.count > 0 ? Math.min(cfg.count, SUGGESTIONS_MAX_COUNT) : SUGGESTIONS_DEFAULT_COUNT;
+    const ac = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort();
+            resolve([]);
+        }, SUGGESTIONS_TIMEOUT_MS);
+    });
+    const work = (async () => {
+        let model = prepared.model;
+        let thinking = prepared.thinking;
+        try {
+            const resolved = resolveTaskModel({ modelRole: cfg.role ?? "summarize", roles: spec.roles }, runner.deps);
+            model = resolved.model;
+            thinking = resolved.thinking;
+        }
+        catch (roleErr) {
+            if (cfg.role !== undefined) {
+                let asked;
+                try {
+                    asked = String(cfg.role);
+                }
+                catch {
+                    asked = `<unrenderable ${typeof cfg.role}>`;
+                }
+                try {
+                    runner.deps.onError?.(new Error(`suggestNextPrompts.role ${JSON.stringify(asked.length > 80 ? `${asked.slice(0, 80)}…` : asked)} did not resolve to a model — the prompt-suggestion pass ran on the task's own model (${prepared.model.id}) instead. Configure that role in RunnerDeps.roles / TaskSpec.roles, or omit the field to use the "summarize" role.`, { cause: roleErr }), { phase: "suggestions", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+        }
+        if (!sameRouteIdentity(model, prepared.model)) {
+            const verdict = await adjudicateDerivedRoute({ brain: runner.deps.brain, model, getApiKeyAndHeaders: spec.getApiKeyAndHeaders });
+            if (verdict !== undefined && !verdict.ok) {
+                deliverEngineNotice(runner.deps.onNotice, fallbackToPrimaryNotice({ seat: "prompt-suggestions", from: model.id, to: prepared.model.id, verdict, sessionId: prepared.sessionId, runId: prepared.runId }));
+                model = prepared.model;
+                thinking = prepared.thinking;
+            }
+        }
+        const pricing = runner.deps.pricing?.[model.id] ?? modelCostToPricing(model.cost);
+        const ctx = await prepared.session.buildContext();
+        const transcript = ctx.messages.filter((m) => !isSyntheticApiErrorMessage(m)).slice(-SUGGESTIONS_TRANSCRIPT_MESSAGES);
+        const out = await generatePromptSuggestions({ brain: runner.deps.brain, model, pricing, thinking, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, signal: ac.signal }, transcript, count);
+        if (out.tokens > 0 || out.costMicroUsd > 0) {
+            result.stats.suggestions = { tokens: out.tokens, costMicroUsd: out.costMicroUsd };
+            if (result.stats.costBreakdown) {
+                result.stats.costBreakdown.suggestionsMicroUsd = out.costMicroUsd;
+            }
+        }
+        return out.suggestions;
+    })();
+    work.catch(() => { });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    catch (err) {
+        try {
+            runner.deps.onError?.(err, { phase: "suggestions", sessionId: prepared.sessionId });
+        }
+        catch {
+        }
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function teardownOwnedEnv(prepared, runner) {
+    if (prepared.ownedEnv &&
+        hasDestroy(prepared.ownedEnv) &&
+        prepared.pausedRef.current === undefined) {
+        try {
+            await prepared.ownedEnv.destroy();
+        }
+        catch (err) {
+            runner.deps.onError?.(err, { phase: "config", sessionId: prepared.sessionId });
+        }
+    }
+}

package/dist/core/runner/run-stop-and-final-verify.d.ts

@@ -1,7 +1,7 @@
 import type { PushQueue } from "../push-queue.js";
 import type { TaskEvent, TaskSpec } from "../types.js";
 import type { Stats } from "./assemble-result.js";
-import type { Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
+import type { InstallingPhaseResult, Prepared, RunnerDepsSeat, RunState } from "./contracts.js";
 export interface RunStopAndFinalVerifyInput {
     /** borrowed-readonly — the task spec: the hooks slot and the `finalVerification` opt-in. */
     spec: TaskSpec;
@@ -27,6 +27,6 @@ export interface RunStopAndFinalVerifyInput {
     runner: RunnerDepsSeat;
 }
 /** Nothing comes back: the gate is INSTALLED on the borrowed harness, and the seat's closures are read by it alone. */
-export interface RunStopAndFinalVerifyResult {
+export interface RunStopAndFinalVerifyResult extends InstallingPhaseResult {
 }
 export declare function runStopAndFinalVerify(input: RunStopAndFinalVerifyInput): RunStopAndFinalVerifyResult;