@sema-agent/server 7.93.6 → 7.94.0

package/USAGE.md

@@ -842,6 +842,14 @@ ENGINE_ORPHAN_LINGER_MS=2000  # 可选,默认 2s:成孤儿之后还要静多久
   引擎进程消失 2.0s、`LOCK` 归还 1.96s。最后那一段「停机收尾」本身还有自己的闸:`LOCK` 归还在收尾链
   尾部的 `backend.close()`,正常亚秒级,但卡死的连接池会被 `hardShutdown` 的 **15s 终局闸**兜住 ⇒ 最坏
   上界是「≤10s + 收尾闸」。自动重起的壳请按「撞锁就退避重试」写,别把 10s 当硬保证。
+- 🔴 **`DRAIN_GRACE_MS` 的生效值分车道 —— 别照抄出厂默认**:出厂 `600000`(10 min)是**服务器部署**的
+  取值(半夜一次滚动重启,宁可等长一点也不要砍掉一条在跑的 turn)。而**壳自 spawn 的引擎会被壳注入更短
+  的窗**:sema-cli 在装子进程 env 时把它填成一个分钟级的值(2026-09-22 亲读壳侧实现:`60000`;那是**壳的**
+  常量,以你手上那版壳为准 —— 单机形下这个窗直接等于"退出后多久不能重开",见上一条的撞锁退避),
+  **用户/运维显式设的值原样尊重、壳不覆盖**。⇒ 排壳形的关机/重开预算时,以**进程实际
+  生效值**为准:`GET /v1/config/catalog` 里 `DRAIN_GRACE_MS` 那一行的 `effectiveValue` 就是本进程真在用的
+  数(它读的是活 config,不是这份文档里的默认值),启动期的夹取/警告行同源。本文档其余各处谈这条排空腿
+  时都不带数字,数字只有这一处 —— 照抄默认值去算壳形预算会差一个数量级。
 - **自退留痕 `<数据根>/exit-last.json`**:自退在 **drain 开始那一刻**就把判据写进数据根(`orphan` /
   `reason` / `idleForMs` / `attached` / `inflight` / `lingerMs` + `version` / `at` / `pid`)。壳的 exit
   watch 往往在流断之后才跑,只看退出码分不清"它自己退的"与"它崩了";读到这个文件就能把这个 pid 归入

package/dist/boot/stores.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { FileBackgroundAgentStore, FileMailboxStore, FileRosterStore, FileUsageWindowStore, InMemoryUsageWindowStore, mailboxCrossProcessMountVerdict } from "@sema-agent/core";
+import { createCorruptReadSeat } from "../observability/corrupt-read-seat.js";
 import { createMemorySyncRunner, createMemorySyncTransport } from "../memory-sync-client.js";
 import { memoryEmbedderFor } from "../plugins/memory-embedder.js";
 import { ensurePgMemoryEmbedderMetaSchema, reconcileEmbedderFingerprint } from "../plugins/memory-embedder-fingerprint.js";
@@ -231,7 +232,7 @@ export async function openStores(ctx) {
         }
         else if (backend?.kind === "local") {
             rosterStore = new FileRosterStore(join(config.localDataRoot ?? localRoot, "roster.json"), {
-                onCorruptRead: (info) => logger.warn("roster_corrupt_read", { path: info.path, reason: info.reason }),
+                onCorruptRead: createCorruptReadSeat(logger.warn.bind(logger), "roster_corrupt_read"),
             });
         }
         if (rosterStore)
