@sema-agent/server 7.111.0 → 7.112.0

package/MIGRATION.md

@@ -7,6 +7,14 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.112.0(车UG,S-924)—— `settings.hooks` 里按工具别名写的 matcher 提交当场 400(此前静默不命中)
+
+- **🔴 settings 面硬破坏(响亮拒,无迁移代码、无兼容形)**。① *谁受影响*:提交体 `settings.hooks` 里 PreToolUse / PostToolUse / PostToolUseFailure 的 `matcher`
+  是**引擎工具别名**的(今天只有 `ListPeers` → `ListAgents`;别名表读 core 静态工具目录)—— 它们**早就不命中**(post 两事件自 7.107.0 / core 7.36.0,PreToolUse 一直),只是没人告诉写的人。
+  ② *怎么改*:把 matcher 改成**正名**(错误句直接给出);`正名|别名` 的滚动期写法不受影响(命中正名)。③ *不改会怎样*:该**新提交** `400 request.field_invalid`(错误句点名别名与正名)——
+  不再是「接受、hook 永不跑」。耐久 resume 重放**不判**(会砖 parked 任务):升级前就 parked 的任务,其存量 body 里的别名 matcher 在续跑腿照旧永不命中、同一份 hooks 里其余钩子照常生效(与 7.111.0 逐字同)。
+  嵌入方经 `resolveSpec` 席挂的工具别名在受理面看不见,不在本门射程。
+
 ## 7.111.0(车TA,S-961 / S-972)—— `wiring_manifest` 帧 +`instructions` 段(additive,零动作)
 
 - **wire(additive,零动作)**:`wiring_manifest` 帧(四条腿:流式 SSE / 账本行 / 非流式 `wiringManifest` 回执 / 续跑腿)多一段本服务自铸的 `instructions: { selected: string[] }` = 这条腿选中的项目指令文件(相对 cwd 的链成员);`[]` = 没有,缺席 = 无陈述(契约附录 G.21)。按封闭 schema 校验该帧的消费方加这一可选键;不要它的部署 `PROJECT_MEMORY_ENABLED=false`(连同项目记忆注入一起关)。`task.user_steer_undrained{cause:"crashed"}` 的 `message` 改句序(行动句在前、< 400 字符),`detail` 不变 —— 按文本匹配的脚本改读 `detail.cause`(S-972)。

package/dist/hooks/hook-runner.d.ts

@@ -35,6 +35,11 @@ export interface ParseHooksConfigResult {
     /** 人可读的第一条校验错误(HTTP 层用它 400 fail-loud;resume 防御路径用它 warn)。 */
     error?: string;
 }
+/**
+ * fresh 提交面专用判据(S-924):配置里第一条「永远打不中」的工具事件 matcher 的拒句;没有 ⇒ undefined。
+ * 入参是 {@link parseHooksConfig} 已校验过的配置。**只有 `admission.ts` 的 fresh 提交门调它** —— resume 重放不调(理由见上面的头注)。
+ */
+export declare function deadToolMatcherIssue(config: HooksConfig): string | undefined;
 /**
  * 把 wire 上的 untrusted `settings.hooks` 校验成契约 {@link HooksConfig} + 服务侧上限。
  * 错误返回 error 字符串而不 throw——submit 路径 400 fail-loud、resume 防御路径 warn-drop,由调用方选。

package/dist/hooks/hook-runner.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { hostShell, resolveHostShell, adoptHostForegroundChild } from "../plugins/host-platform.js";
-import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, } from "@sema-agent/settings-schema/hooks";
+import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, } from "@sema-agent/settings-schema/hooks";
+import { describeToolCatalog } from "@sema-agent/core";
 import { boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets, buildDisplaySafeUrl } from "../trace/redact.js";
@@ -56,6 +57,49 @@ function toAssistantTurnError(errorKind) {
         return "unknown";
     return Object.prototype.hasOwnProperty.call(BRAIN_TO_TURN_ERROR, errorKind) ? (BRAIN_TO_TURN_ERROR[errorKind] ?? "unknown") : "unknown";
 }
+const NAME_ALTERNATION = /^[A-Za-z0-9_-]+(?:\|[A-Za-z0-9_-]+)*$/;
+function matcherReadsWireToolName(event) {
+    return HOOK_EVENT_OWNER[event] === "engine" && HOOK_EVENT_MATCHER_FIELD[event] === "tool_name";
+}
+let engineToolAliasTable;
+function engineToolAliases() {
+    if (engineToolAliasTable !== undefined)
+        return engineToolAliasTable;
+    const entries = describeToolCatalog();
+    const wireNames = new Set(entries.map((e) => e.name));
+    const table = new Map();
+    for (const e of entries) {
+        for (const alias of e.face.aliases ?? []) {
+            if (!wireNames.has(alias) && !table.has(alias))
+                table.set(alias, e.name);
+        }
+    }
+    engineToolAliasTable = table;
+    return table;
+}
+function deadAliasInMatcher(event, matcher) {
+    if (matcher === undefined || !matcherReadsWireToolName(event) || !NAME_ALTERNATION.test(matcher))
+        return undefined;
+    const branches = matcher.split("|");
+    const aliases = engineToolAliases();
+    for (const branch of branches) {
+        const canonical = aliases.get(branch);
+        if (canonical !== undefined && !branches.includes(canonical))
+            return { alias: branch, canonical };
+    }
+    return undefined;
+}
+export function deadToolMatcherIssue(config) {
+    for (const [event, groups] of Object.entries(config)) {
+        for (const group of groups ?? []) {
+            const dead = deadAliasInMatcher(event, group.matcher);
+            if (dead) {
+                return `settings.hooks.${event}: matcher "${dead.alias}" is an alias; tool-event matchers match the tool's wire name (PostToolUse / PostToolUseFailure since 7.107.0) — use "${dead.canonical}"`;
+            }
+        }
+    }
+    return undefined;
+}
 export function parseHooksConfig(raw) {
     const parsed = HooksConfig.safeParse(raw);
     if (!parsed.success) {

package/dist/http/admission.js

@@ -7,7 +7,7 @@ import { taskBodyKeyIssue } from "../request-key-closure.js";
 import { FILE_HISTORY_DISABLED_NO_RESTORE, fileHistoryRestoreConflict, inheritEnvFieldIssue, singleMemberOffFieldIssue } from "../request-value-closure.js";
 import { selfOrchestrationDenial } from "../task-workflow.js";
 import { centerEntitlementSourceWired } from "../runtime-caps-resolver.js";
-import { parseHooksConfig } from "../hooks/hook-runner.js";
+import { deadToolMatcherIssue, parseHooksConfig } from "../hooks/hook-runner.js";
 import { judgeRequestWebSearch } from "../plugins/web-search.js";
 import { normalizeApproachNotice, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
 import { isValidCwd, MAX_ADDITIONAL_DIRS, MAX_CWD_CHARS } from "../task-cwd.js";
@@ -200,6 +200,11 @@ export function createAdmission(ctx) {
                     sendError(res, 400, "request.field_invalid", hooksParsed.error ?? "settings.hooks: invalid shape");
                     return null;
                 }
+                const deadMatcher = deadToolMatcherIssue(hooksParsed.config);
+                if (deadMatcher !== undefined) {
+                    sendError(res, 400, "request.field_invalid", deadMatcher);
+                    return null;
+                }
             }
             {
                 const webSearchVerdict = judgeRequestWebSearch(st.webSearch);

package/dist/http/resume-legs.d.ts

@@ -7,8 +7,8 @@
  * 字节不变)。同居是第三条,也是唯一一条既保住静态序又保住 move-only 的。序由 `const` 的 TDZ 亲自执法:
  * 腿是提升的函数声明、ctx 是文件尾的 `const`,谁也不会在工厂执行期读到对方。
  *
- * ctx 字段 28 只(registry 7 + helpers 14 + deps/runnerFor/prepareSpec/finalizeTaskResult + 三只配额/租约/用量窗
- * 判据)—— 这是**如实披露**的耦合读数(设计稿 §9:把它变小是波 3 的事,本刀不承诺)。型一律从既有型派生
+ * ctx 字段 27 只(registry 6 + helpers 14 + deps/runnerFor/prepareSpec/finalizeTaskResult + 三只配额/租约/用量窗
+ * 判据;S-947 删 `cancelledViaVerb` 旁表后 28 → 27,与 `test/split-ctx-parity.test.ts` 的读数同)—— 这是**如实披露**的耦合读数(设计稿 §9:把它变小是波 3 的事,本刀不承诺)。型一律从既有型派生
  * (`RunRegistry` / `RouteHelpers` / `RouteLegs` / `ReturnType<typeof createRequestGuards>`),不手抄签名 ⇒ 不会漂。
  */
 import type { IncomingMessage } from "node:http";
@@ -17,7 +17,7 @@ import type { DecideBinding } from "./wire-types.js";
 import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import { type HostDecision } from "../host-decision.js";
 import { type PlanApprovePermissionModeAfter } from "../task-settings.js";
