@sema-agent/core 5.65.0 → 6.0.0

package/dist/core/runner/runtask.d.ts

@@ -152,16 +152,11 @@ export declare class Runner {
     readonly sessions: SessionStore;
     /** Per-sessionId serialization so two tasks never mutate one session concurrently. */
     private sessionLocks;
-    /** (a) — roots whose rewind-files snapshot hit `too_large`, with the refusal time.
-     *  A 20G workspace otherwise pays a full bounded tree-walk (stat tens of thousands of files) EVERY
-     *  task just to re-discover the same refusal; once too_large, skip further snapshots for that root
-     *  (announced once via onError). E19 semantics unchanged — rewind for that root was already
-     *  impossible. TTL'd (30min), not permanent — a long-lived Runner over a tree the
-     *  user later SHRINKS re-probes instead of being locked out until restart.
-     *  RB-430-b: `skipAnnounced` makes the SKIP itself observable — one announcement per cooldown window,
-     *  so an operator can tell "this turn produced no snapshot" from "snapshots are working", without the
-     *  per-turn log spam the latch exists to prevent. Cleared with the entry when the window elapses. */
-    private snapshotTooLargeRoots;
+    /** #483 rung-1 — per-session read-file-state seats (CC parity: readFileState is session-scoped;
+     *  sema's map stays per-task, so the session scope lives here). A bounded CACHE, never an
+     *  authority: a durable resume's checkpoint seed wins on its leg, and a miss (cross-process,
+     *  evicted) falls back to the transcript-replay rung. See {@link SessionReadFileStates}. */
+    private readonly sessionReadStates;
     /** task notifications born BETWEEN turns (run torn down / harness already idle), parked
      *  per session and drained into the session's next run at its first boundary. Runner-lived (outlives any
      *  single run, like the registry handles that produce into it); bounded + drop-disclosing, see
@@ -274,13 +269,6 @@ export declare class Runner {
      * never rejects. Also fills the budget-excluded `stats.suggestions` line.
      */
     private suggestNextPrompts;
-    /**
-     * design/101 §E19 — capture a working-tree snapshot of the just-finished turn, keyed by the leaf
-     * `SessionTreeEntry.id`. Best-effort + never throws (errors route to `onError(phase:"rewind")`). Runs against
-     * ANY ExecutionEnv (local or remote) when a `fileSnapshotStore` is wired (GATE-SPLIT) — the
-     * snapshot is portable (env FileSystem ops). A deployment wanting VM-snapshot instead wires a VM-backed store.
-     */
-    private snapshotTurn;
     /** Run a task to completion and return a machine-readable result. */
     runTask(spec: TaskSpec, internals?: RunInternals): Promise<TaskResult>;
     /**
@@ -429,9 +417,10 @@ export declare class Runner {
      * reaper is the backstop for an env orphaned by a rare pre-teardown throw (same posture as `mcp`).
      *
      * Runs from the run-loop tail AFTER every env-reader (finish()'s compaction `attachWorkingFiles` +
-     * `snapshotTurn`'s rewind-files capture), so the working tree is still readable when they run. This ORDER is the
-     * fix for a teardown-order defect: the old in-`finish` destroy ran BEFORE `snapshotTurn`, so a factory-minted
-     * remote/worktree lane snapshotted an already-destroyed env (plain host/static lanes were false-green).
+     * the file-history boundary settle), so the working tree is still readable when they run. This ORDER is
+     * the fix for a teardown-order defect: the old in-`finish` destroy ran BEFORE the capture seat, so a
+     * factory-minted remote/worktree lane captured an already-destroyed env (plain host/static lanes were
+     * false-green).
      *
      * design/49 v1.5 / design/76 §2.5: a SUSPENDED (`suspendRef.token`) or `needs_review` (`reviewRef.token`) pause
      * `suspendVM`-paused the env and persisted its `workspaceHandle` into the checkpoint — destroying it would

package/dist/core/runner/runtask.js

@@ -34,9 +34,10 @@ import { toImageContent } from "./image.js";
 import { OUTPUT_TOOL_NAME, SKILLS_LISTING_PROBE_HEADER, resolveOutputRetries } from "./synthetic-tools.js";
 import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
 import { assembleResult, errorCodeOf } from "./assemble-result.js";
-import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, attachmentEnvelopeTags, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
-import { buildWorkingFileAttachments, centerAdoptionOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
+import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, TOTAL_TOKENS_REMINDER_DEFAULT_MODE, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, attachmentEnvelopeTags, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
+import { buildWorkingFileAttachments, centerAdoptionOption, contextInstructionFilesOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
 import { effectiveDelegationFacts, gatedCallIdOf, placementValueOrAbsent, prepareTask, resolveCheckpointStore } from "./prepare-task.js";
+import { SessionReadFileStates } from "./prepare-hands-readface.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
@@ -48,7 +49,7 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, sanitizeUntr
 import { appendInterruptionMarker, reconcileInterruptedSession } from "../session-reconcile.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
-import { checkToolPolicyProjection, constraintChainDigest, constraintChainEntryOf, isApprovalSettledBy, refuseOutOfContractDecision, screenApproverAttribution, toolPolicyNameSets } from "../tool-policy.js";
+import { checkToolPolicyProjection, constraintChainDigest, constraintChainEntryOfSuppliedLayer, isApprovalSettledBy, refuseOutOfContractDecision, screenApproverAttribution, toolPolicyNameSets } from "../tool-policy.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, isDelegatedAgentTerminal, isSystemInjectionPriority, isTerminalTaskNotification, PendingSessionNotifications, renderTaskNotificationXml, SYSTEM_INJECTION_PRIORITIES, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
@@ -57,7 +58,7 @@ import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-
 import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
 function createRunState() {
     return {
-        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, pricingConfigured: true, unpricedSpend: false, tracer: undefined, taskId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
+        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, pricingConfigured: true, unpricedSpend: false, tracer: undefined, taskId: "", runId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
         degrade: { degradeToModel: undefined, degraded: undefined, outputErrorStreak: 0, outputInvalid: false, recordDegraded: () => { } },
         limits: { turnsExceeded: false, budgetHit: undefined, budgetAxis: undefined, platformTerminal: undefined, outputRetryCap: 0, effectiveMaxTurns: undefined },
         budget: { remainingMicroUsd: undefined, maxCostMicroUsd: undefined, remainingTokens: undefined, maxTokensWindow: undefined, overBudget: () => undefined, streamCancel: false, callOutputChars: 0, lastStreamBudgetCheck: 0, projectedOverBudget: () => undefined },
@@ -124,8 +125,6 @@ const SUGGESTIONS_DEFAULT_COUNT = 3;
 const SUGGESTIONS_MAX_COUNT = 8;
 const SUGGESTIONS_TIMEOUT_MS = 30_000;
 const SUGGESTIONS_TRANSCRIPT_MESSAGES = 12;
-const SNAPSHOT_TIMEOUT_MS = 30_000;
-const SNAPSHOT_TOO_LARGE_TTL_MS = 30 * 60_000;
 const LIMIT_APPROACH_DEFAULT_THRESHOLDS = [0.8, 0.95];
 const DEFAULT_PRECALL_OUTPUT_TOKENS = 4096;
 function limitApproachFrames(index, axis, percent, mark) {
@@ -607,7 +606,13 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 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 totalTokensOn = rs.attach.attachmentsCfg?.totalTokensReminder === true && 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()
@@ -897,6 +902,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 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),
@@ -1165,6 +1171,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
         if (event.entryId !== undefined && (m.role === "user" || m.role === "assistant" || m.role === "toolResult")) {
             emitCommitted(event.entryId, m.role, m.role === "toolResult" ? m.toolCallId : undefined);
         }
+        if (event.entryId !== undefined && m.role === "user")
+            prepared.fileHistoryBoundary?.begin(event.entryId);
         if (event.entryId !== undefined && m.role === "user" && prepared.gitStatusRef.pendingReceipt !== undefined) {
             const pr = prepared.gitStatusRef.pendingReceipt;
             const c = m.content;
@@ -1453,7 +1461,7 @@ export class Runner {
     deps;
     sessions;
     sessionLocks = new Map();
-    snapshotTooLargeRoots = new Map();
+    sessionReadStates = new SessionReadFileStates();
     pendingSessionNotifications = new PendingSessionNotifications();
     parentConstraintRegistry = new Map();
     suspendedEnvReaps = new Map();
@@ -1605,7 +1613,7 @@ export class Runner {
         deliverEngineNotice(this.deps.onNotice, {
             code: "config.models_swapped",
             message: `model catalog swapped: ${Object.keys(next.models).length} model(s), ${tiers ? Object.keys(tiers).length : 0} tier binding(s); in-flight tasks finish on their resolved models, new tasks resolve against the new catalog`,
-            detail: { models: Object.keys(next.models).length, tiers: tiers ? Object.keys(tiers).length : 0 },
+            detail: { models: Object.keys(next.models).length, tiers: tiers ? Object.keys(tiers).length : 0, occurrenceId: uuidv7() },
         });
         if (movedEntries.length > 0) {
             const RENDER_CAP = 8;
@@ -1616,7 +1624,7 @@ export class Runner {
                     rendered.map((e) => `"${e.modelId}" ${e.from || "(config root)"} → ${e.to || "(config root)"}`).join("; ") +
                     (movedEntries.length > rendered.length ? `; +${movedEntries.length - rendered.length} more` : "") +
                     " — if the provider changed (not just its domain), update the credential reference in the same step",
-                detail: { entries: rendered, total: movedEntries.length },
+                detail: { entries: rendered, total: movedEntries.length, occurrenceId: uuidv7() },
             });
         }
     }
@@ -1629,6 +1637,7 @@ export class Runner {
                 "(Note the parameter order: runTaskStream(spec, resume?, internals?) — internals is the THIRD parameter.)");
         }
         const entryActor = spec.actor === undefined ? undefined : snapshotActorAssertion(spec.actor);
+        const entryTracer = { tracer: spec.tracer ?? this.deps.tracer };
         const queue = new PushQueue();
         const detachHub = new ToolDetachHub();
         let resultValue;
@@ -1650,6 +1659,7 @@ export class Runner {
         let steerChain = Promise.resolve();
         const acceptedSteerInputs = new Map();
         const notifyRef = {};
+        const captureOptOutRef = {};
         const manualCompactRef = { requested: false, waiters: [] };
         const drainManualCompactWaiters = (outcome) => {
             manualCompactRef.requested = false;
@@ -1688,7 +1698,7 @@ export class Runner {
                 }, (s) => {
                     reapHandle = s;
                     this.suspendedEnvReaps.set(s.token, s);
-                }, manualCompactRef, taskIdRef, resume, { ...(internals ?? {}), detachHub }, notifyRef, entryActor);
+                }, manualCompactRef, taskIdRef, resume, { ...(internals ?? {}), detachHub }, notifyRef, captureOptOutRef, entryActor, entryTracer);
             }
             finally {
                 releaseLock?.();
@@ -1759,6 +1769,7 @@ export class Runner {
             resultValue = {
                 taskId: taskIdRef.current ?? "unknown",
                 sessionId: taskIdRef.sessionId ?? "unknown",
+                ...(taskIdRef.runId !== undefined ? { runId: taskIdRef.runId } : {}),
                 status: "failed",
                 result: "",
                 errorMessage: err instanceof Error ? err.message : String(err),
@@ -1774,10 +1785,11 @@ export class Runner {
                 })(),
                 stats: { turns: 0, tokens: 0, toolCalls: 0, cachedTokens: 0, costMicroUsd: 0 },
             };
-            emitTrace(spec.tracer ?? this.deps.tracer, () => ({
+            emitTrace(entryTracer.tracer, () => ({
                 kind: "task.end",
                 version: 1,
                 taskId: taskIdRef.current ?? "unknown",
+                ...(taskIdRef.runId !== undefined ? { runId: taskIdRef.runId } : {}),
                 status: "failed",
                 errorCode: code,
                 turns: 0,
@@ -1985,6 +1997,7 @@ export class Runner {
                                 detail: {
                                     inputId: effectiveInputId,
                                     sessionId: h.sessionId,
+                                    runId: h.runId,
                                     ...(actor?.id !== undefined ? { actorId: actor.id } : {}),
                                     ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
                                 },
@@ -2065,6 +2078,26 @@ export class Runner {
                 }
                 notifyRef.inject(payload, priority !== undefined ? { priority } : undefined);
             },
+            optOutMemoryCapture: async (options) => {
+                const reasonIn = options?.reason;
+                if (reasonIn !== undefined && typeof reasonIn !== "string") {
+                    const e = new Error(`cannot opt out of memory capture: options.reason must be a string when present`);
+                    e.code = "steering.invalid_content";
+                    throw e;
+                }
+                const reason = reasonIn;
+                if (resultValue)
+                    throw steeringError("the task has already finished");
+                const h = handle ?? (await orTimeout(ready));
+                if (!h)
+                    throw steeringError("the task is not running");
+                if (captureOptOutRef.flip === undefined) {
+                    const e = new Error(`cannot opt out of memory capture: this run mounted no memory session (no memory spec / no backend / prepare degraded memory-less) — there is nothing to opt out of`);
+                    e.code = "memory.capture_optout_unavailable";
+                    throw e;
+                }
+                return captureOptOutRef.flip(reason);
+            },
             compact: async (opts) => {
                 if (resultValue)
                     throw steeringError("the task has already finished");
@@ -2118,6 +2151,60 @@ export class Runner {
                 h.abortController.abort();
                 void h.harness.abort();
             },
+            halt: async () => {
+                const haltRefused = (msg) => {
+                    const e = new Error(`cannot halt: ${msg}`);
+                    e.code = "steering.not_running";
+                    return e;
+                };
+                if (resultValue)
+                    throw haltRefused("the task has already finished");
+                const h = handle ?? (await orTimeout(ready));
+                if (!h)
+                    throw haltRefused("the task is not running");
+                const apply = () => {
+                    const abortOwnedBeforeHalt = h.abortController.signal.aborted;
+                    const receipt = h.harness.halt();
+                    if (receipt.accepted && !abortOwnedBeforeHalt)
+                        h.loop.userHalted = true;
+                    if (receipt.turnCut) {
+                        deliverEngineNotice(this.deps.onNotice, {
+                            code: "task.turn_interrupted",
+                            message: "a bare user halt cut the running turn: in-flight work was cut at a manufactured boundary " +
+                                "(finished tool calls keep their real results; never-started ones settle as interrupted) and " +
+                                "the run is collecting to a clean, resumable stop — no further model turn will start.",
+                            detail: {
+                                cause: "user_halt",
+                                sessionId: h.sessionId,
+                                runId: h.runId,
+                                ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
+                            },
+                        });
+                    }
+                    return { turnCut: receipt.turnCut };
+                };
+                try {
+                    if (resultValue !== undefined || h.loop.ended)
+                        throw haltRefused("the task is no longer running");
+                    return apply();
+                }
+                catch (e) {
+                    if (!(e instanceof Error && e.code === "invalid_state"))
+                        throw e;
+                }
+                const birthDeadline = Date.now() + READY_TIMEOUT_MS;
+                while (resultValue === undefined && !h.loop.ended && Date.now() < birthDeadline) {
+                    try {
+                        return apply();
+                    }
+                    catch (e2) {
+                        if (!(e2 instanceof Error && e2.code === "invalid_state"))
+                            throw e2;
+                    }
+                    await new Promise((r) => setTimeout(r, 10));
+                }
+                throw haltRefused("the task is no longer running");
+            },
             destroy: () => (destroyOnce ??= (async () => {
                 const h = handle ?? (await orTimeout(ready));
                 if (h) {
@@ -2129,7 +2216,7 @@ export class Runner {
             })()),
         };
     }
-    async runLocked(spec, queue, setResult, onSuggestions, onReady, onSuspend, manualCompactRef, taskIdRef, resume, internals, notifyRef, entryActor) {
+    async runLocked(spec, queue, setResult, onSuggestions, onReady, onSuspend, manualCompactRef, taskIdRef, resume, internals, notifyRef, captureOptOutRef, entryActor, entryTracer) {
         const prepareResume = resume
             ? {
                 leafId: resume.cp.leafId,
@@ -2233,6 +2320,7 @@ export class Runner {
             peerSelfRef,
             peerInboundChainRef,
             detachHub,
+            sessionReadStates: this.sessionReadStates,
             onTaskNotification: (notification, opts) => {
                 try {
                     upstreamTaskNotification?.(notification, opts);
@@ -2241,7 +2329,7 @@ export class Runner {
                 }
                 injectTaskNotification(notification, opts);
             },
-        }, this);
+        }, this, taskIdRef);
         notificationHarness = prepared.harness;
         notificationSessionId = prepared.sessionId;
         if (taskIdRef)
@@ -2281,7 +2369,7 @@ export class Runner {
                 undrainedUserAtEnd = counts;
                 return;
             }
-            for (const notice of undrainedUserInputNotices(counts, spec.taskId, prepared.sessionId)) {
+            for (const notice of undrainedUserInputNotices(counts, spec.taskId ?? prepared.sessionId, prepared.sessionId, prepared.runId)) {
                 deliverEngineNotice(this.deps.onNotice, notice);
             }
         };
@@ -2292,6 +2380,9 @@ export class Runner {
         };
         if (notifyRef)
             notifyRef.inject = injectTaskNotification;
+        if (captureOptOutRef && prepared.memoryEngineSession?.captureOptOut !== undefined) {
+            captureOptOutRef.flip = prepared.memoryEngineSession.captureOptOut.flip;
+        }
         try {
             internals?.onNotifyInjectorReady?.(injectTaskNotification);
         }
@@ -2310,8 +2401,8 @@ export class Runner {
                 }
             }
         }
-        const loopLatch = { ended: false, userInterrupted: false };
-        onReady({ harness: prepared.harness, abortController: prepared.abortController, loop: loopLatch, reminderMark: prepared.reminderMark, sessionId: prepared.sessionId, hookTimeoutMs: prepared.hookTimeoutMs, hookIdentity: prepared.hookIdentity });
+        const loopLatch = { ended: false, userInterrupted: false, userHalted: false };
+        onReady({ harness: prepared.harness, abortController: prepared.abortController, loop: loopLatch, reminderMark: prepared.reminderMark, sessionId: prepared.sessionId, runId: prepared.runId, hookTimeoutMs: prepared.hookTimeoutMs, hookIdentity: prepared.hookIdentity });
         const stats = { turns: 0, tokens: 0, toolCalls: 0, promptTokens: 0, totalInputTokens: 0, cachedTokens: 0, cacheWriteTokens: 0, cacheWriteTokensLong: 0, outputTokens: 0, costMicroUsd: 0 };
         prepared.liveSpendRef.get = () => ({ costMicroUsd: stats.costMicroUsd, tokens: stats.tokens, turns: stats.turns, walltimeMs: Math.round(performance.now() - rs.telemetry.taskStartMonotonic) });
         if (resume &&
@@ -2352,8 +2443,9 @@ export class Runner {
         rs.telemetry.cacheBreakReported = false;
         rs.limits.outputRetryCap = resolveOutputRetries(spec.outputRetries);
         rs.limits.effectiveMaxTurns = resolveMaxTurns(spec.limits);
-        rs.telemetry.tracer = spec.tracer ?? this.deps.tracer;
+        rs.telemetry.tracer = entryTracer !== undefined ? entryTracer.tracer : (spec.tracer ?? this.deps.tracer);
         rs.telemetry.taskId = runSourceTaskId;
+        rs.telemetry.runId = prepared.runId;
         if (taskIdRef) {
             taskIdRef.current = rs.telemetry.taskId;
             taskIdRef.sessionId = prepared.sessionId;
@@ -2368,7 +2460,7 @@ export class Runner {
             }
         };
         try {
-            void Promise.resolve(this.sessions.noteTaskRun?.(prepared.sessionId, rs.telemetry.taskId)).catch(discloseNoteTaskRunFailure);
+            void Promise.resolve(this.sessions.noteTaskRun?.(prepared.sessionId, rs.telemetry.taskId, rs.telemetry.runId)).catch(discloseNoteTaskRunFailure);
         }
         catch (err) {
             discloseNoteTaskRunFailure(err);
@@ -2654,7 +2746,7 @@ export class Runner {
         const writeFamilyOf = (name) => writeFamilyByName.get(name) ?? writeFamilyOfCanonical(name);
         const toolStartAt = new Map();
         const startedToolCallIds = new Set();
-        emitTrace(rs.telemetry.tracer, () => ({ kind: "task.start", version: 1, taskId: rs.telemetry.taskId, model: prepared.model.id, engineVersion: engineVersion(), ts: rs.telemetry.taskStart }));
+        emitTrace(rs.telemetry.tracer, () => ({ kind: "task.start", version: 1, taskId: rs.telemetry.taskId, runId: rs.telemetry.runId, model: prepared.model.id, engineVersion: engineVersion(), ts: rs.telemetry.taskStart }));
         emitTrace(rs.telemetry.tracer, () => ({
             kind: "prompt.assembled",
             version: 1,
@@ -2746,7 +2838,9 @@ export class Runner {
                 }
             }
         };
+        const ownCommittedTailRef = { current: undefined };
         const emitCommitted = (entryId, role, toolCallId) => {
+            ownCommittedTailRef.current = entryId;
             if (role === "toolResult" && toolCallId !== undefined)
                 startedToolCallIds.delete(toolCallId);
             queue.push({ type: "message_committed", entryId, role, ...(toolCallId !== undefined ? { toolCallId } : {}), ...ident() });
@@ -2762,6 +2856,7 @@ export class Runner {
                 ...(s.detail !== undefined ? { detail: s.detail } : {}),
                 ...(s.retryInSec !== undefined ? { retryInSec: s.retryInSec } : {}),
                 ...(s.retryInMs !== undefined ? { retryInMs: s.retryInMs } : {}),
+                ...(s.retryAtMs !== undefined ? { retryAtMs: s.retryAtMs } : {}),
                 ...(s.attempt !== undefined ? { attempt: s.attempt } : {}),
                 ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
                 ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),
@@ -3079,6 +3174,7 @@ export class Runner {
                     ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
                     onInputTruncated: emitInputTruncated(rs.telemetry.tracer, rs.telemetry.taskId),
                     workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
+                    ...contextInstructionFilesOption(prepared),
                     ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                     ...this.seamCCompactionOptions(prepared),
                     ...gitRestateOption(prepared),
@@ -3479,6 +3575,7 @@ export class Runner {
                                         detail: {
                                             ...(steer.inputId !== undefined ? { inputId: steer.inputId } : {}),
                                             sessionId: prepared.sessionId,
+                                            runId: prepared.runId,
                                             ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}),
                                         },
                                     });
@@ -3859,7 +3956,7 @@ export class Runner {
                 steer: Math.max(0, undrainedUserAtEnd.steer - migratedParked.steer),
                 followUp: Math.max(0, undrainedUserAtEnd.followUp - migratedParked.followUp),
             };
-            for (const notice of undrainedUserInputNotices(remaining, spec.taskId, prepared.sessionId)) {
+            for (const notice of undrainedUserInputNotices(remaining, spec.taskId ?? prepared.sessionId, prepared.sessionId, prepared.runId)) {
                 deliverEngineNotice(this.deps.onNotice, notice);
             }
         }
@@ -3867,6 +3964,7 @@ export class Runner {
             emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.announce_dropped", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
         }
         const comp = await this.finish(spec, prepared, {
+            telemetry: { tracer: rs.telemetry.tracer, taskId: rs.telemetry.taskId },
             skipCompaction: durablyPaused || compactionBreaker.failures >= MAX_CONSECUTIVE_COMPACTION_FAILURES,
             minTokens: rs.counters.compactionFloor,
             brain: compactionBrain,
@@ -3951,10 +4049,12 @@ export class Runner {
             }
             const result = assembleResult(spec, prepared.sessionId, final, stats, {
                 threw,
+                runId: prepared.runId,
                 model: prepared.model.id,
                 unpricedSpend: rs.telemetry.unpricedSpend,
                 rewindNotes: prepared.rewindNotes,
                 haltedOnUserRejection: prepared.batchHaltRef.current !== undefined,
+                userHalted: loopLatch.userHalted,
                 strandedHumanAnswers,
                 remoteEnvFailures: prepared.remoteEnvFailures,
                 effectiveReadFace: prepared.effectiveReadFace,
@@ -4008,6 +4108,7 @@ export class Runner {
                     r.errorMessage = `${r.errorMessage ?? "the resume leg did not complete"} — the approved action never started, and reopening the checkpoint FAILED: its state is unprovable from here. Re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead`;
                 }
             }
+            prepared.sealReadStateSeat?.(ownCommittedTailRef.current);
             {
                 const wss = prepared.workspaceStateSettle;
                 if (wss !== undefined && result.status !== "suspended" && result.status !== "needs_review") {
@@ -4096,6 +4197,7 @@ export class Runner {
                 kind: "task.end",
                 version: 1,
                 taskId: rs.telemetry.taskId,
+                runId: rs.telemetry.runId,
                 status: result.status,
                 errorCode: result.errorCode,
                 turns: stats.turns,
@@ -4139,9 +4241,7 @@ export class Runner {
             manualCompactRef.emitMooted = undefined;
             queue.push({ type: "done", result });
             queue.close();
-            if (spec.rewindFiles && result.status === "completed") {
-                await this.snapshotTurn(prepared);
-            }
+            await prepared.fileHistoryBoundary?.settle();
             if (spec.suggestNextPrompts && result.status === "completed") {
                 onSuggestions(this.suggestNextPrompts(spec, prepared, result));
             }
@@ -4220,7 +4320,7 @@ export class Runner {
             if (!sameRouteIdentity(model, prepared.model)) {
                 const verdict = await adjudicateDerivedRoute({ brain: this.deps.brain, model, getApiKeyAndHeaders: spec.getApiKeyAndHeaders });
                 if (verdict !== undefined && !verdict.ok) {
-                    deliverEngineNotice(this.deps.onNotice, fallbackToPrimaryNotice({ seat: "prompt-suggestions", from: model.id, to: prepared.model.id, verdict, sessionId: prepared.sessionId }));
+                    deliverEngineNotice(this.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;
                 }
@@ -4253,71 +4353,6 @@ export class Runner {
             clearTimeout(timer);
         }
     }
-    async snapshotTurn(prepared) {
-        const store = this.deps.fileSnapshotStore;
-        const env = prepared.ownedEnv ?? this.deps.executionEnv;
-        if (!store || !env)
-            return;
-        try {
-            const leafId = await prepared.session.getLeafId();
-            if (!leafId)
-                return;
-            const root = prepared.taskRootPath;
-            const refusal = this.snapshotTooLargeRoots.get(root);
-            if (refusal !== undefined) {
-                if (Date.now() - refusal.refusedAt < SNAPSHOT_TOO_LARGE_TTL_MS) {
-                    if (!refusal.skipAnnounced) {
-                        refusal.skipAnnounced = true;
-                        try {
-                            this.deps.onError?.(new Error(`rewind-files snapshot skipped for this working-tree root: a too_large refusal is still inside its ${SNAPSHOT_TOO_LARGE_TTL_MS / 60_000}-minute cooldown (re-probed at ${new Date(refusal.refusedAt + SNAPSHOT_TOO_LARGE_TTL_MS).toISOString()}) — turns completed during the cooldown capture no snapshot and cannot be rewound to. Announced once per cooldown window.`), { phase: "rewind", sessionId: prepared.sessionId, classification: "too_large" });
-                        }
-                        catch {
-                        }
-                    }
-                    return;
-                }
-                this.snapshotTooLargeRoots.delete(root);
-            }
-            const ac = new AbortController();
-            let timer;
-            const timeout = new Promise((resolve) => {
-                timer = setTimeout(() => {
-                    ac.abort();
-                    resolve({ ok: false, error: { code: "aborted", message: "snapshot timed out" } });
-                }, SNAPSHOT_TIMEOUT_MS);
-            });
-            const work = store.snapshot(prepared.sessionId, leafId, env, root, ac.signal);
-            work.catch(() => { });
-            let r;
-            try {
-                r = await Promise.race([work, timeout]);
-            }
-            finally {
-                clearTimeout(timer);
-            }
-            if (!r.ok) {
-                const tooLarge = r.error.code === "too_large";
-                const refusedAt = Date.now();
-                if (tooLarge && !this.snapshotTooLargeRoots.has(root))
-                    this.snapshotTooLargeRoots.set(root, { refusedAt, skipAnnounced: false });
-                try {
-                    this.deps.onError?.(new Error(`rewind-files snapshot failed (${r.error.code}): ${r.error.message}` +
-                        (tooLarge
-                            ? ` — skipping further snapshots for this root (this process) during a ${SNAPSHOT_TOO_LARGE_TTL_MS / 60_000}-minute cooldown, until ${new Date(refusedAt + SNAPSHOT_TOO_LARGE_TTL_MS).toISOString()}, when the tree is re-probed automatically. Raise the store's snapshotBounds to accept a tree this size; shrinking the tree also re-enables rewind, but only at that re-probe — not immediately`
-                            : "")), { phase: "rewind", sessionId: prepared.sessionId, ...(tooLarge ? { classification: "too_large" } : {}) });
-                }
-                catch {
-                }
-            }
-        }
-        catch (err) {
-            try {
-                this.deps.onError?.(err, { phase: "rewind", sessionId: prepared.sessionId });
-            }
-            catch {
-            }
-        }
-    }
     async runTask(spec, internals) {
         const stream = this.runTaskStream(spec, undefined, internals);
         for await (const _ of stream) {
@@ -4687,12 +4722,13 @@ export class Runner {
                         "(corrupt / inconsistently-minted row) — the frozen deny data the resume would execute is not the data the " +
                         "digest authenticates; rejected pre-CAS (the checkpoint stays pending)");
                 }
-                const suppliedDigest = constraintChainDigest((internals?.inheritedGate?.parentConstraints ?? []).map((pc) => constraintChainEntryOf(pc.policy, { ...(pc.autoMode !== undefined ? { autoModeArmed: true } : {}), ...(pc.durableMandate === true ? { durableMandate: true } : {}), ...(pc.contentMandate === true ? { contentMandate: true } : {}) })));
+                const suppliedDigest = constraintChainDigest((internals?.inheritedGate?.parentConstraints ?? []).map((pc, i) => constraintChainEntryOfSuppliedLayer(pc, persistedChain[i])));
                 if (suppliedDigest !== expectedDigest) {
                     throw new CheckpointError("resume.parent_constraint_mismatch", "the re-supplied parent-constraint chain's projection content does not match what the checkpoint recorded " +
                         `(recorded ${expectedDigest}, re-supplied ${suppliedDigest}) — a same-shape chain with different frozen ` +
                         "deny data would run the resumed leg under a different ancestor gate than it suspended with; " +
-                        "rejected pre-CAS (the checkpoint stays pending) — re-resume with the original chain's policies");
+                        "rejected pre-CAS (the checkpoint stays pending) — re-resume with the original chain's policies " +
+                        "(including, when the row recorded one, the ancestor's auto-mode arming recipe verbatim)");
                 }
             }
         }
@@ -5370,9 +5406,10 @@ export class Runner {
                     minTokens: opts?.minTokens,
                     overheadTokens: prepared.promptOverheadTokens,
                     ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
-                    onInputTruncated: emitInputTruncated(spec.tracer ?? this.deps.tracer, spec.taskId ?? prepared.sessionId),
+                    onInputTruncated: emitInputTruncated(opts?.telemetry?.tracer ?? spec.tracer ?? this.deps.tracer, opts?.telemetry?.taskId ?? spec.taskId ?? prepared.sessionId),
                     ...(opts?.windowSafety ?? {}),
                     workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
+                    ...contextInstructionFilesOption(prepared),
                     ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                     ...this.seamCCompactionOptions(prepared),
                     ...gitRestateOption(prepared),
@@ -5383,17 +5420,17 @@ export class Runner {
                 });
                 this.recordCompactionReuse(prepared, finishComp);
                 if (finishComp.unevaluableWindow) {
-                    discloseUnevaluableWindow(finishComp.unevaluableWindow, prepared, spec.tracer ?? this.deps.tracer, spec.taskId ?? prepared.sessionId, this.deps.onError);
+                    discloseUnevaluableWindow(finishComp.unevaluableWindow, prepared, opts?.telemetry?.tracer ?? spec.tracer ?? this.deps.tracer, opts?.telemetry?.taskId ?? spec.taskId ?? prepared.sessionId, this.deps.onError);
                 }
                 comp = finishComp;
             }
             catch (err) {
                 const failMsg = String(err instanceof Error ? err.message : err);
                 const failReason = failMsg.length > 512 ? `${failMsg.slice(0, 512)}…` : failMsg;
-                emitTrace(spec.tracer ?? this.deps.tracer, () => ({
+                emitTrace(opts?.telemetry?.tracer ?? spec.tracer ?? this.deps.tracer, () => ({
                     kind: "compaction.failed",
                     version: 1,
-                    taskId: spec.taskId ?? prepared.sessionId,
+                    taskId: opts?.telemetry?.taskId ?? spec.taskId ?? prepared.sessionId,
                     trigger: "auto",
                     reason: failReason,
                     ts: Date.now(),

package/dist/core/runner/session-file-state-replay.d.ts

@@ -18,11 +18,17 @@
  *     a `git checkout`, a bash command — anything this transcript does not record) therefore fails
  *     the staleness comparison and the edit is refused, exactly as it is inside a single task. A
  *     reconstruction that re-read the file to build its hash would instead wave the dirty edit
- *     through; that is the one thing this module must never do.
- *  2. **Only WHOLE-file records qualify.** A partial read, a notebook projection or an `Edit` result
- *     does not carry the file's full post-condition text, so there is nothing to hash honestly.
- *     Those files are simply not reported: the gate then behaves exactly as it does today (the model
- *     re-reads), which is the pre-existing cost, not a new failure.
+ *     through; that is the one thing this module must never do. (#483 D1, ruled 2026-08-28: this is
+ *     deliberately STRICTER than CC's own rehydrate, whose Edit arm re-reads the disk and would
+ *     admit a between-turns external change — same gate satisfaction, no staleness give-up.)
+ *  2. **Only records whose full post-condition is PROVABLE qualify.** A whole-file `Read` and a
+ *     `Write` carry the text verbatim. An `Edit` card (#483 rung-2) carries a diff BASE — the
+ *     pre-edit whole text plus the resolved mutations — so its post-condition is RECOMPUTED through
+ *     the same single-source application step the tool itself used (`applyRecordedEdit`); a card
+ *     that cannot recompute (malformed, offloaded, or its oldString absent from its own base) falls
+ *     back to RETRACTING the file's record, never to a guess. A partial read or a notebook
+ *     projection proves nothing and is simply not reported: the gate then behaves exactly as before
+ *     (the model re-reads), which is the pre-existing cost, not a new failure.
  */
 import type { AgentMessage } from "../../internal/harness.js";
 /** The whole text of one file at the moment the transcript recorded it. */
@@ -39,11 +45,13 @@ export interface TranscriptFileRecord {
  *
  * Records are read only from SUCCESSFUL results (an `isError` result changed nothing and proves
  * nothing). A `Write` proves the post-condition it just persisted; a whole-file `Read` proves what it
- * just served. An `Edit` result proves that the file CHANGED without recording its new text, so it
- * retracts whatever an earlier record said — leaving a stale entry behind would blame the user for
- * the agent's own edit ("modified since read") the next turn. Anything else (partial reads, dedup
- * stubs, notebook projections, image/document reads, foreign tools) is inert: it neither proves nor
- * retracts, because reading a file does not change it.
+ * just served. An `Edit` card (#483 rung-2) proves the post-condition RECOMPUTED from its recorded
+ * diff base + mutations — or, when it cannot prove (malformed / offloaded / inconsistent), retracts
+ * whatever an earlier record said (leaving a stale entry behind would blame the user for the agent's
+ * own edit, "modified since read", the next turn). A `NotebookEdit` always retracts (deliberate
+ * residual — see {@link RETRACTING_RESULTS}). Anything else (partial reads, dedup stubs, notebook
+ * projections, image/document reads, foreign tools) is inert: it neither proves nor retracts,
+ * because reading a file does not change it.
  *
  * The parameter is the session's own message lane (`AgentMessage`, custom lanes included) rather than
  * the narrowed model-facing union: this reads the branch as the session stores it, and every lane that