@sema-agent/server 7.147.0 → 7.148.0

package/dist/runs.js

@@ -1,5 +1,5 @@
 import { runWithVerification, runCascade, defaultTaskRegistry, taskNotificationDedupKey, DURABLE_AGENT_HANDLE_RE } from "@sema-agent/core";
-import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane } from "./terminal.js";
+import { atHostBoundary, failureCodeOf, sealResultForExit, outwardPlane, outwardThrownMessage } from "./terminal.js";
 import { voidVerifierPauseCard } from "./verifier-pause-card.js";
 import { voidPendingCard } from "./card-void.js";
 import { NOT_IN_ROSTER, entryProblemsFacts } from "./entry-problems.js";
@@ -7,7 +7,10 @@ import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { TOOL_DECLARATION_HTTP_STATUS } from "./tool-declaration-http-status.js";
 import { isSessionErrorCode, sessionErrorHttp } from "./session-error-wire.js";
 import { redactErrorMessage } from "./observability/run-terminal.js";
-import { withPrincipal } from "./observability/principal-context.js";
+import { withSubject } from "./observability/principal-context.js";
+import { partsOf } from "./owner-brands.js";
+import { recoveredSubject } from "./owner-faces.js";
+import { taskSpecIdentityOf } from "./engine-identity.js";
 import { withModelReachScope } from "./model-reach-scope.js";
 import { createInstructionSelectionLeg } from "./instruction-selection.js";
 import { redactSecrets } from "./trace/redact.js";
@@ -16,7 +19,8 @@ import { createLedgerSink } from "./trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "./trace/engine-notice-wire.js";
 import { recordTurnActivity } from "./turn-activity.js";
 import { buildCancelledLedgerRow, CANCELLED_CODE, createRunAbort, mintCancelledResult } from "./run-cancel-context.js";
-import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.js";
+import { resolveApprovalLeg } from "./tool-approval.js";
+import { createHitlTransport } from "./hitl-delivery.js";
 import { fleetRunResiduals } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
@@ -55,7 +59,9 @@ export async function taskHandleStop(registry, handle, access, agentStore) {
     registry.markStopSource(handle, "user");
     return registry.stopTask(handle, access);
 }
