@sema-agent/server 7.126.0 → 7.127.1

package/dist/http/routes/runs.js

@@ -1,3 +1,4 @@
+import { liveToolEndForBacklog } from "../../trace/tool-output-media.js";
 import { redactHead, redactLedgerEventForRead } from "../../observability/run-terminal.js";
 import { z } from "zod";
 import { uuidv7, mintCheckpointToken, CheckpointError, policyCannotAnswer, validatePendingSteer, TASK_OUTPUT_REPLAY_KINDS, isSystemInjectionPriority } from "@sema-agent/core";
@@ -33,6 +34,7 @@ import { readResumeCtx } from "../resume-ctx-read.js";
 import { storedBodyReplayAnswer, storedBodyReplayLogFields } from "../checkpoint-ctx.js";
 import { serviceVersion } from "../../service-version.js";
 import { storedBodyReplayRefusal } from "../stored-body-replay.js";
+import { steerBodyKeyIssue } from "../../request-key-closure.js";
 const STEER_PRIORITY_WORDS = INJECTION_TIERS.map((tier) => `'${tier}'`);
 const STEER_PRIORITY_UNION = STEER_PRIORITY_WORDS.join(" | ");
 const STEER_PRIORITY_CHOICES = STEER_PRIORITY_WORDS.length <= 2 ? STEER_PRIORITY_WORDS.join(" or ") : `${STEER_PRIORITY_WORDS.slice(0, -1).join(", ")}, or ${STEER_PRIORITY_WORDS[STEER_PRIORITY_WORDS.length - 1]}`;
@@ -413,6 +415,13 @@ export async function handleRuns(req, res, match, ctx) {
             sendError(res, 400, "request.body_shape", `body must be { text: string (non-empty), mode?: 'all' | 'one-at-a-time', priority?: ${STEER_PRIORITY_UNION} }`);
             return;
         }
+        {
+            const keyIssue = steerBodyKeyIssue(body, "run");
+            if (keyIssue) {
+                sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
+                return;
+            }
+        }
         if (body.mode !== undefined && body.mode !== "all" && body.mode !== "one-at-a-time") {
             sendError(res, 400, "request.field_invalid", "mode must be 'all' or 'one-at-a-time' when present");
             return;
@@ -737,6 +746,11 @@ export async function handleRuns(req, res, match, ctx) {
                 return;
             }
             text = interruptBody.text;
+            const keyIssue = steerBodyKeyIssue(interruptBody, "interrupt");
+            if (keyIssue) {
+                sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
+                return;
+            }
         }
         const interruptIdemRaw = headerStr(req.headers["idempotency-key"]);
         const interruptInputId = interruptIdemRaw ? `idem-${idemKeyOf(interruptIdemRaw, idemCallerOf(req, ctx), "run").slice(0, 32)}` : uuidv7();
@@ -1040,7 +1054,8 @@ export async function handleRunVerbs(req, res, match, ctx) {
                 const n = await it.next();
                 if (n.done || closed || res.writableEnded)
                     break;
-                res.write(`event: forward\ndata: ${JSON.stringify(n.value)}\n\n`);
+                const frame = n.value.type === "tool_end" ? liveToolEndForBacklog(n.value, res.writableLength) : n.value;
+                res.write(`event: forward\ndata: ${JSON.stringify(frame)}\n\n`);
                 if (n.value.type === "task_settled")
                     break;
             }
@@ -1161,6 +1176,13 @@ export async function handleRunVerbs(req, res, match, ctx) {
             sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
             return;
         }
+        {
+            const keyIssue = steerBodyKeyIssue(body, "content");
+            if (keyIssue) {
+                sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
+                return;
+            }
+        }
         if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
             sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
             return;

package/dist/http/routes/tasks.js

@@ -13,7 +13,8 @@ import { clearTurnActivity, readTurnActivityMs, recordTurnActivity } from "../..
 import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "../../run-cancel-context.js";
 import { recordResourceWindow } from "../../resource-window.js";
 import { redactSecrets } from "../../trace/redact.js";
-import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, textEndEventData, liveIdentityFields } from "../../trace/project.js";
+import { liveToolEndForBacklog } from "../../trace/tool-output-media.js";
+import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, textEndEventData, liveIdentityFields } from "../../trace/project.js";
 import { cascadeConfig, runMeta } from "../run-meta.js";
 import { idemCallerOf, inflightKeyOf, submissionIdemOf } from "../idempotency.js";
 import { replayOfExistingRun } from "../submit-replay.js";
