@sema-agent/server 7.140.0 → 7.142.0

package/dist/runs.d.ts

@@ -1,4 +1,5 @@
 import { defaultTaskRegistry, type CascadeConfig, type CheckpointToken, type RunInternals, type Runner, type SubagentSteerHandle, type TaskResult, type TaskSpec, type TaskStream, type TerminalCause } from "@sema-agent/core";
+import { type CardVoidPort } from "./card-void.js";
 import { type EntryProblem } from "./entry-problems.js";
 import type { SendUserFileEmitter } from "./capabilities/send-user-file-tool.js";
 import type { RunStore } from "./plugins/store-backend.js";
@@ -181,9 +182,24 @@ export declare function releaseKeyIfZeroWorkRefusal(runStore: {
 export declare function createPromptCommitReader(): (ev: {
     readonly type: string;
 }) => string | undefined;
+/** 回退锚写在哪条腿上(探针行的 `leg=`):流式腿 `POST /v1/tasks/stream`、后台腿 `POST /v1/runs`、续跑腿。 */
+export type ResumeAnchorLeg = "stream" | "bg" | "resume";
+/**
+ * 回退锚的**唯一**写法(三条腿同一只):**有界** await 写入(单行店操作期限 {@link BASELINE_IO_DEADLINE_MS},与项目指令基线的
+ * 读写同一只数、同一只 {@link withinIoDeadline} —— 同为单行 PK 写、同在腿的关键路径上);写失败或到期 ⇒ 不抛(锚是这次提示词能不能
+ * 回退的手柄,不是 run 的成败),记一次登记过的 fail-open `server.resume-anchor.capture-failed`(`reason=error|timeout`;计数 + 探针行 + 一次性 warn)。
+ * 调用方在本腿的终帧(流式腿的 `done`)**之前** await 它 ⇒ 客户端拿到终帧时锚已落定或已知没落定,没有「锚晚到」的窗;锚店挂住至多让终帧晚一个期限。
+ * 到期只放手不取消:那次写照常在飞,迟到落定的锚照样可用(迟到的失败被吞,不重复计数)。
+ * 用户面的读数仍只有一处:会话视图用户消息行的 `taskId?`(present-iff 锚在)与 `resumeAt` 的 404 `resume_at.unknown_event`。
+ */
+export declare function settleResumeAnchor(write: () => Promise<void>, where: {
+    readonly leg: ResumeAnchorLeg;
+    readonly kind: "prompt" | "turn";
+}): Promise<void>;
 export declare class TurnAnchorCapture {
     private readonly capture;
-    private readonly onCaptureFail?;
+    /** 这只捕获器在哪条腿上(写失败的 fail-open 探针行带它)。 */
+    private readonly leg;
     /** R8 (CC-parity rewind): capture a USER-message anchor straight from the
      *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
      *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
@@ -197,7 +213,9 @@ export declare class TurnAnchorCapture {
     private turnHadTool;
     /** 用户提交是不是提问的唯一读法({@link createPromptCommitReader};附件帧不是提问)。 */
     private readonly promptCommit;
-    constructor(capture: ((eventId: string) => Promise<void>) | undefined, onCaptureFail?: (() => void) | undefined, 
+    constructor(capture: ((eventId: string) => Promise<void>) | undefined, 
+    /** 这只捕获器在哪条腿上(写失败的 fail-open 探针行带它)。 */
+    leg: Exclude<ResumeAnchorLeg, "stream">, 
     /** R8 (CC-parity rewind): capture a USER-message anchor straight from the
      *  `message_committed{role:"user"}` event — its `entryId` is the persisted user-message `SessionTreeEntry.id`,
      *  ALWAYS a valid `resumeAt` target (core accepts a user message; it rejects a tool-result / mid-tool-call
@@ -247,6 +265,20 @@ export declare function parkToolCallId(result: unknown, cs: ParkCheckpointReader
  *  不塞进 `checkpointGate`——那是 core 的类型,server 不改其形)。非 park / 无 token / tool-less /
  *  读失败 ⇒ **同一引用**原样返回(键缺席)。graft 不负责 strip——组合序恒为 graft → strip。 */
 export declare function graftParkToolCallId<T>(result: T, cs: ParkCheckpointReader | undefined): Promise<T>;
+/**
+ * 🔴 [ref] **停驻没落定就以失败收场的腿:卡的命运先于认领释放**(后台腿与续跑腿同读这一只;动词 = `card-void.ts` 的结算作废)。
+ *
+ * 腿要以失败收场(行 `failed`、认领释放),而手里的结果是宿主层停驻 —— 引擎交回结果之前已把卡落进 checkpoint 店,卡在本 run 的会话上 ——
+ * ⇒ 先把那张卡按它自己的 scope 作废,调用方再放认领。不作废 ⇒ 待决面上留一张卡,兑现它的 run 已经 `failed`、认领已放:决定口照样受理,
+ * 续跑在没有认领的会话上驱动(`resume-legs.ts` 认领缺席的成因清单)。顺序承重:先放认领、后作废 ⇒ 两步之间(作废没做成时一直)就是那一形。
+ * 停驻没落定的成因不在判据里(停驻行 / 用量行 / 结果到手之后的任何一笔账本写抛):判据只读手里那份结果。
+ *
+ * `held` = 手里那份结果过了宿主判官之后的形(判官提上来的嵌套停驻同样算;不在本 run 会话上的嵌套停驻 —— cascade 级上的卡 —— 判官不提,
+ * 不归本腿作废)。不是停驻 ⇒ 零 I/O。不抛:作废没做成 ⇒ 卡回到「留在待决面上、由兜底收割收走」的形,响亮留痕。
+ */
+export declare function voidHeldParkCard(held: {
+    readonly terminal: TerminalCause;
+} | undefined, hostSessionId: string | undefined, cards: CardVoidPort | undefined, leg: "bg" | "resume"): Promise<void>;
 /**
  * Drive a task to completion in the background, persisting its events to the durable run log (S2).
  *
@@ -339,16 +371,11 @@ approval?: {
     declaredFamilies: ReadonlySet<ApprovalFrameFamily>; /** 出处带车道:这条执行上下文的车道(装配点 `durable-run-leg.ts` 写 `ctx.lane`)。 */
     executionLane: import("./execution-lane-caps.js").ExecutionLane;
 }, 
-/** [ref]:park 投影腿的 checkpoint 读口(`deps.checkpointStore`)。在场时,durable park 的
- *  `suspended` 事件带 `toolCallId`(graft 见 {@link parkToolCallId});缺席=旧字节逐字不变。 */
-parkCheckpointReader?: {
-    get(token: CheckpointToken): Promise<{
-        pendingAction?: {
-            kind?: unknown;
-            toolCallId?: unknown;
-        };
-    } | null>;
-}, 
+/** 本腿结算用的 checkpoint 店(`deps.checkpointStore`),两件事:①[ref] park 投影腿的读口 —— 在场时 durable park 的
+ *  `suspended` 事件带 `toolCallId`(graft 见 {@link parkToolCallId});②验证门结算时作废验证器自己的停驻卡
+ *  ({@link voidVerifierPauseCard}:本服务兑现不了的卡不留在待决面上);③停驻没落定就以失败收场时作废手里那张卡({@link voidHeldParkCard})。
+ *  缺席 ⇒ ①旧字节逐字不变;②③带凭据的停驻响亮留痕、卡由兜底收割。 */
+checkpointCards?: ParkCheckpointReader & CardVoidPort, 
 /** [ref]:装配期(`prepareSpec` → `resolveSpec`)铸下的用户面通告 —— 那一刻本腿的通告口还没开,
  *  所以由本腿在 `registerEngineNoticeLeg` 那一拍连同 `pending` 一起投(投递单点仍是 `route()`)。
  *  缺席 ⇒ 一个字节不投(既有调用方逐字不变)。 */

package/dist/runs.js

@@ -1,5 +1,7 @@
 import { runWithVerification, runCascade, defaultTaskRegistry, taskNotificationDedupKey, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
 import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
+import { voidVerifierPauseCard } from "./verifier-pause-card.js";
+import { voidPendingCard } from "./card-void.js";
 import { NOT_IN_ROSTER, entryProblemsFacts } from "./entry-problems.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { TOOL_DECLARATION_HTTP_STATUS } from "./tool-declaration-http-status.js";
@@ -21,6 +23,7 @@ import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 import { isParkLedgerEventType } from "./trace/ledger-events.js";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { BASELINE_IO_DEADLINE_MS, IoDeadlineExceeded, withinIoDeadline } from "./instruction-source-notice.js";
 import { errorText as errText } from "./observability/err-text.js";
 import { LIVENESS_HEARTBEAT_MS } from "./config-invariants.js";
 export async function backgroundAgentOutput(registry, handle, access, agentStore) {
@@ -198,16 +201,25 @@ export function createPromptCommitReader() {
         return closed.commits[closed.commits.length - 1 - closed.frames];
     };
 }
+export async function settleResumeAnchor(write, where) {
+    try {
+        await withinIoDeadline(write);
+    }
+    catch (err) {
+        const why = err instanceof IoDeadlineExceeded ? `reason=timeout boundMs=${BASELINE_IO_DEADLINE_MS}` : `reason=error error=${err instanceof Error ? err.message : String(err)}`;
+        recordFailOpen("server.resume-anchor.capture-failed", `leg=${where.leg} kind=${where.kind} ${why}`);
+    }
+}
 export class TurnAnchorCapture {
     capture;
-    onCaptureFail;
+    leg;
     captureUser;
     firstTextEventId;
     turnHadTool = false;
     promptCommit = createPromptCommitReader();
-    constructor(capture, onCaptureFail, captureUser) {
+    constructor(capture, leg, captureUser) {
         this.capture = capture;
-        this.onCaptureFail = onCaptureFail;
+        this.leg = leg;
         this.captureUser = captureUser;
     }
     onHumanInput(ev) {
@@ -216,9 +228,9 @@ export class TurnAnchorCapture {
     async onMessageCommitted(role, entryId) {
         const committed = { type: "message_committed", role, entryId };
         const prompt = this.promptCommit(committed);
-        if (prompt !== undefined && this.captureUser) {
-            await this.captureUser(prompt).catch(() => this.onCaptureFail?.());
-        }
+        const captureUser = this.captureUser;
+        if (prompt !== undefined && captureUser)
+            await settleResumeAnchor(() => captureUser(prompt), { leg: this.leg, kind: "prompt" });
     }
     onText(eventId) {
         if (this.firstTextEventId === undefined) {
@@ -231,9 +243,10 @@ export class TurnAnchorCapture {
     }
     async onTurnEnd() {
         this.promptCommit({ type: "turn_end" });
-        if (this.firstTextEventId && !this.turnHadTool && this.capture) {
-            await this.capture(this.firstTextEventId).catch(() => this.onCaptureFail?.());
-        }
+        const capture = this.capture;
+        const handle = this.firstTextEventId;
+        if (handle && !this.turnHadTool && capture)
+            await settleResumeAnchor(() => capture(handle), { leg: this.leg, kind: "turn" });
         this.firstTextEventId = undefined;
         this.turnHadTool = false;
     }
@@ -259,7 +272,12 @@ export async function graftParkToolCallId(result, cs) {
     const id = await parkToolCallId(result, cs);
     return id === undefined ? result : { ...result, toolCallId: id };
 }
-export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, parkCheckpointReader, pendingEngineNotices, trustedInternals, userInputLedger, acceptance, workspaceRecorder) {
+export async function voidHeldParkCard(held, hostSessionId, cards, leg) {
+    if (held?.terminal.kind !== "paused")
+        return;
+    await voidPendingCard({ token: held.terminal.token, sessionId: hostSessionId }, cards, "server.park.held-card-void-failed", `leg=${leg}`);
+}
+export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, checkpointCards, pendingEngineNotices, trustedInternals, userInputLedger, acceptance, workspaceRecorder) {
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart();
@@ -274,7 +292,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         ? mintCancelledResult({ taskId, sessionId: spec.sessionId ?? "", startedAtMs: startedAt, message: "cancelled by user", cause, engineResult })
         : mintCancelledResult({ taskId, sessionId: spec.sessionId ?? "", startedAtMs: startedAt, message: "cancelled by user", cause });
     const recordDone = (result, status) => {
-        metrics?.addGauge("runs_active", -1);
         metrics?.inc("tasks_total", { status });
         metrics?.observe("task_duration_seconds", (Date.now() - startedAt) / 1000);
         if (result?.stats.tokens)
@@ -319,7 +336,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         }
     }, HEARTBEAT_MS);
     heartbeat.unref?.();
-    const anchor = new TurnAnchorCapture(captureTurnAnchor, () => metrics?.inc("resume_anchor_capture_failed"), captureUserMessageAnchor);
+    const anchor = new TurnAnchorCapture(captureTurnAnchor, "bg", captureUserMessageAnchor);
     let reached;
     let observedDone;
     let causeAtDone;
@@ -333,15 +350,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         needs_review: (sealed) => runStore.setNeedsReview(taskId, sealed),
     };
     const parkLeg = async (word, res) => {
-        const grafted = await graftParkToolCallId(res, parkCheckpointReader);
+        const grafted = await graftParkToolCallId(res, checkpointCards);
         await sink.appendParked(word, grafted);
-        await flushModelUsage();
         const sealed = sealResultForExit(grafted);
         reached = { kind: word, result: sealed };
         await parkRowWrite[word](sealed);
         acceptance?.settle(sealed);
-        metrics?.addGauge("runs_active", -1);
-        metrics?.inc("tasks_total", { status: word });
     };
     const settleLegResult = async (engineResult) => {
         const result = atHostBoundary(engineResult, spec.sessionId);
@@ -359,10 +373,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
         await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
         acceptance?.settle(safe);
-        recordDone(safe, settledAsCancel ? CANCELLED_CODE : plane.status);
     };
     const instructionLeg = createInstructionSelectionLeg();
-    const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys, onActivity: (kind, statusData) => recordTurnActivity(taskId, kind, statusData), legSections: () => ({ instructions: instructionLeg.segment(), skills: runSkillsOf(spec) }) });
+    const sink = createLedgerSink({ appendEvent: (seq, type, data) => runStore.appendEvent(taskId, seq, type, data), persistThinking, notifiedKeys, onActivity: (kind, statusData) => recordTurnActivity(taskId, kind, statusData), legSections: () => ({ instructions: instructionLeg.segment(), skills: runSkillsOf(spec) }), usage: { modelUsage, taskId } });
     const append = (type, data) => sink.append(type, data);
     const flush = () => sink.flush();
     const flushModelUsage = () => appendModelUsageDelta(append, modelUsage, taskId);
@@ -454,6 +467,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 const result = await compositeLeg();
                 observedDone = result;
                 causeAtDone = cancelCtrl.cause();
+                await voidVerifierPauseCard(result, checkpointCards);
                 await flush();
                 await flushPromptManifest();
                 await settleLegResult(result);
@@ -547,7 +561,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             }
             reached = { kind: "done", result: c };
             await runStore.setTerminal(taskId, "failed", c, outwardPlane(c.terminal).errorMessage ?? null);
-            recordDone(c, CANCELLED_CODE);
         }
     }
     catch (err) {
@@ -585,6 +598,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             else {
                 settledAsCancel = false;
                 const safeMsg = redactErrorMessage(message) ?? message;
+                await voidHeldParkCard(observedDone === undefined ? undefined : atHostBoundary(observedDone, spec.sessionId), spec.sessionId, checkpointCards, "bg");
                 try {
                     await append("failed", { errorMessage: safeMsg });
                 }
@@ -596,48 +610,48 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         }
         catch {
         }
-        if (reached?.kind === "done")
-            recordDone(reached.result, failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status);
-        else if (reached !== undefined) {
-            metrics?.addGauge("runs_active", -1);
-            metrics?.inc("tasks_total", { status: reached.kind });
-        }
-        else if (settledAsCancel) {
-            recordDone(null, CANCELLED_CODE);
-        }
-        else {
-            recordDone(null, "failed");
-        }
     }
     finally {
         legLive = false;
         unregisterEngineNotice();
-        if (fleetPublisher) {
-            if (reached?.kind === "done")
-                fleetPublisher.onTerminal(failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status, fleetRunResiduals(reached.result));
-            else if (reached?.kind === "suspended")
-                fleetPublisher.onTerminal("suspended");
-            else if (reached?.kind === "needs_review")
-                fleetPublisher.onTerminal("needs_review");
+        const verdict = reached?.kind === "done"
+            ? { kind: "terminal", label: failureCodeOf(reached.result.terminal) === CANCELLED_CODE ? CANCELLED_CODE : outwardPlane(reached.result.terminal).status, result: reached.result }
+            : reached !== undefined
+                ? { kind: "park", word: reached.kind }
+                : { kind: "terminal", label: settledAsCancel ? CANCELLED_CODE : "failed", result: null };
+        try {
+            metrics?.addGauge("runs_active", -1);
+            if (verdict.kind === "park")
+                metrics?.inc("tasks_total", { status: verdict.word });
             else
-                fleetPublisher.onTerminal(settledAsCancel ? CANCELLED_CODE : "failed", {
-                    ...(settledAsCancel ? { stoppedBy: "user" } : {}),
-                    ...(spec.sessionId ? { transcriptId: spec.sessionId } : {}),
-                });
+                recordDone(verdict.result, verdict.label);
+        }
+        finally {
+            if (fleetPublisher) {
+                if (verdict.kind === "park")
+                    fleetPublisher.onTerminal(verdict.word);
+                else if (verdict.result !== null)
+                    fleetPublisher.onTerminal(verdict.label, fleetRunResiduals(verdict.result));
+                else
+                    fleetPublisher.onTerminal(verdict.label, {
+                        ...(verdict.label === CANCELLED_CODE ? { stoppedBy: "user" } : {}),
+                        ...(spec.sessionId ? { transcriptId: spec.sessionId } : {}),
+                    });
+            }
+            if (steerableStreamRef !== undefined)
+                await userInputLedger?.settleLeg(steerableStreamRef);
+            if (inflight?.get(taskId) === cancelCtrl)
+                inflight.delete(taskId);
+            if (preemptable?.get(taskId) === preemptCtrl)
+                preemptable.delete(taskId);
+            if (steerableStreamRef !== undefined && steerable?.get(taskId) === steerableStreamRef)
+                steerable.delete(taskId);
+            for (const evict of subagentHandleEvictions)
+                evict();
+            modelUsage?.clear(taskId);
+            promptManifests?.clear(taskId, manifestLease);
+            clearInterval(heartbeat);
         }
-        if (steerableStreamRef !== undefined)
-            await userInputLedger?.settleLeg(steerableStreamRef);
-        if (inflight?.get(taskId) === cancelCtrl)
-            inflight.delete(taskId);
-        if (preemptable?.get(taskId) === preemptCtrl)
-            preemptable.delete(taskId);
-        if (steerableStreamRef !== undefined && steerable?.get(taskId) === steerableStreamRef)
-            steerable.delete(taskId);
-        for (const evict of subagentHandleEvictions)
-            evict();
-        modelUsage?.clear(taskId);
-        promptManifests?.clear(taskId, manifestLease);
-        clearInterval(heartbeat);
     }
 }
 export const HEARTBEAT_MS = LIVENESS_HEARTBEAT_MS;

package/dist/sandbox-egress-policy.d.ts

@@ -52,7 +52,10 @@ export interface EgressPolicyInputs {
  * 读数 → 缺口(纯函数、全函数:不抛;顺序:读不到的表 → 策略缺席 → 逐节点逐地址 → IPv6)。一张表读不到,只跳过要它的那一判;另一张照判。
  */
 export declare function sandboxEgressGaps(inputs: EgressPolicyInputs): SandboxEgressGap[];
-/** 读数的说法:每个缺口一行 warn `sandbox_egress_policy_gap` + 一次 `recordFailOpen`(P-DEBT);零缺口一行 info `sandbox_egress_policy_checked`。 */
+/**
+ * 读数的说法:每个缺口一行 warn `sandbox_egress_policy_gap` + 一次 `recordFailOpen`(P-DEBT);零缺口一行 info `sandbox_egress_policy_checked`。
+ * `unreadable` 的 `detail` 是控制面请求的失败句(客户端异常原文)⇒ 经出口座(`operator-log-text`)出门,与起服面其余运维行里的抛出物文本同一读法。
+ */
 export declare function sayEgressPolicyReading(gaps: readonly SandboxEgressGap[], logger: {
     info(msg: string, fields?: Record<string, unknown>): void;
     warn(msg: string, fields?: Record<string, unknown>): void;

package/dist/sandbox-egress-policy.js

@@ -1,5 +1,6 @@
 import { BlockList, isIP } from "node:net";
 import { recordFailOpen } from "./observability/fail-open.js";
+import { seatText } from "./trace/exit-seat.js";
 export const SANDBOX_IPV6_WORDS = ["enabled", "disabled"];
 export const SANDBOX_IPV6_DEFAULT = "enabled";
 export function sandboxPodSysctls(ipv6) {
@@ -229,7 +230,8 @@ export function sayEgressPolicyReading(gaps, logger, namespace) {
     }
     for (const gap of gaps) {
         recordFailOpen("server.sandbox-egress.policy-gap", `kind=${gap.kind}${gap.kind === "unreadable" ? ` what=${gap.what}` : ""}`);
-        logger?.warn("sandbox_egress_policy_gap", { namespace, ...gap, effect: effectOf(gap) });
+        const shown = gap.kind === "unreadable" ? { ...gap, detail: seatText("operator-log-text", gap.detail) } : gap;
+        logger?.warn("sandbox_egress_policy_gap", { namespace, ...shown, effect: effectOf(gap) });
     }
 }
 //# sourceMappingURL=sandbox-egress-policy.js.map

package/dist/sandbox-git-plane.d.ts

@@ -38,26 +38,36 @@ export interface SandboxGitPlanePremises {
     /** The patch judge's refusal for a pod that carries the broker (`podSpecPatchBrokerRefusal`); `undefined` = the patch may land. */
     readonly patchRefusal: string | undefined;
     readonly brokerImage: string | undefined;
-    /** The routed origins (`readSandboxGitConfig`); `null` = no `sandboxGit` block. */
+    /** The routed origins — the live config's `sandboxGit` block as committed (`config.sandboxGit`); `null` = no block. */
     readonly origins: readonly string[] | null;
 }
+/** The boot's readings the judge needs besides config: the secret seat answer (asked once, by stage 5) and the static patch judge's refusal. */
+export interface SandboxGitPlaneBootReadings {
+    readonly secretSeat?: SandboxSecretSeat;
+    readonly patchRefusal?: string;
+}
 /** THE judge: the first premise that fails, in the written order; all hold ⇒ on with per-origin rows. Pure. */
 export declare function judgeSandboxGitPlane(p: SandboxGitPlanePremises): SandboxGitPlane;
 /** The secret seat is asked for the plane only when every premise before it holds (a deployment the plane is off for asks nothing for it). */
 export declare function sandboxGitPlaneAsksSecretSeat(p: Pick<SandboxGitPlanePremises, "multiTenant" | "k8sLane" | "callerCredential" | "centerUrl">): boolean;
-/** The premises read from config, plus the two boot readings (seat answer, patch refusal) when the boot has them. */
-export declare function sandboxGitPlanePremisesOf(config: ServiceConfig, readings: {
-    readonly secretSeat?: SandboxSecretSeat;
-    readonly patchRefusal?: string;
-}): SandboxGitPlanePremises;
+/** The premises read from the live config, plus the two boot readings (seat answer, patch refusal) when the boot has them. */
+export declare function sandboxGitPlanePremisesOf(config: ServiceConfig, readings: SandboxGitPlaneBootReadings): SandboxGitPlanePremises;
+/** The plane's read-time seat (see the file head): {@link SandboxGitPlaneSeat.now} judges on every call; {@link SandboxGitPlaneSeat.settle} asks the boot's IO premise. */
+export interface SandboxGitPlaneSeat {
+    /** The reading now — the judge over the boot readings settled so far and the live config. Synchronous; every reader calls it per read and keeps no copy. */
+    now(): SandboxGitPlane;
+    /** Asks the secret seat once (stage 5 awaits it), only when the four premises before it hold; a later call asks nothing. */
+    settle(): Promise<void>;
+}
 /**
- * Wiring point — the effective `sandboxGit` block (the origins this deployment routes through the broker, canonical form, ≤ 16). Its shape
- * and its canonical-form judge belong to the settings-schema contract package (`SandboxGitConfig`, 14.7.0 — picked up: the block rides the effective
- * wire verbatim); this reader is not wired to it yet ⇒ `null` (the plane stays off, `no_origins`). To be replaced by the package reader — no local copy of the shape.
+ * The plane's ONE seat. `premisesOf` = the premises over the live config (the execution env hands `(r) => sandboxGitPlanePremisesOf(config, r)` — the
+ * config object every commit of the effective configuration mutates); `boot.patchRefusal` = the static patch judge's answer (a boot reading from the start);
+ * `boot.askSecretSeat` = the lane's secret-seat review (only the k8s lane has one; absent ⇒ never asked ⇒ the seat stays unverified).
  */
-export declare function readSandboxGitConfig(_config: ServiceConfig): {
-    readonly origins: readonly string[];
-} | null;
+export declare function createSandboxGitPlaneSeat(premisesOf: (readings: SandboxGitPlaneBootReadings) => SandboxGitPlanePremises, boot: {
+    readonly patchRefusal?: string | undefined;
+    readonly askSecretSeat?: (() => Promise<SandboxSecretSeat>) | undefined;
+}): SandboxGitPlaneSeat;
 /**
  * Wiring point — does this worker hold the credential the console's vault admits on its resolve endpoint (the worker-assertion token)?
  * The server has no reader for it yet ⇒ `false` (the plane stays off, `no_caller_credential`). Replaced by the plane's vault client.
@@ -76,6 +86,15 @@ export interface SandboxGitRunRows {
  * `sandbox_broker_identity_unread` —— every miss reads as "not sso" ⇒ no broker (fail-closed), none of them throws into the pod's connect.
  */
 export declare function runIdentitySourceOf(runId: string | undefined, runs: SandboxGitRunRows | undefined, logger?: Pick<Logger, "warn">): Promise<IdentitySource | undefined>;
+/**
+ * The k8s run binding's broker-seat reader (the adapter asks it once per pod, `K8sRunEnvSeats.brokerSeatOf`): reads the plane ONCE per pod, before the
+ * run-row read — off ⇒ none and no row read at all; on ⇒ {@link sandboxBrokerSeatOf} over that one reading and the row's recorded identity source.
+ * `runs` is the late-bound run store (absent ⇒ no row ⇒ not `sso` ⇒ none).
+ */
+export declare function createSandboxBrokerSeatOf(planeNow: () => SandboxGitPlane, brokerImage: string | undefined, runs: (() => SandboxGitRunRows | undefined) | undefined, logger?: Pick<Logger, "warn">): (runId: string | undefined) => Promise<{
+    readonly image: string;
+    readonly origins: readonly string[];
+} | undefined>;
 /** The broker seat for one run's pod: the plane on ∧ the image set ∧ the run's recorded identity source `sso` ⇒ the image + every origin of the reading (http too); otherwise none. */
 export declare function sandboxBrokerSeatOf(plane: SandboxGitPlane, brokerImage: string | undefined, identitySource: IdentitySource | undefined): {
     readonly image: string;

package/dist/sandbox-git-plane.js

@@ -21,7 +21,7 @@ export const SANDBOX_GIT_PLANE_OFF_TEXT = {
     secret_seat_denied: `the sandbox Role does not allow secrets ${SANDBOX_SECRET_SEAT_VERBS.lease.join(" / ")} (the lease Secret) in the sandbox namespace`,
     pod_patch_reaches_broker: "the deployment's pod-spec patch could reach the broker container (a podSecurityContext, or a field outside the broker white-list)",
     broker_image_unset: "K8S_SANDBOX_BROKER_IMAGE is not set (the broker container's image; this engine's own image is the recommended value)",
-    no_origins: "the effective configuration routes no git origins to the plane (sandboxGit.origins)",
+    no_origins: `the effective configuration routes no git origins to the plane (sandboxGit.origins): the console projects the block only on this worker's own pull (${WEB_ADMIN_ENV.worker}), and a block that fails its contract is read as no origins (log line web_admin_sandbox_git_refused)`,
 };
 const isHttps = (url) => url !== undefined && URL.canParse(url) && new URL(url).protocol === "https:";
 export function judgeSandboxGitPlane(p) {
@@ -73,11 +73,23 @@ export function sandboxGitPlanePremisesOf(config, readings) {
         secretSeat: readings.secretSeat,
         patchRefusal: readings.patchRefusal,
         brokerImage: lane?.provider === "k8s" ? lane.brokerImage : undefined,
-        origins: readSandboxGitConfig(config)?.origins ?? null,
+        origins: config.sandboxGit?.origins.map((e) => e.origin) ?? null,
     };
 }
-export function readSandboxGitConfig(_config) {
-    return null;
+export function createSandboxGitPlaneSeat(premisesOf, boot) {
+    let readings = boot.patchRefusal !== undefined ? { patchRefusal: boot.patchRefusal } : {};
+    let settled = false;
+    return {
+        now: () => judgeSandboxGitPlane(premisesOf(readings)),
+        settle: async () => {
+            if (settled)
+                return;
+            settled = true;
+            if (boot.askSecretSeat === undefined || !sandboxGitPlaneAsksSecretSeat(premisesOf(readings)))
+                return;
+            readings = { ...readings, secretSeat: await boot.askSecretSeat() };
+        },
+    };
 }
 export function readSandboxGitCallerCredential(_config) {
     return false;
@@ -97,6 +109,14 @@ export async function runIdentitySourceOf(runId, runs, logger) {
         return undefined;
     }
 }
+export function createSandboxBrokerSeatOf(planeNow, brokerImage, runs, logger) {
+    return async (runId) => {
+        const plane = planeNow();
+        if (plane.state !== "on")
+            return undefined;
+        return sandboxBrokerSeatOf(plane, brokerImage, await runIdentitySourceOf(runId, runs?.(), logger));
+    };
+}
 export function sandboxBrokerSeatOf(plane, brokerImage, identitySource) {
     if (plane.state !== "on" || brokerImage === undefined || brokerImage === "" || identitySource !== "sso")
         return undefined;

package/dist/security.d.ts

@@ -6,6 +6,7 @@ import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
 import type { ClientSessionRowWrite, ReplaySessionRowWrite, ReplaySessionRowWriteOutcome, SessionRowPatch, SessionRowWriteOutcome } from "./session-row.js";
 import type { ExecutionPlacementSeat } from "./execution-placement.js";
+import type { SessionUnreadable } from "./session-error-wire.js";
 import type { ForkTarget, ForkToOutcome } from "./plugins/session-fork.js";
 import { type OwnerlessClaim } from "./delegated-session-owner.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
@@ -38,6 +39,12 @@ export interface SessionListItem {
      *  primitive ∧ the row has an occupant token); additive key, passed through unprojected (`sessions-list.ts`). Same name and meaning as
      *  `SessionSummary.rowTag` in `plugins/store-contracts.ts`. */
     rowTag?: string;
+    /** The session's archive cannot be read — present-iff the session head's leaf read throws (a list row is a session ROW: its facts live on the
+     *  row and read fine; this says the CONTENT does not). `errorCode` = the code the session's own reads answer for it (`GET /v1/sessions/:id` /
+     *  `…/head` / `…/events` / `PATCH` once admitted) — one table, `openFaceFaultWire` in `session-error-wire.ts`, the only minter `sessionUnreadableOf`.
+     *  A store whose head leaf is a row column (the SQL twins) never carries it. Additive key, passed through unprojected (`sessions-list.ts`).
+     *  Same name and meaning as `SessionSummary.unreadable` in `plugins/store-contracts.ts`. */
+    unreadable?: SessionUnreadable;
 }
 /**
  * 会话店的行格写原语(规则与判序:`session-row.ts` 头注「写原语」)—— 按入口分两只重载:客户端写(PATCH)的结局闭集四员;行重放(2c 导入落定后的那一笔)
@@ -176,10 +183,10 @@ export declare function legacyUnownedAmnestyOpen(deployment: DeploymentShapeInpu
 export type OwnerAwareSessionStore = SessionStore & {
     /** 属主登记(core `SessionStore.register` 的契约:对没有行的 id 建行并记下属主,首写赢;对已有的行什么都不做)。读回走 `headOf`。 */
     register?: (sessionId: string, owner: string | null) => Promise<void>;
-    /** [ref] 委派继承律的**认领口** —— 只在记录委派树的店上(SQL 两店,只命中 placed 行;local 店没有):判断时读到的那一位住客仍是无主的 placed 行 ⇒ 写 `owner`,
+    /** [ref] 委派继承律的**认领口** —— 只在记录委派树的店上(三只持久会话店,只命中 placed 行;不记委派树的店没有):判断时读到的那一位住客仍是无主的 placed 行 ⇒ 写 `owner`,
      *  返回是否写成(只 CAS 子行自己)。唯一调用方 = 停驻挂点的 `settleDelegatedOwner`(`delegated-session-owner.ts`;M23 走同一句 SQL);规则写在那个模块。 */
     claimOwnerless?: OwnerlessClaim;
-    /** [ref] placed 分区的元组读口(店的既有读口,一行 PK 读;`undefined` = 普通会话或无此行)。店不交它 = 不实现 placement = 没有 placed 行(local 店)。两个读者:
+    /** [ref] placed 分区的元组读口(店的既有读口,一行 PK 读;`undefined` = 普通会话或无此行)。店不交它 = 不实现 placement = 没有 placed 行(无 repo 的内存店)。两个读者:
      *  ① 会话面的属主门只在属主为 NULL 时读它一次(无主的 placed 行不是公共行,`http/principal-gate.ts` 的 `sessionOwnerCellOf`);
      *  ② 会话视图读它投影体顶层 `agent` 键(`audit.ts` 的 `sessionAgentOf`,只在视图读上付):店没有这一面 ⇒ 键缺席,读面不凭别处另铸子代身份。 */
     placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
@@ -456,6 +463,8 @@ export declare function setSsoScope(req: IncomingMessage, scope: string): void;
 export declare function ssoVerifiedScope(req: IncomingMessage): string | undefined;
 export declare function setSsoRole(req: IncomingMessage, role: string): void;
 export declare function ssoVerifiedRole(req: IncomingMessage): string | undefined;
+export declare function setSsoPrincipalInc(req: IncomingMessage, principalInc: string): void;
+export declare function ssoVerifiedPrincipalInc(req: IncomingMessage): string | undefined;
 export declare function verifiedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
 export {};
 //# sourceMappingURL=security.d.ts.map

package/dist/security.js

@@ -210,6 +210,14 @@ export function ssoVerifiedRole(req) {
     const v = SSO_ROLES.get(req);
     return v !== undefined && v.length > 0 ? v : undefined;
 }
+const SSO_PRINCIPAL_INCS = new WeakMap();
+export function setSsoPrincipalInc(req, principalInc) {
+    SSO_PRINCIPAL_INCS.set(req, principalInc);
+}
+export function ssoVerifiedPrincipalInc(req) {
+    const v = SSO_PRINCIPAL_INCS.get(req);
+    return v !== undefined && v.length > 0 ? v : undefined;
+}
 export function verifiedPrincipal(req, config) {
     const sso = ssoVerifiedPrincipal(req);
     if (sso) {

package/dist/server-secret-env.d.ts

@@ -73,7 +73,8 @@ export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKe
  *    所以这一次抛只可能是名的问题。
  *  · **值臂**:{@link serverCredentialValueSources} 的每一个变量此刻在 env 里的值,逐个交给引擎**同一只**判(不另写「什么算凭据值」的第二份判据):引擎收下 ⇒ 记进值臂;
  *    引擎拒(不是凭据值:空白 / 占位词 / 一个字符重复 / 不足 8 字符;或它是每个子进程都会拿到的变量的值)⇒ 这一个值不扣、名照扣、**不拒启**(与引擎自己的收值口
- *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),`console.warn` 点名那个变量一次(引擎的拒句从不回显值;本句也不),能力位 `inherit_env.own_credential_values_withheld`
+ *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),经留痕座结构化点名那个变量一次 —— `warn` 行 `own_credential_value_not_withheld { name, reason }`
+ *    ({@link recordOwnCredentialValueNotWithheld};`reason` 是引擎拒句原文,从不回显值;起服第一步还没有 logger 时当拍经进程默认的 JSON 行日志器写 stderr,不缓冲),能力位 `inherit_env.own_credential_values_withheld`
  *    因此答 false(位真 ⇔ 值臂真扣)。引擎拒一个值时声明保持上一份,所以逐个交表的中间态都是上一份的超集。
  * 返回声明的名单(只名、不值)。
  */

package/dist/server-secret-env.js

@@ -1,7 +1,7 @@
 import { declareWithheldEnv, hostChildEnv, inheritedHostEnv } from "@sema-agent/core";
 import { CONFIG_CATALOG } from "./config-catalog.js";
 import { ENV_NAME_ALLOWLIST_KNOB_NAMES } from "./env-name-allowlist-knobs.js";
-import { recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
+import { recordOwnCredentialValueNotWithheld, recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
 export const CATALOG_SECRET_ENV_NAMES = new Set(CONFIG_CATALOG.filter((spec) => spec.type === "secret").map((spec) => spec.name));
 const NO_MODEL_ENTRIES = Object.freeze({});
 export function serverWithheldEnvNames(modelApiKeyEnv = NO_MODEL_ENTRIES) {
@@ -31,9 +31,7 @@ export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
         catch (e) {
             if (!valueRefusalAnnounced.has(source)) {
                 valueRefusalAnnounced.add(source);
-                console.warn(`[sema-server] own credential ${source}: its value is not withheld by value from spawned children — the engine refused it (${e instanceof Error ? e.message : String(e)}); ` +
-                    "the variable name is still withheld under every inheritEnv policy, but a variable holding the same string under another name is not, and GET /v1/capabilities answers inherit_env.own_credential_values_withheld: false. " +
-                    "Give it a real credential value (at least 8 characters, not a placeholder) to withhold copies of it too.");
+                recordOwnCredentialValueNotWithheld({ name: source, reason: e instanceof Error ? e.message : String(e) });
             }
         }
     }