@sema-agent/server 7.140.0 → 7.141.0

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,13 @@ 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,7 +374,6 @@ 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) }) });
@@ -454,6 +468,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 +562,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 +599,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 +611,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/security.d.ts

@@ -176,10 +176,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>;

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

package/dist/session-error-wire.d.ts

@@ -37,7 +37,7 @@
  *    列表里的缺席),码位各不相同,不由本表统一。
  *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `detail.placement_kind`,固定句);`open` 面留白。
  *    同一个词在两面上说的不是同一件事:import 面只有「会话同步往一只**分区会话**(委派子代的转录)上写」一个来源
- *    (SQL 两店的整段换装 / 暂存提交门:目标 id 的 `placement_kind` 在场 ⇒ 不适用),调用方没做错格式、是**目标**不收这种写;
+ *    (三只持久会话店的整段换装 / 暂存提交门:目标 id 的 `placement_kind` 在场 ⇒ 不适用),调用方没做错格式、是**目标**不收这种写;
  *    open 面上同一个词还含「声明了分区的创建撞上了分区外 / 异组的行」两形(core `TtlSessionStore.assertPlacementAdmission` 的后两条),
  *    那不是「目标是分区会话」。而 run 终局上它是引擎词汇(`terminal.code`),原样随 failed 体走 —— 若在这里分诊成 409,
  *    体上的 `errorCode` 仍是引擎词 `placement_refused`,一个状态两个名字。所以 open 面留白,`invalid_session` 是同形先例。
