@sema-agent/server 7.146.0 → 7.148.0

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export { loadConfig, type ServiceConfig } from "./config.js";
-export { composeExecutionLane, assertExecutionLaneInvariants, type ExecutionLaneComposeCtx } from "./boot/execution-lane.js";
+export { declareServerWithheldEnv } from "./server-secret-env.js";
+export { composeExecutionLane, assertExecutionLaneInvariants, HTTP_SERVICE_LANE_ENTRY, type ExecutionLaneComposeCtx, type ExecutionLaneEntry } from "./boot/execution-lane.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
 export { createStoreBackend, type StoreBackend, type SessionCaptureRecordSource } from "./plugins/store-backend.js";
 export { RetiredSchemaPresentError } from "./plugins/schema-consistency.js";
-export { LocalDataRootSchemaMismatchError, type LocalSidecarMismatch } from "./plugins/local-session-store.js";
+export { LocalDataRootSchemaMismatchError, type LocalDataRootMismatch } from "./plugins/local-session-store.js";
 export { CachingSessionStore, type CachingOptions } from "./plugins/caching-session-store.js";
 export type { RunRecord, RunEvent } from "./plugins/store-contracts.js";
 export { runInBackground } from "./runs.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { loadConfig } from "./config.js";
-export { composeExecutionLane, assertExecutionLaneInvariants } from "./boot/execution-lane.js";
+export { declareServerWithheldEnv } from "./server-secret-env.js";
+export { composeExecutionLane, assertExecutionLaneInvariants, HTTP_SERVICE_LANE_ENTRY } from "./boot/execution-lane.js";
 export { createBrain } from "./brain.js";
 export { createSessionStore } from "./plugins/session-store.js";
 export { createStoreBackend } from "./plugins/store-backend.js";

package/dist/instruction-source-notice.d.ts

@@ -10,7 +10,7 @@
  *
  * ## 基线 = 会话的服务端元数据
  * 基线是「同一 session 上一次 run 选中的链成员相对路径」(不是指纹:指纹密钥每进程随机,跨进程不可比)。它住在会话店的
- * 服务端元数据面 —— SQL 两孪生是 `session_meta.instruction_source` 一列,local 文件店是一只 sidecar —— 所以重启 /
+ * 服务端元数据面 —— SQL 两孪生是 `session_ext.instruction_source` 一列,local 文件店是一只 sidecar —— 所以重启 /
  * 跨副本都读得到、随会话删除一起消失,且不进模型上下文、不进 wire 会话面。不接这张面的店(core 的内存 dev 店、
  * `run-local` 的 core 文件店)⇒ 席缺席 ⇒ 一帧不发(诚实缺席:那两形的会话本来就活不过进程,或没有会话流可投)。
  *

package/dist/key-resolver.d.ts

@@ -84,6 +84,38 @@ export type ModelKeyRef = Pick<Model, "name">;
 export declare function createKeyResolver(modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedCustodyPoison>): ((model: ModelKeyRef) => Promise<{
     apiKey: string;
 } | undefined>) | undefined;
