@sema-agent/server 7.63.0 → 7.65.0

package/dist/read-face-posture.d.ts

@@ -0,0 +1,52 @@
+/**
+ * S-167(clay 裁定 2,[ref] 转达 / [ref] ②)—— **READ 容纳面档位的来源**(单一属主)。
+ *
+ * ## 它解决的问题
+ *
+ * `READ_FACE` 此前只有「显式设了就铸、缺席就不铸」两态,而**缺席**这一态里其实塞了两件完全不同的事:
+ *  · 单机 turnkey(`REQUIRE_PRINCIPAL` 未设,CC 的信任模型:一台机器一个可信主人)—— 运维没表态是因为
+ *    他压根不认为工作区外的读需要围栏;引擎默认的 `roots` 于是成了一道**没人要求过**的墙(clay 裁:
+ *    「工作区外读默认放行(单机形)」)。
+ *  · 多租户 —— 缺席就是缺席,引擎默认 `roots` 正是想要的收敛姿态。
+ *
+ * 于是本模块把「档位」与「档位是谁定的」拆成两个字段:值仍是 `open | roots | 缺席`,来源是本文件的
+ * **四词闭集**。来源不是装饰:
+ *  ① `config-center/read-face.ts` 的 **env 恒赢**判据此前用的是「`config.readFace` 键在不在场」这个
+ *     **代理**;posture 会铸键,代理当场失真(center 的 face 会被一台从没设过 env 的机器挡掉)。
+ *     换成读来源之后判据说的就是它真正想说的那件事:**这台机器的 env 显式占住了这个键吗**。
+ *  ② 运维面:`GET /v1/diagnostics/wiring` 报 `{face, source, note}`,「为什么这台机器是 open」有答案
+ *     (裁定的补偿项:升级即放开,得让运维看得见并知道怎么钉回)。
+ *
+ * ## 优先序(三态,与 `config.ts` 的 `postureOn` 同形)
+ * `env 显式` > `center 发布` > `posture 派生` > `引擎默认`。env 恒赢的论证逐字见 `config-center/read-face.ts`
+ * 头注①(READ 容纳面描述的是**这台机器的磁盘上有什么**,组织的下发面不知道)。
+ *
+ * ## 定界
+ * 本模块**只**管 `face` 一档。内建读拒表(`readDenyPatterns` / `readDenyBuiltinTiers` /
+ * `readDenyBuiltinExclude`)一个字节不动 —— 放开容纳面不等于放开凭证/shell 历史/钱包那几档 deny,
+ * 两者在 core 里是并列机制(deny 表在 open 面上照样拦)。core 的 `config.read_face_deployment_clamped`
+ * (只读挂载钳制)同样不受本件影响。
+ */
+/** 档位来源的闭集词表(顺序 = 优先序:env > center > posture > 引擎默认)。 */
+export declare const READ_FACE_SOURCE_WORDS: readonly ["env", "center", "posture", "engine-default"];
+/** 档位的来源(闭集四词)。加词 ⇒ {@link readFaceSourceNote} 的穷举 switch 编译红。 */
+export type ReadFaceSource = (typeof READ_FACE_SOURCE_WORDS)[number];
+/** 一台 worker 的 READ 面档位事实(值 + 来源)。`ServiceConfigFlat` 结构上满足本形。 */
+export interface ReadFacePostureFacts {
+    readonly readFace?: "open" | "roots" | undefined;
+    readonly readFaceSource: ReadFaceSource;
+}
+/**
+ * 缺席 `READ_FACE` 时的 posture 派生(`config.ts` 的铸点调用;显式值不经此口)。
+ * 单用户 turnkey ⇒ `open`;多租户 ⇒ 不铸(引擎默认 `roots`,server 不复制上游默认)。
+ */
+export declare function readFaceForPosture(singleUserTurnkey: boolean): ReadFacePostureFacts;
+/** 运维指路句 —— **穷举 switch,无缺省臂**:四词闭集加一个成员这里就编译红。 */
+export declare function readFaceSourceNote(source: ReadFaceSource): string;
+/** operator 诊断面的投影(`GET /v1/diagnostics/wiring`)。`face:null` = 本部署没钉档,引擎默认接管。 */
+export declare function buildReadFaceWiring(facts: ReadFacePostureFacts): {
+    face: "open" | "roots" | null;
+    source: ReadFaceSource;
+    note: string;
+};
+//# sourceMappingURL=read-face-posture.d.ts.map

package/dist/read-face-posture.js

