@sema-agent/core 5.34.0 → 5.36.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 5.36.0 — 2026-08-15
+
+No BREAKING changes. Upgrade note: the system-prompt shape change resets provider prompt caches
+ONCE on upgrade — the point of the feature is that they stop resetting after that.
+
+### Added
+
+- Env-tail prefix stability (#254): the turn-dynamic git facts (branch line, working-tree line,
+  status snapshot) leave the system prompt for a value-keyed `git_status` turn frame. The system
+  prompt stays byte-stable across legs while the working tree moves, so provider prefix caches
+  survive leg/resume/fork boundaries (live-verified cache hits past the static-section watermark).
+  The frame re-sends only when its `(kind, hash)` changes; kind flips announce a tombstone once
+  ("may be stale" / "no longer a git repository"); recovery re-asserts loudly. Compaction re-asserts
+  the current frame beside the summary on all three landing paths (boundary / PTL recovery /
+  end-of-task, one single-source hook). Announcement mirrors are branch-authoritative with a
+  transcript-side newest-frame arbiter: the transcript is the truth, a mirror that cannot be audited
+  degrades to one conservative re-announcement.
+- Wire/durable additions for #254: `steering_injected.source` gains `git_status` (preview is a
+  CONSTANT phrase per frame kind — repo text never enters the event face); durable session entry
+  `git_announcement`, compaction `details.gitAnnouncement`, `CheckpointState.gitAnnouncement` (all
+  additive, no version bump — absent fields resume with one conservative re-announcement); `Session`
+  gains two OPTIONAL members (`appendGitAnnouncement`/`getGitAnnouncement`); event-registry row
+  `git_status`. Existing sessions record one `legacy_migration` pin on first resume (env probe
+  sentinel `probe-env@2`).
+- New `TaskResult.errorCode`: `irreducible_core_over_budget` — the request budget cannot fit even
+  the compaction summaries plus the DEGRADED git frame; the run fails loudly instead of shipping a
+  dishonest request. The frame has a trim-protected replace-by-key slot with exactly one
+  deterministic degrade shrink; H4 probe failures degrade to a two-line branch+dirty frame instead
+  of silently omitting the section; the probe sentinel mis-split arm is loud.
+- Fleet row generation out-line (#258): `task_progress` ticks and `BackgroundChildEvent` spawn/tick
+  frames from background-agent rows carry `seq` — the row's stop-cycle generation (fresh spawn = 1,
+  every launched revival bumps it), one axis with `TaskNotificationPayload.seq` — so a fleet
+  consumer can tell a LATE first frame from a REVIVED cycle's frame. BCE terminal frames fall back
+  to the registry generation when the notify-mirror carrier is absent (one run speaks one number;
+  the notification payload's design/144 seq contract is unchanged). Absence stays a fact: sync
+  children, workflow agents and top-level runs carry nothing — never read absence as "cycle 1".
+  Hardening shipped with it: a parked-born resume speaks ONE generation end to end (the consume
+  flip's target), a retained wake realigns forward past a foreign tier-3 cycle's durable advance,
+  and BCE ticks always stamp the ENCLOSING row's generation.
+
+### Changed
+
+- `buildEnvironmentContext` no longer renders gitBranch/gitDirty/gitSnapshot (fields remain as
+  data; the snapshot rides the `git_status` frame). Pre-call budget estimates now include the frame
+  bytes (an informed tightening). Frame bodies clamp astral-safe (U+FFFD at a split code point).
+- Merged-code rescan hardening (18 findings across two rounds, all verified then disposed): the
+  degraded-shrink replacement inserts via thunk (a branch named with `$&`/`$$` — legal ref bytes —
+  no longer expands match context into the frame or silently renames itself; same class swept to
+  `buildMemoryInstruction`); the irreducible core charges the frame segment + summaries only, and a
+  trim-dropped carrier is never resurrected — the guard re-inserts the frame SEGMENT as its own
+  engine-minted request-view message, so the trim's adjudication stands and the request stays
+  servable; the listing-replay scan strips positive git frames before parsing (a commit subject
+  spelling a roster header can no longer reset the announced set); the degraded frame joins the
+  request-lossy disclosure; old-checkpoint resume compat re-pinned honestly (one conservative
+  re-announcement); the PTL-recovery landing path gained real coverage.
+- `probeParkRoundTrip` JSDoc names its write side loudly (diagnostic probe, not a health-poll
+  body).
+
+## 5.35.0 — 2026-08-15
+
+No BREAKING changes. One deliberate fail-closed tighten and one loosening-direction fix are called
+out under Changed; everything else is additive.
+
+### Added
+
+- `TaskStream.steer` takes an optional `inputId` dedup key (additive; absent ⇒ byte-identical
+  behavior). The live steer leg becomes idempotent the way the parked leg already was: an identical
+  payload under a seen key is a no-op (nothing injected, no second ledger frame), a DIFFERENT payload
+  under a seen key is refused loudly (`steering.duplicate_input_id`, the parked leg's code), and the
+  caller's key rides the `human_input` frame verbatim (previously a fresh uuid was always minted, so
+  a replayed injection was indistinguishable from an idempotent hit in the receipt). Validation runs
+  before liveness (empty/overlong/reserved-sentinel values are refused, never silently treated as
+  "no key"). Dedup scope is the live stream's lifetime — narrower than the parked queue's persisted
+  window; the contract states the asymmetry rather than pretending parity.
+- `AskRequest.ruleEvidence` (design/252 G-2): an ask carries the rule-provenance evidence behind it —
+  the org snapshot `revision`, the org rule text, and the matched personal rule's add dots — each
+  member present as a value or as a NAMED absence (`not_wired` / `not_adjudicated` / `unavailable` /
+  `no_match` / `not_reported`), so "nothing governed this", "the source was unreadable" and "the lane
+  was skipped" stop sharing one wire shape.
+- Settlement approver attribution (design/252 G-7): both settlement lanes accept an optional
+  `approver` identity, screened (length/control-characters/lone-surrogates, refused not truncated)
+  and TRANSCRIBED — never adjudicated — onto the settled call's `tool_end` frame beside `settledBy`.
+- `probeParkRoundTrip` + `durableParkGapOf` (design/252 G-6): a park-lane liveness self-check (file a
+  synthetic checkpoint, read it back, enumerate, fence) plus the static two-halves reading that turns
+  a missing-session resume symptom into a named absent seat. `ParkSelfCheckResult.casLossObserved`
+  (additive) marks the one green arm a CAS-mis-reporting backend would pass through.
+
+### Changed
+
+- Fail-closed tighten: a `persistedRules.admits()` answer that is neither a string nor an object no
+  longer clears an ask. Previously any non-`undefined` answer cleared it — "`null` admits this call"
+  was an allow built on an unreadable answer.
+- The org-verdict normalizer reads ANY non-array carrier (class instances and callables included —
+  the structural contract admits them) with own-data field reads; refusing the carrier outright
+  could fold a structurally valid org DENY into `unavailable`, i.e. from un-approvable into a
+  real-approval ask a person could clear. Inherited members still never authorize; revoked proxies
+  are contained; foreign array methods (an overridden or species-substituted `.map`/`.filter`) no
+  longer run anywhere on the evidence path.
+- The park probe sweeps behind a late-committing timed-out `put` on either settle, and the
+  approver screen refuses oversized values before materializing a code-point array.
+- Dev-surface: the live-gate recipe and examples switch the reference live model to
+  `deepseek-v4-flash` (operator directive; prior cache/behavior figures quoted against
+  `deepseek-v4-pro` re-anchor on next measurement).
+
 ## 5.34.0 — 2026-08-15
 
 No BREAKING changes. Two behavior-surface additions (both additive seats), one packaging addition,

package/dist/agents/subagent.js

@@ -544,6 +544,11 @@ export function createSubagentResume(deps) {
                             : "resume unavailable: the agent's registry row no longer exists (terminal GC) — relaunch a new agent instead.", revived.reason === "still_running" ? "steering.still_running" : revived.reason === "recycling" ? "resume.row_recycling" : "resume.row_gone");
                 }
                 reviveCycle = revived.cycle;
+                if (deps.registry !== undefined && deps.taskId !== undefined) {
+                    const settledSeq = deps.registry.backgroundAgentCycleSeq(deps.taskId);
+                    if (settledSeq !== undefined && settledSeq > entry.cycleSeq)
+                        entry.cycleSeq = settledSeq;
+                }
                 if (deps.bgSink !== undefined) {
                     reviveEmit = (event) => {
                         try {
@@ -560,6 +565,7 @@ export function createSubagentResume(deps) {
                         ...(deps.rowScope !== undefined ? { scope: deps.rowScope } : {}),
                         description: `${deps.rowDescription ?? "sub-agent"} (resumed ${marker})`,
                         ...(deps.rowAgentType !== undefined ? { agentType: deps.rowAgentType } : {}),
+                        seq: entry.cycleSeq,
                         ...(deps.rowName !== undefined ? { name: deps.rowName } : {}),
                         sessionId: entry.childSessionId,
                         transcriptId: entry.childSessionId,
@@ -585,6 +591,7 @@ export function createSubagentResume(deps) {
                     transcriptId: entry.childSessionId,
                     sessionId: entry.childSessionId,
                     ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}),
+                    seq: entry.cycleSeq,
                     progressTaskId: entry.childSessionId,
                     ...(currentAction !== undefined ? { currentAction } : {}),
                     ...(currentTool !== undefined ? { currentTool } : {}),
@@ -593,6 +600,7 @@ export function createSubagentResume(deps) {
             }, deps.registry !== undefined && deps.taskId !== undefined ? () => deps.registry.noteBackgroundAgentActivity(deps.taskId) : undefined);
             stream = childRunner.runTaskStream(resumeSpec, undefined, {
                 ...entry.internalsSnapshot,
+                cycleSeq: entry.cycleSeq,
                 ...(true
                     ? {
                         onForwardEvent: (e) => {
@@ -612,6 +620,7 @@ export function createSubagentResume(deps) {
                                     sessionId: entry.childSessionId,
                                     transcriptId: entry.childSessionId,
                                     ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}),
+                                    seq: entry.cycleSeq,
                                     progressTaskId: e.taskId,
                                     ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                     ...(e.name !== undefined ? { name: e.name } : {}),
@@ -1955,6 +1964,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     bg.registry.attachAgentTerminalNotifier(taskId, () => {
                         const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
                         const completionIdReap = bg.registry.getCompletionId(taskId);
+                        const seqReap = bg.registry.backgroundAgentCycleSeq(taskId);
                         const summaryReap = ccCompletionText(shortDesc, "killed", "killed", Date.now() - forkBgHangAt);
                         sinkEmit({
                             kind: "terminal",
@@ -1964,6 +1974,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             transcriptId: forkedId,
                             parentToolCallId: ctx.toolCallId,
                             status: "killed",
+                            ...(seqReap !== undefined ? { seq: seqReap } : {}),
                             stoppedBy: stoppedByReap,
                             summary: summaryReap,
                             resumable: false,
@@ -1992,6 +2003,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         catch {
                         }
                     };
+                    const bgForkCycleSeq = bg.registry.backgroundAgentCycleSeq(taskId);
                     sinkEmit({
                         kind: "spawn",
                         taskId,
@@ -2000,6 +2012,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(bgScope !== undefined ? { scope: bgScope } : {}),
                         description: shortDesc,
                         agentType: spawnAgentType,
+                        ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                         ...(agentName !== undefined ? { name: agentName } : {}),
                         sessionId: forkedId,
                         transcriptId: forkedId,
@@ -2028,6 +2041,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             parentToolCallId: ctx.toolCallId,
                             progressTaskId: forkedId,
                             agentType: spawnAgentType,
+                            ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                             ...(currentAction !== undefined ? { currentAction } : {}),
                             ...(currentTool !== undefined ? { currentTool } : {}),
                             usage: { toolUses: toolStarts },
@@ -2039,6 +2053,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(forkQuestionStrip !== undefined ? forkQuestionStrip.internalsFlag : {}),
                             onNotifyInjectorReady: s2ForkNotifyReady,
                             delegationTaskType: "background_agent",
+                            ...(bgForkCycleSeq !== undefined ? { cycleSeq: bgForkCycleSeq } : {}),
                             onForwardEvent: (e) => {
                                 try {
                                     recordingForward(e, { bgAgentId: taskId });
@@ -2056,6 +2071,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                         sessionId: forkedId,
                                         transcriptId: forkedId,
                                         parentToolCallId: ctx.toolCallId,
+                                        ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                                         progressTaskId: e.taskId,
                                         ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                         agentType: spawnAgentType,
@@ -2072,6 +2088,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(forkQuestionStrip !== undefined ? forkQuestionStrip.internalsFlag : {}),
                             onNotifyInjectorReady: s2ForkNotifyReady,
                             delegationTaskType: "background_agent",
+                            ...(bgForkCycleSeq !== undefined ? { cycleSeq: bgForkCycleSeq } : {}),
                             onForwardEvent: (e) => {
                                 try {
                                     recordingForward(e, { bgAgentId: taskId });
@@ -2147,6 +2164,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 ...(stillbornFork ? {} : { transcriptId: forkTranscriptId }),
                                 parentToolCallId: ctx.toolCallId,
                                 status: settledBg,
+                                ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                                 ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                                 summary: forkTerminalSummary,
                                 ...residualFork,
@@ -2204,6 +2222,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 transcriptId: forkedId,
                                 parentToolCallId: ctx.toolCallId,
                                 status: settledBg,
+                                ...(bgForkCycleSeq !== undefined ? { seq: bgForkCycleSeq } : {}),
                                 ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                                 summary: summaryBg,
                                 ...(completionIdForkReject !== undefined ? { completionId: completionIdForkReject } : {}),
@@ -2420,9 +2439,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const bgStartedAt = Date.now();
                 stepRecorder.lockTo(bgChildSessionId);
                 bg.registry.bindBackgroundAgentSession(taskId, bgChildSessionId);
+                const bgCycleSeq = bg.registry.backgroundAgentCycleSeq(taskId);
                 bg.registry.attachAgentTerminalNotifier(taskId, () => {
                     const stoppedByReap = bg.registry.getStopAttribution(taskId) ?? "system";
                     const completionIdReap = bg.registry.getCompletionId(taskId);
+                    const seqReap = bg.registry.backgroundAgentCycleSeq(taskId);
                     const summaryReap = ccCompletionText(shortDesc, "killed", "killed", Date.now() - bgStartedAt);
                     sinkEmit({
                         kind: "terminal",
@@ -2432,6 +2453,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         transcriptId: bgChildSessionId,
                         parentToolCallId: ctx.toolCallId,
                         status: "killed",
+                        ...(seqReap !== undefined ? { seq: seqReap } : {}),
                         stoppedBy: stoppedByReap,
                         summary: summaryReap,
                         resumable: false,
@@ -2459,6 +2481,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(bgScope !== undefined ? { scope: bgScope } : {}),
                     description: reviveRow !== undefined ? `${shortDesc} (revived)` : shortDesc,
                     agentType: spawnAgentType,
+                    ...(bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                     ...(agentName !== undefined ? { name: agentName } : {}),
                     sessionId: bgChildSessionId,
                     transcriptId: bgChildSessionId,
@@ -2531,6 +2554,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         parentToolCallId: ctx.toolCallId,
                         progressTaskId: bgChildSessionId,
                         agentType: spawnAgentType,
+                        ...(bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                         ...(currentAction !== undefined ? { currentAction } : {}),
                         ...(currentTool !== undefined ? { currentTool } : {}),
                         usage: { toolUses: toolStarts },
@@ -2542,6 +2566,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
                         onNotifyInjectorReady: s2NotifyReady,
                         delegationTaskType: "background_agent",
+                        ...(bgCycleSeq !== undefined ? { cycleSeq: bgCycleSeq } : {}),
                         onForwardEvent: (e) => {
                             try {
                                 recordingForward(e, { bgAgentId: taskId });
@@ -2559,6 +2584,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     sessionId: bgChildSessionId,
                                     transcriptId: bgChildSessionId,
                                     parentToolCallId: ctx.toolCallId,
+                                    ...(bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                                     progressTaskId: e.taskId,
                                     ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                     agentType: spawnAgentType,
@@ -2575,6 +2601,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(bgQuestionStrip !== undefined ? bgQuestionStrip.internalsFlag : {}),
                         onNotifyInjectorReady: s2NotifyReady,
                         delegationTaskType: "background_agent",
+                        ...(bgCycleSeq !== undefined ? { cycleSeq: bgCycleSeq } : {}),
                         onForwardEvent: (e) => {
                             try {
                                 recordingForward(e, { bgAgentId: taskId });
@@ -2858,7 +2885,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(child.sessionId ? { sessionId: child.sessionId, transcriptId: child.sessionId } : {}),
                             parentToolCallId: ctx.toolCallId,
                             status: settled,
-                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
+                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                             ...(stoppedBy !== undefined ? { stoppedBy } : {}),
                             summary: bgTerminalSummary,
                             ...residual,
@@ -2948,7 +2975,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             transcriptId: bgChildSessionId,
                             parentToolCallId: ctx.toolCallId,
                             status: settled,
-                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
+                            ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : bgCycleSeq !== undefined ? { seq: bgCycleSeq } : {}),
                             ...(stoppedBy !== undefined ? { stoppedBy } : {}),
                             summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
                             ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),

package/dist/core/auto-compaction.d.ts

@@ -323,6 +323,29 @@ export interface MaybeCompactOptions {
         path: string;
         content: string;
     }>, preserveReadState?: ReadonlyArray<string>) => void;
+    /**
+     * env-tail migration — the git-status lane's compaction interaction (two-phase receipt). The git
+     * frame lives on the MESSAGE plane, does not enter the summary, and the projection strips it from
+     * serialized history — so a landed compaction would silently lose the model's git view while the
+     * announced hash keeps suppressing every re-send. When present:
+     *   - `pending` is restated on the compaction entry's `details.gitAnnouncement` with
+     *     `pending: true` in the SAME CAS as the new baseline (the promptEpoch/announcedListings
+     *     restatement posture) — any reader between the landing and the re-assert receipt sees an
+     *     OWED announcement, never a false "announced";
+     *   - `land()` is invoked immediately after the landed baseline, BEFORE any context rebuild or
+     *     retry (all three routes — turn-boundary auto, prompt-too-long recovery, end-of-task finish
+     *     — funnel through this one append): it re-appends the current frame and writes the
+     *     announced mirror once the append receipt is in hand. `land` contains its own failures (a
+     *     failed re-assert leaves the pending restatement authoritative — the next boundary/leg
+     *     re-announces); a throw here must never fail a LANDED compaction, so the call is belted.
+     */
+    gitRestate?: {
+        pending: {
+            kind: "full" | "degraded" | "unavailable" | "non-repo";
+            hash: string;
+        };
+        land: () => Promise<void>;
+    };
     /**
      * Fixed per-request prompt overhead (system prompt + tool schemas, in tokens), applied ONLY in the
      * anchor-less regime (design/64 §26.7, search [91] fourth candidate): when no assistant in the

package/dist/core/auto-compaction.js

@@ -446,7 +446,15 @@ export async function maybeCompact(opts) {
         promptEpoch: restatedEpoch,
         ...(restatedListings !== undefined ? { announcedListings: restatedListings } : {}),
         ...(opts.activeTools !== undefined && opts.activeTools.length > 0 ? { activeTools: [...opts.activeTools] } : {}),
+        ...(opts.gitRestate !== undefined ? { gitAnnouncement: { kind: opts.gitRestate.pending.kind, hash: opts.gitRestate.pending.hash, pending: true } } : {}),
     }, false);
+    if (opts.gitRestate !== undefined) {
+        try {
+            await opts.gitRestate.land();
+        }
+        catch {
+        }
+    }
     try {
         opts.onApplied?.(attachedComplete, excludedReadStatePreserveKeys);
     }

package/dist/core/checkpoint-store.d.ts

@@ -577,6 +577,31 @@ export type ResumeOutcome = {
      * with the backends and belongs to its own change, not to this one.
      */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    /**
+     * design/252 G-7 — WHOSE settlement: the identifier the approval channel reports for the party
+     * that ended this wait, transcribed onto the resolved call's `tool_end` frame beside
+     * {@link settledBy}.
+     *
+     * Core AUTHENTICATES NOTHING here. On the durable lane the identity work is entirely the
+     * deployment's — its approval card, its signature check, its operator console decide who this
+     * was; a library holding no identity surface has nothing to check the claim against and does not
+     * pretend otherwise. What core owns is that the claim is well-formed: a plain string, bounded,
+     * free of control characters, refused pre-CAS (`checkpoint.invalid_outcome`) otherwise, like
+     * every other out-of-domain field on this arm. Refused rather than dropped, because a settlement
+     * that silently lost its attributed party reads as unattributed — the misreport this seat exists
+     * to end.
+     *
+     * SCOPE — like {@link settledBy}, this rides the SETTLEMENT and not the persisted winner:
+     * `winnerFromOutcome` records what an `env_failed` replay must reproduce exactly, and who
+     * reported a settlement is not part of that authorization. A replay states its own attribution
+     * and is not held to the first one; binding it into the durable row would also make a re-supply
+     * that merely omits the field fail closed on the recovery path. Carrying it into the row is a
+     * store-shape change owned jointly with the backends and belongs to its own change.
+     *
+     * OPTIONAL and additive: absent means the caller named nobody, which is not the same as "nobody
+     * approved this" and must not be read as one.
+     */
+    approver?: string;
 }
 /** design/74: continue a resource-suspended run with the next slice's allowance. NO decision payload and
  *  NO budget figure — the allowance is computed from {@link Checkpoint.resourceLedger}, so money never
@@ -983,6 +1008,22 @@ export interface CheckpointState {
         skills?: string[];
         models?: string[];
     };
+    /**
+     * The git-status frame's announced `(kind, hash)` state at suspend (env-tail migration: the
+     * run-loop-maintained mirror, advanced at every frame receipt). The LOWEST rung of the resume
+     * read ladder — the session branch walk is the authority (a nearest PENDING mirror there, or an
+     * announced mirror whose frame entry is off the active branch, forces a re-announce regardless of
+     * this field); the checkpoint seeds only when the branch carries no mirror at all, and its
+     * `entryId` must itself sit on the active branch to count as announced. Schema ADDITION
+     * (additive, old readers ignore it — the Q5 posture): an older checkpoint without the field re-announces
+     * conservatively — the frame is a tail append, so a duplicate costs bytes, never a prefix break.
+     */
+    gitAnnouncement?: {
+        kind: "full" | "degraded" | "unavailable" | "non-repo";
+        hash: string;
+        entryId?: string;
+        pending?: true;
+    };
     /**
      * design/180 R-4 (R-2 cross-process variant) — the armed delegation child's MONOTONIC runtime-provenance
      * aggregate at suspend ({@link import("./memory-engine/delegation-provenance.js").DelegationProvenanceAggregate}:
@@ -1631,12 +1672,14 @@ export declare class CheckpointError extends Error {
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
      *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
      *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
-     *  of them, or omit the field). The throw
+     *  of them, or omit the field), or — design/252 G-7 — `"approver"` (the attribution is not a
+     *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
+     *  it). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
          *  damaged/caller-declared and no worker ever will" — blanket-retriable and gate-shape heuristics were
@@ -1752,12 +1795,14 @@ export declare class CheckpointError extends Error {
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
      *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
      *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
-     *  of them, or omit the field). The throw
+     *  of them, or omit the field), or — design/252 G-7 — `"approver"` (the attribution is not a
+     *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
+     *  it). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
          *  damaged/caller-declared and no worker ever will" — blanket-retriable and gate-shape heuristics were

package/dist/core/context-guard.d.ts

@@ -53,6 +53,47 @@ export declare function dropOrphanToolResults(messages: AgentMessage[]): {
         nextRole: string;
     }>;
 };
+/** R2-3 (falsification round 2) — does the message's ENGINE-AUTHORED region cover [start, start+len)?
+ *  The carrier scan must never crown a counterfeit: a tool result or a user paste can reproduce the
+ *  wrapped frame bytes verbatim, but only ENGINE metadata (engineMinted whole-message, the
+ *  enginePrefixChars head, or an engineSegments range) proves the engine put them there. */
+export declare function engineRegionCovers(m: AgentMessage, start: number, len: number): boolean;
+/** Outcome of {@link protectGitFrame} — `over_budget` means the irreducible core (summaries + the
+ *  protected frame carrier) exceeds the budget even after the one-shot degraded shrink: the caller
+ *  must fail the request LOUDLY (`irreducible_core_over_budget`) instead of pretending the trim
+ *  succeeded or looping compaction/re-assertion. */
+export type GitFrameGuardOutcome = {
+    messages: AgentMessage[];
+    action: "kept" | "absent" | "reinserted" | "shrunk";
+} | {
+    action: "over_budget";
+};
+/**
+ * env-tail migration — the git frame's UNCLIPPABLE-CORE protection over a trimmed request view.
+ * The frame's "value unchanged ⇒ never re-sent" contract makes a request-only drop uniquely
+ * dangerous for it: the commit receipt has already landed, so a trim that cuts the carrier makes
+ * the announced hash suppress every future re-send while the model never saw the frame. Rules:
+ *   - REPLACE-BY-KEY SLOT: exactly ONE carrier is protected — the newest message whose flat text CONTAINS
+ *     `protectedText` (the ENGINE-HELD wrapped frame segment; set at delivery/re-assert AND
+ *     re-seeded on value-unchanged legs, so the protection survives legs that send nothing).
+ *     Older frames trim like ordinary history.
+ *   - Re-insert a dropped carrier after the leading summaries/trim-notice (its original relative
+ *     position is always ≥ there — the carrier predates every kept tail message).
+ *   - IRREDUCIBLE-CORE arc: when the core (always-kept summaries + the carrier) alone exceeds the
+ *     budget, substitute the carrier's frame segment with the deterministic DEGRADED rendering —
+ *     exactly once per run (`alreadyShrunk` latch, request-view only; the run loop re-announces the
+ *     shrunk view through its own receipt machinery). Still over after the shrink ⇒ `over_budget`.
+ *   - A total overshoot whose core FITS is left alone (turn-alignment overshoot is a pre-existing,
+ *     tolerated trade — validity beats budget; this guard must not convert it into a failure).
+ */
+export declare function protectGitFrame(before: AgentMessage[], trimmed: AgentMessage[], budgetTokens: number, frame: {
+    protectedText: string;
+    substitute?: {
+        find: string;
+        replace: string;
+    };
+}, // protectedText = the wrapped frame SEGMENT (see the carrier scan below)
+charsPerToken?: number): GitFrameGuardOutcome;
 /** Budget the in-task guard targets for a model — CC-aligned headroom numbers with a 0.85
  *  small-window floor, sema-owned drop-oldest action (see {@link GUARD_HEADROOM_TOKENS}); always
  *  above the compaction/clearStale frontier. Dual-window semantics: deliberately the PHYSICAL

package/dist/core/context-guard.js

@@ -114,6 +114,82 @@ export function dropOrphanToolResults(messages) {
     }
     return { messages: out, dropped };
 }
+export function engineRegionCovers(m, start, len) {
+    const meta = m;
+    if (meta.engineMinted === true)
+        return true;
+    if (Array.isArray(meta.engineSegments))
+        return meta.engineSegments.some((seg) => seg.start <= start && start + len <= seg.end);
+    if (typeof meta.enginePrefixChars === "number")
+        return start + len <= meta.enginePrefixChars;
+    return false;
+}
+function singleText(m) {
+    const c = m.content;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c) && c.length === 1) {
+        const b = c[0];
+        if (b?.type === "text" && typeof b.text === "string")
+            return b.text;
+    }
+    return undefined;
+}
+export function protectGitFrame(before, trimmed, budgetTokens, frame, charsPerToken) {
+    const cpt = charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    let carrier;
+    for (let i = before.length - 1; i >= 0; i--) {
+        const candidate = before[i];
+        if (candidate === undefined || messageRole(candidate) !== "user")
+            continue;
+        const text = singleText(candidate);
+        if (text === undefined)
+            continue;
+        const at = text.indexOf(frame.protectedText);
+        if (at === -1 || !engineRegionCovers(candidate, at, frame.protectedText.length))
+            continue;
+        carrier = candidate;
+        break;
+    }
+    if (carrier === undefined)
+        return { messages: trimmed, action: "absent" };
+    let out = trimmed;
+    let action = "kept";
+    if (!out.includes(carrier)) {
+        carrier = { role: "user", content: [{ type: "text", text: frame.protectedText }], timestamp: carrier.timestamp ?? Date.now(), engineMinted: true };
+        let at = 0;
+        for (; at < out.length; at++) {
+            const head = out[at];
+            if (head === undefined || (!isSummary(head) && singleText(head) !== CONTEXT_TRIM_NOTICE))
+                break;
+        }
+        out = [...out.slice(0, at), carrier, ...out.slice(at)];
+        action = "reinserted";
+    }
+    const segTokens = (text) => estimateTokens({ role: "user", content: [{ type: "text", text }] }, cpt);
+    const coreTokens = (view, frameText) => {
+        let t = segTokens(frameText);
+        for (const m of view)
+            if (isSummary(m))
+                t += estimateTokens(m, cpt);
+        return t;
+    };
+    if (coreTokens(out, frame.protectedText) <= budgetTokens)
+        return { messages: out, action };
+    if (frame.substitute !== undefined) {
+        const text = singleText(carrier);
+        const shrunkText = text.replace(frame.substitute.find, () => frame.substitute.replace);
+        if (shrunkText !== text) {
+            const shrunkCarrier = { ...carrier, content: [{ type: "text", text: shrunkText }] };
+            const idx = out.indexOf(carrier);
+            out = [...out.slice(0, idx), shrunkCarrier, ...out.slice(idx + 1)];
+            if (coreTokens(out, frame.substitute.replace) <= budgetTokens)
+                return { messages: out, action: "shrunk" };
+            return { action: "over_budget" };
+        }
+    }
+    return { action: "over_budget" };
+}
 export function guardBudget(model) {
     const window = model.contextTokens ?? model.contextWindow;
     if (!Number.isFinite(window) || window <= 0) {