@sema-agent/core 5.34.0 → 5.36.0

package/dist/core/runner/runtask.js

@@ -2,7 +2,9 @@ import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
-import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
+import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
+import { GIT_STATUS_ECHO_PREVIEW, branchCarriesVisiblePositiveGitFrame, newestEngineGitFrame, stripGitStatusUnits } from "./git-status-frame.js";
+import { gitFrameContextVisible, normalizeGitAnnouncement } from "../../internal/harness.js";
 import { engineVersion } from "../version.js";
 import { CONFIG_CATALOG_VERSION, declarationReasons, resolveEffectiveConfig } from "../../config/catalog.js";
 import { eventDefaultOn } from "../../prompt-assembly/event-registry.js";
@@ -41,7 +43,7 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, sanitizeUntr
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
-import { checkToolPolicyProjection, constraintChainDigest, constraintChainEntryOf, isApprovalSettledBy, refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
+import { checkToolPolicyProjection, constraintChainDigest, constraintChainEntryOf, isApprovalSettledBy, refuseOutOfContractDecision, screenApproverAttribution, toolPolicyNameSets } from "../tool-policy.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, isDelegatedAgentTerminal, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
@@ -68,6 +70,13 @@ function nextHumanInputSeq(key) {
     }
     return ++box.n;
 }
+function sameAcceptedSteerInput(a, b) {
+    return (a.payload === b.payload &&
+        a.trusted === b.trusted &&
+        a.actor?.id === b.actor?.id &&
+        a.actor?.hostAsserted === b.actor?.hostAsserted &&
+        a.actor?.issuer === b.actor?.issuer);
+}
 const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
 const STOP_HOOK_BLOCK_CAP = 8;
 const COMPACTION_REGROWTH_FACTOR = 1.5;
@@ -130,7 +139,7 @@ function resumeDecisionWasNegative(resume) {
 }
 const DEFERRED_REISSUE = "[DEFERRED] This tool call shared a batch with a call that suspended for durable approval, so it was " +
     "NOT executed on resume. If you still need it, issue it again now.";
-function toolEndBodyFrom(result, isError, settledBy) {
+function toolEndBodyFrom(result, isError, settledBy, approver) {
     const o = toolOutputFrom(result);
     const st = structuredFrom(result);
     const det = isError ? result?.details : undefined;
@@ -142,6 +151,7 @@ function toolEndBodyFrom(result, isError, settledBy) {
         ...(st !== undefined ? { structured: st } : {}),
         ...(typeof code === "string" ? { errorCode: code } : {}),
         ...(settledBy !== undefined ? { settledBy } : {}),
+        ...(approver !== undefined ? { approver } : {}),
     };
 }
 export function reconciledToolEndBody(orphan) {
@@ -860,6 +870,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
                 ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                 ...runnerHooks.seamCCompactionOptions(prepared),
+                ...gitRestateOption(prepared),
                 ...windowSafetyOptions(event.model),
                 ...runnerHooks.compactionHookOptions(spec, prepared.sessionId, passTrigger),
             });
@@ -988,6 +999,96 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
     };
     return onTurnBoundary;
 }
