@sema-agent/core 5.35.0 → 5.37.0

package/dist/core/runner/prepare-task.js

@@ -56,7 +56,8 @@ import { limitConfigError, prepareConfigDoors } from "./prepare-config-doors.js"
 import { NAMESPACED_NAME_SHAPES, prepareSafetyScan } from "./prepare-safety-scan.js";
 import { prepareAcquireReconcile } from "./prepare-acquire-reconcile.js";
 import { prepareWorkspaceRestore, rebaseWorkspacePath, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
-import { defaultPromptProvider, buildEnvironmentContext, buildGitSnapshot, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { defaultPromptProvider, buildEnvironmentContext, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
+import { applyGitFrameGuard, probeGitStatusLane } from "./git-status-frame.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
 import { auditToolCollisions, getToolContract, projectToolManifest } from "../../prompt-assembly/tool-catalog.js";
 import { resolveEpochAgainstBundled } from "../../prompt-assembly/epoch.js";
@@ -1554,7 +1555,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const memoryPairExcludedName = MEMORY_ENGINE_TOOL_NAMES.find((n) => (toolFaceSnapshot.exclude ?? []).includes(n));
         const memoryPairOccupiedName = MEMORY_ENGINE_TOOL_NAMES.find((n) => memoryPairNameDomain.has(n));
         const memorySearchToolsPlanned = memoryPairExcludedName === undefined && memoryPairOccupiedName === undefined;
-        const { memoryEngineSession, memoryBlock: memoryBlockFromEngine, memoryTools, seedFiles: memorySeedFiles, admittedOrgScopes: memoryAdmittedOrgScopes, ownOrgVerdict: memoryOwnOrgVerdict, } = await prepareMemory({
+        const { memoryEngineSession, memoryBlock: memoryBlockFromEngine, memoryTools, seedFiles: memorySeedFiles, admittedOrgScopes: memoryAdmittedOrgScopes, ownOrgVerdict: memoryOwnOrgVerdict, effectiveMemoryScopes: memoryEffectiveScopes, } = await prepareMemory({
             spec,
             deps,
             sessionId,
@@ -1875,38 +1876,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
             catch {
             }
-            if (envFacts.isGitRepo === true) {
-                const SEP = "@@SEMA_ENV_GIT_SPLIT@@";
-                try {
-                    const snap = await executionEnv.exec(`(m=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null); m=\${m#origin/}; for s in "$m" main master; do if [ -n "$s" ] && git show-ref --verify --quiet "refs/remotes/origin/$s"; then echo "$s"; break; fi; done) || true; echo "${SEP}"; (git config user.name 2>/dev/null || true); echo "${SEP}"; gs=$(git --no-optional-locks status --short) || exit 41; printf '%s\\n' "$gs"; echo "${SEP}"; gl=$(git --no-optional-locks log --oneline -n 5) || exit 42; printf '%s\\n' "$gl"`, { cwd: envFacts.cwd, timeout: 10 });
-                    if (snap.ok && snap.value.exitCode === 0) {
-                        const parts = snap.value.stdout.split(`${SEP}\n`);
-                        if (parts.length === 4) {
-                            envFacts.gitSnapshot = buildGitSnapshot({
-                                branch: envFacts.gitBranch ?? "HEAD",
-                                mainBranch: parts[0].trim() || "main",
-                                ...(parts[1].trim() ? { userName: parts[1].trim() } : {}),
-                                status: parts[2],
-                                log: parts[3],
-                            });
-                        }
-                    }
-                    else {
-                        const reason = snap.ok
-                            ? snap.value.exitCode === 41
-                                ? "git status failed (exit 41)"
-                                : snap.value.exitCode === 42
-                                    ? "git log failed (exit 42)"
-                                    : `git exited ${snap.value.exitCode}`
-                            : `exec failed: ${snap.error.message}`;
-                        deps.onError?.(new Error(`env git snapshot skipped — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
-                    }
-                }
-                catch (err) {
-                    deps.onError?.(new Error(`env git snapshot skipped — ${err instanceof Error ? err.message : String(err)}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
-                }
-            }
         }
+        const gitStatusRef = await probeGitStatusLane({
+            executionEnv,
+            envFacts,
+            handsEnabled,
+            taskRoot: taskRootFinal,
+            onDegrade: (reason) => deps.onError?.(new Error(`env git snapshot degraded — ${reason}`), { phase: "degraded", sessionId, classification: "env-git-snapshot" }),
+        });
         if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
             const excluded = new Set(toolFaceSnapshot.exclude);
             for (let i = tools.length - 1; i >= 0; i--)
@@ -3577,6 +3554,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         ...(announcedListingsRef.models !== undefined ? { models: [...announcedListingsRef.models] } : {}),
                     }
                     : undefined,
+                gitAnnouncement: gitStatusRef.announced !== undefined ? { ...gitStatusRef.announced } : undefined,
                 delegationProvenance: internals?.delegationProvenance !== undefined ? { ...internals.delegationProvenance.ref.current } : undefined,
             });
             const commitSuspendSaga = async (token, cp, remoteEnv, remoteHandle) => {
@@ -4388,6 +4366,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ts: Date.now(),
                 }));
             }
+            trimmed = applyGitFrameGuard({
+                before: edited,
+                trimmed,
+                budgetTokens: guardAt,
+                ref: gitStatusRef,
+                charsPerToken,
+                onDegrade: (message) => {
+                    try {
+                        deps.onError?.(new Error(message), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                    }
+                    catch {
+                    }
+                },
+            });
             const swept = dropOrphanToolResults(trimmed);
             if (swept.dropped.length > 0) {
                 try {
@@ -4404,7 +4396,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     mediaCapped !== capped ||
                     edited !== mediaCapped ||
                     trimDroppedMessages ||
-                    swept.dropped.length > 0;
+                    swept.dropped.length > 0 ||
+                    gitStatusRef.overBudgetShrunk === true;
             return { messages: swept.messages };
         });
         const cacheBreakDetector = deps.cacheBreakDetection === false ? undefined : new CacheBreakDetector();
@@ -4593,7 +4586,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const effectiveReadFaceObserved = carrierReadFace();
         const effectiveReadDenyObserved = readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized.map((e) => ({ ...e })) : undefined;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -3,6 +3,8 @@ 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, 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";
@@ -868,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),
             });
@@ -996,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({
@@ -1040,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)
@@ -1261,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 },
@@ -1552,6 +1659,7 @@ export class Runner {
                 errorMessage: err instanceof Error ? err.message : String(err),
                 errorCode: code,
                 ...(remoteEnvFailure !== undefined ? { remoteEnvFailures: remoteEnvFailure } : {}),
+                ...(taskIdRef.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: taskIdRef.effectiveMemoryScopes } : {}),
                 ...(() => {
                     const hinted = err.retryAfterMs;
                     return code === "memory.admission_required" && typeof hinted === "number" && Number.isFinite(hinted) && hinted > 0
@@ -1922,6 +2030,8 @@ export class Runner {
         }, this);
         notificationHarness = prepared.harness;
         notificationSessionId = prepared.sessionId;
+        if (taskIdRef)
+            taskIdRef.effectiveMemoryScopes = prepared.effectiveMemoryScopes;
         const runSourceTaskId = spec.taskId ?? prepared.sessionId;
         const parentToolCallId = internals?.parentToolCallId;
         const ident = () => parentToolCallId !== undefined ? { eventId: uuidv7(), parentToolCallId, sourceTaskId: runSourceTaskId } : { eventId: uuidv7() };
@@ -2175,12 +2285,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 [];
                     });
                 }
