@sema-agent/core 5.35.0 → 5.36.0

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 },
@@ -2175,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 [];
                     });
                 }
@@ -2692,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"),
                         });
@@ -2762,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) {
@@ -2839,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" })),
@@ -2868,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 {
@@ -2900,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;
@@ -2937,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) {
@@ -2979,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() });
@@ -3004,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;
@@ -3033,6 +3290,7 @@ export class Runner {
             }
             notificationLaneLive = false;
             unsubscribeTaskNotifications();
+            unsubGitRetry();
             unsubBoundary();
             unsub();
         }
@@ -3176,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
@@ -3304,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 },
@@ -4316,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}. */

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);
     }

package/dist/core/types.d.ts

@@ -3647,9 +3647,15 @@ export type TaskEvent = ({
      * (one event per attachment; a multi-attachment boundary still coalesces into ONE steer message
      * on the model lane). [c209-C]: the listing family's FIRST-FRAME deliveries (initial roster /
      * `<skills>` block riding the first user message, not a steer) emit the same echo frames.
+     *
+     * `git_status` (env-tail migration, additive member): the git-status frame — the turn-dynamic
+     * git facts' carrier since they left the system prompt. Emitted at the frame's append RECEIPT
+     * (first-frame / resume-continuation / compaction re-assert deliveries alike). Its `preview`
+     * is a CONSTANT wording on purpose (never frame bytes): branch names and status text are
+     * repo-controlled and must not enter the event telemetry plane through this echo.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**
@@ -3790,6 +3796,18 @@ export type TaskEvent = ({
      * read absence as "not an agent".
      */
     taskType?: DelegationTaskType;
+    /**
+     * #258 — the registry row's STOP-CYCLE generation this tick reports from (fresh
+     * spawn = 1, every launched revival bumps it), the same counter `TaskNotificationPayload.seq`
+     * and `BackgroundChildEvent.seq` already speak — one axis, not a third spelling. It answers
+     * the one question a fleet consumer cannot otherwise decide when a frame arrives late: "late
+     * first frame of the cycle I know (same value), or a revived run I have not folded yet
+     * (higher value)?" Advisory observation, stamped at spawn/revive from the registry's own
+     * counter; the settle-time ledger stays the authority. ABSENT is a fact, not a gap: a run
+     * with no `a*` registry row (a SYNCHRONOUS delegated child, a workflow `wa*` agent, a
+     * top-level run) has no generation concept, and absence must never be read as "cycle 1".
+     */
+    seq?: number;
     /** [1611] workflow-lane self-identification (server field-proof: the SSE-forwarded tick of a
      *  WORKFLOW child previously carried a bare uuid with no workflow identity — indistinguishable
      *  from an unknown nested subagent; the fleet lane had `wa*`+workflowRunId but this lane had
@@ -4294,12 +4312,14 @@ export interface BackgroundChildEvent {
     resumable?: boolean;
     /** terminal: the settled status. */
     status?: "completed" | "killed" | "failed";
-    /** terminal (PAIR-REVIEW-01 C-3 half): the stop-cycle number — MIRROR of the sibling
-     *  task_notification's `TaskNotificationPayload.seq` (same settle, same X3 snapshot), so a
-     *  fleet-lane consumer can key multi-cycle events (`taskId:status[:seq]`) without the notify lane.
-     *  Same honest downgrade: present whenever a cycle number is knowable (the retain ledger's `cycleSeq`,
-     *  or the durable row's `seq` on a tier-3 revival / parked resume), absent when neither carrier exists
-     *  (single-cycle child; forging a period would lie). */
+    /** terminal + spawn/tick (#258 widened the carriers): the stop-cycle number — on a TERMINAL frame
+     *  a MIRROR of the sibling task_notification's `TaskNotificationPayload.seq` (same settle, same X3
+     *  snapshot); on SPAWN and TICK frames the registry row's generation at emit (fresh spawn = 1, a
+     *  revived cycle's bumped counter), so a fleet consumer can tell a LATE first frame from a revived
+     *  cycle's frame without waiting for the terminal. One axis with `task_progress`'s `seq` — the tick
+     *  mirrors the frame's own stamp. Same honest downgrade as ever: present whenever a cycle number is
+     *  knowable (the registry handle / retain ledger's `cycleSeq`, the durable row's `seq` on a tier-3
+     *  revival / parked resume), absent when no carrier exists (forging a period would lie). */
     seq?: number;
     /** terminal, P1-3(黑板 [1920]/[1921]/[1924]/[1925]): the cross-channel completion correlation id —
      *  MIRROR of the sibling task_notification's `TaskNotificationPayload.completionId` (same settle,

package/dist/engine/harness/types.d.ts

@@ -498,6 +498,53 @@ export interface WorkspaceState {
 export interface WorkspaceStateEntry extends SessionTreeEntryBase, WorkspaceState {
     type: "workspace_state";
 }
+/** The closed kind set of a git-status announcement (the availability half of the `(kind, hash)`
+ *  comparison tuple): `full` = five-segment snapshot frame; `degraded` = branch+dirty two-line frame
+ *  (the snapshot round-trip failed while the basic probe succeeded); `unavailable` / `non-repo` =
+ *  tombstone frames announcing that earlier git frames no longer describe the tree. */
+export type GitAnnouncementKind = "full" | "degraded" | "unavailable" | "non-repo";
+/**
+ * The git-status frame ANNOUNCED STATE — which rendered git view the model has last been shown on
+ * this branch, as a `(kind, hash)` tuple (hash = content hash of the rendered frame body with the
+ * frame format version and the canonical repo root bound into the digest domain). Two-phase receipt
+ * protocol: `pending: true` = a re-announcement is OWED but its frame append has not produced a
+ * receipt (a compaction restates the tuple as pending in the same CAS that lands the summary; the
+ * announced form is written only once the frame's own append returned an entry id) — any reader
+ * that finds pending nearest MUST conservatively re-announce. `entryId` = the session entry of the
+ * message CARRYING the announced frame; an announced state whose entryId is not on the active
+ * branch (rewind cut it) is treated as pending by the read walk (branch-authority read ladder).
+ */
+export interface GitAnnouncementState {
+    kind: GitAnnouncementKind;
+    hash: string;
+    /** Session entry id of the message carrying the announced frame (absent on a pending restatement). */
+    entryId?: string;
+    /** Two-phase receipt: the tuple is owed but its frame append has no receipt yet. */
+    pending?: true;
+}
+/**
+ * The git-status announced state as a FIRST-CLASS typed entry (same snapshot doctrine as
+ * {@link AnnouncedListingEntry}): the nearest carrier on the branch IS the announced state.
+ * Written at every frame COMMIT point (first-frame receipt / resume-continuation receipt /
+ * compaction re-assertion receipt); a compaction additionally restates the tuple as `pending`
+ * inside its own `details.gitAnnouncement` (same-CAS with the new baseline) until the re-asserted
+ * frame's append receipt lands. The checkpoint mirror (`CheckpointState.gitAnnouncement`) is the
+ * lower seed rung, consulted only when the branch carries no mirror at all.
+ */
+export interface GitAnnouncementEntry extends SessionTreeEntryBase, GitAnnouncementState {
+    type: "git_announcement";
+}
+/** Bounded cap for {@link normalizeGitAnnouncement} entry ids (self-generated ids are short; an
+ *  oversize value is a forgery signal, same posture as the sibling caps). */
+export declare const GIT_ANNOUNCEMENT_MAX_ENTRY_ID_CHARS = 256;
+/**
+ * Strict shape gate for the git announced state — the SINGLE normalization the read walk, the
+ * public append, and the import-validate door all use (the {@link normalizeAnnouncedListing}
+ * posture). Returns a shaped copy carrying ONLY the known keys, or undefined when the value is not
+ * structurally valid: closed kind set, full `sha256:<hex64>` hash grammar (a prefix-only check
+ * would accept junk), bounded entryId, `pending` only as literal `true`.
+ */
+export declare function normalizeGitAnnouncement(v: unknown): GitAnnouncementState | undefined;
 /** Bounded cap for {@link normalizeWorkspaceState} paths (a sha is capped by its hex shape check). */
 export declare const WORKSPACE_STATE_MAX_PATH_CHARS = 4096;
 /**
@@ -544,7 +591,7 @@ export declare function normalizeAnnouncedListing(v: unknown): {
     models?: string[];
 } | undefined;
 /** All persisted session tree entry variants. */
-export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | WorkspaceStateEntry;
+export type SessionTreeEntry = MessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | LeafEntry | PromptEpochEntry | AnnouncedListingEntry | GitAnnouncementEntry | WorkspaceStateEntry;
 export interface SessionContext {
     messages: AgentMessage[];
     thinkingLevel: string;
@@ -684,6 +731,23 @@ export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
      *  epoch restatement) calls it with `?.()` — an implementer without it degrades to the pre-epoch
      *  path (no restatement), never a crash. */
     getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
+    /** Persist the git-status announced state as a first-class {@link GitAnnouncementEntry}
+     *  (snapshot semantics; see `Session.appendGitAnnouncement`). OPTIONAL on the interface — same
+     *  external-implementer posture as `getPromptEpoch`; consumers call it with `?.()` and an
+     *  implementer without it degrades to conservative re-announcement every leg (duplicate-tolerant
+     *  by design), never a crash. */
+    appendGitAnnouncement?(state: GitAnnouncementState): Promise<string>;
+    /** Branch-authority read of the git announced state (see `Session.getGitAnnouncement`): nearest
+     *  carrier on the active branch, with a pending restatement — or an announced state whose frame
+     *  entryId is NOT on the active branch — surfaced as `status:"pending"` (the reader must
+     *  conservatively re-announce). Undefined ⇒ no carrier visible on this branch. OPTIONAL, same
+     *  posture as `appendGitAnnouncement`. */
+    getGitAnnouncement?(): Promise<{
+        kind: GitAnnouncementKind;
+        hash: string;
+        status: "announced" | "pending";
+        entryId?: string;
+    } | undefined>;
 }
 export interface SessionCreateOptions {
     id?: string;