+function wrapGitFrame(body) {
+    return `<system-reminder>\n${sanitizeUntrustedText(body)}\n</system-reminder>`;
+}
+async function resolveGitLegDelivery(prepared, cpMirror, report) {
+    const ref = prepared.gitStatusRef;
+    const frame = ref.frame;
+    if (frame === undefined)
+        return undefined;
+    let prior;
+    let pending = false;
+    try {
+        const branchReadout = await prepared.session.getGitAnnouncement?.();
+        if (branchReadout !== undefined) {
+            if (branchReadout.status === "pending") {
+                pending = true;
+                prior = { kind: branchReadout.kind, hash: branchReadout.hash };
+            }
+            else {
+                prior = { kind: branchReadout.kind, hash: branchReadout.hash, ...(branchReadout.entryId !== undefined ? { entryId: branchReadout.entryId } : {}) };
+            }
+        }
+        else {
+            const shaped = normalizeGitAnnouncement(cpMirror);
+            if (shaped !== undefined) {
+                if (shaped.pending === true || shaped.entryId === undefined) {
+                    pending = true;
+                    prior = { kind: shaped.kind, hash: shaped.hash };
+                }
+                else if (gitFrameContextVisible(await prepared.session.getBranch(), shaped.entryId)) {
+                    prior = { kind: shaped.kind, hash: shaped.hash, entryId: shaped.entryId };
+                }
+                else {
+                    pending = true;
+                    prior = { kind: shaped.kind, hash: shaped.hash };
+                }
+            }
+        }
+    }
+    catch (err) {
+        pending = true;
+        report(err instanceof Error ? err : new Error(String(err)));
+    }
+    if (prior !== undefined && !pending && prior.entryId !== undefined) {
+        try {
+            const newest = newestEngineGitFrame(await prepared.session.getBranch());
+            if (newest === undefined || newest.entryId !== prior.entryId)
+                pending = true;
+        }
+        catch (err) {
+            pending = true;
+            report(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    if (prior !== undefined)
+        ref.announced = pending ? { ...prior, pending: true } : { ...prior };
+    const negative = frame.kind === "unavailable" || frame.kind === "non-repo";
+    if (negative) {
+        if (prior === undefined && !pending) {
+            let mustDisown;
+            try {
+                mustDisown = branchCarriesVisiblePositiveGitFrame(await prepared.session.getBranch());
+            }
+            catch (err) {
+                mustDisown = true;
+                report(err instanceof Error ? err : new Error(String(err)));
+            }
+            return mustDisown ? frame.body : undefined;
+        }
+        if (prior !== undefined && !pending && prior.kind === frame.kind && prior.hash === frame.hash)
+            return undefined;
+        return frame.body;
+    }
+    if (!pending && prior !== undefined && prior.kind === frame.kind && prior.hash === frame.hash) {
+        ref.protectedText = wrapGitFrame(frame.body);
+        if (frame.kind === "full" && frame.shrunk !== undefined) {
+            ref.wrappedShrink = { find: ref.protectedText, replace: wrapGitFrame(frame.shrunk.body) };
+        }
+        return undefined;
+    }
+    return frame.body;
+}
+function gitRestateOption(prepared) {
+    const ref = prepared.gitStatusRef;
+    if (ref.frame === undefined || ref.announced === undefined || ref.reassert === undefined)
+        return {};
+    const use = ref.overBudgetShrunk && ref.frame.shrunk !== undefined
+        ? { kind: "degraded", hash: ref.frame.shrunk.hash }
+        : { kind: ref.frame.kind, hash: ref.frame.hash };
+    return { gitRestate: { pending: use, land: ref.reassert } };
+}
 function makeHarnessHandlers(prepared, stats, rs, deps) {
     const { spec, queue, internals, ident, parentToolCallId, subagentName, pushContent, emitCommitted, startedToolCallIds, toolStartAt, writeFamilyOf, toolLabels, postToolBatchHook, batchArgs } = deps;
     const internalsNotifier = createSafeNotifier({
@@ -1032,6 +1133,19 @@ 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.gitStatusRef.pendingReceipt !== undefined) {
+            const pr = prepared.gitStatusRef.pendingReceipt;
+            const c = m.content;
+            const text = typeof c === "string"
+                ? c
+                : Array.isArray(c) && c.length >= 1 && c[0].type === "text"
+                    ? c[0].text
+                    : undefined;
+            if (text === pr.text) {
+                delete prepared.gitStatusRef.pendingReceipt;
+                pr.commit(event.entryId);
+            }
+        }
         if (rs.degrade.degraded === undefined && m.role === "assistant") {
             const deg = readDegradation(m);
             if (deg)
@@ -1213,16 +1327,16 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                     prepared.lspDiagnostics.nudge(p);
             }
         }
-        const settledBy = prepared.approvalSettledBy.get(event.toolCallId);
-        if (settledBy !== undefined)
-            prepared.approvalSettledBy.delete(event.toolCallId);
+        const settlement = prepared.approvalSettlement.get(event.toolCallId);
+        if (settlement !== undefined)
+            prepared.approvalSettlement.delete(event.toolCallId);
         pushContent({
             type: "tool_end",
             toolCallId: event.toolCallId,
             toolName: event.toolName,
             ...(toolLabels.get(event.toolName) !== undefined ? { label: toolLabels.get(event.toolName) } : {}),
             isError: event.isError,
-            ...toolEndBodyFrom(event.result, event.isError, settledBy),
+            ...toolEndBodyFrom(event.result, event.isError, settlement?.settledBy, settlement?.approver),
             ...ident(),
         });
         announceWorkspaceMove();
@@ -1253,6 +1367,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 type: "task_progress",
                 taskId: rs.telemetry.taskId,
                 ...(internals?.delegationTaskType !== undefined ? { taskType: internals.delegationTaskType } : {}),
+                ...(internals?.cycleSeq !== undefined ? { seq: internals.cycleSeq } : {}),
                 ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
                 ...(subagentName ? { name: subagentName } : {}),
                 usage: { totalTokens: stats.tokens, toolUses: stats.toolCalls, durationMs: Date.now() - rs.telemetry.taskStart },
@@ -1444,6 +1559,7 @@ export class Runner {
         };
         let reapHandle;
         let steerChain = Promise.resolve();
+        const acceptedSteerInputs = new Map();
         const notifyRef = {};
         const manualCompactRef = { requested: false, waiters: [] };
         const drainManualCompactWaiters = (outcome) => {
@@ -1565,6 +1681,7 @@ export class Runner {
             queue.push({ type: "done", result: resultValue });
             queue.close();
         });
+        void settled.then(() => acceptedSteerInputs.clear(), () => acceptedSteerInputs.clear());
         const steeringError = (msg, code = "steering.not_running") => {
             const e = new Error(`cannot steer: ${msg}`);
             e.code = code;
@@ -1613,22 +1730,40 @@ export class Runner {
                 return suggestionsDone.catch(() => []);
             },
             steer: async (text, options) => {
-                if (options?.trusted && sanitizeUntrustedText(text) !== text) {
+                const trusted = options?.trusted ? true : false;
+                if (trusted && sanitizeUntrustedText(text) !== text) {
                     throw steeringError("trusted steering text must not contain a </system-reminder> tag", "steering.invalid_content");
                 }
-                const actor = options?.actor === undefined ? undefined : snapshotActorAssertion(options.actor);
+                const inputId = options?.inputId;
+                if (inputId !== undefined) {
+                    if (typeof inputId !== "string") {
+                        throw steeringError("inputId must be a string when supplied", "steering.invalid_content");
+                    }
+                    if (inputId === "" || inputId.length > MAX_STEER_INPUT_ID_CHARS) {
+                        throw steeringError(`inputId must be a non-empty string of at most ${MAX_STEER_INPUT_ID_CHARS} characters`, "steering.invalid_content");
+                    }
+                    if (inputId === LEGACY_PENDING_STEER_INPUT_ID) {
+                        throw steeringError(`inputId "${LEGACY_PENDING_STEER_INPUT_ID}" is reserved for a pre-queue parked steer and cannot be supplied by a caller`, "steering.invalid_content");
+                    }
+                }
+                const actorIn = options?.actor;
+                const actor = actorIn === undefined ? undefined : snapshotActorAssertion(actorIn);
                 const projected = projectHumanInput({ text, actor, source: "steer" });
-                const payload = options?.trusted ? formatHookFeedback(projected) : projected;
+                const payload = trusted ? formatHookFeedback(projected) : projected;
                 const mintsAFrame = payload.trim().length !== 0;
-                const emitAccepted = (h) => {
+                const replay = { payload, trusted, ...(actor !== undefined ? { actor } : {}) };
+                const noteAccepted = (h) => {
                     if (!mintsAFrame)
                         return;
+                    if (typeof inputId === "string")
+                        acceptedSteerInputs.set(inputId, replay);
                     queue.push({
                         ...buildHumanInputEvent({
                             carrier: "steer",
                             source: "steer",
                             delivery: "queued",
                             sessionSeq: nextHumanInputSeq(h.harness),
+                            ...(typeof inputId === "string" ? { inputId } : {}),
                             ...(actor !== undefined ? { actor } : {}),
                             ...(actor?.issuer !== undefined ? { issuer: actor.issuer } : {}),
                             ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
@@ -1645,9 +1780,21 @@ export class Runner {
                     const h = handle ?? (await orTimeout(ready));
                     if (!h)
                         throw steeringError("the task is not running");
+                    if (typeof inputId === "string") {
+                        const prior = acceptedSteerInputs.get(inputId);
+                        if (prior !== undefined) {
+                            if (resultValue !== undefined || h.loop.ended)
+                                throw steeringError("the task is no longer running");
+                            if (!sameAcceptedSteerInput(prior, replay)) {
+                                throw steeringError("a different steering instruction was already accepted under this inputId — re-issue this one with a fresh inputId " +
+                                    "(an identical payload would have been an idempotent retry)", "steering.duplicate_input_id");
+                            }
+                            return;
+                        }
+                    }
                     try {
                         await h.harness.steer(payload, { provenance: "engine-note", ...(actor !== undefined ? { actor } : {}) });
-                        emitAccepted(h);
+                        noteAccepted(h);
                         return;
                     }
                     catch (e) {
@@ -1658,7 +1805,7 @@ export class Runner {
                     while (resultValue === undefined && !h.loop.ended && Date.now() < birthDeadline) {
                         try {
                             await h.harness.steer(payload, { provenance: "engine-note", ...(actor !== undefined ? { actor } : {}) });
-                            emitAccepted(h);
+                            noteAccepted(h);
                             return;
                         }
                         catch (e2) {
@@ -2135,12 +2282,12 @@ export class Runner {
                             return [];
                         const full = textOf(e.message);
                         if (m.engineMinted === true)
-                            return [full];
+                            return [stripGitStatusUnits(full)];
                         if (Array.isArray(m.engineSegments) && m.engineSegments.length > 0) {
-                            return m.engineSegments.map((s) => full.slice(Math.max(0, s.start), Math.max(0, s.end)));
+                            return m.engineSegments.map((s) => stripGitStatusUnits(full.slice(Math.max(0, s.start), Math.max(0, s.end))));
                         }
                         if (typeof m.enginePrefixChars === "number" && m.enginePrefixChars > 0)
-                            return [full.slice(0, m.enginePrefixChars)];
+                            return [stripGitStatusUnits(full.slice(0, m.enginePrefixChars))];
                         return [];
                     });
                 }
@@ -2652,6 +2799,7 @@ export class Runner {
                             workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
                             ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                             ...this.seamCCompactionOptions(prepared),
+                            ...gitRestateOption(prepared),
                             ...windowSafetyOptions(prepared.harness.getModel()),
                             ...this.compactionHookOptions(spec, prepared.sessionId, "forced"),
                         });
@@ -2722,6 +2870,80 @@ export class Runner {
                 recordCompactionReuse: (p, c) => this.recordCompactionReuse(p, c),
             },
         });
+        prepared.gitStatusRef.reassert = async () => {
+            const ref = prepared.gitStatusRef;
+            const frame = ref.frame;
+            if (frame === undefined)
+                return;
+            delete ref.mirrorOwed;
+            const use = ref.overBudgetShrunk && frame.shrunk !== undefined
+                ? { kind: "degraded", body: frame.shrunk.body, hash: frame.shrunk.hash }
+                : { kind: frame.kind, body: frame.body, hash: frame.hash };
+            const wrapped = wrapGitFrame(use.body);
+            try {
+                const entryId = await prepared.session.appendMessage({
+                    role: "user",
+                    content: [{ type: "text", text: wrapped }],
+                    timestamp: Date.now(),
+                    engineMinted: true,
+                });
+                ref.announced = { kind: use.kind, hash: use.hash, entryId };
+                ref.protectedText = wrapped;
+                if (use.kind === "full" && frame.shrunk !== undefined) {
+                    ref.wrappedShrink = { find: wrapped, replace: wrapGitFrame(frame.shrunk.body) };
+                }
+                else {
+                    delete ref.wrappedShrink;
+                }
+                queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[use.kind], ...ident() });
+                rs.attach.attachmentsInjected += 1;
+                try {
+                    await prepared.session.appendGitAnnouncement?.({ kind: use.kind, hash: use.hash, entryId });
+                }
+                catch (mirrorErr) {
+                    try {
+                        this.deps.onError?.(new Error(`git announcement mirror write failed (frame delivered; next leg re-announces): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`), { phase: "degraded", sessionId: prepared.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+            catch (err) {
+                ref.announced = { kind: use.kind, hash: use.hash, pending: true };
+                try {
+                    this.deps.onError?.(new Error(`git status frame re-assert append failed (pending; retried at the next boundary): ${err instanceof Error ? err.message : String(err)}`), { phase: "degraded", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+        };
+        const flushGitMirror = async () => {
+            const owed = prepared.gitStatusRef.mirrorOwed;
+            if (owed === undefined)
+                return;
+            if (prepared.gitStatusRef.overBudgetShrunk && owed.kind === "full") {
+                delete prepared.gitStatusRef.mirrorOwed;
+                return;
+            }
+            delete prepared.gitStatusRef.mirrorOwed;
+            try {
+                await prepared.session.appendGitAnnouncement?.(owed);
+            }
+            catch (mirrorErr) {
+                prepared.gitStatusRef.mirrorOwed = owed;
+                try {
+                    this.deps.onError?.(new Error(`git announcement mirror write failed (frame delivered; retried at the next serialization point): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`), { phase: "degraded", sessionId: prepared.sessionId });
+                }
+                catch {
+                }
+            }
+        };
+        const unsubGitRetry = prepared.harness.on("turn_boundary", async () => {
+            await flushGitMirror();
+            if (prepared.gitStatusRef.announced?.pending === true)
+                await prepared.gitStatusRef.reassert?.();
+            return undefined;
+        });
         const unsubBoundary = prepared.harness.on("turn_boundary", onTurnBoundary);
         const unsub = prepared.harness.subscribe((event) => {
             switch (event.type) {
@@ -2799,6 +3021,25 @@ export class Runner {
                             continuation += "\n\n" + formatHookFeedback(renderOrphanedBackgroundTasks(orphans));
                         }
                     }
+                    let gitResumeDelivered;
+                    {
+                        const gitBody = await resolveGitLegDelivery(prepared, resume.cp.state.gitAnnouncement, (err) => {
+                            try {
+                                this.deps.onError?.(new Error(`git announcement ladder unreadable (conservative re-announce): ${err.message}`), { phase: "degraded", sessionId: prepared.sessionId });
+                            }
+                            catch {
+                            }
+                        });
+                        const gitFrame = prepared.gitStatusRef.frame;
+                        if (gitBody !== undefined && gitFrame !== undefined) {
+                            const wrappedGit = wrapGitFrame(gitBody);
+                            continuation += "\n\n" + wrappedGit;
+                            gitResumeDelivered = { kind: gitFrame.kind, hash: gitFrame.hash, wrapped: wrappedGit };
+                            if (gitFrame.kind === "full" && gitFrame.shrunk !== undefined) {
+                                prepared.gitStatusRef.wrappedShrink = { find: wrappedGit, replace: wrapGitFrame(gitFrame.shrunk.body) };
+                            }
+                        }
+                    }
                     const engineSegments = continuation.length > 0 ? [{ start: 0, end: continuation.length }] : [];
                     const resumeFrames = [
                         ...readPendingSteerQueue(resume.cp.state).map((entry) => ({ entry, source: "steer" })),
@@ -2828,7 +3069,23 @@ export class Runner {
                     }
                     if (resume !== undefined)
                         resume.decisionDelivered = true;
+                    if (gitResumeDelivered !== undefined) {
+                        const delivered = gitResumeDelivered;
+                        prepared.gitStatusRef.protectedText = delivered.wrapped;
+                        prepared.gitStatusRef.pendingReceipt = {
+                            text: continuation,
+                            commit: (entryId) => {
+                                prepared.gitStatusRef.announced = { kind: delivered.kind, hash: delivered.hash, entryId };
+                                queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[delivered.kind], ...ident() });
+                                rs.attach.attachmentsInjected += 1;
+                                prepared.gitStatusRef.mirrorOwed = { kind: delivered.kind, hash: delivered.hash, entryId };
+                            },
+                        };
+                    }
                     final = await withBrainSinks(() => prepared.harness.prompt(continuation, { engineSegments }));
+                    await flushGitMirror();
+                    if (prepared.gitStatusRef.announced?.pending === true)
+                        await prepared.gitStatusRef.reassert?.();
                 }
             }
             else {
@@ -2860,6 +3117,27 @@ export class Runner {
                         promptBlocked = true;
                     }
                 }
+                let gitLegDelivered;
+                if (!promptBlocked) {
+                    const gitBody = await resolveGitLegDelivery(prepared, undefined, (err) => {
+                        try {
+                            this.deps.onError?.(new Error(`git announcement ladder unreadable (conservative re-announce): ${err.message}`), { phase: "degraded", sessionId: prepared.sessionId });
+                        }
+                        catch {
+                        }
+                    });
+                    const gitFrame = prepared.gitStatusRef.frame;
+                    if (gitBody !== undefined && gitFrame !== undefined) {
+                        const wrappedGit = wrapGitFrame(gitBody);
+                        const standalone = spec.images !== undefined && spec.images.length > 0;
+                        if (!standalone)
+                            effectiveObjective = `${wrappedGit}\n${effectiveObjective}`;
+                        gitLegDelivered = { kind: gitFrame.kind, hash: gitFrame.hash, standalone, wrapped: wrappedGit };
+                        if (gitFrame.kind === "full" && gitFrame.shrunk !== undefined) {
+                            prepared.gitStatusRef.wrappedShrink = { find: wrappedGit, replace: wrapGitFrame(gitFrame.shrunk.body) };
+                        }
+                    }
+                }
                 const firstFrames = [];
                 if (rs.attach.attachState !== undefined) {
                     const attach = rs.attach.attachState;
@@ -2897,17 +3175,18 @@ export class Runner {
                         effectiveObjective = `${firstFrames.map((f) => `<system-reminder>\n${sanitizeUntrustedText(f.body)}\n</system-reminder>`).join("\n")}\n${effectiveObjective}`;
                     }
                 }
+                const gitQueuedChars = gitLegDelivered !== undefined && gitLegDelivered.standalone ? gitLegDelivered.wrapped.length : 0;
                 const precallMicroUsd = rs.budget.maxCostMicroUsd === undefined
                     ? 0
                     : computeCostMicroUsd({
-                        totalInputTokens: Math.ceil(effectiveObjective.length / 4),
+                        totalInputTokens: Math.ceil((effectiveObjective.length + gitQueuedChars) / 4),
                         cacheReadTokens: 0,
                         cacheWriteTokens: 0,
                         cacheWriteTokensLong: 0,
                         outputTokens: prepared.model.maxTokens ?? DEFAULT_PRECALL_OUTPUT_TOKENS,
                     }, rs.telemetry.pricing);
                 const precallCeilingMicroUsd = prepared.suspendForResource !== undefined ? rs.budget.remainingMicroUsd : rs.budget.maxCostMicroUsd;
-                const precallTokens = Math.ceil(effectiveObjective.length / 4) + (prepared.model.maxTokens ?? DEFAULT_PRECALL_OUTPUT_TOKENS);
+                const precallTokens = Math.ceil((effectiveObjective.length + gitQueuedChars) / 4) + (prepared.model.maxTokens ?? DEFAULT_PRECALL_OUTPUT_TOKENS);
                 const precallCeilingTokens = prepared.suspendForResource !== undefined ? rs.budget.remainingTokens : rs.budget.maxTokensWindow;
                 const entryUsageRetryAfterMs = prepared.usageGovernance !== undefined ? await prepared.usageGovernance.check(Date.now()) : undefined;
                 if (promptBlocked) {
@@ -2939,6 +3218,21 @@ export class Runner {
                     const images = spec.images
                         ? await Promise.all(spec.images.map((img) => toImageContent(img, this.deps.allowImageUrl)))
                         : undefined;
+                    if (gitLegDelivered !== undefined) {
+                        const delivered = gitLegDelivered;
+                        if (delivered.standalone)
+                            await prepared.harness.nextTurn(delivered.wrapped, { engineMinted: true });
+                        prepared.gitStatusRef.protectedText = delivered.wrapped;
+                        prepared.gitStatusRef.pendingReceipt = {
+                            text: delivered.standalone ? delivered.wrapped : effectiveObjective,
+                            commit: (entryId) => {
+                                prepared.gitStatusRef.announced = { kind: delivered.kind, hash: delivered.hash, entryId };
+                                queue.push({ type: "steering_injected", source: "git_status", preview: GIT_STATUS_ECHO_PREVIEW[delivered.kind], ...ident() });
+                                rs.attach.attachmentsInjected += 1;
+                                prepared.gitStatusRef.mirrorOwed = { kind: delivered.kind, hash: delivered.hash, entryId };
+                            },
+                        };
+                    }
                     for (const f of firstFrames) {
                         f.commit();
                         queue.push({ type: "steering_injected", source: f.source, preview: f.body.slice(0, 220), ...ident() });
@@ -2964,6 +3258,9 @@ export class Runner {
                         ...(enginePrefixChars > 0 ? { enginePrefixChars } : {}),
                         ...(objectiveActor !== undefined ? { actor: objectiveActor } : {}),
                     }));
+                    await flushGitMirror();
+                    if (prepared.gitStatusRef.announced?.pending === true)
+                        await prepared.gitStatusRef.reassert?.();
                 }
             }
             loopLatch.ended = true;
@@ -2993,6 +3290,7 @@ export class Runner {
             }
             notificationLaneLive = false;
             unsubscribeTaskNotifications();
+            unsubGitRetry();
             unsubBoundary();
             unsub();
         }
@@ -3136,6 +3434,7 @@ export class Runner {
                 budgetAxis: rs.limits.budgetAxis,
                 blockedReason: prepared.blockedRef.reason,
                 conflict: prepared.conflictRef.hit,
+                gitCoreOverBudget: prepared.gitStatusRef.terminalCode === "irreducible_core_over_budget",
                 outputInvalid: rs.degrade.outputInvalid,
                 suspendLoop: prepared.suspendLoopRef.hit,
                 suspendRef: prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined
@@ -3264,6 +3563,7 @@ export class Runner {
                     type: "task_progress",
                     taskId: rs.telemetry.taskId,
                     ...(internals?.delegationTaskType !== undefined ? { taskType: internals.delegationTaskType } : {}),
+                    ...(internals?.cycleSeq !== undefined ? { seq: internals.cycleSeq } : {}),
                     ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
                     ...(subagentName ? { name: subagentName } : {}),
                     usage: { totalTokens: stats.tokens, toolUses: stats.toolCalls, durationMs: Date.now() - rs.telemetry.taskStart },
@@ -3664,6 +3964,15 @@ export class Runner {
                 throw new CheckpointError("checkpoint.invalid_outcome", `resume carries decision "allow" with settledBy "${settledBy}" — a non-human settlement is a fail-closed end (nobody answered), so it cannot be the source of an approval that EXECUTES; ` +
                     "supply \"human\", or omit the field if the allow came from configuration rather than a person; refusing pre-CAS, the checkpoint stays pending", { field: "settledBy" });
             }
+            const approver = decide.approver;
+            const attribution = screenApproverAttribution(approver);
+            if (attribution.defect !== undefined) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume carries an approver attribution this engine refuses: ${attribution.defect}; refusing pre-CAS, the checkpoint stays pending`, { field: "approver" });
+            }
+            if (attribution.approver !== undefined && settledBy === undefined) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume names an approver but no settledBy — an attribution says WHOSE settlement it was and needs the word that says what KIND of end it was beside it; ` +
+                    `supply settledBy ("human" / "timeout" / "aborted"), or omit the approver; refusing pre-CAS, the checkpoint stays pending`, { field: "approver" });
+            }
             const reason = decide.reason;
             assertOutcomeText(reason, "reason");
             plainPolicyOutcome = {
@@ -3675,6 +3984,7 @@ export class Runner {
                 ...(reason !== undefined ? { reason } : {}),
                 ...(redeemedAnswer !== undefined ? { answer: redeemedAnswer } : {}),
                 ...(settledBy !== undefined ? { settledBy } : {}),
+                ...(attribution.approver !== undefined ? { approver: attribution.approver } : {}),
             };
             if (plainPolicyOutcome.decision === "deny" && plainPolicyOutcome.reason && sanitizeUntrustedText(plainPolicyOutcome.reason) !== plainPolicyOutcome.reason) {
                 throw new CheckpointError("checkpoint.invalid_outcome", "resume deny/reject reason must not contain a </system-reminder> tag");
@@ -4037,7 +4347,7 @@ export class Runner {
         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 emitEnd = (isError, result) => emit({ type: "tool_end", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, isError, ...toolEndBodyFrom(result, isError, outcome.settledBy) });
+        const emitEnd = (isError, result) => emit({ type: "tool_end", toolCallId: pendingAction.toolCallId, toolName: pendingAction.toolName, ...pendingLabel, isError, ...toolEndBodyFrom(result, isError, outcome.settledBy, outcome.approver) });
         if (outcome.decision === "deny") {
             const defaultDenial = outcome.settledBy === "timeout"
                 ? `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.`
@@ -4266,6 +4576,7 @@ export class Runner {
                     workingFileAttachments: buildWorkingFileAttachments(spec, prepared),
                     ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                     ...this.seamCCompactionOptions(prepared),
+                    ...gitRestateOption(prepared),
                     ...this.compactionHookOptions(spec, prepared.sessionId, "auto"),
                 });
                 this.recordCompactionReuse(prepared, finishComp);

package/dist/core/task-registry-agent.d.ts

@@ -275,6 +275,21 @@ export declare function resolveBackgroundAgentByNameLane(core: DurableAgentCore,
  *  alone does NOT retain the child session, so declaring at register time acknowledged parks that
  *  a capacity/pin failure (or plain session-scope) could never drain. No-op on unknown ids. */
 export declare function markRetainedContinuationLane(core: DurableAgentCore, id: string): void;
+/**
+ * #258 — the stop-cycle generation of the RUN BEING SPAWNED under this row (the same counter the
+ * register/revive lanes keep on the handle: fresh spawn = 1, durable-seeded revive = the claimed
+ * row's seq, in-memory wake = the bump). The spawn lanes read it ONCE, right after registering, to
+ * thread into the child's `RunInternals.cycleSeq` — one authoritative source instead of each lane
+ * re-deriving the seed-vs-fresh arithmetic. `undefined` for an unknown id or a non-agent row.
+ *
+ * PARKED-BORN arm (falsification F1): a parked handle's counter still names the cycle that PARKED —
+ * the run this spawn lane is about to drive begins at the consume flip, which installs the bumped
+ * value (`flipped.seq = seq + 1`, the §7.2d consume write). Answering the pre-flip number made one
+ * resumed run speak two generations (spawn/ticks at n, terminal at n+1), so the parked arm answers
+ * the flip's target instead. A resume that loses the consume arbitration never runs, so the answer
+ * is never attached to a live cycle it doesn't describe.
+ */
+export declare function backgroundAgentCycleSeqLane(core: DurableAgentCore, id: string): number | undefined;
 /** S2b RB-27② — REVIVE a settled background-agent row for a retained-session RESUME cycle: the
  *  row flips back to "running" with a fresh "attaching" channel and a bumped revive-cycle stamp
  *  (returned; the resume leg threads it through attach and settle so a stale cycle's late calls

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

@@ -867,6 +867,12 @@ export function markRetainedContinuationLane(core, id) {
     if (handle && handle.type === "background_agent")
         handle.retainedContinuation = true;
 }
+export function backgroundAgentCycleSeqLane(core, id) {
+    const handle = core.handles.get(id);
+    if (handle === undefined || handle.type !== "background_agent")
+        return undefined;
+    return handle.status === "parked" ? (handle.cycleSeq ?? 1) + 1 : handle.cycleSeq;
+}
 async function claimTerminalRowForRevive(core, store, handle, scope) {
     for (let attempt = 0; attempt < 3; attempt++) {
         let live;
@@ -972,6 +978,9 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
             return { ok: false, reason: "still_running" };
         }
         ensureDurableHeartbeatLane(core);
+        if (claim.status === "claimed" && typeof claim.row.seq === "number" && (handle.cycleSeq ?? 1) < claim.row.seq) {
+            handle.cycleSeq = claim.row.seq;
+        }
     }
     handle.status = "running";
     handle.channelState = "attaching";

package/dist/core/task-registry.d.ts

@@ -267,6 +267,9 @@ export declare class TaskRegistry {
         suggestion?: string;
     };
     markRetainedContinuation(id: string): void;
+    /** #258 — the row's current stop-cycle counter, read by the spawn lanes right after registering to
+     *  thread into the child's `RunInternals.cycleSeq`; see {@link backgroundAgentCycleSeqLane}. */
+    backgroundAgentCycleSeq(id: string): number | undefined;
     /** ASYNC (revive arbitration) — the durable half is a guarded ownership claim on the row (awaited before the
      *  in-memory flip), so this leg and a cross-process claim arbitrate in one domain instead of both
      *  believing they own the cycle. See {@link reviveBackgroundAgentLane}. */