-import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview } from "./route-ctx.js";
+import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview, ResumeLegOutcome } from "./route-ctx.js";
 import { type TrustedRunInternals } from "./durable-run-leg.js";
 import type { RunRegistry, RouteHelpers, RouteLegs } from "./route-ctx.js";
 import type { createRequestGuards } from "./request-guards.js";
@@ -33,21 +33,12 @@ export declare function createResumeLegs(ctx: {
     }) => Promise<void>, acceptEarly?: boolean, decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }) => Promise<{
-        status: number;
-        body: object;
-    }>;
-    driveResumeIntoRunLog: (args: DriveResumeArgs) => Promise<{
-        status: number;
-        body: object;
-    }>;
+    }) => Promise<ResumeLegOutcome>;
+    driveResumeIntoRunLog: (args: DriveResumeArgs) => Promise<ResumeLegOutcome>;
     driveResumeLeg: (args: DriveResumeArgs, onAccepted?: (receipt: {
         status: number;
         body: object;
-    }) => void) => Promise<{
-        status: number;
-        body: object;
-    }>;
+    }) => void) => Promise<ResumeLegOutcome>;
     mayDiscloseRowError: (cs: CheckpointStoreFull, token: CheckpointToken, decider: {
         principal?: string;
         explicitOperator: boolean;

package/dist/http/resume-legs.js

@@ -8,7 +8,7 @@ const sessionFaceUnavailable = async (sessionId) => {
 import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import { evictIfConflict, parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { failureCodeOf, nestedPauseOf, sealResultForExit, outwardPlane } from "../terminal.js";
-import { mintCancelledResult } from "../run-cancel-context.js";
+import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "../run-cancel-context.js";
 import {} from "../host-decision.js";
 import { readTurnActivityMs, recordTurnActivity } from "../turn-activity.js";
 import { recordResumeResourceWindow } from "../resource-window.js";
@@ -75,7 +75,7 @@ function notResumableAnswer() {
     return { status: 409, body: { error: "run is not in a resumable (suspended) state (already resumed, decided, or expired)", errorCode: "conflict.not_resumable" } };
 }
 export function createResumeLegs(ctx) {
-    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
     const resumeFleetScope = (req, auth) => req ? (gatedPrincipal(req, deps.config) ?? "default") : (auth.principal ?? "default");
     async function resumeCheckpoint(sessionId, decision, reason, hostDecision, req, answer, binding, onResumeCommitted, acceptEarly, decider) {
         const cs = deps.checkpointStore;
@@ -225,7 +225,7 @@ export function createResumeLegs(ctx) {
         const noteLateSettleIfAccepted = (out) => {
             if (lateSettleSink === undefined || lateSettleAnchor === undefined || out.status !== 200)
                 return;
-            if (out.body?.errorCode === "cancelled")
+            if (out.body?.errorCode === "cancelled" && out.decisionCommitted !== true)
                 return;
             try {
                 lateSettleSink.recordLateSettle({ ...lateSettleAnchor, outcome: decision === "approve" ? "allowed" : "denied", decidedBy: hostDecision.decidedBy, ...(hostDecision.approver !== undefined ? { approver: hostDecision.approver } : {}), settledAtMs: Date.now() });
@@ -472,7 +472,8 @@ export function createResumeLegs(ctx) {
         let resumeLegLive = false;
         const subagentHandleEvictions = [];
         let claimedRow = false;
-        const cancelCtrl = new AbortController();
+        const cancelCtrl = createRunAbort();
+        let cancelLedgerAppend;
         const preemptCtrl = new AbortController();
         if (taskId && deps.runStore) {
             claimedRow = freshRunClaimed ? true : await deps.runStore.markResuming(taskId, deps.instanceId ?? "default");
@@ -488,7 +489,7 @@ export function createResumeLegs(ctx) {
                 void rs.heartbeat(taskId, owner).catch(() => undefined);
                 if (!cancelCtrl.signal.aborted) {
                     void rs.isCancelRequested(taskId, owner).then((c) => { if (c)
-                        cancelCtrl.abort(); }).catch(() => undefined);
+                        cancelCtrl.abort("cancel_verb"); }).catch(() => undefined);
                 }
                 if (!preemptCtrl.signal.aborted) {
                     void rs.isPreemptRequested(taskId, owner).then((p) => { if (p)
@@ -531,6 +532,7 @@ export function createResumeLegs(ctx) {
                         instructionsSegment: instructionLeg.segment,
                     });
                     const vAppend = (type, data) => verifySink.append(type, data);
+                    cancelLedgerAppend = vAppend;
                     const verifyTailContentMode = resumeTaskConfig.forwardSubagentEvents === true ? "on" : "progress_only";
                     const verifyInternals = {
                         ...(taskId ? { onActivity: () => recordTurnActivity(taskId) } : {}),
@@ -579,7 +581,9 @@ export function createResumeLegs(ctx) {
                             : {}),
                     };
                     resumeLegLive = true;
-                    const vr = await resumeWithVerification(legRunner, token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds, verifyInternals);
+                    const vrEngine = await resumeWithVerification(legRunner, token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds, verifyInternals);
+                    const vrCause = cancelCtrl.cause();
+                    const vr = vrCause !== undefined && taskId !== undefined ? mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: "cancelled by user", engineResult: vrEngine, cause: vrCause }) : vrEngine;
                     await commitResumeCtx();
                     let safe = sealResultForExit(vr);
                     const vrNested = nestedPauseOf(vr.terminal);
@@ -622,6 +626,7 @@ export function createResumeLegs(ctx) {
                 const persistThinking = deps.config.traceThinking;
                 const serialAppend = createSerialLedgerAppend((s, type, data) => rs.appendEvent(taskId, s, type, data), startSeq);
                 const append = (type, data) => (rs && taskId ? serialAppend(type, data) : Promise.resolve());
+                cancelLedgerAppend = append;
                 unregisterEngineNotice = registerEngineNoticeLeg({
                     sessionId,
                     ...(args.engineNotices !== undefined && args.engineNotices.length > 0 ? { pending: [...args.engineNotices] } : {}),
@@ -715,7 +720,10 @@ export function createResumeLegs(ctx) {
                     if (!taskId || !rs)
                         return sealResultForExit(await stream.result());
                     onAccepted?.(acceptedResumingReceipt(taskId, sessionId));
+                    let causeAtDone;
                     for await (const ev of stream) {
+                        if (ev.type === "done")
+                            causeAtDone = cancelCtrl.cause();
                         recordTurnActivity(taskId);
                         fleetPub?.onEvent(ev);
                         await appendPromptManifest(append, deps.promptManifests, taskId);
@@ -823,7 +831,8 @@ export function createResumeLegs(ctx) {
                         }
                     }
                     await flush();
-                    const r = await stream.result();
+                    const rEngine = await stream.result();
+                    const r = causeAtDone !== undefined ? mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: "cancelled by user", engineResult: rEngine, cause: causeAtDone }) : rEngine;
                     const rPark = r.terminal.kind === "paused" ? outwardPlane(r.terminal).status : undefined;
                     if (rPark === "suspended") {
                         const parkCallId = await parkToolCallId(r, deps.checkpointStore);
@@ -898,7 +907,11 @@ export function createResumeLegs(ctx) {
                         }
                     }
                     if (claimedRow && taskId && deps.runStore) {
-                        const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: e.message });
+                        const handleCause = cancelCtrl.cause();
+                        if (handleCause === undefined)
+                            recordFailOpen("server.runs.abort-cause-missing", `task=${taskId} arm=resume-aborted`);
+                        const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: e.message, cause: handleCause ?? "cancel_verb" });
+                        await cancelLedgerAppend?.("failed", buildCancelledLedgerRow(c)).catch((err) => recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=resume-append-resume-aborted ${errorText(err)}`));
                         await deps.runStore.setTerminal(taskId, "failed", c, e.message).catch(() => undefined);
                     }
                     settleFleet("failed");
@@ -953,9 +966,11 @@ export function createResumeLegs(ctx) {
                     },
                 };
             }
-            if (cancelCtrl.signal.aborted) {
+            const thrownCause = cancelCtrl.cause();
+            if (thrownCause !== undefined) {
                 if (taskId && deps.runStore) {
-                    const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: "cancelled by user" });
+                    const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: "cancelled by user", cause: thrownCause });
+                    await cancelLedgerAppend?.("failed", buildCancelledLedgerRow(c)).catch((err) => recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=resume-append-thrown-cancel ${errorText(err)}`));
                     await deps.runStore.setTerminal(taskId, "failed", c, "cancelled by user").catch(() => undefined);
                 }
                 settleFleet("failed");
@@ -1002,6 +1017,7 @@ export function createResumeLegs(ctx) {
         settleFleet(checkpointReopened ? "suspended" : resumePlane.status, fleetRunResiduals(sealed));
         return {
             status: 200,
+            decisionCommitted: true,
             body: {
                 taskId, sessionId, status: resumePlane.status,
                 bindingEnforced: true,
@@ -1301,7 +1317,7 @@ export function createResumeLegs(ctx) {
     }
     const routeCtxBase = {
         deps,
-        registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
+        registry: { idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters },
         helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal(), capabilities: createCapabilitiesLocal() },
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, preparePlanReview, drivePlanReview },

package/dist/http/route-ctx.d.ts

@@ -26,12 +26,15 @@ import type { SessionsLocal } from "./routes/sessions.js";
 import type { SessionSyncLocal } from "./routes/session-sync.js";
 import type { PlanApprovePermissionModeAfter } from "../task-settings.js";
 import type { VerifyRoundsSpec } from "./verify-rounds.js";
-/** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。 */
+import type { RunAbort } from "../run-cancel-context.js";
+/** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。
+ *  S-947:`cancelledViaVerb`(按 taskId 键控的「这次是取消动词」旁表)删除 —— 中止成因改挂在每条腿自己的
+ *  {@link RunAbort} 句柄上(`inflightRuns` 的值),同寿同删,不再有一张与腿不同寿的旁表。 */
 export interface RunRegistry {
     idemCache: IdempotencyCache<SubmitOutcome>;
-    inflightRuns: Map<string, AbortController>;
+    /** 本副本在飞的 durable 腿 → 它的中止句柄(取消动词的同副本快路在这里按 `cancel_verb` 中止它)。 */
+    inflightRuns: Map<string, RunAbort>;
     preemptableRuns: Map<string, AbortController>;
-    cancelledViaVerb: Set<string>;
     steerableRuns: Map<string, TaskStream>;
     wakeParkMints: Map<string, Promise<void>>;
     /** 裸 number 的登记簿(`let` 拆不出闭包)—— 装进盒子才能跨模块自增/自减。 */
@@ -380,15 +383,9 @@ export interface RouteLegs {
     decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }): Promise<{
-        status: number;
-        body: object;
-    }>;
+    }): Promise<ResumeLegOutcome>;
     /** 全 resume 家族的共同下半场(lease admission + 写 run log + fleet 发布)。 */
-    driveResumeIntoRunLog(args: DriveResumeArgs): Promise<{
-        status: number;
-        body: object;
-    }>;
+    driveResumeIntoRunLog(args: DriveResumeArgs): Promise<ResumeLegOutcome>;
     /** assistant 抢占腿的复位(gate-kind 守卫 + 行级属主复核 + 驱动)。 */
     resumePreempted(sessionId: string, req: IncomingMessage | undefined, 
     /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/resume` 腿传 `true`。 */
@@ -628,6 +625,26 @@ export type RouteDecl = RouteDispatchDecl | RouteGateDecl;
  * 两臂逐字节同形,指路价值不丢。钉=audit-fixes-http「[ref]」格(两臂全文比对);文案变更走
  * api-error-text-freeze 基线流程。
  */
+/**
+ * resume 家族一条腿的结局:HTTP 应答(`status` / `body`)+ 一位**进程内**事实(不上 wire)。
+ *
+ * `decisionCommitted` —— **这条腿的终局是在引擎受理了这次决定之后才结出来的**([ref] X5,7.112.0):本腿走到了「引擎交回结果」那一步
+ * (`resumeStream` / `resumeWithVerification` 解析 = core 的全部 pre-CAS 门 + checkpoint resolve CAS 都过了 —— 受理点的判据属主
+ * = {@link DriveResumeArgs.acceptEarly} 顶注),之后才收场。只由 `driveResumeLeg` 走完引擎那一步的终局出口铸;`CheckpointError` 臂、
+ * 「中止抛穿」臂、一切 4xx / 拒绝出口一律**不铸**(缺席 ⇒ 证不出提交,读者按「没提交」读 —— fail-closed)。
+ *
+ * 读者:`/decide` 的两道「这次决定提交了没有」门 —— [ref] 迟到结算留痕(`noteLateSettleIfAccepted`)与 remember 豁免落店
+ * (`routes/approvals-assistant.ts`)。它们原先只读 wire 体的 `errorCode !== "cancelled"`(「取消 = 决定没提交」),S-947 给续跑腿补了
+ * 「引擎受理之后才被取消」的取消终局之后,`cancelled` 不再等价「没提交」⇒ 两门改读本位:`200 ∧ (errorCode≠cancelled ∨ decisionCommitted)`。
+ * 🔴 为什么不放进 `result.cancelContext`(主会话初稿的落点):那只快照的契约是「分诊材料,不是状态机输入:任何门 / CAS / resume 判定都不许
+ * 读它」(`plugins/store-contracts.ts` `RunCancelContext` 顶注)—— 这两道门正是判定;而且门读的是 `/decide` 的平面体、看不到结果对象。
+ * 受理与否是腿自己的控制流事实,在腿上说,零 wire 变更。
+ */
+export interface ResumeLegOutcome {
+    status: number;
+    body: object;
+    decisionCommitted?: true;
+}
 /**
  * **「决定/续跑已受理」那一枚 200 收据的单一铸点**(S-218)。
  *

package/dist/http/routes/approvals-assistant.js

@@ -764,7 +764,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 : undefined;
             const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, hostDecisionFacts(settledBy, deciderPrincipal), req, answer, binding, grantOnCommit, true, { principal: deciderPrincipal, explicitOperator });
             const outErrorCode = out.body.errorCode;
-            if (pendingGrant !== undefined && out.status === 200 && outErrorCode !== "cancelled" && deps.approvalExemptionStore) {
+            if (pendingGrant !== undefined && out.status === 200 && (outErrorCode !== "cancelled" || out.decisionCommitted === true) && deps.approvalExemptionStore) {
                 try {
                     await deps.approvalExemptionStore.grant(pendingGrant.sessionId, pendingGrant.toolName, deciderPrincipal ?? null);
                     rememberApplied = true;

package/dist/http/routes/runs.js

@@ -148,7 +148,7 @@ async function acceptLiveUserInput(deps, res, at) {
 }
 export async function handleRuns(req, res, match, ctx) {
     const { deps } = ctx;
-    const { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints } = ctx.registry;
+    const { idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints } = ctx.registry;
     const { readJson, rateLimited, quotaExceeded, leaseDenied, usageWindowDenied, runOwnerOk, runSessionAcceptOk } = ctx.helpers;
     const { prepareSpec } = ctx.legs;
     const source = ctx.req.source;
@@ -319,7 +319,7 @@ export async function handleRuns(req, res, match, ctx) {
             }
             const err = note;
             try {
-                const result = mintCancelledResult({ taskId, sessionId: run.sessionId, startedAtMs: Date.parse(run.createdAt), message: err });
+                const result = mintCancelledResult({ taskId, sessionId: run.sessionId, startedAtMs: Date.parse(run.createdAt), message: err, cause: "cancel_verb" });
                 let lastErr;
                 for (let attempt = 0;; attempt++) {
                     try {
@@ -368,10 +368,7 @@ export async function handleRuns(req, res, match, ctx) {
                 sendJson(res, 202, { taskId, status: now?.status ?? "failed", cancelRequested: now?.cancelRequested ?? false, note: "run already terminal — cancel is a no-op" });
                 return;
             }
-            if (inflightRuns.has(taskId)) {
-                cancelledViaVerb.add(taskId);
-                inflightRuns.get(taskId).abort();
-            }
+            inflightRuns.get(taskId)?.abort("cancel_verb");
             sendJson(res, 202, { taskId, status: "cancelling", cancelRequested: true });
         }
         else if (isParkedRunStatus(run.status)) {

package/dist/http/routes/tasks.d.ts

@@ -11,8 +11,9 @@
  *   · {@link handleTasksBody} 内的 `runStreamSubmitLeg` —— plain-stream 腿(原 703 行匿名体);
  *   · `runSyncSubmitLeg` —— 同步腿(原 128 行匿名体);
  *   · 同步腿内 `verifyLeg` / `cascadeLeg` / `plainLeg` —— 三条模型驱动腿,判别顺序与短路语义逐字不变。
- * 提名**只改名字不改行为**:闭包捕获的自由变量、语句顺序、`cancelledViaVerb` 的 first-writer-wins 取值时点
- * ([1.207 codex H2]:在 `inflightRuns` 身份守卫内先取后删)、settle/registry 生命周期注释全部随代码原样迁移。
+ * 提名**只改名字不改行为**:闭包捕获的自由变量、语句顺序、settle/registry 生命周期注释全部随代码原样迁移。
+ * (S-947 起「这次是不是被 server 中止、为什么」读每腿自己的中止句柄 `RunAbort`,不再有按 taskId 键控的
+ * `cancelledViaVerb` 旁表与它「身份守卫内先取后删」的取值时点。)
  *
  * 与 runs 域共用 `ctx.legs.prepareSpec`(读体/校验/建 spec 的同一条前段)。
  */

package/dist/http/routes/tasks.js

@@ -10,7 +10,7 @@ import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotific
 import { createLedgerSink } from "../../trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "../../trace/engine-notice-wire.js";
 import { clearTurnActivity, readTurnActivityMs, recordTurnActivity } from "../../turn-activity.js";
-import { mintCancelledResult } from "../../run-cancel-context.js";
+import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "../../run-cancel-context.js";
 import { recordResourceWindow } from "../../resource-window.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { contextUsageEventData, turnEndEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestFaceEventData, toolRosterDeltaEventData, toolProgressEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, textEndEventData, liveIdentityFields } from "../../trace/project.js";
@@ -57,7 +57,7 @@ function sendSubmitResult(res, resp) {
 const MULTI_ATTEMPT_NO_EVENT_CHANNEL_NOTICE = "verify / cascade ran with their normal multi-attempt semantics, but the synchronous /v1/tasks endpoint has no event channel — no status/progress frames exist to replay on this shape. For status / progress / delegated-child frames and the terminal done, submit via POST /v1/runs and read GET /v1/runs/:id/events; note that verify / cascade legs carry no per-turn stream there either (no wiring_manifest / text / turn_end frames — the engine runs those legs as result-returning attempts).";
 export async function handleTasks(req, res, match, ctx) {
     const { deps } = ctx;
-    const { idemCache, inflightRuns, cancelledViaVerb, steerableRuns, counters } = ctx.registry;
+    const { idemCache, inflightRuns, steerableRuns, counters } = ctx.registry;
     const { rateLimited, quotaExceeded, leaseDenied, usageWindowDenied } = ctx.helpers;
     const { prepareSpec, finalizeTaskResult } = ctx.legs;
     const reqState = ctx.req;
@@ -136,7 +136,7 @@ export async function handleTasks(req, res, match, ctx) {
             if (earlyDurableTid) {
                 res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId: earlyDurableTid, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) })}\n\n`);
             }
-            const ac = new AbortController();
+            const ac = createRunAbort();
             let closed = false;
             let detachLogged = false;
             let disconnectParkGrace;
@@ -158,14 +158,14 @@ export async function handleTasks(req, res, match, ctx) {
                         deps.logger?.info("stream_disconnect_ask_parked", { taskId: earlyDurableTid, sessionId: prepared.spec.sessionId, asks: parked, graceMs: DISCONNECT_PARK_GRACE_MS });
                         disconnectParkGrace = setTimeout(() => {
                             closed = true;
-                            ac.abort();
+                            ac.abort("ask_park_grace_exhausted");
                         }, DISCONNECT_PARK_GRACE_MS);
                         disconnectParkGrace.unref?.();
                         return;
                     }
                 }
                 closed = true;
-                ac.abort();
+                ac.abort("client_disconnected");
             };
             req.on("close", onDisconnect);
             res.on("close", () => {
@@ -213,13 +213,7 @@ export async function handleTasks(req, res, match, ctx) {
                 let runRowSettled = false;
                 let durableTaskId;
                 let durableHeartbeat;
-                const cancelledResult = (errorMessage, engineResult) => mintCancelledResult({
-                    taskId: durableTaskId ?? "",
-                    sessionId: prepared.spec.sessionId ?? "",
-                    startedAtMs: streamLegStartedAt,
-                    message: errorMessage,
-                    ...(engineResult !== undefined ? { engineResult } : {}),
-                });
+                const cancelledResult = (errorMessage, cause) => mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId ?? "", startedAtMs: streamLegStartedAt, message: errorMessage, cause });
                 let userMsgEntryId;
                 let anchorPut = false;
                 const putRewindAnchor = () => {
@@ -267,10 +261,7 @@ export async function handleTasks(req, res, match, ctx) {
                     usageKey = tid;
                     deps.modelUsage?.register(tid);
                     const owner = principal ?? null;
-                    const abortFromVerb = () => {
-                        cancelledViaVerb.add(tid);
-                        ac.abort();
-                    };
+                    const abortFromVerb = () => ac.abort("cancel_verb");
                     durableHeartbeat = setInterval(() => {
                         void rs.heartbeat(tid, owner).catch(() => undefined);
                         if (!ac.signal.aborted) {
@@ -292,10 +283,8 @@ export async function handleTasks(req, res, match, ctx) {
                 catch (e) {
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
-                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
+                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac)
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
-                    }
                     throw e;
                 }
                 let fleetSettled = false;
@@ -315,10 +304,8 @@ export async function handleTasks(req, res, match, ctx) {
                 catch (e) {
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
-                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
+                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac)
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
-                    }
                     settleFleet("failed");
                     throw e;
                 }
@@ -430,13 +417,13 @@ export async function handleTasks(req, res, match, ctx) {
                                     sseData(res, end);
                                 if (ev.type === "message_committed" && ev.role === "user")
                                     userMsgEntryId = ev.entryId;
-                                const cancelVerbAtDone = ev.type === "done" && durableTaskId !== undefined && cancelledViaVerb.has(durableTaskId);
+                                const causeAtDone = ev.type === "done" ? ac.cause() : undefined;
                                 if (ev.type === "done") {
                                     finalResult = await mintSubmitExitResult(ev.result, deps.checkpointStore);
                                     if (durableTaskId && finalResult)
                                         finalResult = { ...finalResult, taskId: durableTaskId };
-                                    if (cancelVerbAtDone && finalResult !== undefined) {
-                                        finalResult = cancelledResult("cancelled by user", finalResult);
+                                    if (causeAtDone !== undefined && finalResult !== undefined) {
+                                        finalResult = mintCancelledResult({ taskId: durableTaskId ?? "", sessionId: prepared.spec.sessionId ?? "", startedAtMs: streamLegStartedAt, message: "cancelled by user", cause: causeAtDone, engineResult: finalResult });
                                     }
                                     finalizeTaskResult(ev.result, principal, prepared.spec.objective, prepared.spec.sessionId);
                                     noteRunOutcome(finalResult);
@@ -672,6 +659,7 @@ export async function handleTasks(req, res, match, ctx) {
                         else {
                             putRewindAnchor();
                             const pending = await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId);
+                            const dcCause = ac.cause();
                             if (pending) {
                                 if (ledgerSink && !ledgerTerminal) {
                                     ledgerTerminal = true;
@@ -681,18 +669,28 @@ export async function handleTasks(req, res, match, ctx) {
                                 await deps.runStore.setSuspended(durableTaskId, null);
                                 settleFleet("suspended");
                             }
-                            else {
+                            else if (dcCause !== undefined) {
                                 const dcErr = "stream client disconnected before completion (run aborted)";
-                                const dc = cancelledResult(dcErr);
+                                const dc = cancelledResult(dcErr, dcCause);
                                 if (ledgerSink && !ledgerTerminal) {
                                     ledgerTerminal = true;
                                     await ledgerSink.flush().catch(() => undefined);
-                                    await ledgerSink.append("failed", { errorMessage: dcErr, errorCode: "cancelled" }).catch(() => undefined);
+                                    await ledgerSink.append("failed", buildCancelledLedgerRow(dc)).catch(() => undefined);
                                 }
                                 await deps.runStore.setTerminal(durableTaskId, "failed", dc, dcErr);
                                 noteRunOutcome(dc);
                                 settleFleet("failed");
                             }
+                            else {
+                                const err = "stream ended before a terminal event";
+                                if (ledgerSink && !ledgerTerminal) {
+                                    ledgerTerminal = true;
+                                    await ledgerSink.flush().catch(() => undefined);
+                                    await ledgerSink.append("failed", { errorMessage: err }).catch(() => undefined);
+                                }
+                                await deps.runStore.setTerminal(durableTaskId, "failed", null, err);
+                                settleFleet("failed");
+                            }
                         }
                         runRowSettled = true;
                     }
@@ -706,10 +704,8 @@ export async function handleTasks(req, res, match, ctx) {
                         steerableRuns.delete(durableTaskId);
                     if (liveStreamRef !== undefined)
                         await deps.userInputLedger?.settleLeg(liveStreamRef);
-                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac) {
+                    if (durableTaskId && inflightRuns.get(durableTaskId) === ac)
                         inflightRuns.delete(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
-                    }
                     for (const evict of subagentHandleEvictions)
                         evict();
                     if (!runRowSettled && durableTaskId && deps.runStore) {
@@ -717,6 +713,7 @@ export async function handleTasks(req, res, match, ctx) {
                             const row = await deps.runStore.getRun(durableTaskId);
                             if (row?.status === "running") {
                                 const pending = prepared.spec.sessionId ? await deps.checkpointStore?.findPendingTokenBySession(prepared.spec.sessionId) : undefined;
+                                const backstopCause = ac.cause();
                                 if (pending) {
                                     if (ledgerSink && !ledgerTerminal) {
                                         ledgerTerminal = true;
@@ -735,13 +732,13 @@ export async function handleTasks(req, res, match, ctx) {
                                     await deps.runStore.setTerminal(durableTaskId, retryPlane.status, finalResult, retryPlane.errorMessage ?? null);
                                     settleFleet(retryPlane.status, fleetRunResiduals(finalResult));
                                 }
-                                else if (ac.signal.aborted) {
+                                else if (backstopCause !== undefined) {
                                     const err = "stream aborted before completion (run cancelled)";
-                                    const c = cancelledResult(err);
+                                    const c = cancelledResult(err, backstopCause);
                                     if (ledgerSink && !ledgerTerminal) {
                                         ledgerTerminal = true;
                                         await ledgerSink.flush().catch(() => undefined);
-                                        await ledgerSink.append("failed", { errorMessage: err, errorCode: "cancelled" }).catch(() => undefined);
+                                        await ledgerSink.append("failed", buildCancelledLedgerRow(c)).catch(() => undefined);
                                     }
                                     await deps.runStore.setTerminal(durableTaskId, "failed", c, err);
                                 }
@@ -808,17 +805,14 @@ export async function handleTasks(req, res, match, ctx) {
                 if (deps.checkpointStore && prepared.spec.sessionId) {
                     await deps.checkpointStore.putCtx(prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
                 }
-                const syncCancelCtrl = new AbortController();
+                const syncCancelCtrl = createRunAbort();
                 if (prepared.spec.sessionId)
                     markChildrenStoppedByUserOnAbort(syncCancelCtrl.signal, durableTaskId ?? prepared.spec.sessionId, prepared.auth?.principal);
                 if (durableTaskId && deps.runStore) {
                     const rs = deps.runStore;
                     const tid = durableTaskId;
                     const owner = principal ?? null;
-                    const abortFromVerb = () => {
-                        cancelledViaVerb.add(tid);
-                        syncCancelCtrl.abort();
-                    };
+                    const abortFromVerb = () => syncCancelCtrl.abort("cancel_verb");
                     durableHeartbeat = setInterval(() => {
                         void rs.heartbeat(tid, owner).catch(() => undefined);
                         if (!syncCancelCtrl.signal.aborted) {
@@ -841,7 +835,6 @@ export async function handleTasks(req, res, match, ctx) {
                     wiringReceipt = wiringManifestFaceEventData(ev, wiringOperatorFace, instructionLeg.segment());
                 };
                 let result;
-                let cancelVerbLabel = false;
                 counters.uncountedBillableInflight++;
                 try {
                     const verifyLeg = (v) => runWithVerification(prepared.runner, specWithSignal, v);
@@ -858,18 +851,17 @@ export async function handleTasks(req, res, match, ctx) {
                     counters.uncountedBillableInflight--;
                     if (durableHeartbeat)
                         clearInterval(durableHeartbeat);
-                    if (durableTaskId && inflightRuns.get(durableTaskId) === syncCancelCtrl) {
+                    if (durableTaskId && inflightRuns.get(durableTaskId) === syncCancelCtrl)
                         inflightRuns.delete(durableTaskId);
-                        cancelVerbLabel = cancelledViaVerb.has(durableTaskId);
-                        cancelledViaVerb.delete(durableTaskId);
-                    }
                 }
-                if (cancelVerbLabel) {
+                const syncAbortCause = syncCancelCtrl.cause();
+                if (syncAbortCause !== undefined) {
                     result = mintCancelledResult({
                         taskId: durableTaskId ?? "",
                         sessionId: prepared.spec.sessionId ?? "",
                         startedAtMs: syncLegStartedAt,
                         message: "cancelled by user",
+                        cause: syncAbortCause,
                         engineResult: result,
                     });
                 }

package/dist/http/server.js

@@ -43,7 +43,6 @@ export function createHttpServer(rawDeps) {
     }
     const idemCache = new IdempotencyCache();
     const inflightRuns = new Map();
-    const cancelledViaVerb = new Set();
     const preemptableRuns = new Map();
     const steerableRuns = new Map();
     const wakeParkMints = new Map();
@@ -97,7 +96,7 @@ export function createHttpServer(rawDeps) {
     }
     const { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, runSessionAcceptOk, readJson, readRawBody } = createRequestGuards({ deps });
     const { prepareSpec } = createAdmission({ deps, readJson, runnerFor });
-    const { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake } = createResumeLegs({ deps, runnerFor, idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor });
+    const { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake } = createResumeLegs({ deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor });
     const { denyExpiredApprovals, redeemParkedAsk } = createApprovalSweeps({ deps, resumeCheckpoint, mayDiscloseRowError });
     const { handle } = createDispatch({ deps, noteActivity, routeCtxBase, counters });
     const server = http.createServer((req, res) => {

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

@@ -281,9 +281,13 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-107:持久 error 脱后 UTF-8 字节 > 65,000(TiDB TEXT 65,535 字节)⇒ 脱后切并带标记(切在占位里不是泄漏);计数=多少条终态文案被字节封顶截断";
     };
+    readonly "server.runs.abort-cause-missing": {
+        readonly cls: "F";
+        readonly note: "S-947 候裁 ⑤(主会话裁:默认值保留,miss 臂必须响):续跑腿 `http/resume-legs.ts` 的 `checkpoint.resume_aborted` 臂 —— core 只在本腿递进去的信号**已中止**时铸该码,而那只信号唯一的写者是取消动词(快路 / 耐久旗轮询,句柄登记 `cancel_verb`),所以**只有 core 契约外的形**(桩 / 非 core Runner 直接抛该码,本腿句柄从未中止)才到得了「句柄上读不到成因」这一臂。取消终局照铸,成因取本腿唯一的中止词 `cancel_verb`(取消终局恒带成因由铸点签名保证,不让它缺);detail `task=<taskId>`;计数 = 多少次取消成因是默认值而不是句柄登记的。生产上恒零是证据,不归零 = 有一条不走 core 契约的 Runner 在跑续跑腿。";
+    };
     readonly "server.runs.terminal-ledger-write-failed": {
         readonly cls: "F";
-        readonly note: "S-107(全量门 silent-degradation 棘轮抓出的五处静默 `catch {}`):run 终局链里**账本腿**(flush 缓冲 text/reasoning、append `failed` 行)与终态翻转(setTerminal)已不共命运——账本 INSERT 抛不再让 run 卡 running 到 reaper;但那条抛掉的账本行之前是**静默**吞的。detail `arm=` 四臂(flush-clean-cancel / append-clean-cancel / flush-catch / append-thrown-cancel / append-failed):缺的是 run_events 尾巴(缓冲文本或 failed 事件),run 行本身仍是 durable truth,读面/reaper 容忍缺失,故 F 类;计数=多少次终局账本写失败。";
+        readonly note: "S-107(全量门 silent-degradation 棘轮抓出的五处静默 `catch {}`):run 终局链里**账本腿**(flush 缓冲 text/reasoning、append `failed` 行)与终态翻转(setTerminal)已不共命运——账本 INSERT 抛不再让 run 卡 running 到 reaper;但那条抛掉的账本行之前是**静默**吞的。detail `arm=` 四臂(flush-clean-cancel / append-clean-cancel / flush-catch / append-thrown-cancel / append-failed);S-947 起续跑腿(`http/resume-legs.ts`)两座同 tag:resume-append-resume-aborted / resume-append-thrown-cancel(取消抛出两臂的 `failed` 行,修前那两臂根本不落账本终局行):缺的是 run_events 尾巴(缓冲文本或 failed 事件),run 行本身仍是 durable truth,读面/reaper 容忍缺失,故 F 类;计数=多少次终局账本写失败。";
     };
     readonly "server.redact.ppk-eat-to-end": {
         readonly cls: "F";

package/dist/observability/fail-open.js

@@ -260,7 +260,8 @@ export const FAIL_OPEN_TAGS = {
     "server.run-terminal.artifact-capped": { cls: "F", note: "S-107:leader_run 行上的工件字节(salvaged[].patch / candidatePatch.patch / merge.candidatePatch / merge.rej)长度 > ARTIFACT_INPUT_CAP(256KB)⇒ 整份换 «redacted:oversized-artifact»(fail-closed 取证丢弃;原字节仍在 worker 分支/merge 咽喉);计数=多少份工件被整份丢弃" },
     "server.run-terminal.diag-capped": { cls: "F", note: "S-107:诊断文本座(merge details/measure/grader trace、leader 日志座、planner 样本、journal 预览、workflow_run error cut)长度 > DIAG_INPUT_CAP(256KB)⇒ 整段换 «redacted:oversized-diagnostic» [len=N](fail-closed 取证丢弃;固定窗不 fail-closed 故不开窗);计数=多少段诊断文本被整段丢弃" },
     "server.run-terminal.output-truncated": { cls: "F", note: "S-107:持久 error 脱后 UTF-8 字节 > 65,000(TiDB TEXT 65,535 字节)⇒ 脱后切并带标记(切在占位里不是泄漏);计数=多少条终态文案被字节封顶截断" },
-    "server.runs.terminal-ledger-write-failed": { cls: "F", note: "S-107(全量门 silent-degradation 棘轮抓出的五处静默 `catch {}`):run 终局链里**账本腿**(flush 缓冲 text/reasoning、append `failed` 行)与终态翻转(setTerminal)已不共命运——账本 INSERT 抛不再让 run 卡 running 到 reaper;但那条抛掉的账本行之前是**静默**吞的。detail `arm=` 四臂(flush-clean-cancel / append-clean-cancel / flush-catch / append-thrown-cancel / append-failed):缺的是 run_events 尾巴(缓冲文本或 failed 事件),run 行本身仍是 durable truth,读面/reaper 容忍缺失,故 F 类;计数=多少次终局账本写失败。" },
+    "server.runs.abort-cause-missing": { cls: "F", note: "S-947 候裁 ⑤(主会话裁:默认值保留,miss 臂必须响):续跑腿 `http/resume-legs.ts` 的 `checkpoint.resume_aborted` 臂 —— core 只在本腿递进去的信号**已中止**时铸该码,而那只信号唯一的写者是取消动词(快路 / 耐久旗轮询,句柄登记 `cancel_verb`),所以**只有 core 契约外的形**(桩 / 非 core Runner 直接抛该码,本腿句柄从未中止)才到得了「句柄上读不到成因」这一臂。取消终局照铸,成因取本腿唯一的中止词 `cancel_verb`(取消终局恒带成因由铸点签名保证,不让它缺);detail `task=<taskId>`;计数 = 多少次取消成因是默认值而不是句柄登记的。生产上恒零是证据,不归零 = 有一条不走 core 契约的 Runner 在跑续跑腿。" },
+    "server.runs.terminal-ledger-write-failed": { cls: "F", note: "S-107(全量门 silent-degradation 棘轮抓出的五处静默 `catch {}`):run 终局链里**账本腿**(flush 缓冲 text/reasoning、append `failed` 行)与终态翻转(setTerminal)已不共命运——账本 INSERT 抛不再让 run 卡 running 到 reaper;但那条抛掉的账本行之前是**静默**吞的。detail `arm=` 四臂(flush-clean-cancel / append-clean-cancel / flush-catch / append-thrown-cancel / append-failed);S-947 起续跑腿(`http/resume-legs.ts`)两座同 tag:resume-append-resume-aborted / resume-append-thrown-cancel(取消抛出两臂的 `failed` 行,修前那两臂根本不落账本终局行):缺的是 run_events 尾巴(缓冲文本或 failed 事件),run 行本身仍是 durable truth,读面/reaper 容忍缺失,故 F 类;计数=多少次终局账本写失败。" },
     "server.redact.ppk-eat-to-end": { cls: "F", note: "S-107 第三十二轮重扫:PuTTY .ppk 容器扫描器(redact.ts redactPpkContainers)在「无合格终止 / 收口后同容器范围再见私钥字段 / 收口后到下一版本头之间夹非空白」三形下从头**吃到输入末尾**(fail-closed 取证丢弃)——终态 errorMessage 座上=整条错误文案变成 «redacted:private-key»,与 redactions_applied_total{private-key} 的诚实替换同形不可分,故要有自己的计数/探针;影子扫不计;计数=多少次整段吃尾。" },
     "server.approval-card.closed-word-out-of-set": {
         cls: "F",

package/dist/plugins/store-contracts.d.ts

@@ -94,16 +94,49 @@ export interface RunCancelContext {
     elapsedMs?: number;
 }
 /**
- * 落库/上 wire 的终局结果 = core 的 `TaskResult` **加上** server 自铸的可缺席侧记键。
+ * 🔴 S-947(cli [ref] 第 3 件 / L-212)—— **server 为什么中止了这条 run**:取消终局的机读成因,闭集。
  *
- * 今天只有一个成员({@link RunCancelContext});additive 且可缺席,所以旧行、旧消费端逐字不受影响
- * (`TaskResult` 仍可原样赋给本型)。⚠️ 这不是给「往 core 结果里塞私货」开的口子:每加一个键都要能
- * 回答「为什么它属于 run 账本而不属于 core 的任务结果」——`cancelContext` 的答案是它描述的是
- * **server 侧的取消现场**,core 那一侧根本不知道有人按了取消。
+ * 病:非 detach 流断连、`POST /v1/runs/:id/cancel`、断连时有 ask 但 park 宽限用尽 —— 三件事在终局上**逐字同形**
+ * (`failed` + `terminal.code:"cancelled"`),壳只能按 `errorMessage` 文案猜。
+ *
+ * 每个词都必须有一个**真站点**(没有站点的词不许进表;普查与站点坐标见契约 §5.0d):
+ *  · `client_disconnected`      —— 非 detach 的 `POST /v1/tasks/stream` 客户端断连,断连那一刻本 run 没有流内未决 ask
+ *                                  (`http/routes/tasks.ts` 的断连臂,立即中止);
+ *  · `ask_park_grace_exhausted` —— 同一断连臂,但断连那一刻有流内未决 ask、已按窗到期同路转 park,宽限计时器用尽时 park 仍没落成;
+ *  · `cancel_verb`              —— `POST /v1/runs/:id/cancel`:同副本快路、跨副本耐久取消旗的轮询(四条腿的心跳 / 登记追平),
+ *                                  以及 park 中的 run 被它直接终局化(那一形不经 abort,成因照样是这条动词)。
+ * **刻意不在表里**(普查过、没有真站点):抢占(`preempt` 是优雅让出,终局是 `paused`,不是取消)、有序关停
+ * (S-929 只把未决卡转 park,从不中止活 run;进程退出后的行由收割器落「持有者死亡」判决,那不是本仓铸的取消终局)、
+ * `interrupt`(引擎的 turn 动词,终局 `completed` + `haltedByUser`)、detach 断连(不中止)。
+ *
+ * 词表属主 = 本文件(与它所在的 {@link PersistedTaskResult} 同住);**单写者** = `run-cancel-context.ts` 的 `createRunAbort`
+ * (中止那一刻登记)与 `mintCancelledResult`(终局铸点读它),自铸 wire 值登记 = `trace/self-minted-wire.ts` 的 `abortCause`
+ * (`satisfies Record<AbortCause, …>`:加 / 删一个词而登记没跟 ⇒ tsc 红)。
  */
-export type PersistedTaskResult = TaskResult & {
+export declare const ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
+export type AbortCause = (typeof ABORT_CAUSES)[number];
+/**
+ * server 自铸、挂在终局结果上的**侧记键**全集(都描述「server 这一侧发生了什么」,core 那一侧无从知道)。
+ * 本型是这一族键的**唯一登记处**(`trace/core-keyset-guard.ts` 的辖域线指向这里;那边另有一道编译期钉:
+ * core 的 `TaskResult` 哪天长出同名键 ⇒ 当场红 —— 同一个键两个铸者是本型存在要防的那件事)。
+ *  · `cancelContext`([ref])—— 取消现场快照(分诊材料:多久没动静、起跑多久);
+ *  · `abortCause`(S-947)—— 这次取消是谁 / 什么发起的({@link AbortCause})。
+ * 两键**同一只铸点**(`mintCancelledResult`)、**同一条在场闸**(「只补空座」:终局就是被那次中止打断的那一条,
+ * 才挂;与中止赛跑跑完的终局、引擎自带码的失败一律原样立住、两键都不挂)。差别只在缺席纪律:快照一键都证不出 ⇒ 整只缺席;
+ * 成因在铸点那一刻恒已知 ⇒ 取消终局上恒在场。
+ */
+export interface PersistedResultSideKeys {
     cancelContext?: RunCancelContext;
-};
+    abortCause?: AbortCause;
+}
+/**
+ * 落库/上 wire 的终局结果 = core 的 `TaskResult` **加上** server 自铸的可缺席侧记键({@link PersistedResultSideKeys})。
+ *
+ * additive 且可缺席,所以旧行、旧消费端逐字不受影响(`TaskResult` 仍可原样赋给本型)。⚠️ 这不是给「往 core 结果里塞私货」
+ * 开的口子:每加一个键都要能回答「为什么它属于 run 账本而不属于 core 的任务结果」—— 两键的答案都是它们描述的是
+ * **server 侧的取消现场**,core 那一侧根本不知道有人按了取消、谁按的。落点 = `result` JSON 列(三孪生整只存),**零新列**。
+ */
+export type PersistedTaskResult = TaskResult & PersistedResultSideKeys;
 /**
  * 🔴 run 店「持有它的实例丢了」那一判的**行上落款**(S-928 codex r1-F1 提为常量):三只 run 店的 `reapStale` 把心跳过期的 running 行翻成
  * `failed` 并写下这一句。它是 run 店死亡判决留在行上的证据之一(另一只 = {@link RUN_ORPHANED_ERROR})—— 用户输入受理账本的收敛判词

package/dist/plugins/store-contracts.js

@@ -1,5 +1,6 @@
 export class StoreBootRefusalError extends Error {
 }
+export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
 export const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 export const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
 export function buildRunOrphanedError(heldBy) {

package/dist/run-cancel-context.d.ts

@@ -1,4 +1,4 @@
-import type { PersistedTaskResult, RunCancelContext } from "./plugins/store-contracts.js";
+import type { AbortCause, PersistedTaskResult, RunCancelContext } from "./plugins/store-contracts.js";
 /**
  * @param taskId  这条 run 的账本 id(turn 活性登记的键)。
  * @param startedAtMs 这条 run 起跑的墙钟时刻(epoch ms):取消腿手上有行就用行的 `createdAt`,
@@ -43,11 +43,23 @@ export declare const CANCELLED_CODE = "cancelled";
  *  · `cancelContext`:已经有快照就不重铸(重铸会把「上一条引擎事件多久以前」重新计时)。
  *
  * ## 为什么不判「这条 failed 是不是 abort 形」
- * 判据在**调用点**:调用点问的是「本腿这次是不是被取消动词打中了」(`cancelCtrl.signal.aborted` /
- * `cancelledViaVerb`),那是 server 自己的事实。让本函数去嗅 `terminal.message` 的字面就是再造事实
+ * 判据在**调用点**:调用点问的是「本腿这次是不是被 server 中止了」—— 本腿 {@link RunAbort} 句柄上登记的成因
+ * (`cause()` 在场),那是 server 自己的事实。让本函数去嗅 `terminal.message` 的字面就是再造事实
  * —— [ref] 二那次事故的同一个形。
+ *
+ * ## S-947:成因(`abortCause`)与码、快照**同进同退**
+ * `cause` 是**必填**:本函数是 server 铸取消终局的唯一出口,而每一次取消都有一个发起者 ⇒ 「本仓铸的取消终局上恒有
+ * `abortCause`」由签名保证,不靠调用方记得。它走与补码、补快照**同一条**空座闸 —— 引擎给的终局不是无码的 failed
+ * (与中止赛跑跑完了 / 引擎自带码)⇒ 整只原样返回,成因也不挂(那条终局不是这次中止的结果,挂上就是「完成了却带着取消便签」)。
  */
-export declare function mintCancelledResult(args: {
+export declare function mintCancelledResult<R extends PersistedTaskResult>(args: CancelMintArgs & {
+    engineResult: R;
+}): R;
+export declare function mintCancelledResult(args: CancelMintArgs & {
+    engineResult?: undefined;
+}): PersistedTaskResult;
+/** {@link mintCancelledResult} 的公共实参(`engineResult` 另列:在场与否决定返回型)。 */
+interface CancelMintArgs {
     /** 这条 run 的账本 id(活性登记的键;账本不在场时给空串,快照按「证不出」处理)。 */
     taskId: string;
     /** 会话 id(合成形要写进结果;引擎给了结果时不用)。 */
@@ -56,7 +68,47 @@ export declare function mintCancelledResult(args: {
     startedAtMs: number;
     /** 合成形的失败文案(引擎给了终局时不用)。 */
     message: string;
-    /** 引擎给出的终局(在场 ⇒ 在它之上补标)。 */
-    engineResult?: PersistedTaskResult;
-}): PersistedTaskResult;
+    /** S-947:这次取消的发起者(本腿 {@link RunAbort} 句柄上登记的那一个;park 中直接终局化的取消动词给 `"cancel_verb"`)。 */
+    cause: AbortCause;
+}
+/**
+ * S-947 —— 没有 `done` 可落的取消形在账本上的那一行(`failed`):**从铸好的取消终局投影**,不手抄。
+ *
+ * 账本 `failed` 行是平面形(`errorMessage` / `errorCode` 顶层),所以成因也在顶层、与 `errorCode` 并列;有 `done` 可落的
+ * 那几形,成因随 `done.result` 走(结果本身带它)。两形同一个来源 = 同一只取消终局,不是两处各写一份。
+ * 返回纯数据 ⇒ `build*`。
+ */
+export declare function buildCancelledLedgerRow(c: PersistedTaskResult): {
+    errorMessage?: string;
+    errorCode?: string;
+    abortCause?: AbortCause;
+};
+/**
+ * S-947 —— 一条 run 腿的**中止句柄**:server 中止这条腿的唯一入口,也是「为什么中止」的唯一登记处。
+ *
+ * ## 为什么是句柄、不是一张按 taskId 键控的表
+ * 修前这件事由 `cancelledViaVerb: Set<taskId>`(「这次是取消动词」一个词)+ 各腿手写的生命周期(登记 / finally 里按身份守卫删 /
+ * 同步腿「删之前先取」)承担:一个键控在 **taskId** 上的旁表,要防的病都来自键与腿不同寿 —— 快速续跑在旧腿 finally 之前
+ * 用同一 taskId 登记新腿、旧腿收尾删掉新腿的条目;同步腿必须在删之前取值。成因挂在**腿自己的中止控制器**上之后,
+ * 这些规则一条都不需要:句柄与腿同寿,换腿就是换句柄,没有可删、可串、可漏的旁表。
+ *
+ * ## 先到先得(first-writer-wins)
+ * 第一次 `abort(cause)` 生效并登记成因;之后的调用全是 no-op(信号早已中止,成因不改写)—— 断连之后又到了取消动词、
+ * 取消之后又断连,终局说的都是**真正让这条腿停下来**的那一个。`AbortController.abort()` 自身就是幂等的,本句柄只是在
+ * 「第一次」那一刻把词记下。
+ *
+ * ## 引擎看到的东西不变
+ * 中止走 `AbortController.abort()` 的默认原因(引擎、provider 的 fetch、子进程看到的仍是标准 `AbortError`)—— 成因**不**塞进
+ * `signal.reason`:那会改掉引擎与 provider 层收到的拒绝值,是在下游改上游接缝的输入(立宪禁区)。
+ */
+export interface RunAbort {
+    /** 交给引擎的那只信号(`spec.signal` / 审批 / 提问 ALS 的 `abortSignal` / 子代 stoppedBy 归因都用它)。 */
+    readonly signal: AbortSignal;
+    /** 以 `cause` 中止本腿。已中止 ⇒ no-op(成因不改写)。 */
+    abort(cause: AbortCause): void;
+    /** 让本腿停下来的那次中止的成因;未中止 ⇒ `undefined`。 */
+    cause(): AbortCause | undefined;
+}
+export declare function createRunAbort(): RunAbort;
+export {};
 //# sourceMappingURL=run-cancel-context.d.ts.map

package/dist/run-cancel-context.js

@@ -23,6 +23,7 @@ export function mintCancelledResult(args) {
             ...engine,
             terminal: { ...engine.terminal, code: CANCELLED_CODE },
             ...(engine.cancelContext === undefined && ctx !== undefined ? { cancelContext: ctx } : {}),
+            abortCause: args.cause,
         };
     }
     return {
@@ -32,6 +33,31 @@ export function mintCancelledResult(args) {
         result: "",
         stats: { turns: 0, tokens: 0, usageMissing: true },
         ...(ctx ? { cancelContext: ctx } : {}),
+        abortCause: args.cause,
+    };
+}
+export function buildCancelledLedgerRow(c) {
+    const t = c.terminal;
+    return {
+        ...(t.kind === "failed" && t.message !== undefined ? { errorMessage: t.message } : {}),
+        ...(t.kind === "failed" && t.code !== undefined ? { errorCode: t.code } : {}),
+        ...(c.abortCause !== undefined ? { abortCause: c.abortCause } : {}),
+    };
+}
+export function createRunAbort() {
+    const ctrl = new AbortController();
+    let landed;
+    return {
+        signal: ctrl.signal,
+        abort(cause) {
+            if (ctrl.signal.aborted)
+                return;
+            landed = cause;
+            ctrl.abort();
+        },
+        cause() {
+            return landed;
+        },
     };
 }
 //# sourceMappingURL=run-cancel-context.js.map

package/dist/runs.d.ts

@@ -2,6 +2,7 @@ import { defaultTaskRegistry, type CascadeConfig, type CheckpointToken, type Run
 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";
+import { type RunAbort } from "./run-cancel-context.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "./budget.js";
 import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
@@ -259,10 +260,11 @@ export declare function evictIfConflict(runner: Runner, sessionId: string | unde
  * text); tool/lifecycle events are recorded individually. Per-token live streaming stays on the
  * synchronous `/v1/tasks/stream` endpoint. Never throws — failures are recorded on the run.
  *
- * Cancellation (POST /v1/runs/:id/cancel): the run registers an AbortController in `inflight` (same-replica
- * fast path — the cancel handler aborts it directly) and its heartbeat tick polls the durable
- * `cancel_requested` flag (cross-replica, ≤HEARTBEAT_MS lag). Either way the run settles to
- * status "failed" + errorCode "cancelled" (metric label "cancelled"); the entry is removed in `finally`.
+ * Cancellation (POST /v1/runs/:id/cancel): the run registers its abort handle (S-947 `RunAbort`) in `inflight`
+ * (same-replica fast path — the cancel handler aborts it directly) and its heartbeat tick polls the durable
+ * `cancel_requested` flag (cross-replica, ≤HEARTBEAT_MS lag); both abort with `cancel_verb`. Either way the run settles
+ * to status "failed" + errorCode "cancelled" + `result.abortCause` (metric label "cancelled"); the entry is removed in
+ * `finally`.
  *
  * Preemption (POST /v1/assistant/tasks/:id/preempt, [ref] seam #2): a SECOND, INDEPENDENT controller
  * (`preemptCtrl`, registered in `preemptable`) carries the scheduler's graceful "yield this task" — when raised,
@@ -281,7 +283,7 @@ export declare function evictIfConflict(runner: Runner, sessionId: string | unde
 export declare function runInBackground(runner: Runner, spec: TaskSpec, runStore: RunStore, taskId: string, metrics?: Metrics, principal?: string, verify?: VerifyRoundsSpec, // 快审 F1:number 参升整对象——cost 顶随传
 cascade?: CascadeConfig, instrumentDegenerate?: (result: TaskResult) => void, planCacheProbe?: {
     record: (scope: string | undefined, objective: string, completed: boolean) => void;
-}, persistThinking?: boolean, inflight?: Map<string, AbortController>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 
+}, persistThinking?: boolean, inflight?: Map<string, RunAbort>, preemptable?: Map<string, AbortController>, steerable?: Map<string, TaskStream>, modelUsage?: ModelUsageTracker, elicitation?: ElicitationCoordinator, 
 /** E23: the VERIFIED principal (gatedPrincipal) that may answer this run's elicitations — matches the respond
  *  owner-gate's identity source (NOT the cost-attribution `principal`, which on a direct door is the self-asserted
  *  header → can be null while a JWT principal exists). Falls back to the run owner when not supplied. */

package/dist/runs.js

@@ -12,7 +12,7 @@ import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest,
 import { createLedgerSink } from "./trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "./trace/engine-notice-wire.js";
 import { recordTurnActivity } from "./turn-activity.js";
-import { CANCELLED_CODE, mintCancelledResult } from "./run-cancel-context.js";
+import { buildCancelledLedgerRow, CANCELLED_CODE, createRunAbort, mintCancelledResult } from "./run-cancel-context.js";
 import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.js";
 import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
@@ -178,14 +178,16 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart();
-    const cancelCtrl = new AbortController();
+    const cancelCtrl = createRunAbort();
     inflight?.set(taskId, cancelCtrl);
     markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
     const preemptEligible = verify === undefined && cascade === undefined;
     const preemptCtrl = new AbortController();
     if (preemptEligible)
         preemptable?.set(taskId, preemptCtrl);
-    const cancelledResult = (engineResult) => mintCancelledResult({ taskId, sessionId: spec.sessionId ?? "", startedAtMs: startedAt, message: "cancelled by user", ...(engineResult !== undefined ? { engineResult } : {}) });
+    const cancelledResult = (cause, engineResult) => engineResult !== undefined
+        ? mintCancelledResult({ taskId, sessionId: spec.sessionId ?? "", startedAtMs: startedAt, message: "cancelled by user", cause, engineResult })
+        : mintCancelledResult({ taskId, sessionId: spec.sessionId ?? "", startedAtMs: startedAt, message: "cancelled by user", cause });
     const recordDone = (result, status) => {
         metrics?.addGauge("runs_active", -1);
         metrics?.inc("tasks_total", { status });
@@ -222,7 +224,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         void runStore.heartbeat(taskId, owner).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
         if (!cancelCtrl.signal.aborted) {
             void runStore.isCancelRequested(taskId, owner).then((c) => { if (c)
-                cancelCtrl.abort(); }).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "cancel" }); });
+                cancelCtrl.abort("cancel_verb"); }).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "cancel" }); });
         }
         if (preemptEligible && !preemptCtrl.signal.aborted) {
             void runStore.isPreemptRequested(taskId, owner).then((p) => { if (p)
@@ -233,7 +235,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     const anchor = new TurnAnchorCapture(captureTurnAnchor, () => metrics?.inc("resume_anchor_capture_failed"), captureUserMessageAnchor);
     let reached;
     let observedDone;
-    let cancelledAtDone = false;
+    let causeAtDone;
     let settledAsCancel = false;
     let steerableStreamRef;
     let legLive = true;
@@ -364,7 +366,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             for await (const ev of stream) {
                 if (ev.type === "done") {
                     observedDone = ev.result;
-                    cancelledAtDone = cancelCtrl.signal.aborted;
+                    causeAtDone = cancelCtrl.cause();
                 }
                 fleetPublisher?.onEvent(ev);
                 await flushPromptManifest();
@@ -402,7 +404,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     }
                     evictIfConflict(runner, spec.sessionId, ev.result);
                     {
-                        const settled = cancelledAtDone ? cancelledResult(ev.result) : ev.result;
+                        const settled = causeAtDone !== undefined ? cancelledResult(causeAtDone, ev.result) : ev.result;
                         settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
                         const safe = await withModelUsage(sealResultForExit(settled));
                         await sink.appendDone(safe);
@@ -448,17 +450,18 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 ? sendUserFile.runWithContext({ taskId, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); } }, withApproval)
                 : withApproval();
         })));
-        if (!reached && cancelCtrl.signal.aborted) {
+        const cleanCancelCause = cancelCtrl.cause();
+        if (!reached && cleanCancelCause !== undefined) {
             try {
                 await flush();
             }
             catch (e) {
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=flush-clean-cancel ${errText(e)}`);
             }
-            const c = cancelledResult();
+            const c = cancelledResult(cleanCancelCause);
             settledAsCancel = failureCodeOf(c.terminal) === CANCELLED_CODE;
             try {
-                await append("failed", { errorMessage: "cancelled by user", errorCode: CANCELLED_CODE });
+                await append("failed", buildCancelledLedgerRow(c));
             }
             catch (e) {
                 recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-clean-cancel ${errText(e)}`);
@@ -469,6 +472,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         }
     }
     catch (err) {
+        const thrownCancelCause = cancelCtrl.cause();
         const message = errText(err);
         try {
             try {
@@ -488,11 +492,11 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             else if (reached?.kind === "needs_review") {
                 await runStore.setNeedsReview(taskId, reached.result);
             }
-            else if (cancelCtrl.signal.aborted && observedDone === undefined) {
-                const c = cancelledResult();
+            else if (thrownCancelCause !== undefined && observedDone === undefined) {
+                const c = cancelledResult(thrownCancelCause);
                 settledAsCancel = failureCodeOf(c.terminal) === CANCELLED_CODE;
                 try {
-                    await append("failed", { errorMessage: "cancelled by user", errorCode: CANCELLED_CODE });
+                    await append("failed", buildCancelledLedgerRow(c));
                 }
                 catch (e) {
                     recordFailOpen("server.runs.terminal-ledger-write-failed", `arm=append-thrown-cancel ${errText(e)}`);

package/dist/trace/self-minted-wire.d.ts

@@ -58,6 +58,28 @@ export declare const SELF_MINTED_WIRE: {
             };
         };
     };
+    /**
+     * S-947(7.112.0):server 发起的中止在取消终局上留下的机读成因 —— `PersistedTaskResult.abortCause`,与 `cancelContext` 同住、同铸点、
+     * 同在场闸(在场 ⇔ 这条终局就是 server 那次中止铸出来的取消终局)。逐词站点见契约 §5.0d。键本身是 run 结果上的 server 侧记键
+     * (`store-contracts.ts` 的 `PersistedResultSideKeys`),不是事件投影面的键 ⇒ 不在 `wire-projection-faces.ts`。
+     */
+    readonly abortCause: {
+        readonly at: "run 结果 result.abortCause(GET /v1/runs/:id → result · done.result · POST /v1/tasks 200 体顶层 · 账本 done 行 result / 无 done 的取消形账本 failed 行顶层)";
+        readonly members: {
+            client_disconnected: {
+                attr: string;
+                since: string;
+            };
+            ask_park_grace_exhausted: {
+                attr: string;
+                since: string;
+            };
+            cancel_verb: {
+                attr: string;
+                since: string;
+            };
+        };
+    };
     /**
      * 会话所有者自助抹除面的**已分类拒** → HTTP 状态(S-930 起与 operator 面 `POST /v1/memory/erase` 同一只映射;`since` 记的是**本面**
      * 自哪一版起这样答 —— 7.107.0 及以前本面只认前两只,其余落 500 `internal.error`)。

package/dist/trace/self-minted-wire.js

@@ -21,6 +21,14 @@ export const SELF_MINTED_WIRE = {
             ".claude/AGENTS.md": { attr: "-", since: "7.111.0" },
         },
     },
+    abortCause: {
+        at: "run 结果 result.abortCause(GET /v1/runs/:id → result · done.result · POST /v1/tasks 200 体顶层 · 账本 done 行 result / 无 done 的取消形账本 failed 行顶层)",
+        members: {
+            client_disconnected: { attr: "-", since: "7.112.0" },
+            ask_park_grace_exhausted: { attr: "-", since: "7.112.0" },
+            cancel_verb: { attr: "-", since: "7.112.0" },
+        },
+    },
     sessionMemoryEraseStatus: {
         at: "POST /v1/sessions/:id/memory/erase(已分类拒 errorCode → HTTP 状态)",
         members: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.111.0",
+  "version": "7.112.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -61,7 +61,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.38.2",
+    "@sema-agent/core": "7.38.3",
     "@sema-agent/settings-schema": "6.4.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -77,7 +77,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "15.1.1",
+    "@sema-agent/sdk": "15.3.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",