@@ -47,16 +47,18 @@
  *    (请求 core 把种类放进错误,而不是在这里解析句子)。
  *  · `invalid_entry` / `invalid_fork_target` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
  *    应答(它们在 core 的追加 / 分叉面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
- *  · `conflict` —— `import` 面 **409 `conflict`**(固定句 {@link STAGED_IMPORT_OWNER_CHANGED_SENTENCE});`open` 面留白。import 面上这个词只有一个来源:
+ *  · `conflict` —— `import` 面 **409 `conflict`**(固定句 {@link STAGED_IMPORT_OWNER_CHANGED_SENTENCE});`open` 面留白。按码映射时 import 面上这个词只有一个来源:
  *    暂存提交的属主 CAS(`session-sync-kernel.ts` 的 `StagedCommitOwnerChangedError`,三家店在提交事务里比「此刻的属主格 = 这次导入的门判过的那一格」,
  *    不等 ⇒ 回滚)—— 码位与同族的提交期同步冲突(`SyncConflictError` ⇒ 409 `conflict`「sync conflict」)同一个,出路也相同:从第一阶段重来(重新过门)。
+ *    本服务自铸的同码具名拒 {@link StampedSessionArchiveError}(local 店:存档仍带更早版本写下的属主戳)不按码映射 —— 出路不同(重来照样撞),
+ *    由 {@link sessionErrorWireOf} 按**型**先认:两面同答 409 `conflict` + 固定句 {@link STAMPED_SESSION_ARCHIVE_SENTENCE}。
  *    open 面上它是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局(`terminal.code: "conflict"`),提交腿不另作处置。
  *  · `storage` / `unknown` —— 留白:故障类,通用 500 就是它们今天的应答。
  *
  * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
  * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。
  */
-import type { SessionError } from "@sema-agent/core";
+import { SessionError } from "@sema-agent/core";
 /** core `SessionError` 的码闭集(core 不从包根导出这个型名 ⇒ 从导出类的 `code` 键派生,不手抄)。 */
 export type SessionErrorCode = SessionError["code"];
 /** 映射的面(见文件头注)。 */
@@ -76,7 +78,7 @@ export interface SessionErrorWire {
 /** import 面 `invalid_session` 的固定句(修前 session-sync 暂存导入腿那一行的原文)。 */
 export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
 /**
- * import 面 `placement_refused` 的固定句:wire 上不发引擎原句 —— 两家 SQL 店的原句不同(措辞各自铸),都点名会话 id 与引擎内部词
+ * import 面 `placement_refused` 的固定句:wire 上不发引擎原句 —— 三只持久会话店的原句各不相同(措辞各自铸),都点名会话 id 与引擎内部词
  * (「placement partition」「delegation transcript」);固定句只说调用方能做什么(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
  */
 export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
@@ -85,6 +87,22 @@ export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated a
  * 不发店的原句(它点名会话 id);固定句只说发生了什么与出路(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
  */
 export declare const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported \u2014 start the sync again";
+/**
+ * local 店的具名拒(唯一铸点 `plugins/local-session-store.ts`):这只会话的引擎存档仍带更早版本写下的属主戳(一次性迁移 M33 改写不了它,或数据根跳过了带这次迁移的版本)
+ * ⇒ 不在它上面造新存档(fork),也不原地换它的日志(改日志的推送);零写。码是 core 闭集的 `conflict`(码不另铸);句子(给运维日志,点名会话 id)归本错,
+ * wire 上发固定句 {@link STAMPED_SESSION_ARCHIVE_SENTENCE}(两面同一句;映射 {@link sessionErrorWireOf})。
+ */
+export declare class StampedSessionArchiveError extends SessionError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/** {@link StampedSessionArchiveError} 的 wire 固定句(fork 与改日志的推送同一句;不点名会话 id;出路在句里 —— 从头再同步照样撞)。 */
+export declare const STAMPED_SESSION_ARCHIVE_SENTENCE = "this session's stored archive still carries an owner stamp written by an earlier server version, so it cannot be forked or have its log replaced; nothing was written \u2014 delete the session and push it again";
+/**
+ * 一只 `SessionError` 在一面上的 wire 答复 —— 下发点({@link sendSessionError} 的唯一读法)经这里:本服务自铸的同码具名拒先按型认(它的出路与同码的
+ * 按码答复不同),其余按码({@link sessionErrorHttp})。
+ */
+export declare function sessionErrorWireOf(e: SessionError, face: SessionErrorFace): SessionErrorWire | undefined;
 export declare function sessionErrorHttp(code: SessionErrorCode, face: SessionErrorFace): SessionErrorWire | undefined;
 export declare function isSessionErrorCode(code: string): code is SessionErrorCode;
 //# sourceMappingURL=session-error-wire.d.ts.map

package/dist/session-error-wire.js

@@ -1,12 +1,28 @@
+import { SessionError } from "@sema-agent/core";
 export const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
 export const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
 const PLACEMENT_KIND = "subagent";
 export const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported — start the sync again";
+export class StampedSessionArchiveError extends SessionError {
+    sessionId;
+    constructor(sessionId) {
+        super("conflict", `session ${sessionId}'s stored archive still carries an owner stamp written by an earlier version (the one-time migration M33 could not rewrite it as anonymous, ` +
+            "or this data root skipped the versions that carry that migration) — no new session is made from it and its log is not replaced, so this write was refused and nothing was written. " +
+            "Reading, resuming and pulling the session are unaffected. Way out: delete the session and push it again (a push onto an absent session creates it anew).");
+        this.sessionId = sessionId;
+        this.name = "StampedSessionArchiveError";
+    }
+}
+export const STAMPED_SESSION_ARCHIVE_SENTENCE = "this session's stored archive still carries an owner stamp written by an earlier server version, so it cannot be forked or have its log replaced; nothing was written — delete the session and push it again";
 const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
 const STORED_LOG_INVALID = { status: 500, errorCode: "invalid_session" };
 const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
 const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, detail: { placement_kind: PLACEMENT_KIND } };
 const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
+const STAMPED_SESSION_ARCHIVE = { status: 409, errorCode: "conflict", sentence: STAMPED_SESSION_ARCHIVE_SENTENCE };
+export function sessionErrorWireOf(e, face) {
+    return e instanceof StampedSessionArchiveError ? STAMPED_SESSION_ARCHIVE : sessionErrorHttp(e.code, face);
+}
 export function sessionErrorHttp(code, face) {
     switch (code) {
         case "corrupt_session":

package/dist/session-incarnation.d.ts

@@ -6,9 +6,15 @@
  * 一个可比的答案 —— 今天只能比属主,同一个人删了重建就比不出来。
  *
  * ## 规则(全仓唯一处写)
- *  · **铸点只在新建行**:会话店的 `register` / 无 id 创建 / fork / session-sync 的导入新行。已存在的行一个字节都不动
- *    (与 `owner` 同一条 first-write 律);session-sync 的整段换装(replace / staged commit)换的是**同一位住客**的日志,
- *    化身沿用。删除随行消失,同 id 重新登记铸新的。
+ *  · **铸点只在新建行**:会话店的 `register` / 无 id 创建 / fork / session-sync 的导入新行。已存在的行化身一个字节都不动;
+ *    session-sync 的整段换装(replace / staged commit)换的是**同一位住客**的日志,化身沿用 —— 属主却可以被换装重戳为导入者(local 的 M10 认领同理),
+ *    所以化身与属主不是同一条律(读法分三种,见下「两读」)。删除随行消失,同 id 重新登记铸新的。
+ *  · **两读(住客的三种问法,各读各的格,不混用)**:
+ *    K1 **住客自己的记录**(工作区、记忆、空间分区……按「这一位住客」落的东西)只按化身绑 —— 同一位住客的属主换代(推送重戳 / 认领)不换住客,记录照落;
+ *    K2 **以「这一行的这一代」为条件的写**(执行放置的换绑 / 收回、执行上下文的复核)比属主与化身整对,判官 = core 的行期望判官 `sessionRowMatches`
+ *    (`execution-placement.ts` 的 `sameOccupant`,SQL `incarnation = ? AND owner <=> ?` 的对位)—— 读与写之间属主换了一代 ⇒ 不是判过的那一行;
+ *    K0 **只问属主的门**(授权门、暂存提交的属主 CAS)只读属主那一格。三种都读会话**行**;local 店的行 = 会话元数据边档那一格(引擎仓里的存档是匿名内容仓,
+ *    存档头上的属主不是行事实 —— `plugins/local-session-store.ts` 头注)。
  *  · **值是不透明随机串**(`randomUUID()`,v4:没有时间戳、没有机器信息 —— 刻意不用 uuidv7,那一形带铸造时刻)。只拿来比较。
  *  · **一格、一个解码**:住客令牌是会话**行**上的一格 —— SQL `session_meta.incarnation`(两方言)、local 后端的会话元数据边档那一格
  *    (`plugins/local-session-store.ts` 的 `session-incarnations.json`)。行上的值只经 {@link incarnationFromCell} 解码。

package/dist/session-sync-kernel.d.ts

@@ -8,7 +8,8 @@
  * (security ↔ session-sync; lens2 §B/§E). This file imports nothing from the repo but TYPES from leaves (core types, and
  * the session-face type from `session-incarnation.ts`, itself a leaf) — a leaf, same shape as session-sync-content.ts. Its one VALUE import is
  * core's `SessionError` class (the closed-set store error the three adapters already throw). session-sync.ts re-exports everything here, so existing import sites
- * keep working unchanged.
+ * keep working unchanged. The import door's anchor judge ({@link readImportAnchors}) was written here, not moved: it is pure too, and the route and the
+ * tests read it from the same leaf.
  */
 import { SessionError, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionFace } from "./session-incarnation.js";
@@ -180,4 +181,44 @@ export declare class SyncConflictError extends Error {
         relation: "fork" | "stale";
     }>);
 }
+/**
+ * §9 — one anchor of a Phase-A import body as the import door reads it: the live `eventId` the shell holds → the persisted `entryId` it resumes at.
+ * The wire's `owner` is not carried: every replay re-keys the anchor to the IMPORTING principal (the importer, never the exporter, owns the row),
+ * so nothing downstream reads the sender's value and nothing here judges it.
+ */
+export interface ImportAnchor {
+    readonly eventId: string;
+    readonly entryId: string;
+}
+/** The import door's verdict on `anchors[]`: the judged list, or ONE sentence for the first violation (index + the offending `entryId`, nothing else). */
+export type ImportAnchorsRead = {
+    readonly anchors: ImportAnchor[];
+} | {
+    readonly problem: string;
+};
+/**
+ * §9 — THE predicate of the anchor law, and its only spelling: an anchor is sound iff the entry it resumes at is one of the entries declared next to it
+ * (an import body's `entryIds`; a manifest's `entryIds`). The import door ({@link readImportAnchors}) refuses an anchor that fails it, and the manifest
+ * export (`exportSessionManifest`) does not hand one out — one fact, one reading, on both sides of the wire.
+ */
+export declare function anchorEntryDeclared(declared: ReadonlySet<string>, anchorEntryId: string): boolean;
+/**
+ * §9 — the ONE judge of a Phase-A body's `anchors[]`, run at the door before anything is classified, mirrored, staged or written (a refusal
+ * writes no anchor, no log, no session row, opens no staging, takes no lease, and leaves the execution cell alone).
+ *
+ * The law (single source): an anchor may only point at an entry the session HOLDS once the import has landed, and what an import lands is the log
+ * its body declares (`entryIds`): a commit REPLACES the destination's log with the staged entries (SQL: purge + row rename in one transaction; local:
+ * an in-place swap), `fresh` / `fast_forward` / `identical` leave no destination entry the declaration lacks, and an `overwrite-dst` `fork` / `stale`
+ * removes the destination-only entries (and wipes the anchors that pointed at them). So "the entries the import declares" is the whole question: an
+ * `entryId` outside it names a row that is not there once the import lands (an anchor to a destination-only entry is exactly the dangling anchor the
+ * purge exists to prevent). An entry a concurrent writer appends after the body's ids were read is outside the declaration too, and an anchor to it is
+ * refused the same way — the conservative direction: the sender re-reads its manifest and pushes again (`exportSessionManifest` reads the anchors BEFORE
+ * the entry ids, so a manifest never carries an anchor newer than its own id list, and drops — loudly, by the same {@link anchorEntryDeclared} — an
+ * anchor an earlier version stored for an entry the log does not hold). The replays downstream (the `identical` arm, the post-commit leg)
+ * only iterate the list this function returned — they do not judge again.
+ *
+ * Shape is judged by the same reader — an element that is not an object with a string `eventId` and a string `entryId` is refused by index —
+ * so a `null` element is a 400 at the door, not a TypeError in a replay leg.
+ */
+export declare function readImportAnchors(raw: readonly unknown[], declaredEntryIds: readonly string[]): ImportAnchorsRead;
 //# sourceMappingURL=session-sync-kernel.d.ts.map

package/dist/session-sync-kernel.js

@@ -55,4 +55,21 @@ export class SyncConflictError extends Error {
         this.name = "SyncConflictError";
     }
 }
+export function anchorEntryDeclared(declared, anchorEntryId) {
+    return declared.has(anchorEntryId);
+}
+export function readImportAnchors(raw, declaredEntryIds) {
+    const declared = new Set(declaredEntryIds);
+    const anchors = [];
+    for (let i = 0; i < raw.length; i++) {
+        const a = raw[i];
+        const { eventId, entryId } = (typeof a === "object" && a !== null && !Array.isArray(a) ? a : {});
+        if (typeof eventId !== "string" || typeof entryId !== "string")
+            return { problem: `anchors: [${i}] must be an object with a string eventId and a string entryId` };
+        if (!anchorEntryDeclared(declared, entryId))
+            return { problem: `anchors: [${i}].entryId ${JSON.stringify(entryId)} is not among the entryIds this import declares` };
+        anchors.push({ eventId, entryId });
+    }
+    return { anchors };
+}
 //# sourceMappingURL=session-sync-kernel.js.map

package/dist/session-sync.js

@@ -1,4 +1,5 @@
-import { classifySyncRelationship } from "./session-sync-kernel.js";
+import { anchorEntryDeclared, classifySyncRelationship } from "./session-sync-kernel.js";
+import { recordFailOpen } from "./observability/fail-open.js";
 import { loosenReasons, normalizeRules } from "@sema-agent/core";
 import { headReadOf } from "./session-incarnation.js";
 import { judgeSessionRulesWrite } from "@sema-agent/core";
@@ -60,8 +61,14 @@ export async function replayFileHistory(store, scope, envelope, srcGetBlob, opts
 function ownerAware(backend) {
     return backend.session();
 }
+const DIAG_VALUE_MAX = 96;
+function brief(value) {
+    return JSON.stringify(value.length > DIAG_VALUE_MAX ? `${value.slice(0, DIAG_VALUE_MAX)}…(${value.length} chars)` : value);
+}
 export async function exportSessionManifest(sessionId, srcBackend, historyStore) {
     const session = ownerAware(srcBackend);
+    const anchorStore = srcBackend.resumeAnchor();
+    const anchors = await anchorStore.listBySession(sessionId);
     const listEntryIds = session.listEntryIds?.bind(session);
     if (!listEntryIds)
         return null;
@@ -76,15 +83,20 @@ export async function exportSessionManifest(sessionId, srcBackend, historyStore)
     const policy = typeof policyStore.listBySession === "function"
         ? await policyStore.listBySession(sessionId)
         : [];
-    const anchorStore = srcBackend.resumeAnchor();
-    const anchors = await anchorStore.listBySession(sessionId);
     const summaryOf = session.sessionSummaryOf?.bind(session);
     if (summaryOf === undefined)
         throw new Error("exportSessionManifest: the session store has no row read face (sessionSummaryOf) — the sessionSync fact should have refused this deployment");
     const row = await summaryOf(sessionId);
     const getBlob = blobGetterOf(fs);
+    const declared = new Set(entryIds);
+    const soundAnchors = anchors.filter((a) => {
+        if (anchorEntryDeclared(declared, a.entryId))
+            return true;
+        recordFailOpen("server.session-sync.dangling-anchor-export", `sessionId=${brief(sessionId)} eventId=${brief(a.eventId)} entryId=${brief(a.entryId)}`);
+        return false;
+    });
     return {
-        manifest: { sessionId, entryIds, entryCount: entryIds.length, leafId, fileHistory, policy, anchors, ...(row !== undefined ? { title: row.title, pinned: row.pinned } : {}) },
+        manifest: { sessionId, entryIds, entryCount: entryIds.length, leafId, fileHistory, policy, anchors: soundAnchors, ...(row !== undefined ? { title: row.title, pinned: row.pinned } : {}) },
         getBlob,
     };
 }

package/dist/sql-engine-coordinates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 一只 SQL 引擎「开店所需的坐标」—— 单一来源(纯叶,零依赖)。
+ *
+ * ## 病
+ * 显式 `DB_BACKEND=pg|mysql` 是运维在说「我要这只持久引擎」。可是坐标缺席时,起服在三种 `SESSION_BACKEND` 写法下走三条路:
+ * 未设 / `mysql` ⇒ 读坐标抛 `missing required env`(响亮);`auto` ⇒ 「坐标不在就不探测」,**静默落内存**,姿态位却照报 `declared: "pg"` ——
+ * 一个自以为在持久化的部署跑在内存里,`/health` 照样 200。`REQUIRE_PRINCIPAL=true` 同形。同一个声明,拒不拒取决于第二个旋钮怎么写。
+ *
+ * ## 药
+ * 声明 ∧ 坐标缺席 ⇒ 配置期拒启,**不看** `SESSION_BACKEND`(判官在 `config.ts` 的 store 域,一只):三种写法同一句拒句,
+ * 拒句点名缺的坐标**键名**(不回显值,也读不到值)与两条出路。本模块只出两样东西:各引擎的必需坐标键表,与按这张表铸的两句话
+ * ({@link buildDeclaredEngineWithoutCoordinatesRefusal} 给配置判官、{@link buildSqlPoolMissingRefusal} 给 `boot/stores.ts` 的记忆引擎同池门)。
+ *
+ * ## 为什么键表在这里、`config.ts` 的 `env("MYSQL_HOST")` 读法不动
+ * 配置目录的对账门按名字面扫 `env("NAME")` 与 `process.env.NAME`,把读法改成按表取名会让它看不见这些键;所以两块 `env()` 读仍是字面读,
+ * 本表与它们的一致由 `test/sql-engine-coordinates.test.ts` 的源码钉守(表里每个键在 `config.ts` 里恰有一处 `env("KEY")` 必需读)。
+ */
+/** SQL 引擎词(`DB_BACKEND` 闭集里的两只持久引擎;`local` / `memory` 没有坐标)。 */
+export type SqlEngine = "mysql" | "pg";
+/**
+ * 每只引擎开店**必需**的坐标键(缺一 `config.ts` 的对应块抛 `missing required env`)。可选键(`*_PORT` / `*_PASSWORD` / `*_POOL_SIZE`)不在表里 ——
+ * 它们缺席有缺省,不是「没有坐标」。主机键是首位:它是「SQL 信号」与 `auto` 探测的唯一判据(`config.ts` `dbHostSet`)。
+ */
+export declare const SQL_ENGINE_COORDINATE_KEYS: {
+    readonly mysql: readonly ["MYSQL_HOST", "MYSQL_USER", "MYSQL_DATABASE"];
+    readonly pg: readonly ["PG_HOST", "PG_USER", "PG_DATABASE"];
+};
+/** 该引擎的主机键(`SQL_ENGINE_COORDINATE_KEYS` 的首位)。 */
+export declare function sqlEngineHostKey(engine: SqlEngine): string;
+/** 必需坐标键里此刻缺席(未设或空串 —— 空串在本仓一律等同未设)的那几个,表序。只读键名,不读值。 */
+export declare function missingSqlCoordinateKeys(engine: SqlEngine, env: NodeJS.ProcessEnv): readonly string[];
+/**
+ * 显式 `DB_BACKEND=<engine>` 而该引擎的坐标缺席 ⇒ 配置期拒启句(唯一铸点;**与 `SESSION_BACKEND` 无关**,所以句子里没有它)。
+ * `missing` 是 {@link missingSqlCoordinateKeys} 的读数(此时至少含主机键)。
+ */
+export declare function buildDeclaredEngineWithoutCoordinatesRefusal(engine: SqlEngine, missing: readonly string[]): string;
+/**
+ * 记忆引擎要绑 `<engine>` 的池而店后端没给 ⇒ `boot/stores.ts` 的拒句。记忆持久面的 SQL 方言词与店的引擎词是**同一个字**(`MEMORY_ENGINE_BACKEND=pg|mysql`
+ * ↔ `DB_BACKEND=pg|mysql`),所以拒句只收引擎词。分两形(`DB_BACKEND` 是否已经点名该引擎):
+ *  · 没点名 ⇒ 缺的是声明:`MEMORY_ENGINE_BACKEND=<engine>` 要 `DB_BACKEND=<engine>`;
+ *  · 已点名 ⇒ 声明没缺,「要 DB_BACKEND=<engine>」指错了修法 —— 点名真正开店的两个条件(持久会话后端、必需坐标)与此刻缺的坐标键。
+ *    坐标缺席本身在配置期已被 {@link buildDeclaredEngineWithoutCoordinatesRefusal} 拒掉,走到这里的已点名形 = 坐标齐(或只缺非主机键)而会话后端是 `memory`。
+ */
+export declare function buildSqlPoolMissingRefusal(args: {
+    readonly engine: SqlEngine;
+    readonly declared: boolean;
+    readonly missing: readonly string[];
+}): string;
+//# sourceMappingURL=sql-engine-coordinates.d.ts.map

package/dist/sql-engine-coordinates.js

@@ -0,0 +1,27 @@
+export const SQL_ENGINE_COORDINATE_KEYS = {
+    mysql: ["MYSQL_HOST", "MYSQL_USER", "MYSQL_DATABASE"],
+    pg: ["PG_HOST", "PG_USER", "PG_DATABASE"],
+};
+export function sqlEngineHostKey(engine) {
+    return SQL_ENGINE_COORDINATE_KEYS[engine][0];
+}
+export function missingSqlCoordinateKeys(engine, env) {
+    return SQL_ENGINE_COORDINATE_KEYS[engine].filter((key) => env[key] === undefined || env[key] === "");
+}
+const ENGINE_LABEL = { mysql: "MySQL-protocol", pg: "PostgreSQL" };
+export function buildDeclaredEngineWithoutCoordinatesRefusal(engine, missing) {
+    const required = SQL_ENGINE_COORDINATE_KEYS[engine];
+    return (`DB_BACKEND=${engine} declares the ${ENGINE_LABEL[engine]} engine, but its connection coordinates are not set (missing: ${missing.join(", ")}) — ` +
+        `no session store can open, so the deployment would run IN MEMORY while declaring a durable engine. ` +
+        `Refusing to boot rather than starting non-durable under that declaration (whatever SESSION_BACKEND says). ` +
+        `To persist: set ${required.join(", ")} (optional: ${engine === "pg" ? "PG_PORT, PG_PASSWORD" : "MYSQL_PORT, MYSQL_PASSWORD"}); ` +
+        `to run without SQL: DB_BACKEND=local (single-user file store) or DB_BACKEND=memory.`);
+}
+export function buildSqlPoolMissingRefusal(args) {
+    const { engine, declared, missing } = args;
+    if (!declared)
+        return `MEMORY_ENGINE_BACKEND=${engine} requires DB_BACKEND=${engine} (the memory engine binds the same ${ENGINE_LABEL[engine]} pool) — refusing to start half-configured`;
+    return (`MEMORY_ENGINE_BACKEND=${engine} binds the ${ENGINE_LABEL[engine]} pool of the deployment's store, but none is open although the effective DB_BACKEND is ${engine}: the SQL store opens only under a durable session backend (SESSION_BACKEND unset, mysql or auto — not memory) ` +
+        `with ${SQL_ENGINE_COORDINATE_KEYS[engine].join(", ")} set${missing.length > 0 ? ` (not set now: ${missing.join(", ")})` : ""} — refusing to start half-configured`);
+}
+//# sourceMappingURL=sql-engine-coordinates.js.map