@@ -37,7 +38,8 @@ const DISCONNECT_PARK_GRACE_MS = 10_000;
 function sseData(res, payload) {
     const anchor = payload.eventId;
     const idLine = typeof anchor === "string" && anchor.length > 0 ? `id: ${anchor}\n` : "";
-    res.write(`${idLine}data: ${JSON.stringify(payload)}\n\n`);
+    const frame = payload.type === "tool_end" ? liveToolEndForBacklog(payload, res.writableLength) : payload;
+    res.write(`${idLine}data: ${JSON.stringify(frame)}\n\n`);
 }
 async function mintSubmitExitResult(result, checkpoints) {
     return redactTerminalResult(sealResultForExit(await graftParkToolCallId(result, checkpoints)));
@@ -263,8 +265,6 @@ export async function handleTasks(req, res, match, ctx) {
                         clearTurnActivity(tid);
                     if (created.ok)
                         recordResourceWindow(tid, prepared.spec.resourceSuspend);
-                    if (created.ok)
-                        deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id);
                     if (created.existing) {
                         const replay = await replayOfExistingRun(created.existing, { principal: submitter, idem }, "sync", deps, deps.runStore);
                         sseData(res, { type: "done", result: doneResultOfOutcome(replay), replay: true });
@@ -390,6 +390,9 @@ export async function handleTasks(req, res, match, ctx) {
                                     if (t === "task_progress") {
                                         sseData(res, { type: "task_progress", ...taskProgressEventData(e) });
                                     }
+                                    else if (t === "task_started") {
+                                        sseData(res, { type: "task_started", ...taskStartedEventData(e) });
+                                    }
                                     else if (t === "tool_start") {
                                         const tsv = e;
                                         sseData(res, { type: "tool_start", ...toolStartEventData(tsv) });
@@ -458,6 +461,7 @@ export async function handleTasks(req, res, match, ctx) {
                                     userMsgEntryId = ev.entryId;
                                 const causeAtDone = ev.type === "done" ? ac.cause() : undefined;
                                 await deps.userInputLedger?.observeLegEvent(liveStream, ev);
+                                prepared.acceptance.observe(ev);
                                 if (ev.type === "done") {
                                     finalResult = await mintSubmitExitResult(ev.result, deps.checkpointStore);
                                     if (durableTaskId && finalResult)
@@ -465,7 +469,7 @@ export async function handleTasks(req, res, match, ctx) {
                                     if (causeAtDone !== undefined && finalResult !== undefined) {
                                         finalResult = mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId ?? "", startedAtMs: streamLegStartedAt, message: "cancelled by user", cause: causeAtDone, engineResult: finalResult });
                                     }
-                                    finalizeTaskResult(ev.result, principal, prepared.spec.objective, prepared.spec.sessionId);
+                                    finalizeTaskResult(ev.result, principal, prepared.spec.objective);
                                     noteRunOutcome(finalResult);
                                     putRewindAnchor();
                                     settleFleet(outwardPlane(finalResult.terminal).status, fleetRunResiduals(finalResult));
@@ -517,6 +521,9 @@ export async function handleTasks(req, res, match, ctx) {
                                 else if (ev.type === "task_progress") {
                                     sseData(res, { type: "task_progress", ...taskProgressEventData(ev) });
                                 }
+                                else if (ev.type === "task_started") {
+                                    sseData(res, { type: "task_started", ...taskStartedEventData(ev) });
+                                }
                                 else if (ev.type === "compacted") {
                                     sseData(res, { type: "compacted", ...compactedEventData(ev) });
                                 }
@@ -843,7 +850,6 @@ export async function handleTasks(req, res, match, ctx) {
                     const placementReject = await commitPlacement(deps, deps.runStore, tid, prepared.bindingIntent);
                     if (placementReject)
                         return { status: placementReject.status, body: devicePlacementErrorBody(placementReject) };
-                    deps.sessionTitler?.maybeTitle(prepared.spec.sessionId, prepared.spec.objective, typeof prepared.spec.model === "string" ? prepared.spec.model : prepared.spec.model?.id);
                     durableTaskId = tid;
                 }
                 commitSessionInheritEnv(deps, prepared.spec.sessionId, prepared.body);
@@ -886,8 +892,10 @@ export async function handleTasks(req, res, match, ctx) {
                     const cascadeLeg = () => runCascade(prepared.runner, specWithSignal, cascadeConfig(deps.config.cascadeLadder, prepared.spec.limits?.maxCostUsd));
                     const plainLeg = async () => {
                         const stream = prepared.runner.runTaskStream(specWithSignal);
-                        for await (const ev of stream)
+                        for await (const ev of stream) {
                             observeSyncLegEvent(ev);
+                            prepared.acceptance.observe(ev);
+                        }
                         return stream.result();
                     };
                     result = await instructionLeg.run(prepared.spec.sessionId, () => withPrincipal(principal, () => prepared.verify ? verifyLeg(prepared.verify) : prepared.cascade ? cascadeLeg() : plainLeg()));
@@ -934,7 +942,8 @@ export async function handleTasks(req, res, match, ctx) {
                 }
                 if (durableTaskId && deps.runStore)
                     await deps.runStore.setTerminal(durableTaskId, syncPlane.status, exitResult, syncPlane.errorMessage ?? null);
-                finalizeTaskResult(result, principal, prepared.spec.objective, prepared.spec.sessionId);
+                prepared.acceptance.settle(result);
+                finalizeTaskResult(result, principal, prepared.spec.objective);
                 noteRunOutcome(result);
                 return { status: 200, body: withSyncSubmitKeys(buildSyncSubmitBody(exitResult)) };
             };

package/dist/http/routes/workflows.js

@@ -13,6 +13,7 @@ import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
+import { steerBodyKeyIssue } from "../../request-key-closure.js";
 export async function handleWorkflows(req, res, match, ctx) {
     const { deps } = ctx;
     const { runSessionAcceptOk } = ctx.helpers;
@@ -188,6 +189,13 @@ export async function handleWorkflowAgentSteer(req, res, match, ctx) {
             sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
             return;
         }
+        {
+            const keyIssue = steerBodyKeyIssue(body, "content");
+            if (keyIssue) {
+                sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
+                return;
+            }
+        }
         if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
             sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
             return;

package/dist/http/server.js

@@ -5,7 +5,6 @@ import { validatePendingSteer } from "@sema-agent/core";
 import {} from "../web-admin-client/facade.js";
 import { HttpError } from "../security.js";
 import {} from "../memory-sync.js";
-import { evictIfConflict } from "../runs.js";
 import {} from "../orchestration/workflow-agent-steer.js";
 import {} from "../orchestration/workflow-completion-inbox.js";
 import {} from "../fleet/fleet-bus.js";
@@ -162,10 +161,9 @@ export function createHttpServer(rawDeps) {
             deps.metrics?.inc("cascade_total", { outcome: cascadeOutcome });
         deps.instrumentDegenerate?.(result);
     }
-    function finalizeTaskResult(result, principal, objective, sessionId) {
+    function finalizeTaskResult(result, principal, objective) {
         recordTaskResult(result);
         deps.planCacheProbe?.record(principal, objective, result.terminal.kind === "completed");
-        evictIfConflict(deps.runner, sessionId, result);
     }
     const isRunLiveOnThisReplica = (taskId) => inflightRuns.has(taskId) || steerableRuns.has(taskId);
     return Object.assign(server, { denyExpiredApprovals, isRunLiveOnThisReplica, redeemParkedAsk });

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { composeExecutionLane, assertExecutionLaneInvariants, type ExecutionLane
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
 export { createStoreBackend, type StoreBackend, type SessionCaptureRecordSource } from "./plugins/store-backend.js";
+export { RetiredSchemaPresentError } from "./plugins/one-time-migrations.js";
 export { CachingSessionStore, type CachingOptions } from "./plugins/caching-session-store.js";
 export type { RunRecord, RunEvent } from "./plugins/store-contracts.js";
 export { runInBackground } from "./runs.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { composeExecutionLane, assertExecutionLaneInvariants } from "./boot/exec
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
 export { createStoreBackend } from "./plugins/store-backend.js";
+export { RetiredSchemaPresentError } from "./plugins/one-time-migrations.js";
 export { CachingSessionStore } from "./plugins/caching-session-store.js";
 export { runInBackground } from "./runs.js";
 export { createHardenedVmRunner, runInHardenedVm } from "./orchestration/hardened-vm-runner.js";

package/dist/lsp/manager.js

@@ -79,7 +79,7 @@ export class E2bLspManager {
                 return undefined;
             }
             if (heal)
-                await session.warmOpen(heal.carry).catch(() => ({ opened: 0, failed: heal.carry.length }));
+                await session.warmOpen(heal.carry).catch(() => ({ opened: 0, failed: heal.carry.length, deferred: 0 }));
             if (sessions.get(language) !== job) {
                 await session.close().catch(() => undefined);
                 return undefined;

package/dist/observability/fail-open.d.ts

@@ -35,6 +35,18 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-297(`http/routes/sessions.ts lastLegMcpFor`,`/mcp` 面板的可选键 `lastLegMcp`):按会话取最近 run 的索引读 / 那条 run 的账本读**抛错或超期** ⇒ 该键缺席,面板本体照常 200。放行的最坏后果=这一屏少一格「上一次真挂上了什么」(壳退回翻账本),不是门、不是权限、不是凭证 —— 而反方向(让附加键的读失败打掉整张面板)会给一口此前零 MCP 配置下根本不碰账本的**既有**读面新加一条挂掉的理由。缺席本就是本键 wire 上的一等状态(消费端必须会读),所以这条兜底不产生任何新的消费端形态;计数让「某台部署的账本一直读不出来」显形。";
     };
+    readonly "server.ledger.forward-append-failed": {
+        readonly cls: "F";
+        readonly note: "durable 腿 forward 道的写失败(`trace/ledger-sink.ts` 的 `createForwardAppendFailedNote`:账本汇 `onForwardEvent` —— bg 腿、sync detach 车道、续跑腿 verify 臂 —— 与续跑腿自己的 forward 回调同一只出口)。forward 道是同步回调里的 fire-and-forget 写(序号同步分配,结构上不能 await),写失败 ⇒ 这一帧(子代的 `task_started` / `task_progress` / 工具卡)永远不在 `GET /v1/runs/:id/events` 的回放面,run 照跑。放行的最坏后果 = 回放面少一帧子代事实(起跑帧每周期一只,丢了就补不回 `agentType` / `rootSessionId` / `startedAt`),不是门、不是凭据、不改任何裁决;不重试 —— 晚到的重试行会落在读方游标之后(单写串行链存在的理由)。计数非零 = 这台部署的账本写口在出错(主流的 awaited 写多半同时在报错),去看库。detail = `type=<帧型> err=<原句,经记录器脱敏>`。";
+    };
+    readonly "server.tool-end-media.live-backlog-degraded": {
+        readonly cls: "F";
+        readonly note: "core 7.50.0 媒体块提货(`trace/tool-output-media.ts` 的 `liveToolEndForBacklog`,三处活面写口共用的那一只判据 —— 同步流出口 `sseData`、子代 tail 路由写环、tail 总线每订阅者队列):本帧媒体字节 + 这条连接 / 这个订阅者还没送出去的字节 > 上界(64 MiB)⇒ 本帧媒体块降成持久面那只描述符(`{ type, mimeType?, bytes, truncated: true }`,帧级 `truncated` + `totalChars`)。每降一帧记一次,只在这只函数里记(三处写口不各记)。放行的最坏后果 = 一个读得慢的观众在 SSE 上看不到这张图,只见「这里有一张多大的什么图、没送达」(账本面本就恒是描述符),不是门、不是凭据、不改任何裁决;反方向(不降)让一条停读的连接随帧数线性压住几百 MiB。帧上它与引擎自己的媒体预算降级同形不可分,所以计数是运维唯一能看出「多少观众丢了图」的位;计数持续非零 = 有消费端读流太慢(或网络瓶颈),去看那几条连接。detail = `backlog=<待发字节> media=<本帧媒体字节>`。";
+    };
+    readonly "server.memory-consolidation.operator-valve-unjudged": {
+        readonly cls: "P-DEBT";
+        readonly note: "core 7.50.0 #1653 提货(`boot/memory-consolidation.ts` `createOperatorValveWriteJudge`):运维手动整理阀门这条腿的写判官座答 `no_objection` —— 这条腿没有腿(无名册写脸、无引擎盖的豁免根、无人的持久规则车道),引擎包不导出它那只合成写判官的构造器,本仓不手搭第二只。每被问一次(早问库目录一次 + 每个产物一次)记一次。放行的最坏后果 = 运维手动整理时,一条点名记忆库路径的部署写策略或人的持久规则拦不住这一轮折叠(与引擎 7.49.x 逐字同:那时驱动根本不问);自动整理腿走引擎腿自己的判官,不在本 tag 射程。收口 = 引擎导出宿主可用的写判官构造器,换上即删本 tag。";
+    };
     readonly "server.workflow-park-index.sync-failed": {
         readonly cls: "P-DEBT";
         readonly note: "S-185 车CM(codex r1-F2 [high],验真后登记):workflow 出身 park 的 join 索引(`workflow_agent_session` / local 账本)在**一次成功的 run 写之后**同步失败 ⇒ 该次同步被吞,重试要等这条 run 的**下一次**写。而 park 恰好常常是这条 run 的**最后**一次写(park = run 终局 `failed`)⇒ 那条 park 可能永久 join 不到。**多数情形**是诚实 miss:这张卡没有别的指针 ⇒ `/decide` 结构性退回本批之前的行为(409 `conflict.resume_context_unavailable`),不误配、不伪造、不放行,丢的是「人能不能把这条批准送出去」这个能力。**7.118.0 起不止于此**:路由把指针候选当持有者的全集读,并有分叉门(两条同代次持有者 ⇒ 409 `decide.workflow_park_forked`);同一张卡上一枚**竞争**指针没写上(本臂的写失败,或写记录与写指针之间进程崩溃 —— 后者不经本臂、不计数)⇒ 分叉被判成唯一持有者 ⇒ 决定投给幸存的那一支(它确实持有这张卡,但另一支同样站在上面,引擎把这种形交给消费方拒)。归 P 类的理由:缺指针决定**车道选择**(缺行 ⇒ 选中 legacy 腿),且能让分叉门失效;归 DEBT 的理由是真正的解要一条**按子代 checkpoint 键的耐久决议回执 + 重启期回填**(与 codex r1-F3 同一件欠账,另车),分叉门失效那一形另有设计票。计数非零 = 有 park 可能决不掉、或这张卡的分叉门可能失效,运维要按 detail 里的 runId 去查那条 run 的续跑链。";
@@ -431,6 +443,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "k8s 车道工作区空间结束时对**快照对象**的回收(`plugins/remote-env-k8s.ts` `createSpaceReclaimer` 的对象部分;与上一条同一只回收座、两条腿:会话删除协调器与托管留存 sweep):按空间的 `<前缀>/<化身>/space/` 分区(快照 + `latest`)和该会话停驻车道里名字带被结束住客归属记号的 `<前缀>/<会话 id>/*.tar.gz` 分别 LIST、逐个预签 DELETE;LIST 失败、DELETE 失败(HTTP 非 2xx / 非 404、网络)LIST 超过 1000 个对象被截断,或回收座一次调用的绝对截止(= 快照时限;卷回收也在内)到点〔切断在途请求、停掉余下的;这次调用里还没轮到的空间零请求、各记一次;没删的归生命周期规则〕,各记一次(detail `lane=space|park stage=list|delete|budget`;会话删除口把回收座脱离应答路径,座若抛了——契约禁止——记 `stage=seat_threw`)⇒ 这些对象留在桶里,会话照删(不挡删除)。放行的最坏后果 = 一份已无人能读的工作区快照留在桶里(会话已删,经 API 不可达;内容是用户工作区,所以不是「只占盘」—— 留到桶的生命周期规则把它过期掉为止);不碰任何别的空间、不是门不是凭据;反方向(清不掉对象就拒删会话)会让一个对象存储抖动挡住用户的删除权。故 F 类,但必须留痕:静默吞掉之后「这个会话删了、它的工作区内容还在不在桶里」在遥测里没有任何痕迹。同拍一行 `workspace_space_reclaim_failed`(`space` 前缀 / `sessionId` / `lane` / `stage` / `error`)。计数非零 = 有对象没回收掉,运维按行里的空间前缀 / 会话 id 去桶里手清,并核对象存储的可达性与 DELETE 权限。回收与同一空间的尚在途的 run 末提交不是互斥的:会话删除时没有活 run(409 挡),但上一条 run 的提交若恰在删除之后才落对象,这批对象不在本次回收射程内(同样归桶的生命周期规则)。停驻分区按会话 id 分区,所以只删名字带被结束住客归属记号的对象(不读任何钟)—— 会话 id 删后被别人重新登记,新住客停驻出的快照带它自己的记号、不碰;不带记号的旧形与 `none` 留给桶的生命周期规则。";
     };
+    readonly "server.sandbox-egress.policy-gap": {
+        readonly cls: "P-DEBT";
+        readonly note: "k8s 车道沙箱出网的起服自检(`plugins/remote-env-k8s.ts` `checkSandboxEgressPolicy` 读节点表与沙箱 ns 的 NetworkPolicy,判法 `sandbox-egress-policy.ts` `sandboxEgressGaps`;起服一次、不挡起服)读出一个缺口 —— 某节点的 InternalIP / ExternalIP 落在一条放行 ipBlock 内(`kind=node_address_open`)、没有策略以 Egress 选中沙箱 pod(`kind=policy_absent`)、pod 保留 IPv6 而策略层担保不了 v6(`kind=ipv6_enabled`)、节点表或策略表读不到(`kind=unreadable what=nodes|networkpolicies`)⇒ 车道**照常起**,每个缺口一行 `sandbox_egress_policy_gap`(带后果句与去哪改)。归 P 类:出网策略是保护面,缺口意味着沙箱里的代码可能够到节点上的服务;归 DEBT 的理由:修法都在集群配置里(节点地址点名、kubelet 放行 v6 sysctl、CNI 的 v6 执行、RBAC),本服务改不了,而拒起车道会让缺省单节点装法(恒有 `ipv6_enabled`)升级即停摆沙箱执行 —— 车道自己的隔离(VM 边界、零 SA token)仍在。放行的最坏后果 = 读出缺口的那一面照旧可达,直到运维按行里的后果句改配置。计数非零 = 这台部署的沙箱出网面有读得出的缺口。读不出的面(宿主 DNAT 发布端口、「pod 所在节点恒放行」的实现差异、CNI 根本不执行策略)不在本 tag 的射程里。";
+    };
     readonly "server.fleet.announce-reply-unreadable": {
         readonly cls: "P-DEBT";
         readonly note: "7.121.0 修复验证轮(`fleet-client.ts` 的公告环,fleet 成员每一拍心跳 2xx 答复;detail = `why=<body|not-an-object|invalid-capabilities> leaseState=<此刻的租约态>`):答复不是能力读数(体读不出 / 不是对象 / `capabilities` 键在场而形坏 —— settings-schema 9.0.0 `readCapabilityReading` 的 `unreadable`,外加本仓的 `body`)⇒ 当作没有这一拍答复,租约的状态与钟原样。**一律**计数(不论租约生效与否):租约还没生效(`leaseState=none`)时这只成员**一直不受围栏**,而修前这一形零计数(中心每拍答 `<html>` ⇒ 成员恒 none、零痕迹);租约已生效时计数说明中心的答复在坏、围栏靠的是上一次读数。归 P 类:围栏轴;归 DEBT:本进程判不出中心为什么答坏体,收口条件 = 中心契约 / 监控(中心侧对心跳答复形的执法)落地。每段连拍另有一行 warn `fleet_announce_reply_unreadable`(带 `why`)。";

package/dist/observability/fail-open.js

@@ -16,6 +16,18 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-297(`http/routes/sessions.ts lastLegMcpFor`,`/mcp` 面板的可选键 `lastLegMcp`):按会话取最近 run 的索引读 / 那条 run 的账本读**抛错或超期** ⇒ 该键缺席,面板本体照常 200。放行的最坏后果=这一屏少一格「上一次真挂上了什么」(壳退回翻账本),不是门、不是权限、不是凭证 —— 而反方向(让附加键的读失败打掉整张面板)会给一口此前零 MCP 配置下根本不碰账本的**既有**读面新加一条挂掉的理由。缺席本就是本键 wire 上的一等状态(消费端必须会读),所以这条兜底不产生任何新的消费端形态;计数让「某台部署的账本一直读不出来」显形。",
     },
+    "server.ledger.forward-append-failed": {
+        cls: "F",
+        note: "durable 腿 forward 道的写失败(`trace/ledger-sink.ts` 的 `createForwardAppendFailedNote`:账本汇 `onForwardEvent` —— bg 腿、sync detach 车道、续跑腿 verify 臂 —— 与续跑腿自己的 forward 回调同一只出口)。forward 道是同步回调里的 fire-and-forget 写(序号同步分配,结构上不能 await),写失败 ⇒ 这一帧(子代的 `task_started` / `task_progress` / 工具卡)永远不在 `GET /v1/runs/:id/events` 的回放面,run 照跑。放行的最坏后果 = 回放面少一帧子代事实(起跑帧每周期一只,丢了就补不回 `agentType` / `rootSessionId` / `startedAt`),不是门、不是凭据、不改任何裁决;不重试 —— 晚到的重试行会落在读方游标之后(单写串行链存在的理由)。计数非零 = 这台部署的账本写口在出错(主流的 awaited 写多半同时在报错),去看库。detail = `type=<帧型> err=<原句,经记录器脱敏>`。",
+    },
+    "server.tool-end-media.live-backlog-degraded": {
+        cls: "F",
+        note: "core 7.50.0 媒体块提货(`trace/tool-output-media.ts` 的 `liveToolEndForBacklog`,三处活面写口共用的那一只判据 —— 同步流出口 `sseData`、子代 tail 路由写环、tail 总线每订阅者队列):本帧媒体字节 + 这条连接 / 这个订阅者还没送出去的字节 > 上界(64 MiB)⇒ 本帧媒体块降成持久面那只描述符(`{ type, mimeType?, bytes, truncated: true }`,帧级 `truncated` + `totalChars`)。每降一帧记一次,只在这只函数里记(三处写口不各记)。放行的最坏后果 = 一个读得慢的观众在 SSE 上看不到这张图,只见「这里有一张多大的什么图、没送达」(账本面本就恒是描述符),不是门、不是凭据、不改任何裁决;反方向(不降)让一条停读的连接随帧数线性压住几百 MiB。帧上它与引擎自己的媒体预算降级同形不可分,所以计数是运维唯一能看出「多少观众丢了图」的位;计数持续非零 = 有消费端读流太慢(或网络瓶颈),去看那几条连接。detail = `backlog=<待发字节> media=<本帧媒体字节>`。",
+    },
+    "server.memory-consolidation.operator-valve-unjudged": {
+        cls: "P-DEBT",
+        note: "core 7.50.0 #1653 提货(`boot/memory-consolidation.ts` `createOperatorValveWriteJudge`):运维手动整理阀门这条腿的写判官座答 `no_objection` —— 这条腿没有腿(无名册写脸、无引擎盖的豁免根、无人的持久规则车道),引擎包不导出它那只合成写判官的构造器,本仓不手搭第二只。每被问一次(早问库目录一次 + 每个产物一次)记一次。放行的最坏后果 = 运维手动整理时,一条点名记忆库路径的部署写策略或人的持久规则拦不住这一轮折叠(与引擎 7.49.x 逐字同:那时驱动根本不问);自动整理腿走引擎腿自己的判官,不在本 tag 射程。收口 = 引擎导出宿主可用的写判官构造器,换上即删本 tag。",
+    },
     "server.workflow-park-index.sync-failed": {
         cls: "P-DEBT",
         note: "S-185 车CM(codex r1-F2 [high],验真后登记):workflow 出身 park 的 join 索引(`workflow_agent_session` / local 账本)在**一次成功的 run 写之后**同步失败 ⇒ 该次同步被吞,重试要等这条 run 的**下一次**写。而 park 恰好常常是这条 run 的**最后**一次写(park = run 终局 `failed`)⇒ 那条 park 可能永久 join 不到。**多数情形**是诚实 miss:这张卡没有别的指针 ⇒ `/decide` 结构性退回本批之前的行为(409 `conflict.resume_context_unavailable`),不误配、不伪造、不放行,丢的是「人能不能把这条批准送出去」这个能力。**7.118.0 起不止于此**:路由把指针候选当持有者的全集读,并有分叉门(两条同代次持有者 ⇒ 409 `decide.workflow_park_forked`);同一张卡上一枚**竞争**指针没写上(本臂的写失败,或写记录与写指针之间进程崩溃 —— 后者不经本臂、不计数)⇒ 分叉被判成唯一持有者 ⇒ 决定投给幸存的那一支(它确实持有这张卡,但另一支同样站在上面,引擎把这种形交给消费方拒)。归 P 类的理由:缺指针决定**车道选择**(缺行 ⇒ 选中 legacy 腿),且能让分叉门失效;归 DEBT 的理由是真正的解要一条**按子代 checkpoint 键的耐久决议回执 + 重启期回填**(与 codex r1-F3 同一件欠账,另车),分叉门失效那一形另有设计票。计数非零 = 有 park 可能决不掉、或这张卡的分叉门可能失效,运维要按 detail 里的 runId 去查那条 run 的续跑链。",
@@ -391,6 +403,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "k8s 车道工作区空间结束时对**快照对象**的回收(`plugins/remote-env-k8s.ts` `createSpaceReclaimer` 的对象部分;与上一条同一只回收座、两条腿:会话删除协调器与托管留存 sweep):按空间的 `<前缀>/<化身>/space/` 分区(快照 + `latest`)和该会话停驻车道里名字带被结束住客归属记号的 `<前缀>/<会话 id>/*.tar.gz` 分别 LIST、逐个预签 DELETE;LIST 失败、DELETE 失败(HTTP 非 2xx / 非 404、网络)LIST 超过 1000 个对象被截断,或回收座一次调用的绝对截止(= 快照时限;卷回收也在内)到点〔切断在途请求、停掉余下的;这次调用里还没轮到的空间零请求、各记一次;没删的归生命周期规则〕,各记一次(detail `lane=space|park stage=list|delete|budget`;会话删除口把回收座脱离应答路径,座若抛了——契约禁止——记 `stage=seat_threw`)⇒ 这些对象留在桶里,会话照删(不挡删除)。放行的最坏后果 = 一份已无人能读的工作区快照留在桶里(会话已删,经 API 不可达;内容是用户工作区,所以不是「只占盘」—— 留到桶的生命周期规则把它过期掉为止);不碰任何别的空间、不是门不是凭据;反方向(清不掉对象就拒删会话)会让一个对象存储抖动挡住用户的删除权。故 F 类,但必须留痕:静默吞掉之后「这个会话删了、它的工作区内容还在不在桶里」在遥测里没有任何痕迹。同拍一行 `workspace_space_reclaim_failed`(`space` 前缀 / `sessionId` / `lane` / `stage` / `error`)。计数非零 = 有对象没回收掉,运维按行里的空间前缀 / 会话 id 去桶里手清,并核对象存储的可达性与 DELETE 权限。回收与同一空间的尚在途的 run 末提交不是互斥的:会话删除时没有活 run(409 挡),但上一条 run 的提交若恰在删除之后才落对象,这批对象不在本次回收射程内(同样归桶的生命周期规则)。停驻分区按会话 id 分区,所以只删名字带被结束住客归属记号的对象(不读任何钟)—— 会话 id 删后被别人重新登记,新住客停驻出的快照带它自己的记号、不碰;不带记号的旧形与 `none` 留给桶的生命周期规则。",
     },
+    "server.sandbox-egress.policy-gap": {
+        cls: "P-DEBT",
+        note: "k8s 车道沙箱出网的起服自检(`plugins/remote-env-k8s.ts` `checkSandboxEgressPolicy` 读节点表与沙箱 ns 的 NetworkPolicy,判法 `sandbox-egress-policy.ts` `sandboxEgressGaps`;起服一次、不挡起服)读出一个缺口 —— 某节点的 InternalIP / ExternalIP 落在一条放行 ipBlock 内(`kind=node_address_open`)、没有策略以 Egress 选中沙箱 pod(`kind=policy_absent`)、pod 保留 IPv6 而策略层担保不了 v6(`kind=ipv6_enabled`)、节点表或策略表读不到(`kind=unreadable what=nodes|networkpolicies`)⇒ 车道**照常起**,每个缺口一行 `sandbox_egress_policy_gap`(带后果句与去哪改)。归 P 类:出网策略是保护面,缺口意味着沙箱里的代码可能够到节点上的服务;归 DEBT 的理由:修法都在集群配置里(节点地址点名、kubelet 放行 v6 sysctl、CNI 的 v6 执行、RBAC),本服务改不了,而拒起车道会让缺省单节点装法(恒有 `ipv6_enabled`)升级即停摆沙箱执行 —— 车道自己的隔离(VM 边界、零 SA token)仍在。放行的最坏后果 = 读出缺口的那一面照旧可达,直到运维按行里的后果句改配置。计数非零 = 这台部署的沙箱出网面有读得出的缺口。读不出的面(宿主 DNAT 发布端口、「pod 所在节点恒放行」的实现差异、CNI 根本不执行策略)不在本 tag 的射程里。",
+    },
     "server.fleet.announce-reply-unreadable": {
         cls: "P-DEBT",
         note: "7.121.0 修复验证轮(`fleet-client.ts` 的公告环,fleet 成员每一拍心跳 2xx 答复;detail = `why=<body|not-an-object|invalid-capabilities> leaseState=<此刻的租约态>`):答复不是能力读数(体读不出 / 不是对象 / `capabilities` 键在场而形坏 —— settings-schema 9.0.0 `readCapabilityReading` 的 `unreadable`,外加本仓的 `body`)⇒ 当作没有这一拍答复,租约的状态与钟原样。**一律**计数(不论租约生效与否):租约还没生效(`leaseState=none`)时这只成员**一直不受围栏**,而修前这一形零计数(中心每拍答 `<html>` ⇒ 成员恒 none、零痕迹);租约已生效时计数说明中心的答复在坏、围栏靠的是上一次读数。归 P 类:围栏轴;归 DEBT:本进程判不出中心为什么答坏体,收口条件 = 中心契约 / 监控(中心侧对心跳答复形的执法)落地。每段连拍另有一行 warn `fleet_announce_reply_unreadable`(带 `why`)。",

package/dist/observability/metrics.js

@@ -280,7 +280,7 @@ export function createMetrics() {
     m.counter("memory_dedup_folded_total", "Memory writes folded into an existing near-duplicate row (LOW)");
     m.counter("memory_dedup_probe_failed_total", "Memory dedup KNN probes that failed and fell through to INSERT (LOW)");
     m.counter("redactions_applied_total", "redactSecrets rewrites (S24), by pattern label and `arm` (S-88: full vs prefix-fragment arm — which RULE fired, NOT proof the text was upstream-truncated)");
-    m.counter("stale_cache_conflict_total", "Warm session-cache entries evicted by a cross-instance write while cached (S25)");
+    m.counter("session_cache_stale_hit_total", "Warm session-cache hits dropped because the store had moved past the cached leaf (written by another replica, or gone); the session was re-woken from the store");
     m.counter("breaker_writethrough_failed_total", "Circuit-breaker cross-replica write-through failures (LOW), by backend");
     m.counter("web_search_bad_payload_total", "Web-search provider responses whose results field was not an array (LOW), by provider");
     m.counter("auto_mode_classifier_deny_cause_total", "Auto-mode gate denials where the classifier did NOT rule, by the FORM of the deny (core CLASSIFIER_DENY_CAUSES on GateDisposition.cause: 'unavailable' = the classifier could not run at all (threw/rejected/ran past the cap — retryable), 'parse_error' = it ran but answered outside its verdict contract (blocked for safety); 'other' = this build cannot name the word). 🔴 BREAKING in server 7.72.0: this counter was named auto_mode_classifier_unavailable_total through 7.71.0 and is RENAMED with NO alias (a counter that also counts parse_error is not an 'unavailable' counter); its label vocabulary was 'error'/'timeout' (WHY it was unavailable) — those two collapsed into 'unavailable' (the WHY now rides the deny sentence and the auto_mode.classified trace frame), and 'parse_error' is a bucket the old counter could not see, so by-cause series do NOT splice across the upgrade. Distinct from permission_denied_total{deniedBy=\"classifier\"}, which also counts genuine safety blocks (the classifier's own <block> ruling carries NO cause) — a spike here means the classifier itself is not working (gateway/credential fault, too slow, or answering off-contract), not that the model kept asking for dangerous things");

package/dist/observability/run-terminal.js

@@ -6,6 +6,7 @@ import { isUnsuccessfulRunStatus } from "../plugins/store-contracts.js";
 import { sealResultForExit } from "../terminal.js";
 import { errorText } from "./err-text.js";
 import { recordFailOpen } from "./fail-open.js";
+import { toolEndMediaAsDescriptors } from "../trace/tool-output-media.js";
 const MESSAGE_CAP = 1024;
 export function runTerminalLogLevel(status, errorCode) {
     if (!isUnsuccessfulRunStatus(status))
@@ -451,6 +452,8 @@ export function redactLedgerEventData(type, data) {
     }
     if (type === "turn_end")
         return shapeEchoMembers(data, TURN_END_ECHO_TREATMENT, "turn_end");
+    if (type === "tool_end")
+        return toolEndMediaAsDescriptors(data);
     if (type === "task_notification") {
         const af = data.apiFailure;
         if (af === undefined)

package/dist/plugins/caching-session-store.d.ts

@@ -8,24 +8,36 @@ export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
     sweepIntervalMs?: number;
-    /** S25 (SILENT-FALLBACK P1): called when a cross-instance write (import/replace) evicts a WARM entry —
-     *  the affinity-contract violation signal that previously had zero fingerprint. */
-    onConflictEvict?: (sessionId: string) => void;
+    /** Called once per warm hit that turned out stale (the store's head no longer names the cached leaf, or the session is
+     *  gone): the entry was dropped and the session woken from the store again. Not an error — the operator signal for
+     *  "requests for one session alternate between replicas within the TTL" (the hit rate affinity would buy back). */
+    onStaleHit?: (sessionId: string) => void;
 }
+/** The store's current head for one session — the one read every warm hit is checked against (`undefined` = no such
+ *  session). The same single-row read `OwnerAwareSessionStore.getHead` names; this cache requires its inner store to have it. */
+export type SessionHeadReader = Required<Pick<OwnerAwareSessionStore, "getHead">>;
 /**
- * Warm/sticky cache in front of a durable {@link SessionStore} (Option A).
+ * Warm cache in front of a durable {@link SessionStore}.
  *
- * Keeps a woken session in memory and **reuses the same storage instance across turns**, so a hot
- * session is not re-read from TiDB every short turn (treats the cattle like a warm pet while it's
- * active). Idle sessions expire after `ttlSec`; `release` evicts immediately.
+ * Keeps a woken session in memory and **reuses the same storage instance across turns**, so an active session is not
+ * woken from the store (meta row + event log) on every short turn. Idle sessions expire after `ttlSec`; `release` evicts.
  *
- * ⚠️ **Session affinity is REQUIRED** when this cache is enabled (`SESSION_CACHE_TTL_SEC>0`): route a
- * given sessionId to the same instance. Under affinity the cached storage is the sole writer, so its
- * in-memory leaf is always current and consistent with TiDB (write-through; F2 CAS still applies).
- * Without affinity a concurrent write from another instance makes this cache stale; that surfaces as
- * a `SessionError("conflict")` on the next append — the async run driver calls `evict()` on conflict
- * (defense-in-depth) and the entry also expires after `ttlSec`, but those are backstops, not the
- * guarantee. If you cannot guarantee affinity, set `SESSION_CACHE_TTL_SEC=0` to disable the cache.
+ * **One rule: a warm entry is served only while the store's head for that session still names the leaf the entry
+ * holds.** Every hit reads the head first (`getHead` — one primary-key row read on the SQL twins); head gone or leaf
+ * moved ⇒ the entry is dropped and the session is woken from the store again ({@link CachingOptions.onStaleHit}). The
+ * leaf is the token because it is exactly what the stores' conditional writes compare (`expectedLeafId`): a handle this
+ * cache hands out is never behind the store's leaf, so those writes fail only on a genuinely concurrent write — two runs
+ * writing one session at the same time. Any number of replicas may share one store under any routing; session affinity
+ * only raises the hit rate.
+ *
+ * Open item (the same before this rule): a write that rewrites history while leaving the final leaf id where it was —
+ * a session-sync replace / `overwrite-dst` staged commit on ANOTHER replica that changes entry payloads under the same
+ * ids — moves no leaf, so a warm entry elsewhere keeps its old payloads until it expires or is evicted. Its conditional
+ * writes still succeed (the leaf matches); what is stale is the content of the entries under it. Closing it needs a
+ * store revision bumped by every write path (append, leaf move, replace, staged commit) and carried by the woken handle.
+ *
+ * Writes that go around the cached handle through THIS wrapper (import / replace / staged commit / delete) also drop
+ * the entry at the write site, so the next acquire wakes from the written state.
  *
  * Orthogonal to the F3 branch-floor change: floor bounds the *cold wake* size; this cache removes
  * *repeated* re-reads of an active session.
@@ -36,6 +48,7 @@ export declare class CachingSessionStore implements SessionStore {
     private readonly pending;
     private readonly ttlMs;
     private readonly timer?;
+    private readonly onStaleHit?;
     /** Delegated tenant-ownership ops, present only if the inner store exposes them (the TiDB store does). */
     readonly ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
     /** S-790:属主 + 化身一次读,纯转发(不经暖缓存 —— 化身判的就是「此刻坐在座位上的是谁」,缓存的旧答案正是要消灭的那一形)。
@@ -76,11 +89,8 @@ export declare class CachingSessionStore implements SessionStore {
     /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
      *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     readonly getLeafId?: (sessionId: string) => Promise<string | null>;
-    /** [ref] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
-    readonly getHead?: (sessionId: string) => Promise<{
-        owner: string | null;
-        leafId: string | null;
-    } | undefined>;
+    /** [ref] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。内层店必有(本类的暖命中按它核新鲜)。 */
+    readonly getHead: SessionHeadReader["getHead"];
     /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
      *  list/fork: an export reads the full durable log, an import writes durable state). */
     readonly exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;
@@ -99,7 +109,7 @@ export declare class CachingSessionStore implements SessionStore {
      *  转发白名单里 ⇒ 默认部署(SESSION_CACHE_TTL_SEC=300 把真店包进本类)PUSH Phase A 恒 501
      *  `capability.session_store_required`,而 capabilities().sessionSync 谓词三项(backend/exportEntries/
      *  fileHistoryStore)都被转发了 ⇒ 照报 true(能力面谎)。转发形:handle 的 `commit` 是唯一写真 id 的
-     *  时刻,成功后逐出该 id 的暖 handle + S25 指纹(importEntries/replaceEntries 同纪律);`abort` 只丢
+     *  时刻,成功后逐出该 id 的暖 handle(importEntries/replaceEntries 同纪律);`abort` 只丢
      *  staging 行、不碰真 id ⇒ 不逐出。 */
     readonly beginImportStaging?: (realSessionId: string, token: string) => StagingHandle;
     /** Staging 清扫面(kernel `ImportStagingStore.sweepStagingSessions`)。当下 reaper 走 `backend.session()`
@@ -136,11 +146,18 @@ export declare class CachingSessionStore implements SessionStore {
         scope?: string;
     }) => Promise<PlacedSessionRow[]>;
     readonly placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
-    constructor(inner: SessionStore, opts: CachingOptions);
+    constructor(inner: SessionStore & SessionHeadReader, opts: CachingOptions);
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     touch(sessionId: string): Promise<void>;
     release(sessionId: string): Promise<void>;
-    /** Drop a session from the warm cache (e.g. after a cross-instance write conflict). */
+    /**
+     * The cache's one rule: the warm entry for `sessionId`, if the store's head still names the leaf it holds; otherwise
+     * the entry is dropped (counted once via `onStaleHit`) and `undefined` sends the caller to the store. The head is read
+     * first, the cached leaf second: a write this replica commits in between can only turn a fresh verdict into a stale
+     * one (an extra wake), never the reverse.
+     */
+    private freshHit;
+    /** Drop a session from the warm cache. */
     evict(sessionId: string): void;
     get size(): number;
     dispose(): void;

package/dist/plugins/caching-session-store.js

@@ -5,6 +5,7 @@ export class CachingSessionStore {
     pending = new Map();
     ttlMs;
     timer;
+    onStaleHit;
     ownerOf;
     sessionFaceOf;
     incarnationOf;
@@ -35,6 +36,8 @@ export class CachingSessionStore {
     constructor(inner, opts) {
         this.inner = inner;
         this.ttlMs = Math.max(0, opts.ttlSec) * 1000;
+        this.onStaleHit = opts.onStaleHit;
+        this.getHead = inner.getHead.bind(inner);
         const declared = inner.retention;
         if (declared !== undefined)
             this.retention = declared;
@@ -72,8 +75,6 @@ export class CachingSessionStore {
             this.fork = ownerAware.fork.bind(inner);
         if (ownerAware.getLeafId)
             this.getLeafId = ownerAware.getLeafId.bind(inner);
-        if (ownerAware.getHead)
-            this.getHead = ownerAware.getHead.bind(inner);
         if (ownerAware.exportEntries)
             this.exportEntries = ownerAware.exportEntries.bind(inner);
         if (ownerAware.listEntryIds)
@@ -88,8 +89,6 @@ export class CachingSessionStore {
             const imp = ownerAware.importEntries.bind(inner);
             this.importEntries = async (sessionId, owner, entries) => {
                 await imp(sessionId, owner, entries);
-                if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId);
                 this.evict(sessionId);
             };
         }
@@ -97,8 +96,6 @@ export class CachingSessionStore {
             const rep = ownerAware.replaceEntries.bind(inner);
             this.replaceEntries = async (sessionId, owner, entries) => {
                 await rep(sessionId, owner, entries);
-                if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId);
                 this.evict(sessionId);
             };
         }
@@ -112,8 +109,6 @@ export class CachingSessionStore {
                     appendBatch: (entries) => h.appendBatch(entries),
                     commit: async (owner, o) => {
                         const r = await h.commit(owner, o);
-                        if (this.cache.has(realSessionId))
-                            opts.onConflictEvict?.(realSessionId);
                         this.evict(realSessionId);
                         return r;
                     },
@@ -144,7 +139,7 @@ export class CachingSessionStore {
             this.store(fresh);
             return fresh;
         }
-        const hit = this.cache.get(sessionId);
+        const hit = await this.freshHit(sessionId);
         if (hit && opts?.requireExisting !== true && this.placements !== undefined && this.placementOf !== undefined) {
             assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
         }
@@ -185,6 +180,18 @@ export class CachingSessionStore {
         this.cache.delete(sessionId);
         await this.inner.release(sessionId);
     }
+    async freshHit(sessionId) {
+        const hit = this.cache.get(sessionId);
+        if (hit === undefined)
+            return undefined;
+        const head = await this.inner.getHead(sessionId);
+        if (head !== undefined && head.leafId === (await hit.acquired.session.getLeafId()))
+            return hit;
+        if (this.cache.get(sessionId) === hit)
+            this.cache.delete(sessionId);
+        this.onStaleHit?.(sessionId);
+        return undefined;
+    }
     evict(sessionId) {
         this.cache.delete(sessionId);
     }

package/dist/plugins/host-platform.d.ts

@@ -18,6 +18,9 @@
  *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
  *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
  *              inherit base is spread first).
+ *  - layering = env COMPOSITION is a pure function of config + process.env and never reads the resolved shell;
+ *              the shell belongs to the SPAWN layer only ({@link pinHostShell}, applied by the spawn sites after
+ *              `shellReady()`). A read surface (`cdPath`) therefore never depends on resolution having settled.
  *
  * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
  * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
@@ -39,10 +42,22 @@ export interface HostShell {
  * read the cached value synchronously via {@link hostShell}.
  */
 export declare function resolveHostShell(): Promise<HostShell>;
-/** Synchronous read of the resolved shell — valid only AFTER {@link resolveHostShell} settled (the spawn sites
- *  are all behind `shellReady()`, which awaits it). POSIX never needs the async step. Throws on a mis-ordered
- *  call (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
+/** Synchronous read of the resolved shell — a SPAWN-layer read, valid only AFTER {@link resolveHostShell} settled
+ *  (the spawn sites are all behind `shellReady()`, which awaits it). It is never an env-composition or read-surface
+ *  input (see {@link pinHostShell}). POSIX never needs the async step.
+ *  win32, not settled: a resolve that FAILED throws that failure (the real cause + the way out, memoised above);
+ *  only a resolve that never ran / is still in flight reaches the ordering sentence — on the spawn paths that arm
+ *  is unreachable (they await the resolve first), so it stays as the loud guard against a future mis-ordered caller
+ *  (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
 export declare function hostShell(): HostShell;
+/**
+ * The SPAWN layer's one env edit: win32 pins `SHELL` to the resolved Git Bash (subshell scripts read `$SHELL`).
+ * Takes the {@link HostShell} the caller already read via {@link hostShell} — so a spawn site cannot reach the pin
+ * without a resolved shell (the type is the ordering guard), and env COMPOSITION never needs one. Mutates and
+ * returns `env` (call it BEFORE {@link collapseWin32EnvKeys} so an inherited case-variant `Shell` folds into one
+ * entry). POSIX: identity — `SHELL` is whatever the composed env already carried (byte-identical to pre-Windows).
+ */
+export declare function pinHostShell(env: NodeJS.ProcessEnv, sh: HostShell): NodeJS.ProcessEnv;
 /** test-only: reset the shell caches (each test can re-drive resolution). */
 export declare function resetHostShellCacheForTest(): void;
 /** Per-platform spawn options for a group-killable child (design D3).