@@ -251,7 +252,9 @@ export async function openStores(ctx) {
             backgroundAgentStore = new TiDBBackgroundAgentStore(mysqlPool);
         }
         else if (backend?.kind === "local") {
-            backgroundAgentStore = new FileBackgroundAgentStore(config.localDataRoot ?? localRoot);
+            backgroundAgentStore = new FileBackgroundAgentStore(config.localDataRoot ?? localRoot, {
+                onCorruptRead: createCorruptReadSeat(logger.warn.bind(logger), "background_agent_corrupt_read"),
+            });
         }
         if (backgroundAgentStore)
             logger.info("background_agent_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
@@ -305,7 +308,7 @@ export async function openStores(ctx) {
         }
         else if (backend?.kind === "local") {
             mailboxStore = new FileMailboxStore(config.localDataRoot ?? localRoot, {
-                onCorruptRead: (info) => logger.warn("mailbox_corrupt_read", { path: info.path, reason: info.reason }),
+                onCorruptRead: createCorruptReadSeat(logger.warn.bind(logger), "mailbox_corrupt_read"),
             });
             mailboxRecipientLifecycle = createDropOnlyRecipientLifecycle(mailboxStore);
         }

package/dist/boot/workflow-orchestration.js

@@ -2,6 +2,7 @@ import { FileWorkflowRunStore, InMemoryWorkflowRunStore } from "@sema-agent/core
 import { join } from "node:path";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
 import { LocalWorkflowAgentSessionIndex } from "../orchestration/workflow-agent-session-index.js";
+import { createCorruptReadSeat } from "../observability/corrupt-read-seat.js";
 import { FileWorkflowCompletionInbox, InMemoryWorkflowCompletionInbox, resolveCompletionRoute } from "../orchestration/workflow-completion-inbox.js";
 import { FileWorkflowNotifyJournalStore, JournalingWorkflowRunStore, WorkflowNotifyGate } from "../orchestration/workflow-notify-journal.js";
 import { SubagentSteerRegistry } from "../orchestration/subagent-steer.js";
@@ -13,7 +14,10 @@ export function createWorkflowOrchestration(ctx) {
     const baseWorkflowRunStore = config.selfOrchestrationEnabled
         ? config.workflowRunStoreBackend === "memory"
             ? new InMemoryWorkflowRunStore()
-            : (sqlWorkflowRunStore ?? new FileWorkflowRunStore(join(config.localDataRoot ?? localRoot, "workflows")))
+            : (sqlWorkflowRunStore ??
+                new FileWorkflowRunStore(join(config.localDataRoot ?? localRoot, "workflows"), {
+                    onCorruptRead: createCorruptReadSeat(logger.warn.bind(logger), "workflow_run_corrupt_read"),
+                }))
         : undefined;
     const workflowNotifyJournal = config.selfOrchestrationEnabled && config.workflowRunStoreBackend !== "memory"
         ? (sqlWorkflowRunStore ? backend.notifyJournal() : new FileWorkflowNotifyJournalStore(join(config.localDataRoot ?? localRoot, "workflows")))

package/dist/config-catalog.js

@@ -127,7 +127,7 @@ export const CONFIG_CATALOG = [
     r("DOCKER_PATH", "orchestration", "path", "docker 二进制路径"),
     r("DOCKER_PIDS_LIMIT", "orchestration", "number", "local-docker fork-bomb 背栓(--pids-limit;非法值回 adapter 默认 512+warn)", { danger: SEC, derivedDefaultNote: "缺席 ⇒ adapter 默认 512" }),
     r("DOCKER_SANDBOX_ENV", "orchestration", "csv", "转发进容器的本进程 env **名字**表(值只在 worker env,不进 spec/center)", { danger: SEC }),
-    r("DRAIN_GRACE_MS", "limitsHttp", "number", "SIGTERM 优雅排空窗(ms;期间新计费提交 503+Retry-After)", { staticDefault: String(10 * 60 * 1000), configKey: "drainGraceMs", center: cLimits("drainGraceMs") }),
+    r("DRAIN_GRACE_MS", "limitsHttp", "number", "SIGTERM 优雅排空窗(ms;期间新计费提交 503+Retry-After)。出厂默认是**服务器部署**的取值;壳自 spawn 的引擎会被壳注入更短的窗 ⇒ 排壳形关机预算时以本行的 effectiveValue(= 本进程实际生效值)为准,不照抄 staticDefault", { staticDefault: String(10 * 60 * 1000), configKey: "drainGraceMs", center: cLimits("drainGraceMs") }),
     r("DURABLE_APPROVAL", "approval", "boolean", "durable suspend/resume HITL(需 SQL 店;决定 checkpointStore 与 /v1/approvals 面的存在性)", { danger: SEC, derivedDefaultNote: "posture 三态(S-178):显式词恒赢,缺席 = 单用户(REQUIRE_PRINCIPAL≠true)且有耐久店 ⇒ on / 多租户或无耐久店 ⇒ off;生效来源见 GET /v1/diagnostics/wiring 的 serverGates.durableApproval.source", configKey: "durableApproval" }),
     r("E2B_ALLOW_NET", "orchestration", "boolean", "e2b 沙箱出网许可", { danger: SEC, derivedDefaultNote: "缺席 ⇒ 不铸键(adapter 默认允许)" }),
     r("E2B_API_KEY", "orchestration", "secret", "E2B 车道 API 凭据(REMOTE_EXEC=e2b 必需件)", { danger: [...SEC, ...BILL] }),

package/dist/http/resume-ctx-read.d.ts

@@ -0,0 +1,40 @@
+/**
+ * **续跑上下文这一次读的结局**(S-577 第二半,7.94.0)—— 属主模块,所有消费腿共用这一只读口。
+ *
+ * 🔴 **为什么必须有这只铸点**:此前各消费腿各写一句 `.catch(() => null)`(还有一处把异常文案拼上 wire),
+ * 于是店层在 S-577 里把坏体从「答缺席」改成「响亮拒」之后,那些 `catch` 会把那次拒**原样吞回缺席** ——
+ * 机制上「坏体不再与缺席同答」成立,**用户面上不成立**(用户拿到的还是同一个 409)。判据要钉用户实际
+ * 拿到的码,这只铸点就是让那句判据有地方落(test [ref] 的判据订正,当拍采纳)。
+ *
+ * 三态与各自的理由:
+ *  · `ok` —— 读出来了。
+ *  · `absent` —— 行不在(`reapCtx` 按设计在 run 终态后删掉它),**或**读腿抛了一个**不是坏体**的错
+ *    (连接 / 超时 / 权限 / 店抖动):证不出它在就当它不在,**这是刻意保守**([ref] 方向锚:
+ *    拒绝可重试,搁浅不可)。
+ *  · `corrupt` —— 读腿抛了**坏体类**错(属主谓词 `isJsonColumnBodyProblem`:`not-json` / `malformed`)。
+ *    **不折成缺席**:两者的运维动作完全不同(前者去查那一行,后者什么都不用做)。
+ *    ⚠️ `not-text`(投影漂 = 我方的码病)**刻意不进这一态**,原样上抛、响亮成 500 —— 不许伪装成
+ *    「数据坏了」,更不许折成缺席(那会让一次代码漂看起来像「这条会话没有上下文」)。
+ */
+import type { CheckpointCtx } from "./route-ctx.js";
+export type ResumeCtxRead = {
+    readonly kind: "ok";
+    readonly ctx: CheckpointCtx;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "corrupt";
+    readonly where: string;
+};
+export declare function readResumeCtx(load: Promise<CheckpointCtx | null>): Promise<ResumeCtxRead>;
+/** 坏体的对外答复 —— 与会话策略面**同码**(`session-policy-wire.ts` 的 `corrupt` ⇒ 500),不铸新词。
+ *  文案只说「哪一行读不出来 + 该找谁」,不把店层 detail 拼上 wire(内部机件不上 wire,S-376 同律)。 */
+export declare function resumeCtxCorruptAnswer(where: string): {
+    status: number;
+    body: {
+        error: string;
+        errorCode: string;
+        where: string;
+    };
+};
+//# sourceMappingURL=resume-ctx-read.d.ts.map

package/dist/http/resume-ctx-read.js

@@ -0,0 +1,25 @@
+import { isJsonColumnBodyProblem, SqlJsonColumnError } from "../plugins/sql-json-column.js";
+export async function readResumeCtx(load) {
+    try {
+        const ctx = await load;
+        return ctx == null ? { kind: "absent" } : { kind: "ok", ctx };
+    }
+    catch (e) {
+        if (isJsonColumnBodyProblem(e))
+            return { kind: "corrupt", where: e.where };
+        if (e instanceof SqlJsonColumnError)
+            throw e;
+        return { kind: "absent" };
+    }
+}
+export function resumeCtxCorruptAnswer(where) {
+    return {
+        status: 500,
+        body: {
+            error: "the stored resume context for this session cannot be read — nothing was decided and nothing was resumed. Ask whoever operates this deployment to look at the row named in `where`: it has to be repaired or removed before this session can resume.",
+            errorCode: "corrupt",
+            where,
+        },
+    };
+}
+//# sourceMappingURL=resume-ctx-read.js.map

package/dist/http/resume-legs.js

@@ -35,6 +35,7 @@ import { gatedPrincipal, explicitOperatorOk } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
 import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
+import { readResumeCtx, resumeCtxCorruptAnswer } from "./resume-ctx-read.js";
 function isCheckpointReopenedFailure(r) {
     const code = failureCodeOf(r.terminal);
     return code === "resume.env_failed" || code === "resume.tool_unavailable" || code === "resume.tool_contract_mismatch";
@@ -278,13 +279,10 @@ export function createResumeLegs(ctx) {
                     : await startFreshHostTurn(plan.hostSessionId, plan.message, admittedPayer, req, parkedResume, plan.runId);
             }
         }
-        let ctx;
-        try {
-            ctx = await ctxPromise;
-        }
-        catch (e) {
-            return { status: 409, body: { error: `resume context load failed: ${e instanceof Error ? e.message : String(e)}`, errorCode: "conflict.resume_context_unavailable" } };
-        }
+        const ctxRead0 = await readResumeCtx(ctxPromise);
+        if (ctxRead0.kind === "corrupt")
+            return resumeCtxCorruptAnswer(ctxRead0.where);
+        const ctx = ctxRead0.kind === "ok" ? ctxRead0.ctx : null;
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
@@ -1036,9 +1034,12 @@ export function createResumeLegs(ctx) {
         if (gateKind !== RESUMABLE_GATE_KIND) {
             return { status: 409, body: { error: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a resumable resource/preempt suspension — an approval gate must be decided via POST /v1/approvals/:id/decide`, errorCode: "gate_not_resumable" } };
         }
-        const ctx = await cs.getCtx(sessionId).catch(() => null);
-        if (!ctx)
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        if (ctxRead.kind === "corrupt")
+            return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "absent")
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const ctx = ctxRead.ctx;
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
@@ -1050,7 +1051,10 @@ export function createResumeLegs(ctx) {
         if (!deps.runStore) {
             return { status: 501, body: { error: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)", errorCode: "capability.run_store_required" } };
         }
-        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        if (ctxRead.kind === "corrupt")
+            return resumeCtxCorruptAnswer(ctxRead.where);
+        const ctx = ctxRead.kind === "ok" ? ctxRead.ctx : null;
         if (!ctx) {
             return {
                 status: 409,
@@ -1140,9 +1144,12 @@ export function createResumeLegs(ctx) {
                 throw e;
             }
         }
-        const ctx = await cs.getCtx(sessionId).catch(() => null);
-        if (!ctx)
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        if (ctxRead.kind === "corrupt")
+            return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "absent")
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const ctx = ctxRead.ctx;
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
@@ -1222,9 +1229,12 @@ export function createResumeLegs(ctx) {
                 },
             };
         }
-        const ctx = await cs.getCtx(sessionId).catch(() => null);
-        if (!ctx)
+        const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
+        if (ctxRead.kind === "corrupt")
+            return resumeCtxCorruptAnswer(ctxRead.where);
+        if (ctxRead.kind === "absent")
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const ctx = ctxRead.ctx;
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const effMode = storedBodyPermissionMode(ctx.body);
         if (permissionModeAfter !== undefined && effMode !== "plan") {

package/dist/http/routes/images.js

@@ -331,6 +331,18 @@ export async function handleImages(req, res, match, ctx) {
                 sendError(res, 400, "request.field_invalid", "profile, repo, digest are required");
                 return;
             }
+            if (b.bands !== undefined && b.bands !== null && !Array.isArray(b.bands)) {
+                sendError(res, 400, "request.field_invalid", `bands must be an array when present`);
+                return;
+            }
+            const badObjectMeta = ["toolchainVersions", "capabilities", "podContract"].find((k) => {
+                const v = b[k];
+                return v !== undefined && v !== null && (typeof v !== "object" || Array.isArray(v));
+            });
+            if (badObjectMeta !== undefined) {
+                sendError(res, 400, "request.field_invalid", `${badObjectMeta} must be an object when present`);
+                return;
+            }
             const id = await idx.registerBuilding({
                 profile: b.profile,
                 bands: Array.isArray(b.bands) ? b.bands : [],

package/dist/http/routes/runs.js

@@ -29,6 +29,7 @@ import { assertNever } from "../route-ctx.js";
 import { mintAndDriveDurableRun } from "../durable-run-leg.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
 import { withPrincipal } from "../../observability/principal-context.js";
+import { readResumeCtx } from "../resume-ctx-read.js";
 const ASK_PARKING_RETRY_AFTER_SEC = 2;
 const ASK_ACTOR_LABEL_MAX = 256;
 const AskDecisionActorSchema = ActorAssertionWire.strip();
@@ -588,8 +589,12 @@ export async function handleRuns(req, res, match, ctx) {
                 const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
                 if (leafId === undefined || leafId === null)
                     return;
-                const resumeCtx = await Promise.resolve(cs.getCtx(run.sessionId)).catch(() => null);
-                if (resumeCtx === null || resumeCtx === undefined) {
+                const resumeRead = await readResumeCtx(Promise.resolve(cs.getCtx(run.sessionId)));
+                if (resumeRead.kind === "corrupt") {
+                    mintResult.corruptCtxWhere = resumeRead.where;
+                    return;
+                }
+                if (resumeRead.kind === "absent") {
                     mintResult.noResumeCtx = true;
                     return;
                 }
@@ -607,8 +612,13 @@ export async function handleRuns(req, res, match, ctx) {
                     createdAt: Date.now(),
                     sourceTaskId: taskId,
                 });
-                const ctxStillThere = await Promise.resolve(cs.getCtx(run.sessionId)).catch(() => null);
-                if (ctxStillThere === null || ctxStillThere === undefined) {
+                const stillRead = await readResumeCtx(Promise.resolve(cs.getCtx(run.sessionId)));
+                if (stillRead.kind === "corrupt") {
+                    await cs.expire(wakeToken, cpScope).catch(() => undefined);
+                    mintResult.corruptCtxWhere = stillRead.where;
+                    return;
+                }
+                if (stillRead.kind !== "ok") {
                     await cs.expire(wakeToken, cpScope).catch(() => undefined);
                     mintResult.noResumeCtx = true;
                     return;
@@ -638,6 +648,10 @@ export async function handleRuns(req, res, match, ctx) {
                 sendDuplicateKey();
                 return;
             }
+            if (mintResult.corruptCtxWhere !== undefined) {
+                sendError(res, 500, "corrupt", "run already ended and this session's stored resume context cannot be read — no wake card was minted and nothing was queued. Ask whoever operates this deployment to repair or remove the row named in `where` before steering this session again.", { where: mintResult.corruptCtxWhere });
+                return;
+            }
             if (mintResult.noResumeCtx) {
                 sendError(res, 409, "conflict.resume_context_unavailable", "run already ended and this session's resume context is gone — a steer queued now could never be delivered by POST /v1/sessions/:id/wake; submit a new task instead");
                 return;

package/dist/http/routes/workflows.js

@@ -2,7 +2,8 @@ import { persistedPlaneOf } from "../../terminal.js";
 import { z } from "zod";
 import { getWorkflowRun, subscribeWorkflow, deriveAgentDisplayStatus, callKeyOrdinal } from "@sema-agent/core";
 import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../../orchestration/workflow-agent-steer.js";
-import { journalEntryOfRow, journalEntryPayload, journalRowPayloadOf } from "../../orchestration/workflow-journal-entry.js";
+import { journalEntryOfBody, journalEntryPayload, journalRowPayloadOf, readJournalRowBody } from "../../orchestration/workflow-journal-entry.js";
+import { decodeJsonColumn } from "../../plugins/sql-json-column.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { createHash } from "node:crypto";
 import { redactErrorMessage, redactHead } from "../../observability/run-terminal.js";
@@ -108,7 +109,7 @@ export async function handleWorkflows(req, res, match, ctx) {
                         return oversizeStub(row.callKey, row.resultBytes);
                     }
                     try {
-                        const { payload, parked } = journalEntryPayload(journalEntryOfRow(row.callKey, row.resultJson));
+                        const { payload, parked } = journalEntryPayload(journalEntryOfBody(row.callKey, decodeJsonColumn(row.resultJson, readJournalRowBody, `workflow_journal.result for entry ${row.callKey}`)));
                         return projectEntry(row.callKey, payload, parked);
                     }
                     catch {

package/dist/observability/corrupt-read-seat.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 🔴 **腐读披露座的唯一属主**(S-569,core 7.28.1 提货批;#1013 F4 的 server 半场)。
+ *
+ * ## core 那边发生了什么
+ * core 对**读不出来的**持久文件是 documented fail-open —— 当作「缺席」继续跑(抛会让整条任务死,也会
+ * 自锁修复写)。7.27.0(#1013 F4)把这条 fail-open 的披露面收成**一只共用 guard**
+ * (`stores/file/corrupt-read-sink.js`:`CorruptReadInfo` + `guardCorruptSink`),并给每一只容错 File 店
+ * 都开了座 —— core 自己的原话是那只 guard「hand-written four times」,其中三份包住了 async sink 的
+ * rejection、mailbox 那份只包住同步 throw。**同一个病,server 这侧也有**:座的载荷投影当时在本仓被
+ * 手抄了四遍(roster / mailbox / run-local 与 store-backend 的两只 FileStorageBackend)。
+ *
+ * ## 为什么是一个属主,而不是第五、六、七、八份手抄([ref])
+ * 7.27.0 之后 server 真构造的店里又多出**四只空座**(`FileCheckpointStore` / `FileWorkflowRunStore` /
+ * `FileBackgroundAgentStore` / `FileWorkflowJournalStore`)。按老形接线 = 八处各写一遍
+ * `{ path, reason, ...可选成员 }` 的转发 —— 而这八处**本来就该是同一句话**:
+ *
+ *   「一次持久读因为字节读不出来被当成了缺席。ENOENT 不触发(那是真缺席,不是腐读)。」
+ *
+ * 载荷形不是本仓铸的:`FileStorageCorruptReadInfo` 是 **core 的导出**,并且是 core 亲口说的**最宽**那一只
+ * ——"the widest shape any store this backend constructs can deliver, so ONE sink reaches all of them…
+ * the two-field store seats are satisfied by it"。于是本属主就按那只最宽形收参:两个窄座
+ * (`CorruptReadInfo = {path, reason}`)与 roster/mailbox 的内联形都因**可选成员**而逐字接受它
+ * (`{path,reason}` 可赋给最宽形 ⇒ 吃最宽形的函数可赋给窄座)。**本仓因此零镜像类型**。
+ *
+ * ## 刻意不做的两件事
+ * · **不在这里下统一结论**:后果按脸各不相同(少了会话规则这一层 / 列表静默少行 / rewind 边界读成缺席 /
+ *   durable park 丢一行 / resume 读到「无事可重放」于是把活重跑),把其中一种写成「整个任务无约束」会误导
+ *   事故定级,而且对另外几张脸根本不成立(codex R2-medium 的原案)。所以 `note` 是**按脸传进来的一句话**,
+ *   不是本属主里的一张词表 —— 属主里放一张「事件名 → 后果句」的表,等于把调用点的知识搬进属主再抄回去。
+ * · **不接 `recordFailOpen`**:那条通道是给 F 类(装饰/缓存)fail-open 的计数与探针用的;这里的 fail-open
+ *   是 core 的裁定、本仓不改它,server 的职责只有一条 —— **不许无声**([ref] 安全轴纪律)。响亮 warn 就是
+ *   那条职责的兑现;要不要再进 fail-open 台账是另一件事、另一台车的设计。
+ *
+ * ⚠️ core 那只 guard 的纪律同样适用:sink 是**无绑定**调用的(`this` 是 undefined)。本属主返回的是箭头
+ * 闭包,天然满足;但**不要**把某个对象的裸方法引用直接塞进座 —— 读 `this` 会抛,而那个抛会被 core 的
+ * guard 吞掉,于是披露**静默丢失**(比没接座更难查)。
+ */
+import type { FileStorageCorruptReadInfo } from "@sema-agent/core";
+import type { Logger } from "./logger.js";
+/**
+ * 铸一只腐读披露座。
+ *
+ * @param warn 日志座。形取 `Logger["warn"]` —— 本仓日志 sink 形的既有属主,`plugins/store-backend.ts` 的
+ *   `BootLogSink` 结构上就是它,所以这里**不引入第三种拼法**。
+ * @param event warn 事件名。**留在调用点**:它是那只店的身份,接线锚(test/roster-corrupt-read.test.ts)
+ *   正是靠「构造实参里能读到这个名字」来证明座不是个空回调。
+ * @param note 这张脸的后果句(可选)。缺席 ⇒ 不写这个键。
+ */
+export declare function createCorruptReadSeat(warn: Logger["warn"], event: string, note?: string): (info: FileStorageCorruptReadInfo) => void;
+/**
+ * `FileStorageBackend` 那两只座共用的后果句 —— 一个座覆盖 core 转发的三张脸,所以共同事实只有一句,
+ * 差别只在第三张脸叫什么(`run-local` 腿看到的是 file-snapshot,HTTP 服务腿看到的是 file-history)。
+ * 这一句从前在两处各抄一份、只差一个词;现在词从参数来,句子只有一份。
+ */
+export declare function buildDurableAbsenceNote(thirdFace: string): string;
+//# sourceMappingURL=corrupt-read-seat.d.ts.map

package/dist/observability/corrupt-read-seat.js

@@ -0,0 +1,16 @@
+export function createCorruptReadSeat(warn, event, note) {
+    return (info) => warn(event, {
+        path: info.path,
+        reason: info.reason,
+        ...(info.sessionId !== undefined ? { sessionId: info.sessionId } : {}),
+        ...(info.principal !== undefined ? { principal: info.principal } : {}),
+        ...(note !== undefined ? { note } : {}),
+    });
+}
+export function buildDurableAbsenceNote(thirdFace) {
+    return ("a durable read was treated as ABSENT because the bytes were unreadable (never a plain ENOENT). " +
+        "Consequence depends on which store read it: session-policy = that run lost its SUBTRACTIVE session-rule " +
+        "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
+        `rows; ${thirdFace}. Inspect the named path before deciding.`);
+}
+//# sourceMappingURL=corrupt-read-seat.js.map

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

@@ -137,6 +137,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-550(`plugins/run-store-sql.ts` 的 `usageScan`,`/v1/usage/*` 的扫窗腿):窗内某一行的 `task_run.result` 这一格读不出形 ⇒ 这一行**计 tasks、不计 token/cost**(`stats` 键缺席),其余行照常。放行的最坏后果 = 用量总数偏低一行的量(`projectUsageStats` 的成文降级口径逐字如此,三个后端共用);不放行的代价是**一行坏 cell 打掉整个租户的用量页**(扫窗上限 50k 行)。⚠️ 同一列在 `getRun` / `listRuns` 两条腿上**刻意相反**(抛,不容忍):那两条腿上这一格是提交方要的**答案**,把它折成「跑完了没有结果」是在替一次不知道的读编一个答案;而这里它只是一个加数。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。";
     };
+    readonly "server.sql-json.memory-engine.embedding": {
+        readonly cls: "F";
+        readonly note: "S-550 车③a(`plugins/memory-engine-pg.ts` 的 `search()` 便携档):一行 `agent_memory_engine_entry.embedding` 这一格读不出形(撕裂字节 / 手改 / 不是 JSON 数组 / `null` 字面)⇒ **这一行退到词面档打分**,行**从不消失**(这一列的成文口径逐字如此:any missing/invalid side falls open to the lexical floor for THIS row)。放行的最坏后果 = 这一行的排名按词面算、可能靠后;不放行的代价是**一行坏 cell 打掉整个 scope 的记忆检索**(`search()` 是 `rows` 的整只循环)。这一列不携任何授权 / 来源 / 曝光带事实(那些全在 `frontmatter`,它照旧**拒**)。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。⚠️ 如实交代:改调前 `not-json` 经裸 `JSON.parse` **抛**、而「解出来不是数组」只降级 —— 同一列两个方向;本车把两支收成一支(降级 + 留痕),这是 S-550 整批**唯一**一处把原本 fail-closed 的臂改成容忍。";
+    };
     readonly "server.retention.sweep-report-dropped": {
         readonly cls: "F";
         readonly note: "留存 sweep 的**失败上报**自己抛了(poison error 的 toString / 一条抛异常的 logger transport)⇒ 那一条 warn 与 stuck 指标发不出去。放行的最坏后果是**可观测性**损失而不是数据面损失:删除与审计的正确性完全在店事务里,本臂只影响运维看不看得见「这个域连败了」。不放行的后果反而更坏 —— 一个从上报里逃出去的异常会打断 per-domain 循环、饿死后面每一个域(reapers 的同款保护逐字同理由)。";

package/dist/observability/fail-open.js

@@ -128,6 +128,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-550(`plugins/run-store-sql.ts` 的 `usageScan`,`/v1/usage/*` 的扫窗腿):窗内某一行的 `task_run.result` 这一格读不出形 ⇒ 这一行**计 tasks、不计 token/cost**(`stats` 键缺席),其余行照常。放行的最坏后果 = 用量总数偏低一行的量(`projectUsageStats` 的成文降级口径逐字如此,三个后端共用);不放行的代价是**一行坏 cell 打掉整个租户的用量页**(扫窗上限 50k 行)。⚠️ 同一列在 `getRun` / `listRuns` 两条腿上**刻意相反**(抛,不容忍):那两条腿上这一格是提交方要的**答案**,把它折成「跑完了没有结果」是在替一次不知道的读编一个答案;而这里它只是一个加数。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。",
     },
+    "server.sql-json.memory-engine.embedding": {
+        cls: "F",
+        note: "S-550 车③a(`plugins/memory-engine-pg.ts` 的 `search()` 便携档):一行 `agent_memory_engine_entry.embedding` 这一格读不出形(撕裂字节 / 手改 / 不是 JSON 数组 / `null` 字面)⇒ **这一行退到词面档打分**,行**从不消失**(这一列的成文口径逐字如此:any missing/invalid side falls open to the lexical floor for THIS row)。放行的最坏后果 = 这一行的排名按词面算、可能靠后;不放行的代价是**一行坏 cell 打掉整个 scope 的记忆检索**(`search()` 是 `rows` 的整只循环)。这一列不携任何授权 / 来源 / 曝光带事实(那些全在 `frontmatter`,它照旧**拒**)。故 F 类;**只容忍体的问题**,`not-text`(读腿漏了投影)与连接 / 超时原样上抛。⚠️ 如实交代:改调前 `not-json` 经裸 `JSON.parse` **抛**、而「解出来不是数组」只降级 —— 同一列两个方向;本车把两支收成一支(降级 + 留痕),这是 S-550 整批**唯一**一处把原本 fail-closed 的臂改成容忍。",
+    },
     "server.retention.sweep-report-dropped": {
         cls: "F",
         note: "留存 sweep 的**失败上报**自己抛了(poison error 的 toString / 一条抛异常的 logger transport)⇒ 那一条 warn 与 stuck 指标发不出去。放行的最坏后果是**可观测性**损失而不是数据面损失:删除与审计的正确性完全在店事务里,本臂只影响运维看不看得见「这个域连败了」。不放行的后果反而更坏 —— 一个从上报里逃出去的异常会打断 per-domain 循环、饿死后面每一个域(reapers 的同款保护逐字同理由)。",

package/dist/orchestration/workflow-journal-entry.d.ts

@@ -16,7 +16,7 @@
  * 收敛到这里之后,第三臂到货 ⇒ 本文件**一处**编译红。
  *
  * 🔴 **park 臂的形是 fail-closed 的**:core 的类型要求 `parked.terminal.kind === "paused"`。从盘上读回来的
- * 字节没有类型,所以 {@link journalEntryOfRow} 在铸 park 臂时**亲验**这一位,不合就**抛**——它是 LOAD-BEARING
+ * 字节没有类型,所以 {@link readJournalRowBody} 在铸 park 臂时**亲验**这一位,不合就判坏——它是 LOAD-BEARING
  * 面上的坏行(一条说自己 park 了却拿不出暂停终局的记录,既不能驱动、也不能当成跑完),吞掉它会让 resume
  * 在一个被钉住的子代 session 旁边重新起一只活跑,正是 core 那条「一次性、响亮」的 schema 台阶要防的形。
  *
@@ -25,6 +25,7 @@
  * 而不是把一个暂停终局当成可重放结果)。
  */
 import type { TaskResult, WorkflowJournalEntry } from "@sema-agent/core";
+import type { JsonColumnReader } from "../plugins/sql-json-column.js";
 /** park 臂的载荷型(core 的 `WorkflowJournalEntry` park 成员逐字):一只 `terminal` 收敛到 `paused` 的 `TaskResult`。 */
 export type ParkedTaskResult = TaskResult & {
     terminal: Extract<TaskResult["terminal"], {
@@ -63,16 +64,33 @@ export declare function journalEntryPayload(entry: WorkflowJournalEntry): {
  */
 export declare function journalRowPayloadOf(entry: WorkflowJournalEntry): string;
 /**
- * {@link journalRowPayloadOf} 的逆 —— 盘上一行的 payload 文本 → 记录。**唯一**的回装点(SQL 店的 `load`
- * 与 HTTP journal 读面共读它)。
+ * 盘上一行 payload 的**形读者**(S-550 车③a:`workflow_journal.result` 这一列的唯一判据)。
  *
  * 判别式 = 解出来的对象上有没有**自有** `parked` 键。它与 `TaskResult` 结构上不相交(core 的 `TaskResult`
  * 没有这个成员),所以历史字节(裸 TaskResult)恒判 result 臂 —— 不需要任何「老字节 = result」的兼容规则,
  * 判别式自己就说清了。
  *
- * park 臂验 `terminal.kind === "paused"`;不合 ⇒ **抛**,由 LOAD-BEARING 的 `load` 把它当店故障传上去。
+ * park 臂验 `terminal.kind === "paused"`;不合 ⇒ 判坏,由 LOAD-BEARING 的读腿把它当店故障传上去。
  * 一条「说自己 park 了却拿不出暂停终局」的行既驱动不了、也不能当跑完,吞掉它会让 resume 在被钉住的子代
- * session 旁边重新起一只活跑 —— 与上面那条屏障要防的是同一件事。
+ * session 旁边重新起一只活跑 —— 与 {@link journalRowPayloadOf} 那道信封屏障要防的是同一件事。
+ *
+ * 🔴 **「一只 JSON 对象」这一条也必须判**(S-550):此前回装点是裸 `JSON.parse` + `as TaskResult`,于是
+ * 一行 `null` 字面 / JSON 字符串标量 / 双重编码的 `result` 会被当成一条**合法的已完成记录**端给 resume
+ * (`{callKey, result: null}`)—— 那正是「一次已完成的子代被当成跑过而不再跑」与「一条坏行冒充跑完」
+ * 两种最坏形的同一个入口。
+ */
+export declare const readJournalRowBody: JsonColumnReader<JournalRowBody>;
+/** {@link readJournalRowBody} 收窄出来的两臂(判别位已定,载荷已验形)。 */
+export type JournalRowBody = {
+    parked: true;
+    payload: ParkedTaskResult;
+} | {
+    parked: false;
+    payload: TaskResult;
+};
+/**
+ * {@link journalRowPayloadOf} 的逆的**后半**:已解码、已验形的载荷 → 记录。**唯一**的铸点(SQL 店的 `load`
+ * 与 HTTP journal 读面共读它;两处各自经 `decodeJsonColumn(text, readJournalRowBody, …)` 把文本收成这只体)。
  */
-export declare function journalEntryOfRow(callKey: string, json: string): WorkflowJournalEntry;
+export declare function journalEntryOfBody(callKey: string, body: JournalRowBody): WorkflowJournalEntry;
 //# sourceMappingURL=workflow-journal-entry.d.ts.map

package/dist/orchestration/workflow-journal-entry.js

@@ -5,16 +5,23 @@ export function journalRowPayloadOf(entry) {
     const { payload, parked } = journalEntryPayload(entry);
     return JSON.stringify(parked ? { parked: payload } : payload);
 }
-export function journalEntryOfRow(callKey, json) {
-    const raw = JSON.parse(json);
-    if (typeof raw === "object" && raw !== null && Object.hasOwn(raw, "parked")) {
-        const payload = raw.parked;
-        const terminal = payload.terminal;
-        if (terminal === undefined || terminal.kind !== "paused") {
-            throw new Error(`workflow journal: entry ${callKey} is recorded as PARKED but its stored terminal is "${terminal === undefined ? "absent" : terminal.kind}" (expected "paused") — refusing to admit it (a park row that cannot be driven must not be replayed as a completed result)`);
-        }
-        return { callKey, parked: { ...payload, terminal } };
+export const readJournalRowBody = (body) => {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return { problem: "expected a JSON object (a TaskResult, or the `{parked: …}` envelope)" };
     }
-    return { callKey, result: raw };
+    if (!Object.hasOwn(body, "parked"))
+        return { value: { parked: false, payload: body } };
+    const payload = body.parked;
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return { problem: "the `parked` envelope does not carry an object" };
+    }
+    const terminal = payload.terminal;
+    if (terminal === undefined || terminal.kind !== "paused") {
+        return { problem: `recorded as PARKED but its stored terminal is "${terminal === undefined ? "absent" : terminal.kind}" (expected "paused") — a park row that cannot be driven must not be replayed as a completed result` };
+    }
+    return { value: { parked: true, payload: { ...payload, terminal } } };
+};
+export function journalEntryOfBody(callKey, body) {
+    return body.parked ? { callKey, parked: body.payload } : { callKey, result: body.payload };
 }
 //# sourceMappingURL=workflow-journal-entry.js.map

package/dist/plugins/approval-ask-store-sql.js

@@ -1,7 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
-import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readAnyJsonValueColumn, readJsonObjectColumn } from "./sql-json-column.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 export function assertIntegralEpochMs(field, value) {
     if (!Number.isSafeInteger(value)) {
@@ -284,7 +284,7 @@ function mapAskRowBody(r, askId) {
         decisionActor: r.decision_actor == null ? null : decodeJsonColumn(r.decision_actor, readJsonObjectColumn, `${APPROVAL_ASK_TABLE}.decision_actor for ask ${askId}`),
         decisionNote: strOrNull(r.decision_note),
         settledBy: strOrNull(r.settled_by),
-        ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readAnyJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
+        ...(r.updated_input == null ? {} : { updatedInput: decodeJsonColumn(r.updated_input, readTriStateJsonValueColumn, `${APPROVAL_ASK_TABLE}.updated_input for ask ${askId}`) }),
         decidedAtMs: numOrNull(r.decided_at_ms),
         deniedReason: strOrNull(r.denied_reason),
         gateToken: strOrNull(r.gate_token),

package/dist/plugins/checkpoint-store-sql.d.ts

@@ -760,9 +760,22 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     peekPendingScope(sessionId: string, binding?: PendingRowBinding): Promise<string | null | undefined>;
     /** Upsert the resume rebuild inputs for a session — written at SUBMIT (durable mode on) and, since S-433 F2,
      *  once per resume leg at its CAS win point (`DriveResumeArgs.resumeCtx`). Unconditional per `session_id`:
-     *  the ordering fence lives at the CALLER's CAS win, not in a version column here. */
-    putCtx(sessionId: string, ctx: unknown): Promise<void>;
-    getCtx<T = unknown>(sessionId: string): Promise<T | null>;
+     *  the ordering fence lives at the CALLER's CAS win, not in a version column here.
+     *
+     *  🔴 `ctx: object`, not `unknown` (S-577): the read leg judges this column as a JSON **object**
+     *  ({@link decodeCtxColumn}), so a writer that took `unknown` would be the "writes fine, reads back
+     *  refused" asymmetry this repo keeps paying for — and `putCtx(sessionId, null)` was exactly the
+     *  reachable arm that made the JSON literal `null` (indistinguishable from "no such row" at every
+     *  consumption point) a zero-corruption possibility. All six call sites already pass an object.
+     *
+     *  🔴 The TYPE is not the whole gate (codex adversarial review [medium], verified then fixed as a class):
+     *  `object` admits arrays, `Date`, and objects whose `toJSON()` yields a scalar or `null` — each of those
+     *  serializes to bytes THIS STORE'S READ LEG REFUSES, and the upsert is unconditional, so the write would
+     *  SUCCEED and replace a readable durable row with an unreadable one (caller sees 2xx, the next resume
+     *  409s forever). So the serialized value is judged by {@link assertJsonColumnWritable} — the SAME shape
+     *  reader the read leg uses — BEFORE the statement runs: refuse loudly, leave the row on disk untouched. */
+    putCtx(sessionId: string, ctx: object): Promise<void>;
+    getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
     /**
      * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
      * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.