@@ -2692,6 +2802,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"),
                         });
@@ -2762,6 +2873,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) {
@@ -2839,6 +3024,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" })),
@@ -2868,7 +3072,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 {
@@ -2900,6 +3120,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;
@@ -2937,17 +3178,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) {
@@ -2979,6 +3221,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() });
@@ -3004,6 +3261,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;
@@ -3033,6 +3293,7 @@ export class Runner {
             }
             notificationLaneLive = false;
             unsubscribeTaskNotifications();
+            unsubGitRetry();
             unsubBoundary();
             unsub();
         }
@@ -3168,6 +3429,7 @@ export class Runner {
                 remoteEnvFailures: prepared.remoteEnvFailures,
                 effectiveReadFace: prepared.effectiveReadFace,
                 effectiveReadDenyPatterns: prepared.effectiveReadDenyPatterns,
+                effectiveMemoryScopes: prepared.effectiveMemoryScopes,
                 retryAfterMs: rs.limits.platformTerminal?.retryAfterMs,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
@@ -3176,6 +3438,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
@@ -3304,6 +3567,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 },
@@ -4316,6 +4580,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}. */

package/dist/core/task-registry.js

@@ -10,7 +10,7 @@ import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
-import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
+import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
@@ -191,6 +191,9 @@ export class TaskRegistry {
     markRetainedContinuation(id) {
         return markRetainedContinuationLane(this.core, id);
     }
+    backgroundAgentCycleSeq(id) {
+        return backgroundAgentCycleSeqLane(this.core, id);
+    }
     reviveBackgroundAgent(id, access, abort) {
         return reviveBackgroundAgentLane(this.core, id, access, abort);
     }