@@ -0,0 +1,20 @@
+export const READ_FACE_SOURCE_WORDS = ["env", "center", "posture", "engine-default"];
+export function readFaceForPosture(singleUserTurnkey) {
+    return singleUserTurnkey ? { readFace: "open", readFaceSource: "posture" } : { readFaceSource: "engine-default" };
+}
+export function readFaceSourceNote(source) {
+    switch (source) {
+        case "env":
+            return "pinned by this machine's READ_FACE env var (deployment sovereignty — it wins over any published readFace domain)";
+        case "center":
+            return "applied from the config-center readFace domain (restart-to-apply); set READ_FACE on this machine to take the key back";
+        case "posture":
+            return "derived from the single-user turnkey posture (REQUIRE_PRINCIPAL is not set): reads outside the workspace roots are allowed by default — set READ_FACE=roots to pin the containing posture back";
+        case "engine-default":
+            return "not pinned by this deployment — the engine's own default (roots) is in force";
+    }
+}
+export function buildReadFaceWiring(facts) {
+    return { face: facts.readFace ?? null, source: facts.readFaceSource, note: readFaceSourceNote(facts.readFaceSource) };
+}
+//# sourceMappingURL=read-face-posture.js.map

package/dist/run-local.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { terminalProjection } from "@sema-agent/core";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { realpathSync } from "node:fs";
@@ -513,16 +514,17 @@ export async function runLocal(argv, deps = {}) {
     if (args.json) {
         print(JSON.stringify(result, null, 2));
     }
-    else if (result.status === "completed") {
+    else if (result.terminal.kind === "completed") {
         print(result.result);
     }
     else {
-        const salvage = result.result || result.salvagedOutput || result.blockedReason || "";
+        const plane = terminalProjection(result.terminal);
+        const salvage = result.result || result.salvagedOutput || plane.blockedReason || "";
         if (salvage)
             print(salvage);
-        printErr(`task ${result.status}${result.errorCode ? ` (${result.errorCode})` : ""}${result.errorMessage ? `: ${result.errorMessage}` : ""}`);
+        printErr(`task ${plane.status}${plane.errorCode ? ` (${plane.errorCode})` : ""}${plane.errorMessage ? `: ${plane.errorMessage}` : ""}`);
     }
-    if (result.status !== "completed")
+    if (result.terminal.kind !== "completed")
         exitCode = 1;
     if (memorySync) {
         try {

package/dist/runs.d.ts

@@ -1,4 +1,4 @@
-import { defaultTaskRegistry, type CascadeConfig, type CheckpointToken, type Runner, type SubagentSteerHandle, type TaskResult, type TaskSpec, type TaskStream } from "@sema-agent/core";
+import { defaultTaskRegistry, type CascadeConfig, type CheckpointToken, type Runner, type SubagentSteerHandle, type TaskResult, type TaskSpec, type TaskStream, type TerminalCause } from "@sema-agent/core";
 import type { SendUserFileEmitter } from "./capabilities/send-user-file-tool.js";
 import type { RunStore } from "./plugins/store-backend.js";
 import type { Metrics } from "./observability/metrics.js";
@@ -91,13 +91,11 @@ export declare function taskHandleStop(registry: typeof defaultTaskRegistry, han
 export declare function markChildrenStoppedByUserOnAbort(signal: AbortSignal, taskId: string, principal: string | null | undefined): void;
 /**
  * A session CAS conflict is swallowed by core into a failed `TaskResult` (it is not thrown from
- * `runTaskStream`), so detect it from the result. Prefer the structured `errorCode` (core ≥1.8); fall
+ * `runTaskStream`), so detect it from the result. Prefer the structured `code` (core ≥1.8); fall
  * back to the conflict wording only for older results without one.
  */
 export declare function isSessionConflictResult(result: {
-    status: string;
-    errorMessage?: string;
-    errorCode?: string;
+    terminal: TerminalCause;
 }): boolean;
 /**
  * E18 resume-at CALLER error → an HTTP 4xx. A bad/stale resume-at target (the resolved entryId is gone or is not a
@@ -151,8 +149,7 @@ export declare function isSessionConflictResult(result: {
  * 缺口(不是本批回归),已在上述对表格里逐码显式登记为债务,并由那道门看住不许陈腐。
  */
 export declare function resumeAtHttpStatus(result: {
-    status: string;
-    errorCode?: string;
+    terminal: TerminalCause;
 }): number | undefined;
 /**
  * E18 resume-at — per-turn anchor capture, shared by runInBackground AND the resume-leg driveResume so the (single,
@@ -207,18 +204,6 @@ export declare class TurnAnchorCapture {
     /** turn_end — capture the anchor iff this was a settled assistant-TEXT turn, then reset for the next turn. */
     onTurnEnd(): Promise<void>;
 }
-/**
- * Strip the durable-resume capability token from a result before it is persisted to the replayable event
- * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
- * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended"(inner status
- * "needs_review" ⇒ "unexpected.needs_review";core `agents/suspend-guard.js` `mapNestedSuspend`,由 verify.js
- * 191/201/208 与 cascade.js:125 调用)while still
- * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
- * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
- * non-secret and intentionally kept.
- */
-export declare function stripCheckpointToken<T>(result: T): T;
 /** [ref] 投影腿的最小 checkpoint 读口(结构型——真店 `CheckpointStore.get` 直接对上)。 */
 type ParkCheckpointReader = {
     get(token: CheckpointToken): Promise<{

package/dist/runs.js

@@ -1,4 +1,5 @@
-import { runWithVerification, runCascade, defaultTaskRegistry, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
+import { runWithVerification, runCascade, defaultTaskRegistry, terminalProjection, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
+import { failureCodeOf, stripResumeToken } from "./terminal.js";
 import { redactErrorMessage } from "./observability/run-terminal-log.js";
 import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
@@ -59,36 +60,39 @@ export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
     signal.addEventListener("abort", mark, { once: true });
 }
 export function isSessionConflictResult(result) {
-    if (result.status !== "failed")
+    if (result.terminal.kind !== "failed")
         return false;
-    if (result.errorCode)
-        return result.errorCode === "conflict";
-    return /stale write|concurrent write|conflict/i.test(result.errorMessage ?? "");
+    if (result.terminal.code)
+        return result.terminal.code === "conflict";
+    return /stale write|concurrent write|conflict/i.test(result.terminal.message ?? "");
 }
 export function resumeAtHttpStatus(result) {
-    if (result.status !== "failed")
+    const code = failureCodeOf(result.terminal);
+    if (code === undefined)
         return undefined;
-    if (result.errorCode === "resume.session_not_found")
+    if (code === "resume.session_not_found")
         return 404;
-    if (result.errorCode === "rewind_snapshot.unresolvable")
+    if (code === "rewind_snapshot.unresolvable")
         return 422;
-    if (result.errorCode === "rewind.child_scope_unsupported")
+    if (code === "rewind.child_scope_unsupported")
         return 422;
-    if (result.errorCode === "memory.admission_denied")
+    if (code === "memory.admission_denied")
         return 403;
-    if (result.errorCode === "memory.admission_required")
+    if (code === "memory.admission_required")
         return 503;
-    if (result.errorCode === "memory.capture_optout_denied")
+    if (code === "memory.capture_optout_denied")
         return 403;
-    if (result.errorCode === "memory.capture_optout_unpersisted")
+    if (code === "memory.capture_optout_unpersisted")
         return 503;
-    if (result.errorCode === "config.memory_capture_spelling")
+    if (code === "config.memory_capture_spelling")
         return 400;
-    if (result.errorCode === "config.memory_capture_unsupported")
+    if (code === "config.invalid_checkpoint_store")
+        return 400;
+    if (code === "config.memory_capture_unsupported")
         return 409;
-    if (!(result.errorCode?.startsWith("resume_at.") ?? false))
+    if (!code.startsWith("resume_at."))
         return undefined;
-    return result.errorCode === "resume_at.not_found" ? 404 : 422;
+    return code === "resume_at.not_found" ? 404 : 422;
 }
 export class TurnAnchorCapture {
     capture;
@@ -123,21 +127,14 @@ export class TurnAnchorCapture {
         this.turnHadTool = false;
     }
 }
-export function stripCheckpointToken(result) {
-    if (result !== null && typeof result === "object" && !Array.isArray(result) && Object.hasOwn(result, "checkpointToken")) {
-        const { checkpointToken: _drop, ...rest } = result;
-        return rest;
-    }
-    return result;
-}
 export async function parkToolCallId(result, cs) {
     if (!cs || result === null || typeof result !== "object")
         return undefined;
-    const r = result;
-    if ((r.status !== "suspended" && r.status !== "needs_review") || typeof r.checkpointToken !== "string")
+    const t = result.terminal;
+    if (t === undefined || t.kind !== "paused" || typeof t.token !== "string")
         return undefined;
     try {
-        const pa = (await cs.get(r.checkpointToken))?.pendingAction;
+        const pa = (await cs.get(t.token))?.pendingAction;
         return pa?.kind === "tool_approval" && typeof pa.toolCallId === "string" ? pa.toolCallId : undefined;
     }
     catch (e) {
@@ -169,7 +166,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         preemptable?.set(taskId, preemptCtrl);
     const cancelledResult = () => {
         const ctx = buildCancelContext(taskId, startedAt);
-        return { taskId, sessionId: spec.sessionId, status: "failed", errorCode: "cancelled", errorMessage: "cancelled by user", stats: { turns: 0, tokens: 0 }, ...(ctx ? { cancelContext: ctx } : {}) };
+        return { taskId, sessionId: spec.sessionId, terminal: { kind: "failed", code: "cancelled", message: "cancelled by user" }, stats: { turns: 0, tokens: 0 }, ...(ctx ? { cancelContext: ctx } : {}) };
     };
     const recordDone = (result, status) => {
         metrics?.addGauge("runs_active", -1);
@@ -318,11 +315,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
-                const safe = await withModelUsage(stripCheckpointToken(result));
+                const safe = await withModelUsage(stripResumeToken(result));
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
-                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
-                recordDone(safe, safe.status);
+                const plane = terminalProjection(safe.terminal);
+                await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
+                recordDone(safe, plane.status);
                 return;
             }
             if (cascade !== undefined) {
@@ -330,11 +328,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await flush();
                 evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
-                const safe = await withModelUsage(stripCheckpointToken(result));
+                const safe = await withModelUsage(stripResumeToken(result));
                 await append("done", { result: safe });
                 reached = { kind: "done", result: safe };
-                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
-                recordDone(safe, safe.status);
+                const plane = terminalProjection(safe.terminal);
+                await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
+                recordDone(safe, plane.status);
                 return;
             }
             const stream = runner.runTaskStream({ ...spec, taskId, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, undefined, fwdInternals);
@@ -359,7 +358,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 if (ev.type === "done") {
                     await flush();
-                    if (ev.result.status === "suspended") {
+                    const parkStatus = ev.result.terminal.kind === "paused" ? terminalProjection(ev.result.terminal).status : undefined;
+                    if (parkStatus === "suspended") {
                         await sink.appendParked("suspended", await graftParkToolCallId(ev.result, parkCheckpointReader));
                         await flushModelUsage();
                         reached = { kind: "suspended" };
@@ -368,17 +368,18 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                         metrics?.inc("tasks_total", { status: "suspended" });
                         continue;
                     }
-                    if (ev.result.status === "needs_review") {
+                    if (parkStatus === "needs_review") {
                         await parkNeedsReview(ev.result);
                         continue;
                     }
                     evictIfConflict(runner, spec.sessionId, ev.result);
                     {
-                        const safe = await withModelUsage(stripCheckpointToken(ev.result));
+                        const safe = await withModelUsage(stripResumeToken(ev.result));
                         await sink.appendDone(safe);
                         reached = { kind: "done", result: safe };
-                        await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
-                        recordDone(safe, safe.status);
+                        const plane = terminalProjection(safe.terminal);
+                        await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
+                        recordDone(safe, plane.status);
                     }
                     continue;
                 }
@@ -388,7 +389,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     await anchor.onTurnEnd();
                 }
             }
-            if (spec.suggestNextPrompts && reached?.kind === "done" && reached.result.status === "completed") {
+            if (spec.suggestNextPrompts && reached?.kind === "done" && reached.result.terminal.kind === "completed") {
                 const suggestions = await stream.suggestions().catch(() => []);
                 await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
             }
@@ -426,13 +427,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             }
             const c = cancelledResult();
             try {
-                await append("failed", { errorMessage: c.errorMessage ?? "cancelled by user", errorCode: "cancelled" });
+                await append("failed", { errorMessage: "cancelled by user", errorCode: "cancelled" });
             }
             catch (e) {
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-clean-cancel ${errText(e)}`);
             }
             reached = { kind: "done", result: c };
-            await runStore.setTerminal(taskId, "failed", c, c.errorMessage ?? null);
+            await runStore.setTerminal(taskId, "failed", c, terminalProjection(c.terminal).errorMessage ?? null);
             recordDone(c, "cancelled");
         }
     }
@@ -446,7 +447,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=flush-catch ${errText(e)}`);
             }
             if (reached?.kind === "done") {
-                await runStore.setTerminal(taskId, reached.result.status, reached.result, reached.result.errorMessage ?? null);
+                const plane = terminalProjection(reached.result.terminal);
+                await runStore.setTerminal(taskId, plane.status, reached.result, plane.errorMessage ?? null);
             }
             else if (reached?.kind === "suspended") {
                 await runStore.setSuspended(taskId);
@@ -457,12 +459,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             else if (cancelCtrl.signal.aborted) {
                 const c = cancelledResult();
                 try {
-                    await append("failed", { errorMessage: c.errorMessage ?? "cancelled by user", errorCode: "cancelled" });
+                    await append("failed", { errorMessage: "cancelled by user", errorCode: "cancelled" });
                 }
                 catch (e) {
                     recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-thrown-cancel ${errText(e)}`);
                 }
-                await runStore.setTerminal(taskId, "failed", c, c.errorMessage ?? null);
+                await runStore.setTerminal(taskId, "failed", c, terminalProjection(c.terminal).errorMessage ?? null);
             }
             else {
                 const safeMsg = redactErrorMessage(message) ?? message;
@@ -478,7 +480,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         catch {
         }
         if (reached?.kind === "done")
-            recordDone(reached.result, reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status);
+            recordDone(reached.result, failureCodeOf(reached.result.terminal) === "cancelled" ? "cancelled" : terminalProjection(reached.result.terminal).status);
         else if (reached?.kind === "suspended") {
             metrics?.addGauge("runs_active", -1);
             metrics?.inc("tasks_total", { status: "suspended" });
@@ -495,7 +497,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         unregisterEngineNotice();
         if (fleetPublisher) {
             if (reached?.kind === "done")
-                fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status, fleetRunResiduals(reached.result));
+                fleetPublisher.onTerminal(failureCodeOf(reached.result.terminal) === "cancelled" ? "cancelled" : terminalProjection(reached.result.terminal).status, fleetRunResiduals(reached.result));
             else if (reached?.kind === "suspended")
                 fleetPublisher.onTerminal("suspended");
             else if (reached?.kind === "needs_review")

package/dist/terminal.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 终局因由(`TaskResult.terminal`)的 server 侧**读**面 —— 一个叶子模块,只依赖 `@sema-agent/core`。
+ *
+ * core 7.6.0([ref] S6 D-8,BREAKING)把 `TaskResult` 上并列的八个平面键
+ * (`status` / `errorCode` / `errorMessage` / `blockedReason` / `checkpointToken` / `checkpointId` /
+ * `checkpointGate` / `workspaceRestoreMode`)删成**一条**带标因由 `terminal: TerminalCause`
+ * (`completed` | `failed{code?,message?,nestedPause?}` | `blocked{reason}` | `paused{gate,token,…}`)。
+ * 合法组合从此是**形状**而不是一串跨字段的口头约定(「`suspended` ⇔ 有 token」「review park 与 approval
+ * park 不同时置位」)。
+ *
+ * ## 本仓的两条纪律(与 core 的单铸律配套)
+ *
+ * 1. **判断读因由,不读平面词**。`terminal.kind === "paused"` 是判据;`terminalProjection(terminal).status
+ *    === "suspended"` 不是 —— 后者把一次投影塞进读点,于是同一个事实有了两个真源。
+ * 2. **`terminalProjection` 只在明确的「投影出口」用一次**:必须继续说五词 `TaskStatus` 的那几张脸
+ *    (run 行的 `status` / `error` 列、`tasks_total{status}` 计量标签、fleet 行的终态词)。出口之外不拼。
+ *
+ * wire 面(HTTP 任务体、SSE `done.result`)**就是结果本身**,所以它跟着 core 一起丢八键、带 `terminal`
+ * —— 那里没有投影,只有转发(见 {@link stripResumeToken} 的例外)。
+ */
+import { type PausedCause, type TaskStatus, type TerminalCause } from "@sema-agent/core";
+/**
+ * 这次失败带的**机器码**(`terminal.failed.code`);非失败终局 ⇒ `undefined`。
+ *
+ * 旧形要两键合读(`status === "failed" && errorCode === X`),而「非 failed 的行上有 errorCode」在类型上
+ * 是可表达的 —— 那正是本键此前每个读点都要自己重述一遍 `status` 判断的原因。因由形下「码只属于失败」
+ * 是形状本身,所以判据收成这一个函数:**读点问码,不再各自复述状态**。
+ *
+ * 码是开集(core 的点名族 `limits.*` / `config.*` / `resume_at.*` / brain 扁平码 + 工具层自注册码),
+ * 消费点一律带 default 臂,禁按穷举写。
+ */
+export declare function failureCodeOf(terminal: TerminalCause): string | undefined;
+/**
+ * 把**耐久恢复能力凭据**(`CheckpointToken`)从一条结果里摘掉,再让它进可重放账本 / run 行 / wire。
+ * token 就是 resume 凭据(token-as-auth,search [18] Q1b),**永不离开本服务**;非密的 `gate` /
+ * `checkpointId` / `restoreMode` 有意保留(对账位)。
+ *
+ * 🔴 core 7.6.0 起凭据换了住址:它不再是 `TaskResult` 顶层的 `checkpointToken`,而是因由里
+ * `paused` 那一臂的 `token`。而**一条结果上够得着 paused 因由的位置有两处**,这是类型的形状,不是特判:
+ *  · `terminal`(kind `paused`)—— 本腿自己 park 了;
+ *  · `terminal.nestedPause`(kind `failed`)—— 嵌套边界(verify / cascade)遇到自己驱动不了的耐久暂停,
+ *    在**它的**边界上如实报 `failed`,而把那次暂停的因由整只带在这里(顶层调用方据此仍能恢复)。
+ *    正是这条路径当年让 `checkpointToken` 漏进过账本 —— 摘除腿从来不是「理论上的对称」。
+ * 两处走**同一条**摘除规则({@link stripPausedToken}),不是两条。
+ *
+ * wire 上的形:paused 因由**缺席 `token`**(core 类型里它是必填座,那是**引擎内**的契约;本服务的 wire
+ * 契约逐字声明这一座不出服务边界 —— 见 `docs/ASSISTANT-WIRE-CONTRACT.md`)。消费端要动这次暂停,走
+ * `/v1/approvals` 决策端点,凭 `checkpointId` 对账,从来不是拿 token 直连引擎。
+ *
+ * 对任何输入安全(非普通对象 / 无 `terminal` / 因由不带 token ⇒ **同一引用**原样返回,不重塑)。
+ */
+export declare function stripResumeToken<T extends {
+    terminal: TerminalCause;
+}>(result: T): T;
+/**
+ * 这条腿的结果里**藏着的那次耐久暂停** —— 嵌套边界(verify / cascade)遇到自己驱动不了的耐久 park 时,
+ * 在**它的**边界上如实报 `failed`(码是 `unexpected.suspended` / `unexpected.needs_review`),而把那次
+ * park 的因由**整只**带在这里,顶层调用方据此仍能恢复。非嵌套 park ⇒ `undefined`。
+ *
+ * 🔴 core 7.6.0 之前这件事只能从**码的字面量**推:`status` 恒被改写成 `"failed"`(真 park 词挪进
+ * `errorCode`,token 顺着 `checkpointToken` 原样透传),于是本仓凡是按 `status` 判 park 的门在这条腿上
+ * **恒假**([ref] 二的真案:待批工具卡被谎报成 tool-less park),补救办法是「先把 status 换成真词再递进去」
+ * 这种再造事实的写法。因由形下 park 的门、门上的卡、恢复凭据都在同一个 `PausedCause` 上 —— 那些补救全部
+ * 消失,判据回到一条:**问因由**。
+ */
+export declare function nestedPauseOf(terminal: TerminalCause): PausedCause | undefined;
+/**
+ * 这条结果**停在耐久门上**了吗 —— 若是,给出那次暂停的因由。两条路径合成一个判据:
+ *  · 本腿自己 park(`terminal.kind === "paused"`);
+ *  · 嵌套边界替它带回来的那次 park({@link nestedPauseOf})。
+ *
+ * 🔴 7.6.0 之前这两条路径要用**两个不同的判据**读:平面腿按 `status` 的五词穷举 switch
+ * (`suspended` / `needs_review` 是 park),嵌套腿按「还带着 `checkpointToken` 就是 park」——同一个问题
+ * 两套写法,而两套写法各漏过一次真事故(fanout 的手抄 `=== "suspended"` 漏 `needs_review`;verify 腿的
+ * status 恒 `"failed"`)。因由形下两条路径合成一句话,规则从二变一。
+ */
+export declare function pausedCauseOf(terminal: TerminalCause): PausedCause | undefined;
+/**
+ * **持久 blob 的平面读面** —— 把一条**任何年代**的持久终局结果读成五词 `status` + 三个平面文本格。
+ *
+ * 🔴 为什么这不是「兼容读臂」(codex 对抗复审 r1 [high] ×2,亲读验真后修;首版把它当成兼容 shim 删掉了,
+ * 那是**错的**,理由如下):
+ *  · 本仓 wire 面的纪律「不为老键留兼容读臂」管的是**同一条 wire 上两种形并存** —— 那会让两个写者共用一个
+ *    语义面。而这里是**读盘**:`task_run.result` / `task_event(done).result` / `workflow_journal` 里躺着
+ *    7.63.0 及以前写下的**真字节**,它们本来就是平面形。一个读盘面认识盘上真实存在的两种形,不是第二个写者
+ *    ——**没有任何东西会再写出旧形**(写口只剩因由一条)。
+ *  · 不认旧形的代价是**可复现的两条真回归**:① `terminalProjection(undefined)` 直接抛 TypeError ⇒ 历史 run 的
+ *    `GET /v1/runs/:id` 整个 500;② 读面的二次脱敏(旧行纵深)对旧行**恒不生效** ⇒ 上线前落盘的凭据在
+ *    `GET /v1/runs/:id/events` 回放时重新明文外发。
+ * ⇒ 规则仍然只有一条:**读盘认盘上真有的形,写盘只写一种形**。
+ *
+ * 形不合(非对象 / 两种形都不是)⇒ 全格缺席,不抛(读面永不因为一条坏行整只 500)。
+ */
+export declare function persistedPlaneOf(result: unknown): {
+    status?: TaskStatus;
+    errorCode?: string;
+    errorMessage?: string;
+    blockedReason?: string;
+};
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.js

@@ -0,0 +1,55 @@
+import { terminalProjection } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+export function failureCodeOf(terminal) {
+    return terminal.kind === "failed" ? terminal.code : undefined;
+}
+export function stripResumeToken(result) {
+    const t = result?.terminal;
+    if (t === null || typeof t !== "object")
+        return result;
+    if (t.kind === "paused")
+        return { ...result, terminal: stripPausedToken(t) };
+    if (t.kind === "failed" && t.nestedPause !== undefined)
+        return { ...result, terminal: { ...t, nestedPause: stripPausedToken(t.nestedPause) } };
+    return result;
+}
+function stripPausedToken(paused) {
+    const { token: _drop, ...rest } = paused;
+    return rest;
+}
+export function nestedPauseOf(terminal) {
+    return terminal.kind === "failed" ? terminal.nestedPause : undefined;
+}
+export function pausedCauseOf(terminal) {
+    return terminal.kind === "paused" ? terminal : nestedPauseOf(terminal);
+}
+export function persistedPlaneOf(result) {
+    if (result === null || typeof result !== "object")
+        return {};
+    const r = result;
+    if (r.terminal !== null && typeof r.terminal === "object") {
+        let projected;
+        try {
+            projected = terminalProjection(r.terminal);
+        }
+        catch (e) {
+            recordFailOpen("server.terminal.persisted-plane-malformed", e instanceof Error ? e.message : String(e));
+            projected = undefined;
+        }
+        if (projected !== undefined) {
+            return {
+                status: projected.status,
+                ...(projected.errorCode !== undefined ? { errorCode: projected.errorCode } : {}),
+                ...(projected.errorMessage !== undefined ? { errorMessage: projected.errorMessage } : {}),
+                ...(projected.blockedReason !== undefined ? { blockedReason: projected.blockedReason } : {}),
+            };
+        }
+    }
+    return {
+        ...(typeof r.status === "string" ? { status: r.status } : {}),
+        ...(typeof r.errorCode === "string" ? { errorCode: r.errorCode } : {}),
+        ...(typeof r.errorMessage === "string" ? { errorMessage: r.errorMessage } : {}),
+        ...(typeof r.blockedReason === "string" ? { blockedReason: r.blockedReason } : {}),
+    };
+}
+//# sourceMappingURL=terminal.js.map

package/dist/trace/core-keyset-guard.d.ts

@@ -17,7 +17,7 @@
  * ⑨⑩([ref],2026-08-31)把两个最大的 wire 面也纳入:TaskSpec 按「server 有无写点」记 Wired/Unwired,
  * TaskResult 按「转发/摘除」记 Forwarded/Stripped —— 谁改 resolve-spec.ts / runs.ts 的发射点谁同步本文件。
  */
-import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, TaskEvent, TraceEvent, MailboxMessage, MailboxAppendMessage, TaskSpec, TaskResult } from "@sema-agent/core";
+import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, CheckpointSummary, TaskEvent, TraceEvent, MailboxMessage, MailboxAppendMessage, TaskSpec, TaskResult, GateOutcome, Settlement, PausedCause } from "@sema-agent/core";
 /** 编译期断言:T 必须收敛到 never(有残余键 = tsc 红)。 */
 type AssertAllKeysHandled<T extends never> = T;
 type NotificationProjected = "task_id" | "task_type" | "toolUseId" | "status" | "summary" | "result" | "output_file" | "usage" | "sessionId" | "seq" | "lines" | "stoppedBy" | "source" | "exitCode" | "partial" | "diagnostics" | "recentSteps" | "editedFiles" | "resumable" | "completionId" | "error" | "errorCode" | "apiFailure" | "agentMessage" | "_sema_provenance";
@@ -52,10 +52,20 @@ type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requi
 type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars";
 type _GuardTaskSpec = AssertAllKeysHandled<Exclude<keyof TaskSpec, TaskSpecWired | TaskSpecUnwired>>;
 type _GuardTaskSpecReverse = AssertAllKeysHandled<Exclude<TaskSpecWired | TaskSpecUnwired, keyof TaskSpec>>;
-type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "status" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "blockedReason" | "checkpointId" | "checkpointGate" | "workspaceRestoreMode" | "remoteEnvFailures" | "errorMessage" | "errorCode" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveMemoryScopes" | "stats" | "editedFiles";
-type TaskResultStripped = "checkpointToken";
+type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "terminal" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "remoteEnvFailures" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveMemoryScopes" | "stats" | "editedFiles";
+type TaskResultStripped = never;
 type _GuardTaskResult = AssertAllKeysHandled<Exclude<keyof TaskResult, TaskResultForwarded | TaskResultStripped>>;
 type _GuardTaskResultReverse = AssertAllKeysHandled<Exclude<TaskResultForwarded | TaskResultStripped, keyof TaskResult>>;
+type PausedCauseForwarded = "kind" | "gate" | "checkpointId" | "restoreMode";
+type PausedCauseStripped = "token";
+type _GuardPausedCause = AssertAllKeysHandled<Exclude<keyof PausedCause, PausedCauseForwarded | PausedCauseStripped>>;
+type _NoDoubleBookPausedCause = AssertAllKeysHandled<Extract<PausedCauseForwarded, PausedCauseStripped>>;
+type _GuardPausedCauseReverse = AssertAllKeysHandled<Exclude<PausedCauseForwarded | PausedCauseStripped, keyof PausedCause>>;
+type SettlementKeys = Settlement extends infer S ? (S extends object ? keyof S : never) : never;
+type SettlementWhoKeys = Settlement["who"] extends infer W ? (W extends object ? keyof W : never) : never;
+type _GuardGateOutcome = AssertAllKeysHandled<Exclude<keyof GateOutcome, "disposition" | "settlement" | "origin">>;
+type _GuardSettlement = AssertAllKeysHandled<Exclude<SettlementKeys, "kind" | "who" | "when" | "note">>;
+type _GuardSettlementWho = AssertAllKeysHandled<Exclude<SettlementWhoKeys, "party" | "approver" | "window">>;
 export type CoreKeysetGuards = [
     _GuardNotification,
     _GuardBgNotif,
@@ -71,7 +81,13 @@ export type CoreKeysetGuards = [
     _GuardTaskSpec,
     _GuardTaskSpecReverse,
     _GuardTaskResult,
-    _GuardTaskResultReverse
+    _GuardTaskResultReverse,
+    _GuardGateOutcome,
+    _GuardSettlement,
+    _GuardSettlementWho,
+    _GuardPausedCause,
+    _NoDoubleBookPausedCause,
+    _GuardPausedCauseReverse
 ];
 export {};
 //# sourceMappingURL=core-keyset-guard.d.ts.map

package/dist/trace/ledger-sink.d.ts

@@ -1,3 +1,4 @@
+import { type TerminalCause } from "@sema-agent/core";
 import { brainStatusEventData } from "./project.js";
 import { NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import type { LedgerEventType } from "./ledger-events.js";
@@ -73,7 +74,7 @@ export interface LedgerSink {
     /** Convenience for the sync detach lane (no model-usage interleave there): flush, then project the result
      *  to its park/terminal event exactly like the bg leg's done case. `result` must already be stripped. */
     onDone(result: {
-        status?: string;
+        terminal: TerminalCause;
     }): Promise<void>;
 }
 /**