+/** 两张 per-model 钥匙表(`config.modelApiKeyEnv` / `config.modelApiKeys` 的形;缺席读作空表)。 */
+export interface ModelKeyTables {
+    readonly modelApiKeyEnv?: Readonly<Record<string, string>>;
+    readonly modelApiKeys?: Readonly<Record<string, string | SealedCustodyPoison>>;
+}
+/**
+ * 一只模型的**凭据身份**(不是值):它声明的钥匙来源是谁。
+ *  · `sealed` —— 托管密钥的解封产物(明文,或解不开时的毒丸;与 `config.modelApiKeys` 的值同型)。本进程的托管店 boot 只读一次,同一密文恒解出同一产物 ⇒
+ *    持有产物就是持有那一代的身份;重贴 = 新身份。
+ *  · `apiKeyEnv` —— 目录给它配的 env 变量**名**;值在取值那一刻按名读(同名轮换是同一身份)。
+ * 没有自有凭据 ⇒ `{}`。两张表至多一个条目有效(托管压过 env 引用,registry-core 互斥)。
+ */
+export interface CredentialIdentity {
+    readonly apiKeyEnv?: string;
+    readonly sealed?: string | SealedCustodyPoison;
+}
+/**
+ * 凭据身份的**唯一读法** —— key 链({@link resolveModelApiKey} / {@link modelKeyPoisonOf} / {@link createKeyResolver})取值前先问它,
+ * boot 焊死模型的两只座(降级壳焊住的目标、记忆整理席解到的条目)冻结的也是它的读数:**焊死的 Model 与它的凭据身份同一代**,
+ * 目录把两者一起换掉之后、重启之前,座仍打焊死的端点、带焊死那一代的身份(值按身份现取:env 引用同名轮换仍热)。身份变了 ⇒ 那只座的重启片签
+ * (指纹读 {@link credentialIdentityFingerprint})。
+ */
+export declare function credentialIdentityOf(tables: ModelKeyTables, modelName: string): CredentialIdentity;
+/**
+ * 凭据身份的**非明文**读数 —— 重启片两侧读数里凭据那一位的唯一铸法(明文是活秘密:只取摘要,绝不进日志 / 序列化面)。
+ * `apiKeyEnv` = 变量名(值热、同名轮换不签);`sealedKey`:缺席 ⇒ `null`;毒丸 ⇒ `{ poisoned, reason }`(不含检测时刻 —— 每次 apply 都会重铸);
+ * 明文 ⇒ `{ digest }`(sha256 前 16 位十六进制;同一明文重封一次 = 同一把 key ⇒ 不签)。
+ */
+export declare function credentialIdentityFingerprint(identity: CredentialIdentity): {
+    readonly apiKeyEnv: string | null;
+    readonly sealedKey: unknown;
+};
 /** 「这只模型声明的钥匙来源今天拿不到」⇒ 那一只毒丸;拿得到 / 没声明 ⇒ `undefined`。能力面的配对标注据它答 `"unknown"`(判别,不是 catch)。 */
 export declare function modelKeyPoisonOf(modelName: string, modelApiKeyEnv: Record<string, string>, env?: NodeJS.ProcessEnv, modelApiKeys?: Record<string, string | SealedCustodyPoison>): ModelKeyPoison | undefined;
 /**

package/dist/key-resolver.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 export function modelKeyPoison(p) {
     const at = new Date().toISOString();
     if (p.source === "sealed")
@@ -50,16 +51,29 @@ export function createKeyResolver(modelApiKeyEnv, env = process.env, modelApiKey
     };
 }
 function chainLookup(modelName, modelApiKeyEnv, env, modelApiKeys) {
-    const sealed = modelApiKeys[modelName];
-    if (isModelKeyPoison(sealed))
-        return { kind: "poison", poison: sealed };
-    if (sealed)
-        return { kind: "key", key: sealed };
-    const envName = modelApiKeyEnv[modelName];
-    if (!envName)
+    const identity = credentialIdentityOf({ modelApiKeyEnv, modelApiKeys }, modelName);
+    if (identity.sealed !== undefined)
+        return isModelKeyPoison(identity.sealed) ? { kind: "poison", poison: identity.sealed } : { kind: "key", key: identity.sealed };
+    if (identity.apiKeyEnv === undefined)
         return { kind: "undeclared" };
-    const value = env[envName];
-    return value ? { kind: "key", key: value } : { kind: "poison", poison: modelKeyPoison({ source: "env", reason: "env_missing", apiKeyEnv: envName }) };
+    const value = env[identity.apiKeyEnv];
+    return value ? { kind: "key", key: value } : { kind: "poison", poison: modelKeyPoison({ source: "env", reason: "env_missing", apiKeyEnv: identity.apiKeyEnv }) };
+}
+export function credentialIdentityOf(tables, modelName) {
+    const sealed = tables.modelApiKeys !== undefined && Object.hasOwn(tables.modelApiKeys, modelName) ? tables.modelApiKeys[modelName] : undefined;
+    if (isModelKeyPoison(sealed) || typeof sealed === "string" && sealed !== "")
+        return { sealed };
+    const apiKeyEnv = tables.modelApiKeyEnv !== undefined && Object.hasOwn(tables.modelApiKeyEnv, modelName) ? tables.modelApiKeyEnv[modelName] : undefined;
+    return typeof apiKeyEnv === "string" && apiKeyEnv !== "" ? { apiKeyEnv } : {};
+}
+export function credentialIdentityFingerprint(identity) {
+    const sealed = identity.sealed;
+    const sealedKey = sealed === undefined
+        ? null
+        : isModelKeyPoison(sealed)
+            ? { poisoned: modelKeyPoisonIdentity(sealed), reason: sealed.reason }
+            : { digest: createHash("sha256").update(sealed, "utf8").digest("hex").slice(0, 16) };
+    return { apiKeyEnv: identity.apiKeyEnv ?? null, sealedKey };
 }
 export function modelKeyPoisonOf(modelName, modelApiKeyEnv, env = process.env, modelApiKeys = {}) {
     const r = chainLookup(modelName, modelApiKeyEnv, env, modelApiKeys);

package/dist/leader/diffup.js

@@ -1,5 +1,6 @@
 import { safeRev, DEFAULT_MAX_DIFF_BYTES } from "./diffout.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "../plugins/blob-backend.js";
+import { createEgressFetch } from "../egress-redirect.js";
 export function buildUploadScript(p) {
     if (!safeRev(p.baseSha))
         throw new Error(`buildUploadScript: unsafe baseSha ${JSON.stringify(p.baseSha)}`);
@@ -114,7 +115,7 @@ export function buildUploadLoopScript(p) {
 }
 export async function fetchUploadedDiff(getUrl, opts = {}) {
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_DIFF_BYTES;
-    const f = opts.fetchImpl ?? fetch;
+    const f = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", opts.fetchImpl);
     let res;
     try {
         res = await f(getUrl, { signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });

package/dist/leader/endpoint.d.ts

@@ -1,6 +1,9 @@
 import type { LeaderResult } from "./leader.js";
 import { type LeaderRunRecord, type LeaderRunStatus, type NewLeaderRun, type LeaderRunTerminal } from "../plugins/leader-run-store-sql.js";
 import { type IdemCaller } from "../http/idempotency.js";
+import type { Subject } from "../owner-brands.js";
+import type { RunIdentity } from "../identity-source.js";
+import type { LeaderParkExpiry } from "./wire.js";
 /**
  * endpoint 消费的 store 面(结构型,不是 nominal union):真实现是 `SqlLeaderRunStore` 的两个方言孪生,
  * 测试用进程内假件。窄到只有 endpoint 真调的三个方法 —— 端点不该看见店的其余口。
@@ -14,6 +17,8 @@ export interface LeaderRunStore {
     /** 按提交幂等键(已 scope 的定宽 hash)读行 —— `GET /v1/leader?idempotencyKey=` 的读口。 */
     getByIdem(idemKey: string): Promise<LeaderRunRecord | undefined>;
     finishRun(id: string, patch: LeaderRunTerminal): Promise<boolean>;
