@sema-agent/core 7.7.0 → 7.8.0

package/dist/core/runner/run-turn-boundary.js

@@ -0,0 +1,694 @@
+import { mintSystemReminder } from "../reminder-mint.js";
+import { DEFAULT_COMPACTION_SETTINGS } from "../../internal/harness.js";
+import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
+import { DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, maybeCompact, nextTrimForceBackoff, recordCompactionAndCheckRapidRefill } from "../auto-compaction.js";
+import { emitTrace } from "../trace.js";
+import { redactThenCut } from "../../agents/subagent-steps.js";
+import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, attachmentEnvelopeTags, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, rebaseCadenceWindows, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta } from "./turn-attachments.js";
+import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
+import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { droppedToolDigest, withAnnounceDigests } from "./announce-once-ledger.js";
+import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
+import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-size-guideline.js";
+import { awaitChargeWithSlowDisclosure, discloseUnevaluableWindow, ENV_DUE_GOVERNANCE_READ_BUDGET_MS, GOVERNANCE_READ_STALLED, LIMIT_APPROACH_DEFAULT_THRESHOLDS, limitApproachFrames, platformLimitTerminal, raceUntilDeadline } from "./clock-and-limits.js";
+import { gitRestateOption } from "./git-leg-delivery.js";
+export const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
+export const COMPACTION_REGROWTH_FACTOR = 1.5;
+export const COMPACTION_FREED_EPSILON = 256;
+const BATCH_CONTEXT_MIN_KEEP_BYTES = 160;
+const BATCH_TRUNCATION_MARKER = "\n…[truncated]";
+export function createTurnBoundary(input) {
+    const { prepared, stats, rs, deps } = input;
+    const { spec, queue, manualCompactRef, todoToolMounted, taskToolsMounted, walltimeMonotonicDeadline, timeout, ident, postToolBatchHook, batchArgs, compactionBrain, withinTaskCompaction, compactionBreaker, windowSafetyOptions, rapidRefill, drainManualCompact, runnerHooks } = deps;
+    let finalVerifySeenAtLastBoundary = 0;
+    const onTurnBoundary = async (event) => {
+        let boundarySteered = false;
+        const noNextRequest = () => prepared.stopRequestedRef.current || deps.loopLatch.userHalted;
+        const walltimeHit = walltimeMonotonicDeadline !== undefined && performance.now() >= walltimeMonotonicDeadline;
+        const preemptHit = spec.preemptSignal?.aborted === true;
+        if (preemptHit && !prepared.suspendForResource && !rs.counters.preemptIgnoredReported) {
+            rs.counters.preemptIgnoredReported = true;
+            emitTrace(rs.telemetry.tracer, () => ({ kind: "preempt.ignored", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
+        }
+        let platformCause;
+        let platformRetryAfterMs;
+        const preemptWillSuspend = preemptHit && prepared.suspendForResource !== undefined;
+        if (!preemptWillSuspend && prepared.pausedRef.current === undefined && !prepared.abortController.signal.aborted) {
+            const ledgerReadDeadline = prepared.envLifetimeSuspendAt !== undefined ? prepared.envLifetimeSuspendAt + ENV_DUE_GOVERNANCE_READ_BUDGET_MS : undefined;
+            if (prepared.usageGovernance !== undefined) {
+                const governance = prepared.usageGovernance;
+                try {
+                    const at = Date.now();
+                    await awaitChargeWithSlowDisclosure(governance.commit(stats.tokens, rs.telemetry.unpricedSpend ? undefined : stats.costMicroUsd, at), () => runnerHooks.onError?.(new Error("the usage ledger CHARGE has not settled after 10s — still waiting (a charge is never abandoned: walking away would double-charge on the end-of-task flush). A wedged ledger store wedges this boundary, now visibly."), { phase: "config", sessionId: prepared.sessionId }));
+                    const windowRead = governance.check(at);
+                    let answer;
+                    if (ledgerReadDeadline !== undefined) {
+                        answer = await raceUntilDeadline(windowRead, ledgerReadDeadline);
+                        if (answer === GOVERNANCE_READ_STALLED) {
+                            void windowRead.catch((lateErr) => {
+                                try {
+                                    runnerHooks.onError?.(lateErr instanceof Error ? lateErr : new Error(String(lateErr)), { phase: "config", sessionId: prepared.sessionId });
+                                }
+                                catch {
+                                }
+                            });
+                            try {
+                                runnerHooks.onError?.(new Error("the usage ledger did not answer before the execution environment's suspend deadline — stopping for the environment, the cause this run can still prove. The window state for this boundary is UNKNOWN and was not enforced."), { phase: "config", sessionId: prepared.sessionId });
+                            }
+                            catch {
+                            }
+                        }
+                    }
+                    else {
+                        answer = await windowRead;
+                    }
+                    if (answer !== GOVERNANCE_READ_STALLED) {
+                        platformRetryAfterMs = answer;
+                        if (platformRetryAfterMs !== undefined)
+                            platformCause = "usage_window";
+                    }
+                }
+                catch (govErr) {
+                    rs.limits.platformTerminal = govErr instanceof Error ? govErr : new Error(String(govErr));
+                    void prepared.harness.abort();
+                    prepared.abortController.abort();
+                    return undefined;
+                }
+            }
+            if (platformCause === undefined && prepared.envLifetimeSuspendAt !== undefined && Date.now() >= prepared.envLifetimeSuspendAt) {
+                platformCause = "env_lifetime";
+            }
+        }
+        if (platformCause !== undefined) {
+            const platformSpend = { costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) };
+            const committed = prepared.suspendForPlatformLimit !== undefined &&
+                (await prepared.suspendForPlatformLimit(platformCause, platformSpend, platformRetryAfterMs !== undefined ? { resumeAfterMs: platformRetryAfterMs } : undefined));
+            if (committed) {
+                rs.limits.turnsExceeded = false;
+                rs.limits.budgetHit = undefined;
+                return undefined;
+            }
+            const terminal = platformLimitTerminal(platformCause, platformRetryAfterMs);
+            rs.limits.platformTerminal = terminal;
+            try {
+                runnerHooks.onError?.(terminal, { phase: "config", sessionId: prepared.sessionId });
+            }
+            catch {
+            }
+            void prepared.harness.abort();
+            prepared.abortController.abort();
+            return undefined;
+        }
+        if (prepared.suspendForResource &&
+            (rs.limits.turnsExceeded || rs.limits.budgetHit !== undefined || walltimeHit || preemptHit) &&
+            prepared.pausedRef.current === undefined) {
+            const reason = preemptHit
+                ? "preempt"
+                : rs.limits.budgetHit !== undefined
+                    ? rs.limits.budgetAxis === "tokens"
+                        ? "budget_tokens"
+                        : "budget_cost"
+                    : rs.limits.turnsExceeded
+                        ? "turns"
+                        : "walltime";
+            const sliceSpend = { costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) };
+            if (await prepared.suspendForResource(reason, sliceSpend)) {
+                rs.limits.turnsExceeded = false;
+                rs.limits.budgetHit = undefined;
+            }
+            else {
+                void prepared.harness.abort();
+                prepared.abortController.abort();
+            }
+            return undefined;
+        }
+        if (walltimeMonotonicDeadline !== undefined &&
+            prepared.suspendForResource === undefined &&
+            performance.now() >= walltimeMonotonicDeadline) {
+            if (!timeout.fired) {
+                timeout.fired = true;
+                timeout.clear();
+                timeout.latenessMs = Math.max(timeout.latenessMs ?? 0, performance.now() - walltimeMonotonicDeadline);
+                rs.counters.walltimeSyncBackstopFired = true;
+                void prepared.harness.abort();
+                prepared.abortController.abort();
+            }
+            return undefined;
+        }
+        const approachCfg = spec.limits?.approachNotice;
+        if (approachCfg !== false &&
+            rs.counters.approachNoticesSent < LIMIT_APPROACH_DEFAULT_THRESHOLDS.length &&
+            prepared.suspendForResource === undefined &&
+            rs.turn.lastTurnHadToolCalls &&
+            prepared.batchHaltRef.current === undefined &&
+            !boundarySteered &&
+            !prepared.abortController.signal.aborted) {
+            const thresholds = approachCfg?.at ?? LIMIT_APPROACH_DEFAULT_THRESHOLDS;
+            const ratios = [];
+            if (rs.budget.maxTokensWindow !== undefined && rs.budget.maxTokensWindow > 0) {
+                ratios.push({ axis: "token budget", ratio: stats.tokens / rs.budget.maxTokensWindow });
+            }
+            if (rs.budget.maxCostMicroUsd !== undefined && rs.budget.maxCostMicroUsd > 0) {
+                ratios.push({ axis: "cost budget", ratio: stats.costMicroUsd / rs.budget.maxCostMicroUsd });
+            }
+            const declaredMaxTurns = spec.limits?.maxTurns;
+            if (declaredMaxTurns !== undefined && declaredMaxTurns > 0) {
+                ratios.push({ axis: "turn budget", ratio: (stats.turns + 1) / declaredMaxTurns });
+            }
+            if (walltimeMonotonicDeadline !== undefined) {
+                const walltimeWindowMs = walltimeMonotonicDeadline - rs.telemetry.taskStartMonotonic;
+                if (walltimeWindowMs > 0) {
+                    ratios.push({ axis: "walltime budget", ratio: (performance.now() - rs.telemetry.taskStartMonotonic) / walltimeWindowMs });
+                }
+            }
+            let tightest;
+            for (const r of ratios)
+                if (tightest === undefined || r.ratio > tightest.ratio)
+                    tightest = r;
+            const index = rs.counters.approachNoticesSent;
+            if (tightest !== undefined && tightest.ratio >= thresholds[index]) {
+                rs.counters.approachNoticesSent += 1;
+                const percent = Math.min(100, Math.round(tightest.ratio * 100));
+                const body = limitApproachFrames(index === 0 ? 0 : 1, tightest.axis, percent, prepared.reminderMark);
+                void prepared.harness.steer(body, { engineMinted: true }).catch(() => undefined);
+                queue.push({ type: "steering_injected", source: "limit_approach", preview: body.slice(0, 220), ...ident() });
+                boundarySteered = true;
+            }
+        }
+        if (prepared.reviewRequestRef.pending !== undefined) {
+            const { reason } = prepared.reviewRequestRef.pending;
+            prepared.reviewRequestRef.pending = undefined;
+            const honorable = prepared.suspendForReview !== undefined &&
+                !prepared.abortController.signal.aborted &&
+                prepared.pausedRef.current === undefined;
+            if (honorable && prepared.suspendForReview) {
+                await prepared.suspendForReview(reason);
+                return undefined;
+            }
+            emitTrace(rs.telemetry.tracer, () => ({ kind: "review.dropped", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
+        }
+        if (prepared.lspDiagnostics &&
+            !prepared.lspDiagnostics.registry.isEmpty() &&
+            !prepared.abortController.signal.aborted &&
+            prepared.batchHaltRef.current === undefined) {
+            const files = prepared.lspDiagnostics.registry.drain(prepared.lspDiagnostics.runIdent);
+            if (files.length > 0) {
+                queue.push({ type: "diagnostics", files, isNew: true, ...ident() });
+                const block = mintSystemReminder(formatDiagnosticsBlock(files), prepared.reminderMark);
+                void prepared.harness.steer(block, { provenance: "engine-note" }).catch(() => undefined);
+                boundarySteered = true;
+            }
+        }
+        let boundaryAttachmentBytes = 0;
+        let attachmentsPayload;
+        if ((rs.attach.dateState !== undefined ||
+            rs.attach.instrState !== undefined ||
+            rs.attach.sizeGuidelineState !== undefined ||
+            rs.attach.attachState !== undefined) &&
+            !boundarySteered &&
+            prepared.batchHaltRef.current === undefined &&
+            !noNextRequest() &&
+            rs.counters.finalVerifyInjections === 0 &&
+            !prepared.abortController.signal.aborted) {
+            const due = [];
+            if (rs.attach.attachState !== undefined) {
+                const changedFilesOn = Boolean(rs.attach.attachmentsCfg?.changedFiles);
+                let changed;
+                if (changedFilesOn && prepared.detectExternalChanges !== undefined) {
+                    const maxFiles = typeof rs.attach.attachmentsCfg?.changedFiles === "object"
+                        ? (rs.attach.attachmentsCfg.changedFiles.maxFiles ?? CHANGED_FILES_MAX)
+                        : CHANGED_FILES_MAX;
+                    const SCAN_CEILING_MS = 2_000;
+                    const scan = await Promise.race([
+                        prepared.detectExternalChanges(maxFiles),
+                        new Promise((resolve) => {
+                            setTimeout(() => resolve({ changed: [], evicted: [] }), SCAN_CEILING_MS);
+                        }),
+                    ]);
+                    for (const p of scan.evicted)
+                        rs.attach.attachState.surfacedMtime.delete(p);
+                    changed = scan.changed;
+                }
+                const backgroundTasksOn = (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true;
+                const bgTasks = backgroundTasksOn && rs.attach.attachState.postCompactPending ? prepared.listBackgroundTasks() : undefined;
+                const toolsDeltaOn = rs.attach.attachmentsCfg?.toolsDelta === true;
+                let announcedOnceDirty = false;
+                const tdRef = toolsDeltaOn ? prepared.toolsDeltaRef : undefined;
+                const pendingTools = tdRef !== undefined && tdRef.pending.length > 0 ? [...tdRef.pending] : undefined;
+                const pendingRemovedTools = tdRef !== undefined && tdRef.pendingRemoved.length > 0 ? [...tdRef.pendingRemoved] : undefined;
+                const pendingReaddedTools = tdRef !== undefined && tdRef.pendingReadded.length > 0 ? [...tdRef.pendingReadded] : undefined;
+                const pendingFailedMcp = tdRef !== undefined && tdRef.pendingFailed.length > 0 ? tdRef.pendingFailed.map((f) => ({ ...f })) : undefined;
+                const mcpToolsDelta = pendingRemovedTools !== undefined || pendingReaddedTools !== undefined || pendingFailedMcp !== undefined
+                    ? {
+                        ...(pendingRemovedTools !== undefined ? { removed: pendingRemovedTools } : {}),
+                        ...(pendingReaddedTools !== undefined ? { readded: pendingReaddedTools } : {}),
+                        ...(pendingFailedMcp !== undefined ? { failedServers: pendingFailedMcp } : {}),
+                    }
+                    : undefined;
+                const mcpInstructionsOn = rs.attach.attachmentsCfg?.mcpInstructions === true;
+                const mcpDelta = prepared.mcp.instructionsDelta;
+                const mcpAdds = mcpInstructionsOn && mcpDelta.pendingAdds.length > 0 ? [...mcpDelta.pendingAdds] : undefined;
+                const mcpRemovals = mcpInstructionsOn && mcpDelta.pendingRemovals.length > 0 ? [...mcpDelta.pendingRemovals] : undefined;
+                const mcpDropped = mcpInstructionsOn && prepared.mcp.droppedTools.length > 0 ? selectMcpDroppedBatch(prepared.mcp.droppedTools) : undefined;
+                const budgetUsdOn = rs.attach.attachmentsCfg?.budgetUsd === true && rs.budget.maxCostMicroUsd !== undefined && rs.turn.lastTurnHadToolCalls;
+                const totalTokensDeclared = rs.attach.attachmentsCfg?.totalTokensReminder;
+                const totalTokensMode = rs.attach.attachmentsCfg?.totalTokensReminderMode ?? TOTAL_TOKENS_REMINDER_DEFAULT_MODE;
+                const totalTokensArmedByDefault = totalTokensDeclared === undefined &&
+                    eventDefaultOn("total_tokens_reminder") &&
+                    totalTokensMode !== "fixed" &&
+                    totalTokensMode !== "infinite";
+                const totalTokensOn = (totalTokensDeclared === true || totalTokensArmedByDefault) && rs.turn.lastTurnHadToolCalls;
+                const toolSearchReminderOn = rs.attach.attachmentsCfg?.toolSearchReminder === true && prepared.deferredToolNames !== undefined;
+                const undiscoveredTools = toolSearchReminderOn
+                    ? [...prepared.deferredToolNames].filter((n) => !prepared.activeTools.has(n)).sort()
+                    : undefined;
+                due.push(...collectDueAttachments(rs.attach.attachState, {
+                    turn: stats.turns,
+                    cadenceTurn: rs.counters.cadenceTurns,
+                    todoMounted: todoToolMounted,
+                    taskListMounted: taskToolsMounted,
+                    planActive: prepared.planModeRef.active,
+                    config: {
+                        todoReminder: rs.attach.attachmentsCfg?.todoReminder === true,
+                        ...(rs.attach.attachmentsCfg?.todoReminderMode !== undefined ? { todoReminderMode: rs.attach.attachmentsCfg.todoReminderMode } : {}),
+                        toolSearchReminder: toolSearchReminderOn,
+                        changedFiles: changedFilesOn,
+                        planModeReminder: rs.attach.attachmentsCfg?.planModeReminder === true,
+                        budgetUsd: budgetUsdOn,
+                        totalTokensReminder: totalTokensOn,
+                        ...(rs.attach.attachmentsCfg?.totalTokensReminderMode !== undefined
+                            ? { totalTokensReminderMode: rs.attach.attachmentsCfg.totalTokensReminderMode }
+                            : {}),
+                        backgroundTasks: backgroundTasksOn,
+                        toolsDelta: toolsDeltaOn,
+                        agentListing: rs.attach.agentListingOn,
+                        skillsListing: rs.attach.skillsListingOn,
+                        mcpInstructions: mcpInstructionsOn,
+                    },
+                    ...(undiscoveredTools !== undefined && undiscoveredTools.length > 0
+                        ? { undiscoveredTools, deferDirectCall: prepared.deferDirectCall }
+                        : {}),
+                    ...(changed !== undefined ? { changedFiles: changed } : {}),
+                    ...(budgetUsdOn && rs.budget.maxCostMicroUsd !== undefined
+                        ? { budgetUsd: { used: stats.costMicroUsd / 1e6, total: rs.budget.maxCostMicroUsd / 1e6 } }
+                        : {}),
+                    ...(totalTokensOn && rs.budget.maxTokensWindow !== undefined
+                        ? { totalTokens: { used: stats.tokens, total: rs.budget.maxTokensWindow } }
+                        : {}),
+                    ...(bgTasks !== undefined ? { backgroundTasks: bgTasks } : {}),
+                    ...(pendingTools !== undefined ? { newTools: pendingTools } : {}),
+                    ...(prepared.toolMaterializeStatic ? { newToolsStaticFace: true } : {}),
+                    ...(prepared.toolMaterializeStatic && pendingTools !== undefined
+                        ? { newToolsSwappedUnderStatic: pendingTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
+                        : {}),
+                    ...(prepared.toolMaterializeStatic && pendingReaddedTools !== undefined
+                        ? { readdedToolsSwappedUnderStatic: pendingReaddedTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
+                        : {}),
+                    ...(mcpToolsDelta !== undefined ? { mcpToolsDelta } : {}),
+                    ...(rs.attach.agentListingOn && prepared.agentListing !== undefined
+                        ? {
+                            agentListing: prepared.agentListing.entries,
+                            agentToolName: prepared.agentListing.toolName,
+                            ...(prepared.agentListing.models !== undefined ? { agentModels: prepared.agentListing.models } : {}),
+                        }
+                        : {}),
+                    ...(rs.attach.skillsListingOn && prepared.skillsListing !== undefined ? { skillsListing: prepared.skillsListing.entries } : {}),
+                    ...(mcpAdds !== undefined || mcpRemovals !== undefined
+                        ? { mcpInstructions: { added: mcpAdds ?? [], removed: mcpRemovals ?? [] } }
+                        : {}),
+                    ...(mcpDropped !== undefined ? { mcpDroppedTools: mcpDropped } : {}),
+                }));
+                if (pendingTools !== undefined || mcpToolsDelta !== undefined) {
+                    const exact = renderToolsDelta({
+                        ...(pendingTools !== undefined ? { added: pendingTools } : {}),
+                        ...(prepared.toolMaterializeStatic ? { staticFace: true } : {}),
+                        ...(prepared.toolMaterializeStatic && pendingTools !== undefined
+                            ? { swappedUnderStatic: pendingTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
+                            : {}),
+                        ...(prepared.toolMaterializeStatic && pendingReaddedTools !== undefined
+                            ? { readdedSwappedUnderStatic: pendingReaddedTools.filter((n) => prepared.staticFaceFor?.(n) !== true) }
+                            : {}),
+                        ...(mcpToolsDelta ?? {}),
+                    });
+                    if (exact !== undefined && due.some((a) => a.source === "tools_delta" && a.body === exact)) {
+                        const ref = prepared.toolsDeltaRef;
+                        if (pendingTools !== undefined)
+                            ref.pending.splice(0, pendingTools.length);
+                        if (pendingRemovedTools !== undefined)
+                            ref.pendingRemoved.splice(0, pendingRemovedTools.length);
+                        if (pendingReaddedTools !== undefined)
+                            ref.pendingReadded.splice(0, pendingReaddedTools.length);
+                        if (pendingFailedMcp !== undefined) {
+                            ref.pendingFailed.splice(0, pendingFailedMcp.length);
+                            if (!noNextRequest()) {
+                                prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...pendingFailedMcp];
+                                announcedOnceDirty = true;
+                            }
+                        }
+                    }
+                }
+                if ((mcpAdds !== undefined || mcpRemovals !== undefined) &&
+                    due.some((a) => a.source === "mcp_instructions" && a.body === renderMcpInstructionsDelta(mcpAdds ?? [], mcpRemovals ?? []))) {
+                    if (mcpAdds !== undefined)
+                        mcpDelta.pendingAdds.splice(0, mcpAdds.length);
+                    if (mcpRemovals !== undefined)
+                        mcpDelta.pendingRemovals.splice(0, mcpRemovals.length);
+                }
+                if (mcpDropped !== undefined &&
+                    due.some((a) => a.source === "mcp_dropped_tools" && a.body === renderMcpDroppedTools(mcpDropped))) {
+                    prepared.mcp.droppedTools.splice(0, mcpDropped.length);
+                    if (!noNextRequest()) {
+                        prepared.announcedListingsRef.advisories = withAnnounceDigests(prepared.announcedListingsRef.advisories, mcpDropped.map(droppedToolDigest));
+                        announcedOnceDirty = true;
+                    }
+                }
+                if (rs.attach.agentListingOn && prepared.agentListing !== undefined && due.some((a) => a.source === "agent_listing")) {
+                    const listing = prepared.agentListing;
+                    const intactBody = renderAgentListingDelta(rs.attach.attachState, listing.entries, listing.toolName, listing.models);
+                    if (intactBody !== undefined && due.some((a) => a.source === "agent_listing" && a.body === intactBody)) {
+                        commitAgentListing(rs.attach.attachState, listing.entries, listing.models);
+                        prepared.announcedListingsRef.agents = listing.entries.map((e) => e.name);
+                        if (listing.models !== undefined)
+                            prepared.announcedListingsRef.models = [...listing.models];
+                        if (prepared.announcedSnapshotRecovered)
+                            await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                    }
+                }
+                if (rs.attach.skillsListingOn && prepared.skillsListing !== undefined && due.some((a) => a.source === "skills_listing")) {
+                    const listing = prepared.skillsListing;
+                    const intactBody = renderSkillsListingDelta(rs.attach.attachState, listing.entries);
+                    if (intactBody !== undefined && due.some((a) => a.source === "skills_listing" && a.body === intactBody)) {
+                        commitSkillsListing(rs.attach.attachState, listing.entries);
+                        prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
+                        if (prepared.announcedSnapshotRecovered)
+                            await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                    }
+                }
+                if (announcedOnceDirty && prepared.announcedSnapshotRecovered)
+                    await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+            }
+            if (rs.attach.dateState !== undefined && rs.turn.lastTurnHadToolCalls) {
+                const today = prepared.dateChange.today();
+                const cand = collectDateChange(rs.attach.dateState, today);
+                if (cand !== undefined) {
+                    due.unshift(cand);
+                    rs.attach.dateState.announcedDate = today;
+                }
+            }
+            if (rs.attach.sizeGuidelineState !== undefined && rs.turn.lastTurnHadToolCalls) {
+                const guideline = rs.attach.sizeGuidelineState.current();
+                if (guideline !== rs.attach.sizeGuidelineState.announcedGuideline) {
+                    due.splice(due.length > 0 && due[0].source === "date_change" ? 1 : 0, 0, {
+                        source: "workflow_size_guideline_change",
+                        body: workflowSizeGuidelineChangeNotice(guideline),
+                    });
+                    rs.attach.sizeGuidelineState.announcedGuideline = guideline;
+                }
+            }
+            if (rs.attach.instrState !== undefined && rs.attach.instrProbe !== undefined && rs.turn.lastTurnHadToolCalls) {
+                let probed = null;
+                try {
+                    const PROBE_CEILING_MS = 2_000;
+                    probed = await Promise.race([
+                        rs.attach.instrProbe(prepared.instructionSources),
+                        new Promise((resolve) => {
+                            setTimeout(() => resolve(null), PROBE_CEILING_MS);
+                        }),
+                    ]);
+                }
+                catch {
+                    probed = null;
+                }
+                const cand = collectInstructionsChange(rs.attach.instrState, probed);
+                if (cand !== undefined) {
+                    due.splice(due.length > 0 && due[0].source === "date_change" ? 1 : 0, 0, cand.attachment);
+                    commitInstructionsChange(rs.attach.instrState, cand.announced);
+                }
+            }
+            if (due.length > 0) {
+                attachmentsPayload = due.map((a) => mintSystemReminder(sanitizeUntrustedText(a.body, attachmentEnvelopeTags(a.source)), prepared.reminderMark)).join("\n");
+                for (const a of due)
+                    boundaryAttachmentBytes += Buffer.byteLength(a.body, "utf8");
+                rs.attach.attachmentsInjected += due.length;
+                for (const a of due) {
+                    queue.push({ type: "steering_injected", source: a.source, preview: redactThenCut(a.body, 220), ...ident() });
+                }
+            }
+        }
+        let batchContextBlock;
+        const finalVerifyInjectedThisTurn = rs.counters.finalVerifyInjections !== finalVerifySeenAtLastBoundary;
+        finalVerifySeenAtLastBoundary = rs.counters.finalVerifyInjections;
+        if (postToolBatchHook !== undefined && rs.turn.toolBatch.length > 0) {
+            const batch = rs.turn.toolBatch;
+            rs.turn.toolBatch = [];
+            batchArgs?.clear();
+            const injectedThisTurn = finalVerifyInjectedThisTurn ? "final_verification" : undefined;
+            if (!boundarySteered && !prepared.abortController.signal.aborted) {
+                try {
+                    const batchSeat = await runHookSeat("postToolBatch", { timeoutMs: prepared.hookTimeoutMs, signal: prepared.abortController.signal }, (sig) => postToolBatchHook(batch, injectedThisTurn !== undefined ? { injectedThisTurn } : undefined, { identity: prepared.hookIdentity, signal: sig }));
+                    if (batchSeat.expired) {
+                        runnerHooks.onError?.(hookSeatExpiredError("postToolBatch", prepared.hookTimeoutMs, batchSeat.cause, "the boundary observation was abandoned and its additionalContext dropped; the turn boundary itself is unchanged"), { phase: "hook", sessionId: prepared.sessionId });
+                    }
+                    const r = batchSeat.expired ? undefined : batchSeat.value;
+                    if (r?.additionalContext && injectedThisTurn === undefined) {
+                        const body = sanitizeUntrustedText(r.additionalContext, SHELLED_BODY_ENVELOPE_TAGS);
+                        const budget = ATTACHMENT_BYTE_CAP - boundaryAttachmentBytes;
+                        if (budget >= BATCH_CONTEXT_MIN_KEEP_BYTES) {
+                            const clipped = clipToBytes(body, budget) === body
+                                ? body
+                                : `${clipToBytes(body, budget - Buffer.byteLength(BATCH_TRUNCATION_MARKER, "utf8"))}${BATCH_TRUNCATION_MARKER}`;
+                            batchContextBlock = mintSystemReminder(clipped, prepared.reminderMark);
+                        }
+                    }
+                }
+                catch (err) {
+                    try {
+                        runnerHooks.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        if ((attachmentsPayload !== undefined || batchContextBlock !== undefined) && prepared.batchHaltRef.current === undefined) {
+            const payload = attachmentsPayload !== undefined && batchContextBlock !== undefined ? `${attachmentsPayload}\n${batchContextBlock}` : (attachmentsPayload ?? batchContextBlock);
+            void prepared.harness.steer(payload, { engineMinted: true }).catch(() => { });
+        }
+        const forceManual = manualCompactRef.requested;
+        if ((!withinTaskCompaction && !forceManual) ||
+            prepared.abortController.signal.aborted ||
+            prepared.pausedRef.current !== undefined) {
+            if (forceManual) {
+                emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "task_ending", ts: Date.now() }));
+                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "task_ending", ...ident() });
+                drainManualCompact("mooted");
+            }
+            return undefined;
+        }
+        if (compactionBreaker.failures >= MAX_CONSECUTIVE_COMPACTION_FAILURES) {
+            if (forceManual) {
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.failed",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    trigger: "manual",
+                    reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt",
+                    ts: Date.now(),
+                }));
+                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "manual", reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt", ...ident() });
+                drainManualCompact("failed");
+            }
+            return undefined;
+        }
+        const claimedManual = forceManual
+            ? (() => {
+                const waiters = manualCompactRef.waiters.splice(0);
+                let instructions;
+                for (let i = waiters.length - 1; i >= 0; i--) {
+                    if (waiters[i].instructions !== undefined) {
+                        instructions = waiters[i].instructions;
+                        break;
+                    }
+                }
+                return { instructions, waiters };
+            })()
+            : undefined;
+        if (forceManual) {
+            manualCompactRef.requested = false;
+        }
+        const resolveClaimedWaiters = (outcome) => {
+            if (claimedManual !== undefined)
+                for (const w of claimedManual.waiters.splice(0))
+                    w.resolve(outcome);
+        };
+        const claimedCancelSignals = claimedManual?.waiters.flatMap((w) => (w.signal !== undefined ? [w.signal] : [])) ?? [];
+        const manualCancelSignal = claimedCancelSignals.length === 0
+            ? undefined
+            : claimedCancelSignals.length === 1
+                ? claimedCancelSignals[0]
+                : AbortSignal.any(claimedCancelSignals);
+        const compactionPassSignal = claimedCancelSignals.length > 0
+            ? AbortSignal.any([prepared.abortController.signal, ...claimedCancelSignals])
+            : prepared.abortController.signal;
+        const trimPressureArmed = prepared.trimPressureRef.droppedMessages;
+        if (trimPressureArmed)
+            prepared.trimPressureRef.droppedMessages = false;
+        const trimPressure = trimPressureArmed && !rs.counters.trimForceBackoff;
+        const passTrigger = trimPressure ? "forced" : forceManual ? "manual" : "auto";
+        let manualOutcome = "failed";
+        const manualInstructions = claimedManual?.instructions;
+        try {
+            const comp = await maybeCompact({
+                session: prepared.session,
+                epochDeclaredSections: prepared.epochDeclaredSections,
+                ...centerAdoptionOption(prepared),
+                model: event.model,
+                compactionModel: prepared.compModel,
+                ...forkContextOption(prepared, false),
+                brain: compactionBrain,
+                getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
+                thinking: prepared.thinking,
+                settings: { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction },
+                customInstructions: manualInstructions ?? spec.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
+                signal: compactionPassSignal,
+                ...(manualCancelSignal !== undefined ? { manualCancelSignal } : {}),
+                minTokens: forceManual ? 0 : rs.counters.compactionFloor,
+                force: forceManual,
+                onInputTruncated: emitInputTruncated(rs.telemetry.tracer, rs.telemetry.taskId),
+                forceUnderThreshold: trimPressure,
+                overheadTokens: prepared.promptOverheadTokens,
+                ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
+                workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
+                ...contextInstructionFilesOption(prepared),
+                ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
+                ...runnerHooks.seamCCompactionOptions(prepared),
+                ...gitRestateOption(prepared),
+                ...windowSafetyOptions(event.model),
+                ...runnerHooks.compactionHookOptions(spec, prepared.sessionId, passTrigger),
+            });
+            if (comp.blocked) {
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.blocked",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    trigger: forceManual ? "manual" : "auto",
+                    ts: Date.now(),
+                }));
+            }
+            else {
+                compactionBreaker.failures = 0;
+            }
+            rs.counters.trimForceBackoff = nextTrimForceBackoff(rs.counters.trimForceBackoff, comp, trimPressure);
+            if (comp.contextUsage) {
+                queue.push({ type: "context_usage", ...comp.contextUsage, ...ident() });
+            }
+            if (comp.unevaluableWindow) {
+                discloseUnevaluableWindow(comp.unevaluableWindow, prepared, rs.telemetry.tracer, rs.telemetry.taskId, runnerHooks.onError);
+            }
+            if (comp.suppressedByFloor) {
+                const s = comp.suppressedByFloor;
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.suppressed",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    estTokens: s.estTokens,
+                    floor: s.floor,
+                    ts: Date.now(),
+                }));
+            }
+            manualOutcome = comp.compacted ? "compacted" : comp.blocked ? "blocked" : comp.disabled ? "disabled" : "noop";
+            if (forceManual && !comp.compacted && !comp.blocked) {
+                if (comp.disabled) {
+                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.disabled", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
+                }
+                else {
+                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.noop", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
+                }
+            }
+            if (!comp.compacted) {
+                const outcome = comp.blocked
+                    ? "blocked"
+                    : comp.disabled
+                        ? (forceManual || trimPressure ? "disabled" : undefined)
+                        : comp.suppressedByFloor
+                            ? "suppressed"
+                            : comp.noop || forceManual
+                                ? "noop"
+                                : undefined;
+                if (outcome !== undefined) {
+                    queue.push({ type: "compaction_outcome", outcome, trigger: passTrigger, ...ident() });
+                }
+            }
+            runnerHooks.recordCompactionReuse(prepared, comp);
+            if (comp.compacted) {
+                queue.push({
+                    type: "compacted",
+                    trigger: passTrigger,
+                    tokensBefore: comp.tokensBefore ?? 0,
+                    ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
+                    ...(comp.triggerTokens !== undefined ? { triggerTokensBefore: comp.triggerTokens } : {}),
+                    ...(comp.durationMs !== undefined ? { durationMs: comp.durationMs } : {}),
+                    ...(comp.phaseDurations !== undefined ? { phaseDurations: comp.phaseDurations } : {}),
+                    ...(comp.firstKeptEntryId !== undefined ? { preserved_segment: { firstKeptEntryId: comp.firstKeptEntryId } } : {}),
+                    ...(comp.attachedFiles !== undefined ? { attachedFiles: comp.attachedFiles } : {}),
+                    ...(comp.modelFallback ? { modelFallback: true } : {}),
+                    ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
+                    ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
+                    ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+                    ...ident(),
+                });
+                if (!forceManual && recordCompactionAndCheckRapidRefill(rapidRefill, stats.turns)) {
+                    compactionBreaker.failures = MAX_CONSECUTIVE_COMPACTION_FAILURES;
+                    queue.push({ type: "compaction_outcome", outcome: "disabled", trigger: passTrigger, reason: "rapid_refill: compaction disabled for the rest of this task", ...ident() });
+                    runnerHooks.onError?.(new Error("compaction.rapid_refill: the context refilled within <3 turns of compaction 3 times in a row — compaction disabled for the rest of this task (thrash spiral; the transcript is dominated by incompressible content)"), { phase: "compaction", sessionId: prepared.sessionId });
+                }
+                if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
+                    const pd = comp.phaseDurations;
+                    const pdDur = comp.durationMs;
+                    emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.phase_timings", version: 1, taskId: rs.telemetry.taskId, ...pd, durationMs: pdDur, ts: Date.now() }));
+                }
+                prepared.cacheBreakDetector?.notifyCompaction();
+                if (rs.attach.attachState !== undefined) {
+                    rs.attach.attachState.postCompactPending = true;
+                    rebaseCadenceWindows(rs.attach.attachState, rs.counters.cadenceTurns);
+                }
+                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);
+                }
+            }
+        }
+        catch (err) {
+            const manualCancelAbort = !prepared.abortController.signal.aborted && isCompactionManualCancel(err);
+            if (manualCancelAbort) {
+                emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "cancelled", ts: Date.now() }));
+                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: passTrigger, reason: "cancelled", ...ident() });
+                manualOutcome = "mooted";
+            }
+            else if (!prepared.abortController.signal.aborted) {
+                compactionBreaker.failures += 1;
+                runnerHooks.onError?.(err, { phase: "compaction", sessionId: prepared.sessionId });
+                const msg = String(err instanceof Error ? err.message : err);
+                const failReason = msg.length > 512 ? `${msg.slice(0, 512)}…` : msg;
+                emitTrace(rs.telemetry.tracer, () => ({
+                    kind: "compaction.failed",
+                    version: 1,
+                    taskId: rs.telemetry.taskId,
+                    trigger: passTrigger,
+                    reason: failReason,
+                    ts: Date.now(),
+                }));
+                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: passTrigger, reason: failReason, ...ident() });
+                manualOutcome = "failed";
+            }
+            else {
+                manualOutcome = "mooted";
+            }
+        }
+        if (forceManual)
+            resolveClaimedWaiters(manualOutcome);
+        return undefined;
+    };
+    return onTurnBoundary;
+}