@sema-agent/server 7.63.0 → 7.64.0

package/dist/plugins/file-run-store.js

@@ -3,14 +3,11 @@ import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
+import { terminalProjection } from "@sema-agent/core";
+import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { notifyRunTerminal } from "../observability/run-terminal-log.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
-const PROCESS_FACTS = {
-    pid: process.pid,
-    startedAtMs: Date.now() - Math.round(process.uptime() * 1000),
-};
 const CLAIM_TAKEOVER_ATTEMPTS = 3;
 const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_.-]+$/;
 const isSafePathComponent = (s) => s !== "" && s !== "." && s !== ".." && SAFE_PATH_COMPONENT.test(s);
@@ -22,17 +19,6 @@ function readClaimRecord(recs, sessionId) {
         return undefined;
     return c;
 }
-function isPidAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return true;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code !== "ESRCH";
-    }
-}
 const PARK_ORPHAN_SETTLE_MS = 30_000;
 export class RunStoreStrictHydrateError extends Error {
     name = "RunStoreStrictHydrateError";
@@ -46,7 +32,7 @@ export class FileRunStore {
     events = new Map();
     eventLogs = new Map();
     checkpointProbe;
-    claimOwner = { nonce: randomBytes(12).toString("hex"), ...PROCESS_FACTS };
+    claimOwner = { nonce: randomBytes(12).toString("hex"), ...processFingerprint() };
     claimLocks = new Map();
     logger;
     strictHydrate;
@@ -382,7 +368,7 @@ export class FileRunStore {
             r.status = status;
             r.result = result;
             r.error = error;
-            r.errorCode = result?.errorCode ?? null;
+            r.errorCode = result === null ? null : (terminalProjection(result.terminal).errorCode ?? null);
             r.updatedAt = new Date();
             this.persist(r);
             pending = {
@@ -393,7 +379,7 @@ export class FileRunStore {
                 resultTaskId: result?.taskId,
                 model: result?.model,
                 errorCode: r.errorCode ?? undefined,
-                errorMessage: result?.errorMessage ?? error ?? undefined,
+                errorMessage: (result === null ? undefined : terminalProjection(result.terminal).errorMessage) ?? error ?? undefined,
                 elapsedMs: Math.max(0, Date.now() - r.createdAt.getTime()),
             };
         }
@@ -728,7 +714,7 @@ export class FileRunStore {
     async judgeClaim(sessionId, claim, holderTaskId) {
         const owner = claim?.owner;
         const who = owner
-            ? `pid ${owner.pid} started ${new Date(owner.startedAtMs).toISOString()}`
+            ? `pid ${owner.pid} on ${owner.host ?? "an unnamed host"} started ${owner.startedAtMs === null || owner.startedAtMs === undefined ? "(start time unobtainable)" : new Date(owner.startedAtMs).toISOString()}`
             : "an owner-less claim (written before the liveness stamp existed)";
         const torn = claim === undefined;
         let row = !torn && holderTaskId ? this.authoritativeRow(holderTaskId) : undefined;
@@ -770,7 +756,7 @@ export class FileRunStore {
             return { kind: "stale", reason: `parked run (${row.status}) has no resumable checkpoint — claim reclaimed`, snapshot };
         }
         const mine = owner?.nonce === this.claimOwner.nonce;
-        const ownerGone = owner !== undefined && !isPidAlive(owner.pid);
+        const ownerGone = owner !== undefined && !isProcessLive(owner);
         if (!mine && !ownerGone)
             return live();
         if (!row)
@@ -782,6 +768,11 @@ export class FileRunStore {
         const probe = this.checkpointProbe;
         if (probe && (await probe.hasPending(row.sessionId)))
             return live();
+        this.logger?.error?.("file_run_store_claim_taken_over", {
+            sessionId, holder: holder || null, owner: owner ?? null,
+            pidStillRunning: owner !== undefined && isProcessLive({ pid: owner.pid }),
+            note: "the claim's owner process is provably not the one that wrote it (fingerprint falsified, or the pid is gone) and the row has nothing left to resume — taking the claim over",
+        });
         return { kind: "stale", reason: `run orphaned by engine restart (claim held by ${who}, which is gone)`, snapshot };
     }
     takeOverClaim(sessionId, reason, snapshot) {

package/dist/plugins/memory-run-store.js

@@ -1,5 +1,6 @@
 import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal-log.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
+import { terminalProjection } from "@sema-agent/core";
 import { notifyRunTerminal } from "../observability/run-terminal-log.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class MemoryRunStore {
@@ -119,7 +120,7 @@ export class MemoryRunStore {
             r.status = status;
             r.result = result;
             r.error = error;
-            r.errorCode = result?.errorCode ?? null;
+            r.errorCode = result === null ? null : (terminalProjection(result.terminal).errorCode ?? null);
             r.updatedAt = new Date();
             pending = {
                 runId: taskId,
@@ -129,7 +130,7 @@ export class MemoryRunStore {
                 resultTaskId: result?.taskId,
                 model: result?.model,
                 errorCode: r.errorCode ?? undefined,
-                errorMessage: result?.errorMessage ?? error ?? undefined,
+                errorMessage: (result === null ? undefined : terminalProjection(result.terminal).errorMessage) ?? error ?? undefined,
                 elapsedMs: Math.max(0, Date.now() - r.createdAt.getTime()),
             };
         }

package/dist/plugins/run-store-sql.js

@@ -1,4 +1,5 @@
 import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal-log.js";
+import { terminalProjection } from "@sema-agent/core";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
@@ -118,7 +119,7 @@ export class SqlRunStore {
     async setTerminal(taskId, status, result, error) {
         result = redactTerminalResult(result);
         error = error === null ? null : (redactErrorMessage(error) ?? null);
-        const errorCode = result?.errorCode ?? null;
+        const errorCode = result === null ? null : (terminalProjection(result.terminal).errorCode ?? null);
         let observed;
         await this.tx(async (conn) => {
             const w = await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
@@ -150,7 +151,7 @@ export class SqlRunStore {
                 resultTaskId: result?.taskId,
                 model: result?.model,
                 errorCode: errorCode ?? undefined,
-                errorMessage: result?.errorMessage ?? error ?? undefined,
+                errorMessage: (result === null ? undefined : terminalProjection(result.terminal).errorMessage) ?? error ?? undefined,
                 elapsedMs: observed.createdAt === undefined ? undefined : Math.max(0, Date.now() - observed.createdAt),
             });
         }

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