+    /** 翻耐久取消旗(只翻 `running` 行;回执 = 翻没翻)。驱动副本经 `getRun` 读它(一次读拿到状态 + 旗)。 */
+    requestCancel(id: string): Promise<boolean>;
 }
 export interface LeaderRequestBody {
     /** The task to decompose + execute (the Planner turns it into N disjoint sub-tasks). */
@@ -36,6 +41,10 @@ export interface LeaderRun {
     /** BL-4: the principal that submitted this run (null = anonymous/single-tenant). The GET is owner-checked so
      *  an owned run is visible ONLY to its owner (404 to others — no existence oracle), like GET /v1/runs/:id. */
     owner?: string | null;
+    /** 降级臂的取消旗(店在场时以库上的旗为准,本地这一格只服务降级臂的读面)。 */
+    cancelRequested: boolean;
+    /** 取消口停下的终局带 `cancelled`。 */
+    errorCode?: LeaderRunTerminal["errorCode"];
 }
 export interface LeaderEndpoint {
     /** Returns a {status,body} to send, or null if the (method,url) is not a leader route. Kicks the background
@@ -45,7 +54,9 @@ export interface LeaderEndpoint {
      *  header; `GET /v1/leader`: the `idempotencyKey` query — the read port "which leader run did this key create"; scoped by the
      *  caller's identity bit `principal ?? source` before it reaches the store — the one key minter `idemKeyOf(raw, caller, "leader")`).
      *  ASYNC because the durable arm reads/writes SQL. */
-    handle(method: string, url: string, body: unknown, caller?: IdemCaller, idempotencyKey?: string | null): Promise<{
+    handle(method: string, url: string, body: unknown, caller?: IdemCaller, idempotencyKey?: string | null, 
+    /** POST 受理时的身份元组(路由经 `runIdentityOf` 铸;缺席 = `null` = 不合格)。只写进行,不上 wire。 */
+    identity?: RunIdentity | null): Promise<{
         status: number;
         body: object;
     } | null>;
@@ -59,7 +70,9 @@ export interface LeaderEndpoint {
      *  With a store in place this Map holds only the runs THIS replica is driving. Exposed for tests. */
     runs: Map<string, LeaderRun>;
 }
-export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody) => Promise<LeaderResult>, opts: {
+/** 取消终局的 `error` 句(机读位是 `errorCode: "cancelled"`)。 */
+export declare const LEADER_RUN_CANCELLED_ERROR = "leader run cancelled (POST /v1/leader/:id/cancel): it stopped at an abort checkpoint before any push";
+export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody, signal: AbortSignal) => Promise<LeaderResult>, opts: {
     logger?: {
         info?: (m: string, x?: Record<string, unknown>) => void;
         error?: (m: string, x?: Record<string, unknown>) => void;
@@ -73,8 +86,16 @@ export declare function createLeaderEndpoint(runLeader: (body: LeaderRequestBody
     requiredFields?: readonly string[];
     /** [ref] 车4 件1:durable 登记表。缺席 ⇒ 显式的单副本内存降级臂(见文件头注)。 */
     store?: LeaderRunStore;
-    /** [ref] RH-3:「这个调用方读得到这一行 leader run 吗」—— 属主存取器的判官形(`http/owner-access.ts` 的 `createLeaderRunVisibility`,boot 装一次)。
-     *  必填:本模块不自判属主(修前手抄 `owner == null || owner === requester`,缺 [ref] C8 窄互认臂而注称 mirrors runOwnerOk),读面与幂等重放同读它。 */
-    ownerVisible: (principal: string | null | undefined, owner: string | null | undefined) => boolean;
+    /** [ref] RH-3:「这个调用方读得到这一行 leader run 吗」—— 属主存取器的判官形(`http/owner-access.ts` 的 `seesRunAs("run.leader")`,boot 装一次)。
+     *  必填:本模块不自判属主(修前手抄 `owner == null || owner === requester`,缺 [ref] C8 窄互认臂而注称 mirrors admitRunRow),读面与幂等重放同读它。 */
+    ownerVisible: (subject: Subject | null | undefined, owner: string | null | undefined) => boolean;
+    /** 过期一组 worker 会话的待决停驻(`wire.ts` 的 `createLeaderParkExpirer`,boot 在有 checkpoint 店时递)。缺席 = 本部署没有 checkpoint 店 ⇒
+     *  worker 由构造即不可能停驻(durable spec 要那只店),没有可过期的东西。 */
+    expireWorkerParks?: (workers: ReadonlyArray<{
+        readonly workerId: string;
+        readonly sessionId: string;
+    }>) => Promise<LeaderParkExpiry>;
+    /** 旗读拍距(ms)。缺席 = `LIVENESS_HEARTBEAT_MS`(与 run 心跳同一个数);测试注入短拍。 */
+    cancelPollMs?: number;
 }): LeaderEndpoint;
 //# sourceMappingURL=endpoint.d.ts.map

package/dist/leader/endpoint.js

@@ -1,9 +1,11 @@
 import { uuidv7 } from "@sema-agent/core";
 import { redactErrorMessage, redactHead, redactLeaderResult, redactLeaderResultWithFlag } from "../observability/run-terminal.js";
-import { withPrincipal } from "../observability/principal-context.js";
+import { withSubject } from "../observability/principal-context.js";
 import {} from "../plugins/leader-run-store-sql.js";
 import { idemKeyOf } from "../http/idempotency.js";
 import { refusalBody } from "../http/refusal-body.js";
+import { LIVENESS_HEARTBEAT_MS } from "../config-invariants.js";
+import { seatText } from "../trace/exit-seat.js";
 function statusForLeaderResult(result) {
     if (result.conflict)
         return "needs_human";
@@ -20,6 +22,9 @@ function statusForLeaderResult(result) {
     }
 }
 const LEADER_ID_RE = /^\/v1\/leader\/([^/]+)$/;
+const LEADER_CANCEL_RE = /^\/v1\/leader\/([^/]+)\/cancel$/;
+export const LEADER_RUN_CANCELLED_ERROR = "leader run cancelled (POST /v1/leader/:id/cancel): it stopped at an abort checkpoint before any push";
+const LEADER_RUN_ROW_SETTLED_ELSEWHERE = "leader run stopped: its row was settled elsewhere (stale sweep or external delete) — this replica stopped driving it";
 const RUN_RETENTION_MS = 60 * 60_000;
 const TERMINAL_WRITE_ATTEMPTS = 3;
 const TERMINAL_WRITE_RETRY_MS = 200;
@@ -31,6 +36,12 @@ function idemShapeError(raw) {
 }
 export function createLeaderEndpoint(runLeader, opts) {
     const runs = new Map();
+    const controllers = new Map();
+    const abortLocal = (id, cause) => {
+        const ac = controllers.get(id);
+        if (ac && !ac.signal.aborted)
+            ac.abort(cause);
+    };
     const memIdem = new Map();
     function reap() {
         const cutoff = Date.now() - RUN_RETENTION_MS;
@@ -44,24 +55,63 @@ export function createLeaderEndpoint(runLeader, opts) {
         }
     }
     function drive(id, body, owner) {
+        const ac = new AbortController();
+        controllers.set(id, ac);
+        let pollWarned = false;
+        const poll = opts.store
+            ? setInterval(() => {
+                if (ac.signal.aborted)
+                    return;
+                void readRow(id).then((row) => {
+                    if (row === undefined || row.status !== "running")
+                        abortLocal(id, "stall_verdict");
+                    else if (row.cancelRequested)
+                        abortLocal(id, "cancel_verb");
+                }, (e) => {
+                    if (pollWarned)
+                        return;
+                    pollWarned = true;
+                    opts.logger?.error?.("leader_cancel_poll_failed", { id, err: opErr(e), effect: "a cancel landed on another replica is not seen until a later tick reads the row" });
+                });
+            }, opts.cancelPollMs ?? LIVENESS_HEARTBEAT_MS)
+            : undefined;
+        poll?.unref?.();
         void (async () => {
             let terminal;
+            let result;
             try {
-                const result = redactLeaderResult(await withPrincipal(owner ?? undefined, () => runLeader(body)));
-                const status = statusForLeaderResult(result);
-                terminal = { status: status, result };
-                opts.logger?.info?.("leader_run_done", { id, ok: result.ok, status, ...(result.repairTerminal ? { repairTerminal: result.repairTerminal } : {}), merged: result.merge && result.merge.ok ? result.merge.merged : undefined });
+                result = redactLeaderResult(await withSubject(owner ?? undefined, () => runLeader(body, ac.signal)));
+                const cause = ac.signal.aborted ? ac.signal.reason : undefined;
+                if (result.stopped === true && cause === "cancel_verb") {
+                    terminal = { status: "failed", result, error: LEADER_RUN_CANCELLED_ERROR, errorCode: "cancelled" };
+                }
+                else if (result.stopped === true && cause === "stall_verdict") {
+                    terminal = { status: "failed", result, error: LEADER_RUN_ROW_SETTLED_ELSEWHERE };
+                }
+                else {
+                    const status = statusForLeaderResult(result);
+                    terminal = { status: status, result };
+                }
+                opts.logger?.info?.("leader_run_done", { id, ok: result.ok, status: terminal.status, ...(terminal.errorCode ? { errorCode: terminal.errorCode } : {}), ...(cause ? { stopCause: cause } : {}), ...(result.repairTerminal ? { repairTerminal: result.repairTerminal } : {}), merged: result.merge && result.merge.ok ? result.merge.merged : undefined });
             }
             catch (e) {
                 terminal = { status: "failed", error: redactErrorMessage(e instanceof Error ? e.message : String(e)) ?? "" };
                 opts.logger?.error?.("leader_run_error", { id, err: terminal.error });
             }
+            finally {
+                if (poll)
+                    clearInterval(poll);
+                controllers.delete(id);
+            }
+            let settledElsewhere = ac.signal.reason === "stall_verdict";
             if (opts.store) {
                 for (let attempt = 1;; attempt += 1) {
                     try {
                         const moved = await opts.store.finishRun(id, terminal);
-                        if (!moved)
+                        if (!moved) {
+                            settledElsewhere = true;
                             opts.logger?.error?.("leader_run_terminal_not_applied", { id, status: terminal.status, why: "row missing or already terminal — another writer settled it (e.g. the stale-running sweep), or the row was deleted" });
+                        }
                         break;
                     }
                     catch (e) {
@@ -74,16 +124,68 @@ export function createLeaderEndpoint(runLeader, opts) {
                 }
             }
             const local = runs.get(id);
+            const residueEnds = settledElsewhere || ac.signal.reason === "cancel_verb" || (opts.store ? await cancelFlagAfterSettle(id) : local?.cancelRequested === true);
+            if (residueEnds && result)
+                await expireResidue(id, result, "drive");
             if (local) {
                 local.status = terminal.status;
                 if (terminal.result !== undefined)
                     local.result = terminal.result;
                 if (terminal.error !== undefined)
                     local.error = terminal.error;
+                if (terminal.errorCode !== undefined)
+                    local.errorCode = terminal.errorCode;
                 local.finishedAt = Date.now();
             }
         })();
     }
+    function readRow(id) {
+        return opts.store.getRun(id);
+    }
+    const opErr = (e) => seatText("operator-log-error", e instanceof Error ? e.message : String(e));
+    async function cancelFlagAfterSettle(id) {
+        try {
+            return (await readRow(id))?.cancelRequested === true;
+        }
+        catch (e) {
+            opts.logger?.error?.("leader_cancel_flag_reread_failed", { id, err: opErr(e), effect: "if a cancel landed on this run just before its terminal write, its worker parks are expired only when the cancel is re-sent" });
+            return false;
+        }
+    }
+    function workerSessionsOf(result) {
+        const out = new Map();
+        const r = result && typeof result === "object" ? result : {};
+        for (const list of [r.reports, r.suspended]) {
+            if (!Array.isArray(list))
+                continue;
+            for (const x of list) {
+                const w = x;
+                if (w && typeof w.workerId === "string" && typeof w.sessionId === "string")
+                    out.set(`${w.workerId}\u0000${w.sessionId}`, { workerId: w.workerId, sessionId: w.sessionId });
+            }
+        }
+        return [...out.values()];
+    }
+    async function expireResidue(id, result, site) {
+        const none = { expired: 0, lost: 0 };
+        if (!opts.expireWorkerParks)
+            return none;
+        const sessions = workerSessionsOf(result);
+        if (sessions.length === 0)
+            return none;
+        try {
+            const r = await opts.expireWorkerParks(sessions);
+            if (r.expired > 0 || r.lost > 0)
+                opts.logger?.info?.("leader_cancel_parks_expired", { id, site, expired: r.expired, lost: r.lost });
+            return r;
+        }
+        catch (e) {
+            if (site === "cancel")
+                throw e;
+            opts.logger?.error?.("leader_cancel_parks_expire_failed", { id, err: opErr(e), effect: "the worker parks of this cancelled run stay pending until their own deadline or until the cancel is re-sent" });
+            return none;
+        }
+    }
     const CLEAN_MEMO_CAP = 4096;
     const cleanIds = new Set();
     const DIRTY_MEMO_CAP = 256;
@@ -125,12 +227,12 @@ export function createLeaderEndpoint(runLeader, opts) {
         return view;
     }
     function getBody(run) {
-        return { status: 200, body: { id: run.id, status: run.status, ...redactedView(run) } };
+        return { status: 200, body: { id: run.id, status: run.status, cancelRequested: run.cancelRequested, ...(run.errorCode ? { errorCode: run.errorCode } : {}), ...redactedView(run) } };
     }
     const NOT_FOUND = { status: 404, body: refusalBody({ errorCode: "not_found.leader_run", message: "leader run not found" }) };
-    async function handle(method, url, body, caller, idempotencyKey) {
-        const requester = caller?.principal ?? null;
-        const idemCaller = caller ?? { principal: null, source: null };
+    async function handle(method, url, body, caller, idempotencyKey, identity) {
+        const requester = caller?.subject ?? null;
+        const idemCaller = caller ?? { subject: null, source: null };
         if (method === "POST" && url === "/v1/leader") {
             const b = body;
             if (!b || typeof b.objective !== "string" || b.objective.trim() === "") {
@@ -152,14 +254,14 @@ export function createLeaderEndpoint(runLeader, opts) {
             }
             reap();
             if (opts.store) {
-                const { created, run } = await opts.store.createRun({ objective: b.objective, owner, idemKey: scopedIdem });
+                const { created, run } = await opts.store.createRun({ objective: b.objective, owner, idemKey: scopedIdem, identity: identity ?? null });
                 if (!created) {
                     if (!opts.ownerVisible(requester, run.owner)) {
                         return { status: 409, body: refusalBody({ errorCode: "conflict.leader_run_exists", message: "idempotency key already used by another principal" }) };
                     }
                     return { status: 202, body: { leaderRunId: run.id, status: run.status } };
                 }
-                runs.set(run.id, { id: run.id, status: "running", startedAt: run.startedAtMs, owner });
+                runs.set(run.id, { id: run.id, status: "running", startedAt: run.startedAtMs, owner, cancelRequested: false });
                 drive(run.id, b, owner);
                 return { status: 202, body: { leaderRunId: run.id, status: "running" } };
             }
@@ -170,7 +272,7 @@ export function createLeaderEndpoint(runLeader, opts) {
                     return { status: 202, body: { leaderRunId: priorRun.id, status: priorRun.status } };
             }
             const id = uuidv7();
-            runs.set(id, { id, status: "running", startedAt: Date.now(), owner });
+            runs.set(id, { id, status: "running", startedAt: Date.now(), owner, cancelRequested: false });
             if (scopedIdem)
                 memIdem.set(scopedIdem, id);
             drive(id, b, owner);
@@ -196,11 +298,14 @@ export function createLeaderEndpoint(runLeader, opts) {
                 return NOT_FOUND;
             return getBody(run);
         }
+        const c = method === "POST" ? LEADER_CANCEL_RE.exec(url) : null;
+        if (c)
+            return cancel(c[1], ownerOk);
         const m = method === "GET" ? LEADER_ID_RE.exec(url) : null;
         if (m) {
             const id = m[1];
             if (opts.store) {
-                const run = await opts.store.getRun(id);
+                const run = await readRow(id);
                 if (!run || !ownerOk(run.owner))
                     return NOT_FOUND;
                 return getBody(run);
@@ -212,6 +317,41 @@ export function createLeaderEndpoint(runLeader, opts) {
         }
         return null;
     }
+    async function answerTerminal(id, row) {
+        abortLocal(id, "cancel_verb");
+        const r = await expireResidue(id, row.result, "cancel");
+        if (r.lost > 0) {
+            return { status: 409, body: refusalBody({ errorCode: "conflict.approval_settled", message: `this run is already ${row.status}; ${r.lost} of its worker approvals were settled concurrently (decided or expired) while this cancel tried to expire them — a decided approval continues as its own run (stop it with POST /v1/runs/:id/cancel); retry cancel to expire what is still pending` }) };
+        }
+        return { status: 202, body: { leaderRunId: id, status: row.status, cancelRequested: row.cancelRequested, note: r.expired > 0 ? `already ${row.status} — ${r.expired} pending worker approval(s) it left behind were expired` : `already ${row.status} — nothing left to stop` } };
+    }
+    async function cancel(id, ownerOk) {
+        if (opts.store) {
+            const row = await readRow(id);
+            if (!row || !ownerOk(row.owner))
+                return NOT_FOUND;
+            if (row.status === "running") {
+                if (await opts.store.requestCancel(id)) {
+                    abortLocal(id, "cancel_verb");
+                    return { status: 202, body: { leaderRunId: id, status: "cancelling", cancelRequested: true } };
+                }
+                const now = await readRow(id);
+                if (!now)
+                    return NOT_FOUND;
+                return answerTerminal(id, now);
+            }
+            return answerTerminal(id, row);
+        }
+        const run = runs.get(id);
+        if (!run || !ownerOk(run.owner))
+            return NOT_FOUND;
+        if (run.status === "running") {
+            run.cancelRequested = true;
+            abortLocal(id, "cancel_verb");
+            return { status: 202, body: { leaderRunId: id, status: "cancelling", cancelRequested: true } };
+        }
+        return answerTerminal(id, run);
+    }
     return { handle, inflight: () => [...runs.values()].filter((r) => r.status === "running").length, runs };
 }
 //# sourceMappingURL=endpoint.js.map

package/dist/leader/fanout.d.ts

@@ -100,6 +100,9 @@ export interface FanOutOptions {
      *  suspended worker itself has already settled (its stream is deregistered), so the cancel sweep cannot
      *  touch its checkpoint/paused env (the destroy-exemption falls out of the registration lifecycle). */
     cancelOnSuspend?: boolean;
+    /** 这条 leader run 的中止信号(取消口 / 陈旧裁决;与 core `TaskSpec.signal` 同一约定:缺席 = 不可外部取消)。abort ⇒ 走同一只
+     *  {@link fanOut} 内的 `cancelAll`(先 abort 共享信号、再 destroy 已登记的流)—— 父中止与总超时是同一个动作的两个触发,不是两套收法。 */
+    signal?: AbortSignal;
 }
 export interface FanOutResult {
     reports: WorkerReport[];