-export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
+export function markChildrenStoppedByUserOnAbort(signal, taskId, subject) {
+    const recovered = recoveredSubject(subject);
+    const principal = taskSpecIdentityOf(recovered === undefined ? undefined : partsOf(recovered)).principal;
     const mark = () => {
         try {
             defaultTaskRegistry.markStopSourceForOwner({ owner: taskId, scope: principal ?? "default" }, "user", { skipSessionScoped: true });
@@ -85,6 +91,7 @@ const PREPARE_REFUSAL_HTTP_STATUS = {
     "config.invalid_checkpoint_store": 400,
     "config.skill_listing_budget_invalid": 400,
     "config.user_invoked_skill_unknown": 400,
+    "config.skill_deny_unreadable": 409,
     "config.image_invalid": 400,
     "config.user_attachment_invalid": 400,
     "config.tool_face_control": 400,
@@ -127,6 +134,15 @@ export function syncRefusalHttpStatus(result) {
     return resumeAtHttpStatus(result);
 }
 const ZERO_WORK_REFUSAL_DETAIL_CODES = new Set(["config.user_attachment_invalid"]);
+function attachmentCauseFacts(cause) {
+    if (cause === null || typeof cause !== "object")
+        return {};
+    const c = cause;
+    return {
+        ...(typeof c.path === "string" && c.path !== "" ? { field: c.path } : {}),
+        ...(typeof c.index === "number" && Number.isInteger(c.index) && c.index >= 0 ? { index: c.index } : {}),
+    };
+}
 const ENGINE_ENTRY_SPELLING_REASONS = new Set(["near_miss", "unknown_name"]);
 function engineReasonOf(detail) {
     if (detail === null || typeof detail !== "object")
@@ -155,7 +171,7 @@ export function zeroWorkRefusalFacts(terminal, admissionReadings = []) {
     if (cause === null || typeof cause !== "object")
         return {};
     const c = cause;
-    return c.kind === "coded" && c.detail !== undefined ? { detail: c.detail } : {};
+    return c.kind === "coded" ? attachmentCauseFacts(c.detail) : {};
 }
 const RETRY_CLASS_WORDS = { transient: true, terminal: true };
 function engineRetryClassOf(terminal) {
@@ -339,7 +355,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             });
     }
     const heartbeat = setInterval(() => {
-        void runStore.heartbeat(taskId, owner).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
+        beatRunHeartbeat(runStore, taskId, owner, () => cancelCtrl.abort("stall_verdict"), () => { metrics?.inc("run_signal_poll_errors_total", { kind: "heartbeat" }); });
         if (!cancelCtrl.signal.aborted) {
             void runStore.isCancelRequested(taskId, owner).then((c) => { if (c)
                 cancelCtrl.abort("cancel_verb"); }).catch(() => { metrics?.inc("run_signal_poll_errors_total", { kind: "cancel" }); });
@@ -372,7 +388,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         acceptance?.settle(sealed);
     };
     const settleLegResult = async (engineResult) => {
-        const result = atHostBoundary(engineResult, spec.sessionId);
+        const result = atHostBoundary(engineResult);
         const parkWord = result.terminal.kind === "paused" ? outwardPlane(result.terminal).status : undefined;
         if (parkWord !== undefined && isParkLedgerEventType(parkWord)) {
             await parkLeg(parkWord, result);
@@ -397,18 +413,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
     modelUsage?.register(taskId);
     const manifestSeat = createPromptManifestSeat(promptManifests, taskId);
     const flushPromptManifest = () => manifestSeat.drain(append);
-    const elicitEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
-    const questionEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
-    const approvalEmit = (frame) => {
-        const { type, ...rest } = frame;
-        return append(type, rest);
-    };
+    const hitlTransport = createHitlTransport({ ledger: append });
     const unregisterEngineNotice = registerEngineNoticeLeg({
         sessionId: spec.sessionId,
         ...(pendingEngineNotices !== undefined ? { pending: pendingEngineNotices } : {}),
@@ -532,12 +537,12 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
             }
         };
-        await instructionLeg.run(spec.sessionId, () => withModelReachScope({ sessionId: spec.sessionId, taskId }, () => withPrincipal(principal, () => {
+        await instructionLeg.run(spec.sessionId, () => withModelReachScope({ sessionId: spec.sessionId, taskId }, () => withSubject(recoveredSubject(principal), () => {
             const withElicit = elicitation
-                ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: elicitEmit, abortSignal: cancelCtrl.signal }, runBody)
+                ? () => elicitation.runWithContext({ taskId, owner: elicitOwner ?? owner, transport: hitlTransport, abortSignal: cancelCtrl.signal }, runBody)
                 : runBody;
             const withQuestion = () => question
-                ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
+                ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, transport: hitlTransport, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
             const withApproval = () => approval && approvalLeg.active && approvalLeg.unattended === undefined
                 ? approval.coordinator.runWithContext({
@@ -546,8 +551,8 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     abortSignal: cancelCtrl.signal,
                     ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
                     executionLane: approval.executionLane,
-                    emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
-                    emitRevoke: (f) => approvalEmit(f),
+                    family: "approval_request",
+                    transport: hitlTransport,
                     legKey: "",
                     ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
                 }, withQuestion)
@@ -610,8 +615,9 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             }
             else {
                 settledAsCancel = false;
-                const safeMsg = redactErrorMessage(message) ?? message;
-                await voidHeldParkCard(observedDone === undefined ? undefined : atHostBoundary(observedDone, spec.sessionId), spec.sessionId, checkpointCards, "bg");
+                const outwardMsg = outwardThrownMessage(err, message);
+                const safeMsg = redactErrorMessage(outwardMsg) ?? outwardMsg;
+                await voidHeldParkCard(observedDone === undefined ? undefined : atHostBoundary(observedDone), spec.sessionId, checkpointCards, "bg");
                 try {
                     await append("failed", { errorMessage: safeMsg });
                 }
@@ -644,7 +650,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 if (verdict.kind === "park")
                     fleetPublisher.onTerminal(verdict.word);
                 else if (verdict.result !== null)
-                    fleetPublisher.onTerminal(verdict.label, fleetRunResiduals(verdict.result));
+                    fleetPublisher.onTerminal(verdict.label, fleetRunResiduals(verdict.result, failureCodeOf(verdict.result.terminal)));
                 else
                     fleetPublisher.onTerminal(verdict.label, {
                         ...(verdict.label === CANCELLED_CODE ? { stoppedBy: "user" } : {}),
@@ -667,5 +673,11 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         }
     }
 }
+export function beatRunHeartbeat(runStore, taskId, owner, onLost, onError) {
+    void runStore.heartbeat(taskId, owner).then((running) => {
+        if (!running)
+            onLost();
+    }, onError);
+}
 export const HEARTBEAT_MS = LIVENESS_HEARTBEAT_MS;
 //# sourceMappingURL=runs.js.map

package/dist/runtime-caps-resolver.d.ts

@@ -23,8 +23,8 @@
  *  · `forceDurableGate`— prepare-task.js 的 durable/content mandate、活 content-ask 抑制、
  *                        durable question face（该处合取 `resolveCheckpointStore(spec, deps) !== undefined`
  *                        ⇒ **无 checkpoint 店的部署上这一面本就不成立**，该键在那里 inert）
- *  · `autoMode`        — prepare-task.js `=== true` **∧** `deps.autoMode !== undefined`（部署需先具备分类器；
- *                        显式 opt-in 极性，且 [ref] 起本侧传的是三态 org deny 位，见 toCoreRuntimeCaps 头注）
+ *  · `autoMode`        — 武装式 `spec.permissionMode === "auto"` **∧** `deps.autoMode !== undefined` **∧** `runtimeCaps?.autoMode !== false`
+ *                        （部署需先具备分类器；三态 org deny 位：`true` 与缺席同义、只有 `false` 是拒，见 toCoreRuntimeCaps 头注）
  *  · `bypassPermissions` — `dist/core/mode-policy.js` 的模式折叠（请求 `bypassPermissions` ∧ 本位 `=== false` ⇒ 这条腿跑在
  *                        `default`、发 `config.permission_mode_unavailable{by:"operator_deny"}`、回执 `foldedBy:"operator_deny"`）；
  *                        deny 形，缺席 = 不阻。[ref] D2 起由 center 的 `allowBypassPermissions` 写（此前本仓零写点）
@@ -107,6 +107,15 @@ export interface EntitlementsResolverOpts {
     /** Observability hook for a resolve failure (defaults to a `runtime_caps_resolve_failed` warn). */
     onError?: (err: Error, principal: string) => void;
 }
+/**
+ * 中心拒了 auto 时**是哪一键拒的**(闭集)。中心的 entitlement 里 auto 的拒位今天有两个键(`autoMode` 与 `allowAutoMode`,settings-schema 里一个事实两个源 ——
+ * 折成一键归那个仓),引擎只有一只拒位;读者(`GET /v1/capabilities` 的 `permissionModeAuto.refusedBy`)靠这一词分清该去改中心的哪一键。
+ * 中心折成一键之后两词退役、本词集随之删(零别名)。
+ */
+export declare const AUTO_MODE_REFUSED_BY: readonly ["center.autoMode", "center.allowAutoMode", "both"];
+export type AutoModeRefusedBy = (typeof AUTO_MODE_REFUSED_BY)[number];
+/** 中心这一答拒没拒 auto、哪一键拒的 —— 拒位与来源词的**同一只判**({@link toCoreRuntimeCaps} 的拒位读它)。缺席 = 中心没拒(任一键的 `true` 都不是授予,不覆盖另一键的 `false`)。 */
+export declare function autoModeRefusedByOf(ent: Pick<EntitlementRuntimeCaps, "autoMode" | "allowAutoMode">): AutoModeRefusedBy | undefined;
 /** Map center's `EntitlementRuntimeCaps` → the subset core's engine enforces. `allowUltracode` (shell/UX) is
  *  dropped on purpose (not a core primitive); `allowWorkflows` / `forceDurableGate` / `allowFork` are **three of the
  *  six** the engine reads — the other three (`allowObservers` / `autoMode` / `allowMemoryOptOut`) are documented
@@ -151,6 +160,12 @@ export declare function toCoreRuntimeCaps(ent: EntitlementRuntimeCaps | null | u
  * 所以本谓词为 false **不再**意味着 auto 不武装;「会不会武装」由 `auto-mode-face.ts` 的三项合取答。
  */
 export declare function centerEntitlementSourceWired(config: Pick<ServiceConfig, "webAdmin">): boolean;
+/** 只读腿的一次读数:拒位(caps)与中心拒 auto 的来源词出自**同一个**缓存项。 */
+export interface RuntimeCapsReading {
+    readonly caps: RuntimeCaps | undefined;
+    /** 只在中心亲口拒了 auto 时在场({@link AutoModeRefusedBy})。 */
+    readonly autoModeRefusedBy?: AutoModeRefusedBy;
+}
 /** The two per-principal faces served off ONE caps fetch + cache. */
 export interface PrincipalEntitlementsClient {
     /** core's `RunnerDeps.runtimeCapsResolver` seam — FAIL-CLOSED on error (deny workflows/fork/autoMode/bypassPermissions;
@@ -171,7 +186,7 @@ export interface PrincipalEntitlementsClient {
      *
      * 🔴 **界画在「这句话是谁说的」**(codex r2 [high] 逐条核后的定界,不是「读面完全不碰缓存」):
      *  · **成功项 = center 亲口答的那份** —— 与提交腿自己抓到的**逐字同一份**、同一条 `ttlMs`、同一个**已验证**
-     *    身份(读面的 principal 走 `gatedPrincipal` → `verifiedPrincipal`,与提交腿同源,读不到别人的格)。读面
+     *    身份(读面的 principal 走 `gatedSubject` → `verifiedPrincipal`,与提交腿同源,读不到别人的格)。读面
      *    只是把这个 principal 自己那一格**预热**了一下;org 撤销后的陈旧窗由部署级 `ttlMs` 定义,与哪一腿预热
      *    的无关(提交腿自己预热同样如此),本批**零改动**。
      *  · **降级项 = server 自铸的判决** —— center 从没说过这句 deny,是本层在故障时替它说的。让一次**读**铸的
@@ -185,17 +200,17 @@ export interface PrincipalEntitlementsClient {
      * 而它硬失败 ⇒ 该降级项当场升格为执法项(codex r1 [medium]:否则一条总抢在提交前面的轮询会让每次提交
      * 都重抓,denyTtl 的界对提交腿失效)。让它升格的是一次真提交自己吃到的硬失败,不是那次读。
      */
-    peekRuntimeCaps: (principal: string | undefined) => Promise<RuntimeCaps | undefined>;
+    peekRuntimeCapsReading: (principal: string | undefined) => Promise<RuntimeCapsReading>;
     /** The resolved per-principal scenario ruling for resolveSpec's gateScenarioRequest — a three-state read
      *  ({@link ScenarioRulingRead}): the ruling; `undefined` = absent (no principal ⇒ no center call; older center without
      *  the scenario keys) = no governance; `"unavailable"` = the center could not answer (hard fetch failure — same error entry
      *  as the caps face's fail-closed deny — or malformed ruling keys) ⇒ the gate refuses the run. */
     scenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /**
-     * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCaps} 的界):同一只缓存 / 同一条抓取 /
+     * {@link PrincipalEntitlementsClient.scenarioRuling} 的**只读**孪生(同 {@link PrincipalEntitlementsClient.peekRuntimeCapsReading} 的界):同一只缓存 / 同一条抓取 /
      * 同一份三态读数(故障 ⇒ `"unavailable"`,读面与提交腿同拒),唯一的差别是 center 硬失败时本腿铸的降级项**只对读面自己算数**,提交腿不认、照常重抓。
      * 读面(`GET /v1/capabilities/mcp?scenario=` 的场景门)问中心裁定时必须走这一只 —— 经 `scenarioRuling` 问,center 抖动的那一拍会替这个主体的**真提交**
-     * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCaps` 的病灶同一类)。
+     * 留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面成了别人被拒的原因,与 `peekRuntimeCapsReading` 的病灶同一类)。
      */
     peekScenarioRuling: (principal: string | undefined) => Promise<ScenarioRulingRead>;
     /** (stage7 P5) The resolved per-principal execution-lane ruling for resolveSpec's

package/dist/runtime-caps-resolver.js

@@ -37,6 +37,12 @@ const CENTER_ENGINE_CAP_KEYS = [
     "allowBypassPermissions",
     "allowMemoryOptOut",
 ];
+export const AUTO_MODE_REFUSED_BY = ["center.autoMode", "center.allowAutoMode", "both"];
+export function autoModeRefusedByOf(ent) {
+    const byAutoMode = ent.autoMode === false;
+    const byAllowAutoMode = ent.allowAutoMode === false;
+    return byAutoMode && byAllowAutoMode ? "both" : byAutoMode ? "center.autoMode" : byAllowAutoMode ? "center.allowAutoMode" : undefined;
+}
 export function toCoreRuntimeCaps(ent) {
     if (!ent)
         return undefined;
@@ -53,7 +59,7 @@ export function toCoreRuntimeCaps(ent) {
         caps.allowFork = ent.allowFork;
     if (typeof ent.allowObservers === "boolean")
         caps.allowObservers = ent.allowObservers;
-    if (ent.autoMode === false || ent.allowAutoMode === false)
+    if (autoModeRefusedByOf(ent) !== undefined)
         caps.autoMode = false;
     else if (ent.autoMode === true)
         caps.autoMode = true;
@@ -87,7 +93,6 @@ export function gateExecutionLane(ruling, ownLane, logger = defaultLogger) {
 export function createPrincipalEntitlementsClient(opts) {
     const ttlMs = opts.ttlMs ?? 60_000;
     const denyTtlMs = opts.denyTtlMs ?? Math.min(ttlMs, 10_000);
-    const fetchImpl = opts.fetchImpl ?? fetch;
     const fetchCaps = opts.fetchCaps ?? fetchPrincipalCaps;
     const now = opts.now ?? (() => Date.now());
     const onError = opts.onError ?? ((err, principal) => defaultLogger.warn("runtime_caps_resolve_failed", { principal, err: String(err) }));
@@ -130,12 +135,13 @@ export function createPrincipalEntitlementsClient(opts) {
             return dup;
         const p = (async () => {
             try {
-                const r = await fetchCaps(bin.center, principal, cached?.etag, fetchImpl, opts.worker);
+                const r = await fetchCaps(bin.center, principal, cached?.etag, opts.fetchImpl, opts.worker);
                 if (r === null) {
                     const entry = {
                         caps: cached?.caps,
                         ...(cached?.scenario ? { scenario: cached.scenario } : {}),
                         ...(cached?.execution ? { execution: cached.execution } : {}),
+                        ...(cached?.autoModeRefusedBy ? { autoModeRefusedBy: cached.autoModeRefusedBy } : {}),
                         ...(cached?.etag ? { etag: cached.etag } : {}),
                         expiresAt: now() + ttlMs,
                     };
@@ -148,8 +154,10 @@ export function createPrincipalEntitlementsClient(opts) {
                 if (r.scenarioDrift) {
                     audit(new Error(`scenario ruling wire drift: ${r.scenarioDrift}`), principal);
                 }
+                const refusedBy = r.runtimeCaps ? autoModeRefusedByOf(r.runtimeCaps) : undefined;
                 const entry = {
                     caps: toCoreRuntimeCaps(r.runtimeCaps),
+                    ...(refusedBy !== undefined ? { autoModeRefusedBy: refusedBy } : {}),
                     ...(r.scenarioDrift ? { scenario: "unavailable" } : r.scenario ? { scenario: r.scenario } : {}),
                     ...(r.execution ? { execution: r.execution } : {}),
                     ...(r.etag ? { etag: r.etag } : {}),
@@ -182,7 +190,12 @@ export function createPrincipalEntitlementsClient(opts) {
     }
     return {
         resolveRuntimeCaps: async (principal) => (principal ? (await load(principal)).caps : undefined),
-        peekRuntimeCaps: async (principal) => (principal ? (await load(principal, false)).caps : undefined),
+        peekRuntimeCapsReading: async (principal) => {
+            if (!principal)
+                return { caps: undefined };
+            const entry = await load(principal, false);
+            return { caps: entry.caps, ...(entry.autoModeRefusedBy !== undefined ? { autoModeRefusedBy: entry.autoModeRefusedBy } : {}) };
+        },
         scenarioRuling: async (principal) => (principal ? (await load(principal)).scenario : undefined),
         peekScenarioRuling: async (principal) => (principal ? (await load(principal, false)).scenario : undefined),
         executionRuling: async (principal) => (principal ? (await load(principal)).execution : undefined),

package/dist/runtime-governance.d.ts

@@ -24,7 +24,7 @@
  * name). Real isolation is the `executionEnv` sandbox. Same caveat core documents on `createCoarseCommandNamePolicy`.
  */
 import { type PermissionMode, type ShellGateDoctrine, type TaskSpec, type ToolPolicy } from "@sema-agent/core";
-import { AUTONOMY_MODES, type GovernanceConfig } from "@sema-agent/settings-schema";
+import { AUTONOMY_MODES, GovernanceConfig } from "@sema-agent/settings-schema";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
 import { type GovernanceOverrides } from "./governance-overrides.js";
 /** 运维 autonomy 四档的**闭集**(契约成员表本尊,照旧从本模块转出)。`config.ts` 的 `parseAutonomy` 也从这里读 —— 四档词表全仓一份。 */
@@ -38,7 +38,7 @@ export type Autonomy = NonNullable<GovernanceConfig["autonomy"]>;
 /** 导出给 `test/coarse-shell-tools-mirror.test.ts` 的同源钉用(见那里的顶注)。 */
 export declare const COARSE_SHELL_TOOLS_MIRROR: readonly string[];
 /** Validate `commandPolicy` rules — the shape (array of {command, decision}), the `command` (a bare argv[0] name,
- *  see {@link VALID_COMMAND_NAME}), AND the `decision` enum. Returns the list of human-readable errors (empty =
+ *  judged by the contract's own cell, see {@link commandNameRefused}), AND the `decision` enum. Returns the list of human-readable errors (empty =
  *  OK). Called at config-apply (web-admin-client/facade.ts `applyRuntimeHot`) so a malformed rule that BYPASSED the
  *  registry schema (a hand-edited config.d / a non-conformant publish) is rejected LOUDLY rather than
  *  silently mis-compiling — review MEDIUM: an out-of-enum `decision` (e.g. "DENY") would otherwise fall through

package/dist/runtime-governance.js

@@ -1,5 +1,5 @@
 import { clampPermissionMode, combinePolicies, COARSE_SHELL_TOOLS as CORE_COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, modePolicyOf, parseLeadingCommandName, wrapToolPolicy, } from "@sema-agent/core";
-import { AUTONOMY_MODES, COMMAND_DECISIONS } from "@sema-agent/settings-schema";
+import { AUTONOMY_MODES, COMMAND_DECISIONS, GovernanceConfig } from "@sema-agent/settings-schema";
 import { currentGovernanceAskMarks } from "./governance-ask-marks.js";
 import { tightenGoverned } from "./governance-overrides.js";
 import { createDeploymentAuthoredPolicy, operatorAsk } from "./operator-ask.js";
@@ -25,7 +25,9 @@ function createCommandAskListPolicy(askCommands, tools = COARSE_SHELL_TOOLS) {
         },
     };
 }
-const VALID_COMMAND_NAME = /^[A-Za-z0-9._+-]+$/;
+function commandNameRefused(command) {
+    return GovernanceConfig.safeParse({ commandPolicy: [{ command, decision: COMMAND_DECISIONS[0] }] }).error?.issues.some((issue) => issue.path[2] === "command") ?? false;
+}
 function isCommandDecision(raw) {
     return typeof raw === "string" && COMMAND_DECISIONS.includes(raw);
 }
@@ -39,7 +41,7 @@ export function validateCommandRules(rules) {
             continue;
         }
         const { command, decision } = r;
-        if (typeof command !== "string" || !VALID_COMMAND_NAME.test(command)) {
+        if (commandNameRefused(command)) {
             errors.push(`commandPolicy command "${String(command)}" is not a bare argv[0] name — core matches the EXACT command name (no glob/path/operators). ` +
                 `Use e.g. "git" not "git*"; to gate sub-commands or pipes, deny the interpreter ("sh"/"bash") + rely on the sandbox.`);
         }

package/dist/sealed-key-layout.d.ts

@@ -1,10 +1,11 @@
 /**
- * 钥匙保管目录的布局常量 —— 引擎建目录、建停驻行封签子目录时用的**唯一**值(`src/sealed-key.ts` 读它们)。
- * 钥匙文件的权限位不在这里:它就是本服务文件的那一个值 `plugins/owner-only-file-mode.ts` 的 `OWNER_ONLY_FILE_MODE`(部署事实同读它)。
- *
- * 单独成一只零依赖的叶子模块:随包部署事实 `deploy/facts/sealed-key.json`(`src/deploy-facts.ts` 投影、`scripts/gen-deploy-lanes.ts` 生成)
- * 读的是同一份值,生成器不必为了三个常量把整只保管模块(libsodium / 中心上报)装载进来。
+ * 保管目录的**唯一解析**:`SEALED_KEY_DIR`(配置席 `sealedKeyDir`,唯一 env 读点在 `config.ts`)或缺省 `<数据根>/sealed-key`。
+ * 两个读者同读这一只:起服第 2 段建保管店(`boot/web-admin.ts`),与店的持久性判者取证(`store-posture.ts` 的三根之一,`boot/store-evidence.ts` 递路径)。
  */
+export declare function sealedKeyDirOf(config: {
+    readonly sealedKeyDir?: string;
+    readonly localDataRoot?: string;
+}, localRoot: string): string;
 /** 保管目录的权限位:每次建店都 `mkdir` + `chmod` 成它(目录预先存在时 `mkdir` 的 mode 不生效,所以另 `chmod` 一次)。 */
 export declare const SEALED_KEY_DIR_MODE = 448;
 /**
@@ -13,4 +14,10 @@ export declare const SEALED_KEY_DIR_MODE = 448;
  * 放在模型钥匙目录之下是为了「多副本共享 / 跨重启持久」只有一个目录要管(整个保管目录);模型钥匙店只读这一层的 `*.json`,子目录不进它的视野。
  */
 export declare const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+/**
+ * 首把钥匙的**创建口**的互斥文件名(在保管目录里,`<保管目录>/.keygen.lock`):目录里一把可装载的钥匙都没有时,谁以 `wx`(`O_CREAT | O_EXCL`)独占建成它,谁生成并发布那一把;
+ * 发布之后(或失败退出时)删除。不以 `.json` 结尾 ⇒ 装载不会把它当钥匙文件,目录里恒不留它(崩溃在生成中途的极窄窗口除外 —— 那时拒句点名这个文件的路径)。
+ * 模型钥匙目录与它之下的 {@link CHECKPOINT_CTX_KEY_SUBDIR} 各是一只目录、各有一把自己的锁。
+ */
+export declare const KEYGEN_LOCK_FILE = ".keygen.lock";
 //# sourceMappingURL=sealed-key-layout.d.ts.map

package/dist/sealed-key-layout.js

@@ -1,3 +1,8 @@
+import { join } from "node:path";
+export function sealedKeyDirOf(config, localRoot) {
+    return config.sealedKeyDir ?? join(config.localDataRoot ?? localRoot, "sealed-key");
+}
 export const SEALED_KEY_DIR_MODE = 0o700;
 export const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+export const KEYGEN_LOCK_FILE = ".keygen.lock";
 //# sourceMappingURL=sealed-key-layout.js.map

package/dist/sealed-key.d.ts

@@ -73,14 +73,24 @@ export declare class SealedKeyPublicKeyRefusedError extends Error {
  * 前置:libsodium 已就绪(三处调用方都先等过它);没就绪 ⇒ 当场抛普通错误(不是判决)。
  */
 export declare function judgeSealedKeyPublicKey(publicKeyB64: string): Uint8Array;
+/** {@link ensureSealedKeyStore} 的选项。 */
+export interface EnsureSealedKeyStoreOptions {
+    /** 目录里没有钥匙、别人正拿着创建互斥时,最多等多久(毫秒;缺省 15 s)。测试缝;生产不设。 */
+    readonly genesisLockWaitMs?: number;
+}
 /**
  * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
  * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a
  * half-write — deleting operator key material on a parse error would destroy decryptability, so we
  * never do; we just don't serve them). Throws only when the store cannot exist at all (fs errors,
- * zero loadable keys AND generation failed).
+ * zero loadable keys AND generation failed, or another process holds the key-creation lock past the wait).
+ *
+ * **首把钥匙只有一个创建口**(共享卷上多个副本在空目录上同时首启,全体只出一把):一把可装载的钥匙都没有 ⇒ 取创建互斥({@link takeKeygenLock},`wx` 独占);
+ * 拿到的那一个**再读一次目录**(读目录到拿互斥之间别人可能已发布)—— 仍空才生成并发布({@link mintFirstKey}),然后撤互斥;没拿到(`EEXIST`)⇒ 重读目录:
+ * 有钥匙了就采用,没有就隔 {@link KEYGEN_LOCK_POLL_MS} 再读,等到 `genesisLockWaitMs` 仍没有 ⇒ 响亮拒({@link keygenLockTimeout}),**不**越过别人的互斥自己生成。
+ * 互斥只在「目录里没有可装载的钥匙」时被问到:已有钥匙的目录(含上次崩溃遗留互斥文件的)起服零等待;共享卷须提供原子的 `O_EXCL` 独占创建(本地盘、NFSv3+、常见 RWX 存储类满足)。
  */
-export declare function ensureSealedKeyStore(dir: string, logger?: Logger): Promise<SealedKeyStore>;
+export declare function ensureSealedKeyStore(dir: string, logger?: Logger, opts?: EnsureSealedKeyStoreOptions): Promise<SealedKeyStore>;
 declare const checkpointCtxKeyStoreBrand: unique symbol;
 /**
  * 停驻行封签那一域的保管店(品牌型):读口与 {@link SealedKeyStore} 同形,型不同 —— {@link createCheckpointCtxSealing} 只收它,模型钥匙那只店交进去是 tsc 错

package/dist/sealed-key.js

@@ -1,15 +1,16 @@
 import { createHash } from "node:crypto";
-import { chmod, readdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, open, readdir, readFile, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { ensureDir } from "@sema-agent/core";
 import _sodium from "libsodium-wrappers";
-import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE } from "./sealed-key-layout.js";
-import { OWNER_ONLY_FILE_MODE } from "./plugins/owner-only-file-mode.js";
+import { CHECKPOINT_CTX_KEY_SUBDIR, KEYGEN_LOCK_FILE, SEALED_KEY_DIR_MODE } from "./sealed-key-layout.js";
+import { OWNER_ONLY_FILE_MODE, atomicWriteFileAsync } from "./plugins/owner-only-file-mode.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
 import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
 import { CHECKPOINT_CTX_SEAL_ALG } from "./http/checkpoint-ctx.js";
+import { readUpstreamJson } from "./upstream-body.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -61,12 +62,10 @@ export function judgeSealedKeyPublicKey(publicKeyB64) {
     }
     return bytes;
 }
-export async function ensureSealedKeyStore(dir, logger) {
-    await _sodium.ready;
+async function scanKeyDir(dir) {
     const sodium = _sodium;
-    ensureDir(dir);
-    await chmod(dir, SEALED_KEY_DIR_MODE);
     const keys = new Map();
+    const notes = [];
     for (const name of (await readdir(dir)).filter((n) => n.endsWith(".json")).sort()) {
         const path = join(dir, name);
         try {
@@ -79,34 +78,123 @@ export async function ensureSealedKeyStore(dir, logger) {
             if (privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
                 throw new Error("bad key length");
             if (name !== `${raw.publicKeyId}.json`)
-                logger?.warn("sealed_key_filename_drift", { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" });
+                notes.push({ msg: "sealed_key_filename_drift", fields: { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" } });
             if (keys.has(raw.publicKeyId)) {
-                logger?.warn("sealed_key_duplicate_id", { file: name, publicKeyId: raw.publicKeyId, note: "duplicate publicKeyId — keeping the first, skipping this file" });
+                notes.push({ msg: "sealed_key_duplicate_id", fields: { file: name, publicKeyId: raw.publicKeyId, note: "duplicate publicKeyId — keeping the first, skipping this file" } });
                 continue;
             }
             keys.set(raw.publicKeyId, { publicKey, privateKey, publicKeyB64: raw.publicKey, createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "" });
         }
         catch (err) {
-            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : {}), note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
+            notes.push({
+                msg: "sealed_key_file_unreadable",
+                fields: { file: path, errKind: err instanceof Error ? err.name : "unknown", ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : {}), note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" },
+            });
         }
     }
-    if (keys.size === 0) {
-        const kp = sodium.crypto_box_keypair();
-        const publicKeyB64 = Buffer.from(kp.publicKey).toString("base64");
-        const record = {
-            v: 1,
-            alg: SEALED_KEY_ALG,
-            publicKeyId: deriveKeyId(kp.publicKey),
-            publicKey: publicKeyB64,
-            privateKey: Buffer.from(kp.privateKey).toString("base64"),
-            createdAt: new Date().toISOString(),
-        };
-        const path = join(dir, `${record.publicKeyId}.json`);
-        await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: OWNER_ONLY_FILE_MODE });
-        await chmod(path, OWNER_ONLY_FILE_MODE);
-        keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
-        logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
+    return { keys, notes };
+}
+const isExists = (err) => typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST";
+const KEYGEN_LOCK_POLL_MS = 50;
+const KEYGEN_LOCK_WAIT_MS = 15_000;
+async function takeKeygenLock(dir) {
+    const path = join(dir, KEYGEN_LOCK_FILE);
+    let handle;
+    try {
+        handle = await open(path, "wx", OWNER_ONLY_FILE_MODE);
+    }
+    catch (err) {
+        if (isExists(err))
+            return undefined;
+        throw err;
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        await releaseKeygenLock(path, { error }, undefined);
+        throw error;
+    }
+    return path;
+}
+async function releaseKeygenLock(path, primary, logger) {
+    try {
+        await rm(path, { force: true });
+    }
+    catch (cleanup) {
+        if (primary !== undefined) {
+            const text = (e) => (e instanceof Error ? e.message : String(e));
+            throw new Error(`sealed-key custody: ${text(primary.error)} — and the key-creation lock ${path} this process took could not be removed (${text(cleanup)}): remove it by hand, an empty directory is otherwise blocked on it`, { cause: primary.error });
+        }
+        logger?.warn("sealed_key_keygen_lock_not_released", { lock: path, errKind: cleanup instanceof Error ? cleanup.name : "unknown", note: "the key-creation lock this process took could not be removed — harmless while the directory holds a key; with an empty directory every start waits on it until it is removed by hand" });
+    }
+}
+async function keygenLockTimeout(dir, lock, waitedMs) {
+    const heldFor = await stat(lock).then((s) => Math.max(0, Math.round((Date.now() - s.mtimeMs) / 1000)), () => undefined);
+    return new Error(`sealed-key custody ${dir}: the key-creation lock ${lock} is held${heldFor !== undefined ? ` (for ${heldFor}s)` : ""} and no key file appeared within ${waitedMs} ms — ` +
+        `if no replica is starting right now, an earlier start died while generating the key: remove ${lock} and start again`);
+}
+async function mintFirstKey(dir, logger) {
+    const sodium = _sodium;
+    const kp = sodium.crypto_box_keypair();
+    const publicKeyB64 = Buffer.from(kp.publicKey).toString("base64");
+    const record = {
+        v: 1,
+        alg: SEALED_KEY_ALG,
+        publicKeyId: deriveKeyId(kp.publicKey),
+        publicKey: publicKeyB64,
+        privateKey: Buffer.from(kp.privateKey).toString("base64"),
+        createdAt: new Date().toISOString(),
+    };
+    const path = join(dir, `${record.publicKeyId}.json`);
+    await atomicWriteFileAsync(path, JSON.stringify(record, null, 2) + "\n", { durability: "best-effort" });
+    await chmod(path, OWNER_ONLY_FILE_MODE);
+    logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
+    return { id: record.publicKeyId, key: { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt } };
+}
+export async function ensureSealedKeyStore(dir, logger, opts = {}) {
+    await _sodium.ready;
+    const sodium = _sodium;
+    ensureDir(dir);
+    await chmod(dir, SEALED_KEY_DIR_MODE);
+    const waitMs = opts.genesisLockWaitMs ?? KEYGEN_LOCK_WAIT_MS;
+    const deadline = Date.now() + waitMs;
+    let scan = await scanKeyDir(dir);
+    let minted;
+    try {
+        while (scan.keys.size === 0 && minted === undefined) {
+            const lock = await takeKeygenLock(dir);
+            if (lock !== undefined) {
+                let failure;
+                try {
+                    scan = await scanKeyDir(dir);
+                    if (scan.keys.size === 0)
+                        minted = await mintFirstKey(dir, logger);
+                }
+                catch (error) {
+                    failure = { error };
+                    throw error;
+                }
+                finally {
+                    await releaseKeygenLock(lock, failure, logger);
+                }
+            }
+            else if (Date.now() >= deadline) {
+                throw await keygenLockTimeout(dir, join(dir, KEYGEN_LOCK_FILE), waitMs);
+            }
+            else {
+                await new Promise((resolve) => setTimeout(resolve, KEYGEN_LOCK_POLL_MS));
+                scan = await scanKeyDir(dir);
+            }
+        }
+    }
+    finally {
+        for (const n of scan.notes)
+            logger?.warn(n.msg, n.fields);
     }
+    const keys = new Map(scan.keys);
+    if (minted !== undefined)
+        keys.set(minted.id, minted.key);
     const latestEntry = [...keys.entries()].sort((a, b) => (a[1].createdAt < b[1].createdAt ? 1 : a[1].createdAt > b[1].createdAt ? -1 : a[0] < b[0] ? -1 : 1))[0];
     return {
         latest: { publicKeyId: latestEntry[0], publicKey: latestEntry[1].publicKeyB64, createdAt: latestEntry[1].createdAt },
@@ -209,7 +297,7 @@ export async function reportExecutionPublicKey(opts) {
         if (res.ok) {
             let idempotent = false;
             try {
-                idempotent = (await res.json())?.idempotent === true;
+                idempotent = (await readUpstreamJson(res))?.idempotent === true;
             }
             catch { }
             logger?.info(idempotent ? "sealed_key_already_registered" : "sealed_key_reported", { publicKeyId: key.publicKeyId, status: res.status });