@sema-agent/server 7.103.2 → 7.104.0

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

@@ -2,7 +2,7 @@ import { screenedGate } from "../../trace/project.js";
 import { hostDecisionFacts } from "../../host-decision.js";
 import { sameExecutionRecord } from "@sema-agent/core";
 import { DECIDED_REPLAY_SCAN_CAP, approvalPayloadFingerprint } from "../../plugins/checkpoint-store-sql.js";
-import { APPROVAL_GATE_KINDS, SETTLED_BY_DENY_ONLY, SETTLED_BY_MUST_BE_STRING } from "../../tool-approval.js";
+import { APPROVAL_GATE_KINDS, SETTLED_BY_DENY_ONLY, SETTLED_BY_MUST_BE_STRING, SETTLED_BY_TOO_WIDE, judgeSettledByBody } from "../../tool-approval.js";
 import { isParkedRunStatus } from "../../plugins/store-contracts.js";
 import { principalFrom, decodeCheckpointScope, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
 import { editedPlanBinding, isWellFormedUnicode, verifyDirectDoorProof } from "../../principal-jwt.js";
@@ -27,30 +27,6 @@ const DECIDE_BODY_DECLARED_KEYS = [
 ];
 const DECIDE_PROOF_COVERED_KEYS = ["answer", "boundCallId", "boundInputHash", "decision", "reason"];
 const DECIDE_NOT_IN_PROOF_KEYS = ["checkpointToken", "remember", "settledBy", "updatedInput"];
-const ACCEPTED_DECIDE_BODY = new Set(DECIDE_BODY_DECLARED_KEYS);
-const UNSUPPORTED_DECIDE_BODY = new Set(["editedPlan", "sessionId", "taskId"]);
-export function decideBodyKeyIssue(raw) {
-    if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
-        return null;
-    const buckets = { unknown: [], unsupported: [] };
-    scanKeyClosure(raw, "", ACCEPTED_DECIDE_BODY, UNSUPPORTED_DECIDE_BODY, buckets);
-    if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
-        return null;
-    buckets.unknown.sort();
-    buckets.unsupported.sort();
-    const parts = [
-        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, "unknown (not a decide-request key — check the spelling)")] : []),
-        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, "unsupported (a sibling approval door's field, or a path parameter — never read from this body)")] : []),
-    ];
-    return {
-        message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller ` +
-            `(a misspelled \`remember\` or \`boundInputHash\` silently turns off an exemption / the decision binding). ` +
-            `${parts.join("; ")}. ` +
-            `Accepted: ${[...ACCEPTED_DECIDE_BODY].sort().join(",")}`,
-        unknownKeys: buckets.unknown.slice(0, MAX_KEY_ECHO),
-        unsupportedKeys: buckets.unsupported.slice(0, MAX_KEY_ECHO),
-    };
-}
 const PLAN_REVIEW_BODY_DECLARED_KEYS = [
     "boundCallId", "decision", "editedPlan", "permissionModeAfter", "reason",
 ];
@@ -71,29 +47,108 @@ function buildApprovalEnvelope(sessionId, covered, reading) {
         Object.assign(envelope, { [PROOF_SLOT_OF[key]]: reading[key] });
     return envelope;
 }
-const ACCEPTED_PLAN_REVIEW_BODY = new Set(PLAN_REVIEW_BODY_DECLARED_KEYS);
-const UNSUPPORTED_PLAN_REVIEW_BODY = new Set([
-    ...DECIDE_BODY_DECLARED_KEYS.filter((k) => !PLAN_REVIEW_BODY_DECLARED_KEYS.includes(k)),
-    "permissionMode", "sessionId", "taskId",
-]);
-export function planReviewBodyKeyIssue(raw) {
+const DECISION_DOOR_FAMILY = {
+    "approval-decide": {
+        accepted: DECIDE_BODY_DECLARED_KEYS,
+        requestNoun: "decide-request",
+        costliestTypo: "a misspelled `remember` or `boundInputHash` silently turns off an exemption / the decision binding",
+    },
+    "assistant-task-plan-review": {
+        accepted: PLAN_REVIEW_BODY_DECLARED_KEYS,
+        requestNoun: "plan-review-request",
+        costliestTypo: "a misspelled `permissionModeAfter` silently leaves this task read-only after you approved its plan",
+    },
+};
+const SUBMIT_BODY_NEAR_MISS_KEYS = ["permissionMode"];
+const SUBMIT_ENDPOINT = "POST /v1/tasks";
+function neighborLabel(n) {
+    const where = n.where.join(" / ");
+    switch (n.family) {
+        case "sibling_field":
+            return `unsupported (a body field of ${where} — send it there, this door never reads it)`;
+        case "path_segment":
+            return `unsupported (a path segment of ${where} — identity travels in the URL, never in a body)`;
+        case "submit_body":
+            return `unsupported (a submit-body key of ${where} — set when the task is submitted, this door never reads it)`;
+        default: {
+            const unreachable = n.family;
+            throw new Error(`decision-door key closure: unknown neighbor family ${String(unreachable)}`);
+        }
+    }
+}
+function doorEndpointOf(routes, id) {
+    const decl = routes.find((r) => "id" in r && r.id === id);
+    if (decl === undefined || !("pattern" in decl) || decl.label === undefined) {
+        throw new Error(`decision-door family: route "${id}" is not a labelled pattern row of the route table — the key-closure hints are derived from it`);
+    }
+    const groups = new RegExp(`${decl.pattern.source}|`, decl.pattern.flags).exec("")?.groups ?? {};
+    return { endpoint: `${decl.methods.join("|")} ${decl.label}`, pathSegments: Object.keys(groups) };
+}
+export function deriveDecisionDoorKeyTable(family, routes) {
+    const ids = Object.keys(family);
+    const endpoint = new Map(ids.map((id) => [id, doorEndpointOf(routes, id)]));
+    const collect = (pairs) => {
+        const m = new Map();
+        for (const [k, where] of pairs)
+            m.set(k, [...(m.get(k) ?? []), where]);
+        return m;
+    };
+    const siblingWhere = collect(ids.flatMap((id) => family[id].accepted.map((k) => [k, endpoint.get(id).endpoint])));
+    const pathWhere = collect(ids.flatMap((id) => endpoint.get(id).pathSegments.map((k) => [k, endpoint.get(id).endpoint])));
+    const submitWhere = collect(SUBMIT_BODY_NEAR_MISS_KEYS.map((k) => [k, SUBMIT_ENDPOINT]));
+    const sources = [
+        ["sibling_field", siblingWhere],
+        ["path_segment", pathWhere],
+        ["submit_body", submitWhere],
+    ];
+    for (let i = 0; i < sources.length; i++) {
+        for (let j = i + 1; j < sources.length; j++) {
+            const [fa, a] = sources[i];
+            const [fb, b] = sources[j];
+            const both = [...a.keys()].filter((k) => b.has(k));
+            if (both.length > 0)
+                throw new Error(`decision-door family: key(s) ${both.join(", ")} belong to both ${fa} and ${fb} — a refused key must have exactly one destination`);
+        }
+    }
+    const derive = (self) => {
+        const accepted = new Set(family[self].accepted);
+        const neighbors = new Map();
+        for (const [fam, source] of sources) {
+            for (const [k, where] of source)
+                if (!accepted.has(k))
+                    neighbors.set(k, { family: fam, where });
+        }
+        return { accepted, neighbors, requestNoun: family[self].requestNoun, costliestTypo: family[self].costliestTypo };
+    };
+    return { "approval-decide": derive("approval-decide"), "assistant-task-plan-review": derive("assistant-task-plan-review") };
+}
+export function decisionBodyKeyIssue(door, raw, table = DECISION_DOOR_KEY_TABLE) {
     if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
         return null;
+    const d = table[door];
     const buckets = { unknown: [], unsupported: [] };
-    scanKeyClosure(raw, "", ACCEPTED_PLAN_REVIEW_BODY, UNSUPPORTED_PLAN_REVIEW_BODY, buckets);
+    scanKeyClosure(raw, "", d.accepted, new Set(d.neighbors.keys()), buckets);
     if (buckets.unknown.length === 0 && buckets.unsupported.length === 0)
         return null;
     buckets.unknown.sort();
     buckets.unsupported.sort();
+    const byLabel = new Map();
+    for (const k of buckets.unsupported) {
+        const n = d.neighbors.get(k);
+        if (n === undefined)
+            throw new Error(`decision-door key closure: "${k}" was classified unsupported but has no destination`);
+        const label = neighborLabel(n);
+        byLabel.set(label, [...(byLabel.get(label) ?? []), k]);
+    }
     const parts = [
-        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, "unknown (not a plan-review-request key — check the spelling)")] : []),
-        ...(buckets.unsupported.length > 0 ? [keyClosureClause(buckets.unsupported, "unsupported (a sibling approval door's field, a submit-body key, or a path parameter — never read from this body)")] : []),
+        ...(buckets.unknown.length > 0 ? [keyClosureClause(buckets.unknown, `unknown (not a ${d.requestNoun} key — check the spelling)`)] : []),
+        ...[...byLabel].map(([label, keys]) => keyClosureClause(keys, label)),
     ];
     return {
         message: `body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller ` +
-            `(a misspelled \`permissionModeAfter\` silently leaves this task read-only after you approved its plan). ` +
+            `(${d.costliestTypo}). ` +
             `${parts.join("; ")}. ` +
-            `Accepted: ${[...ACCEPTED_PLAN_REVIEW_BODY].sort().join(",")}`,
+            `Accepted: ${[...d.accepted].sort().join(",")}`,
         unknownKeys: buckets.unknown.slice(0, MAX_KEY_ECHO),
         unsupportedKeys: buckets.unsupported.slice(0, MAX_KEY_ECHO),
     };
@@ -437,7 +492,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 return;
             }
             {
-                const keyIssue = planReviewBodyKeyIssue(body);
+                const keyIssue = decisionBodyKeyIssue("assistant-task-plan-review", body);
                 if (keyIssue) {
                     sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
                     return;
@@ -570,7 +625,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 return;
             }
             {
-                const keyIssue = decideBodyKeyIssue(body);
+                const keyIssue = decisionBodyKeyIssue("approval-decide", body);
                 if (keyIssue) {
                     sendError(res, 400, "request.body_shape", keyIssue.message, { unknownKeys: keyIssue.unknownKeys, unsupportedKeys: keyIssue.unsupportedKeys });
                     return;
@@ -637,18 +692,29 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 sendError(res, 400, "checkpoint_token_not_in_proof", "checkpointToken is not supported on a direct-door worker (not covered by the decision proof); bind the decision with boundCallId and boundInputHash instead");
                 return;
             }
-            if (deps.config.directDoorActive && body.settledBy !== undefined) {
-                sendError(res, 400, "settled_by_not_in_proof", "settledBy is not supported on a direct-door worker (not covered by the decision proof)");
-                return;
-            }
-            if (body.settledBy !== undefined && decision !== "deny") {
-                sendError(res, 400, "request.field_conflict", SETTLED_BY_DENY_ONLY);
-                return;
-            }
-            if (body.settledBy !== undefined && typeof body.settledBy !== "string") {
-                sendError(res, 400, "request.field_invalid", SETTLED_BY_MUST_BE_STRING);
-                return;
+            const settledByVerdict = judgeSettledByBody(body.settledBy, decision, deps.config.directDoorActive);
+            switch (settledByVerdict.kind) {
+                case "not_in_proof":
+                    sendError(res, 400, "settled_by_not_in_proof", "settledBy is not supported on a direct-door worker (not covered by the decision proof)");
+                    return;
+                case "deny_only":
+                    sendError(res, 400, "request.field_conflict", SETTLED_BY_DENY_ONLY);
+                    return;
+                case "not_string":
+                    sendError(res, 400, "request.field_invalid", SETTLED_BY_MUST_BE_STRING);
+                    return;
+                case "too_wide":
+                    sendError(res, 400, "request.field_invalid", SETTLED_BY_TOO_WIDE);
+                    return;
+                case "absent":
+                case "accepted":
+                    break;
+                default: {
+                    const unreachable = settledByVerdict;
+                    throw new Error(`unhandled settledBy verdict: ${JSON.stringify(unreachable)}`);
+                }
             }
+            const settledBy = settledByVerdict.kind === "accepted" ? settledByVerdict.settledBy : undefined;
             const binding = {
                 checkpointToken: body.checkpointToken,
                 boundCallId: body.boundCallId,
@@ -697,7 +763,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     pendingGrant = { sessionId: grant.overrideSessionId ?? sessionId, toolName: canonical };
                 }
                 : undefined;
-            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, hostDecisionFacts(body.settledBy, deciderPrincipal), req, answer, binding, grantOnCommit, true, { principal: deciderPrincipal, explicitOperator });
+            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) {
                 try {
@@ -832,4 +898,5 @@ export const APPROVALS_ASSISTANT_ROUTES = [
     { id: "assistant-task-plan-review", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/plan_review$/, label: "/v1/assistant/tasks/:id/plan_review", billable: true, methods: ["POST"] },
     { prefix: "/v1/approvals", billable: true },
 ];
+const DECISION_DOOR_KEY_TABLE = deriveDecisionDoorKeyTable(DECISION_DOOR_FAMILY, APPROVALS_ASSISTANT_ROUTES);
 //# sourceMappingURL=approvals-assistant.js.map

package/dist/http/routes/capabilities.js

@@ -1,7 +1,7 @@
 import { expandTiers, reasoningEffortLevelsOf, routePairingStatus } from "@sema-agent/core";
 import { isModelAllowlisted, selectableCatalog } from "../../model-select.js";
 import { resolveModelApiKey } from "../../key-resolver.js";
-import { isSealedKeyPoison } from "../../sealed-key.js";
+import { isSealedKeyPoison, projectSealedKeyCapability } from "../../sealed-key.js";
 import { cwdHonored, deviceCwdHonored } from "../../task-cwd.js";
 import { taskApproverPostureHonored, taskWriteFaceRefusal } from "../../hosted-posture.js";
 import { autonomyOverrides } from "../../runtime-governance.js";
@@ -176,7 +176,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 rewindFiles: Boolean(deps.fileHistoryStore),
                 restoreFiles: Boolean(deps.fileHistoryStore),
                 rewindFilesTo: Boolean(deps.fileHistoryStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId),
-                fileHistoryCapture: fileHistoryCaptureOf(deps.fileHistoryStore),
+                fileHistoryCapture: fileHistoryCaptureOf(deps.fileHistoryStore, deps.config.fileHistoryCapture),
                 scheduler: Boolean(deps.config.schedulerEnabled && deps.config.requirePrincipal !== true && deps.config.remoteExec?.provider === "host"),
                 sessionSync: Boolean(deps.backend && deps.sessionStorage?.exportEntries && deps.sessionStorage?.beginImportStaging && deps.fileHistoryStore),
                 sendUserFile: Boolean(deps.sendUserFile && deps.config.sendUserFile?.publicEndpoint),
@@ -199,6 +199,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 })(),
                 manualCompact: Boolean(deps.runStore),
                 configCatalog: deps.config.configCatalogEnabled === true && deps.config.operatorPrincipals.length > 0,
+                sealedKey: projectSealedKeyCapability(deps.sealedKeyPublic),
             });
             return;
         }

package/dist/http/routes/config-catalog.js

@@ -23,6 +23,7 @@ export async function handleConfigCatalog(req, res, match, ctx) {
             sendJson(res, 200, buildConfigCatalog({
                 config: deps.config,
                 env: process.env,
+                boot: { ...(deps.memoryConsolidationValve !== undefined ? { memoryConsolidationValve: deps.memoryConsolidationValve } : {}) },
                 knobs: configKnobTable(),
                 centerDomains: DOMAINS,
                 centerManagedKeys: deps.configCenterManagedKeys?.(),

package/dist/http/routes/memory-consolidation.d.ts

@@ -11,8 +11,9 @@
  *
  * ── 为什么缺席形是 **404 族**而不是 501(D4)───────────────────────────────────────────────────────
  * 本仓的 501 `capability.*` 说的是「**这家店**在本部署上不存在,换部署形态才行」(记忆引擎没接线、
- * 后端没有某个复合面)。本族不是那个形:阀门关着是一句**运维表态**(`MEMORY_CONSOLIDATION_DRIVER=off`,
- * 而且是出厂缺省),不是部署能力的缺失。而阀门开着却结构上跑不了的三种形(引擎没接线 / 后端没有控制面
+ * 后端没有某个复合面)。本族不是那个形:阀门关着是一句**运维表态**(`MEMORY_CONSOLIDATION_DRIVER=off`),或
+ * 出厂缺省派生成关(S-824 / [ref]:未设而整理座落主模型 —— 起服时有一行提示点名 `MODEL_CHEAP_ID`),不是部署能力的
+ * 缺失。而阀门开着却结构上跑不了的三种形(引擎没接线 / 后端没有控制面
  * 归属 / provenance=off)在**启动期**就被拒了(`boot/memory-consolidation.ts` 的
  * `assertConsolidationDriverWirable`)—— 那些机器根本起不来,不会有一个"挂着的 501"去代表它们。
  * ⇒ 剩下的唯一缺席成因就是「阀门没开」,而它的诚实形是**这条路径不存在**:挂载条件写在 server.ts 的

package/dist/http/routes/memory-policy.js

@@ -2,7 +2,7 @@ import { formatUserScope } from "@sema-agent/core";
 import { parseMemorySyncRequest } from "../../memory-sync.js";
 import { sendJson, sendError } from "../send.js";
 import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 const ORG_PREFIX = "org:";
 export const MEMORY_EXPORT_MAX_LIMIT = 500;
@@ -68,7 +68,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
         case "memory-export": {
             const principal = gatedPrincipal(req, deps.config);
             if (!principal) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             if (deps.config.memoryEngineBackend === "file" || !deps.memoryExport) {
@@ -128,7 +128,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
         case "memory-sync-scope": {
             const principal = gatedPrincipal(req, deps.config);
             if (!principal) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             if (deps.config.memoryEngineBackend === "file" || !deps.memorySync) {

package/dist/http/routes/rules.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { sendJson, sendError, httpErrorCode } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import { createLogger } from "../../observability/logger.js";
 import { RULE_IMPORT_RETRY_AFTER_SEC, MAX_RULE_SCOPE_CHARS, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
@@ -90,7 +90,7 @@ export async function handleRules(req, res, match, ctx) {
         return;
     const principal = gatedPrincipal(req, deps.config);
     if (principal === undefined) {
-        sendError(res, 401, "auth.unauthorized", "unauthorized");
+        sendUnauthorized(res, "identity");
         return;
     }
     const lane = deps.ruleConsent;

package/dist/http/routes/runs.js

@@ -16,7 +16,7 @@ import { scopedIdempotencyKey } from "../idempotency.js";
 import { streamSseLog } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames } from "../../approval-card.js";
-import { ASK_DECISION_CONSUMER_ABSENT, outcomeOfDecidedRow, resolveStreamApprovalGate } from "../../tool-approval.js";
+import { ASK_DECISION_CONSUMER_ABSENT, SETTLED_BY_DENY_ONLY, SETTLED_BY_MUST_BE_STRING, SETTLED_BY_TOO_WIDE, judgeSettledByBody, outcomeOfDecidedRow, resolveStreamApprovalGate, respondSettledBy } from "../../tool-approval.js";
 import { MAX_DECISION_NOTE_CHARS } from "../../approval-ask-machine.js";
 import { normalizeRunEventType, screenedStoredEventData } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
@@ -45,6 +45,7 @@ const AskDecisionBodySchema = z
         .refine((k) => k.trim() === k, { message: "idempotency key must not have leading/trailing whitespace" })
         .optional(),
     actor: z.object({ label: z.string().max(ASK_ACTOR_LABEL_MAX) }).strict().optional(),
+    settledBy: z.unknown().optional(),
 })
     .strict();
 const ASK_DECISION_CONFIRM_TIMEOUT_MS = 2_000;
@@ -1287,10 +1288,33 @@ export async function handleRunVerbs(req, res, match, ctx) {
         }
         const parsedBody = AskDecisionBodySchema.safeParse(rawBody);
         if (!parsedBody.success) {
-            sendError(res, 400, "request.body_shape", "invalid ask decision body — expected decision=approve|deny plus optional updatedInput / note / idempotencyKey / actor.label");
+            sendError(res, 400, "request.body_shape", "invalid ask decision body — expected decision=approve|deny plus optional updatedInput / note / idempotencyKey / actor.label / settledBy");
             return;
         }
         const body = parsedBody.data;
+        const settledByVerdict = judgeSettledByBody(body.settledBy, body.decision, deps.config.directDoorActive);
+        switch (settledByVerdict.kind) {
+            case "not_in_proof":
+                sendError(res, 400, "settled_by_not_in_proof", "settledBy is not supported on a direct-door worker (not covered by the decision proof)");
+                return;
+            case "deny_only":
+                sendError(res, 400, "request.field_conflict", SETTLED_BY_DENY_ONLY);
+                return;
+            case "not_string":
+                sendError(res, 400, "request.field_invalid", SETTLED_BY_MUST_BE_STRING);
+                return;
+            case "too_wide":
+                sendError(res, 400, "request.field_invalid", SETTLED_BY_TOO_WIDE);
+                return;
+            case "absent":
+            case "accepted":
+                break;
+            default: {
+                const unreachable = settledByVerdict;
+                throw new Error(`unhandled settledBy verdict: ${JSON.stringify(unreachable)}`);
+            }
+        }
+        const settledBy = settledByVerdict.kind === "accepted" ? settledByVerdict.settledBy : undefined;
         const hasUpdatedInput = typeof rawBody === "object" && rawBody !== null && "updatedInput" in rawBody;
         const taskId = match.params.taskId;
         const askId = match.params.askId;
@@ -1424,6 +1448,7 @@ export async function handleRunVerbs(req, res, match, ctx) {
                 decisionActor: actor,
                 decisionNote: body.note ?? null,
                 idempotencyKey: body.idempotencyKey ?? null,
+                ...(settledBy !== undefined ? { settledBy: respondSettledBy({ settledBy }) } : {}),
                 ...(body.decision === "approve" && hasUpdatedInput ? { updatedInput: body.updatedInput } : {}),
             });
         }

package/dist/http/routes/session-sync.js

@@ -1,13 +1,13 @@
 import { once } from "node:events";
 import { randomBytes, createHash } from "node:crypto";
-import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, SessionError, validateFileHistoryExport } from "@sema-agent/core";
+import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, validateFileHistoryExport } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
 import { exportSessionManifest, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, overwriteWipeIncapable, wipeSessionAttendants } from "../../session-sync.js";
 import { classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync-kernel.js";
 import { isUuidShape } from "../../security.js";
-import { sendJson, sendError, sendSessionPolicyError, msg } from "../send.js";
+import { sendJson, sendError, sendSessionError, sendSessionPolicyError, msg } from "../send.js";
 import { buildDisplaySafeUrl } from "../../trace/redact.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendUnauthorized } from "../principal-gate.js";
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
 const SYNC_IMPORT_BATCH = 500;
@@ -43,12 +43,12 @@ export async function handleSessionSync(req, res, match, ctx) {
             }
             const historyStore = deps.fileHistoryStore;
             if (historyStore === undefined) {
-                sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: file-history capture is turned off (FILE_HISTORY_CAPTURE=false), so there is no file history to export or import");
+                sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: no file-history store is wired, so there is no file history to export or import");
                 return;
             }
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const sessionId = safeDecode(match.params.sessionId);
@@ -459,20 +459,14 @@ export async function handleSessionSync(req, res, match, ctx) {
                     }
                 }
                 catch (e) {
+                    await pending.handle.abort().catch(() => undefined);
+                    cleanupStaging(stagingId);
                     if (e instanceof PrecheckError) {
-                        await pending.handle.abort().catch(() => undefined);
-                        cleanupStaging(stagingId);
                         sendError(res, e.status, "invalid_entries", e.message);
                         return;
                     }
-                    if (e instanceof SessionError && e.code === "invalid_session") {
-                        await pending.handle.abort().catch(() => undefined);
-                        cleanupStaging(stagingId);
-                        sendError(res, 422, "invalid_entries", "staged session log failed validation");
+                    if (sendSessionError(res, e, "import"))
                         return;
-                    }
-                    await pending.handle.abort().catch(() => undefined);
-                    cleanupStaging(stagingId);
                     throw e;
                 }
                 const activeAtCommit = await deps.runStore?.getActiveTaskId(sessionId);

package/dist/http/routes/sessions-list.js

@@ -1,5 +1,6 @@
 import { isUuidV7, legacyUnownedAmnestyOpen } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
+import { sendUnauthorized } from "../principal-gate.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import { assertNever } from "../route-ctx.js";
@@ -10,7 +11,7 @@ export async function handleSessionsList(req, res, match, ctx) {
         case "sessions-list": {
             const { fleetWide, gateOwner } = sessionOwnerScope(req);
             if (!fleetWide && gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const lister = deps.sessionStorage?.listSessions?.bind(deps.sessionStorage) ?? deps.runStore?.listSessions?.bind(deps.runStore);
@@ -25,7 +26,7 @@ export async function handleSessionsList(req, res, match, ctx) {
         case "sendfile-links": {
             const { fleetWide, gateOwner } = sessionOwnerScope(req);
             if (!fleetWide && gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             if (!deps.sendFileLedger) {

package/dist/http/routes/sessions.js

@@ -7,9 +7,10 @@ import { recordFailOpen } from "../../observability/fail-open.js";
 import { targetOutsideStoreOf } from "../../memory-store-refusal.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../../task-settings.js";
 import { readSessionPermissionRules, describeSessionPermissionRulesProblem } from "../../session-policy-wire.js";
-import { sendJson, sendError, sendSessionPolicyError, sseHeaders } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefusal } from "../principal-gate.js";
+import { sendJson, sendError, sendSessionError, sendSessionPolicyError, sseHeaders } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
+import { rosterAgentId } from "./agents-roster.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
 const A2A_STATUS_TTL_MS = 5_000;
@@ -67,6 +68,34 @@ async function readLastLegMcp(deps, sessionId, principal) {
 export async function handleSessions(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson, safeDecode, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite } = ctx.helpers;
+    const readOwnedSessionView = async (sessionAudit, sessionId, notFoundForm) => {
+        const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
+        if (ownerOf !== undefined) {
+            const owner = await ownerOf(sessionId);
+            if (owner === undefined) {
+                sendError(res, 404, "not_found.session", "session not found");
+                return undefined;
+            }
+            if (!runOwnerOk(req, res, owner, notFoundForm))
+                return undefined;
+        }
+        let audit;
+        try {
+            audit = await sessionAudit(sessionId);
+        }
+        catch (e) {
+            if (ownerOf !== undefined)
+                throw e;
+            throw new Error(`session view read failed before ownership could be established: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+        if (!audit) {
+            sendError(res, 404, "not_found.session", "session not found");
+            return undefined;
+        }
+        if (!runOwnerOk(req, res, audit.owner, notFoundForm))
+            return undefined;
+        return audit;
+    };
     const sse = ctx.local.sessions;
     const { mcpStatusCache, a2aStatusCache } = ctx.local.sessions;
     {
@@ -441,6 +470,8 @@ export async function handleSessions(req, res, match, ctx) {
             }
             catch (e) {
                 cleanup();
+                if (!res.headersSent && sendSessionError(res, e, "open"))
+                    return;
                 if (!res.headersSent)
                     sendError(res, 500, "internal.error", `session events failed: ${e instanceof Error ? e.message : "unknown"}`);
                 else
@@ -467,12 +498,7 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 501, "capability.memory_engine_required", "memory provenance and erasure are not available on this deployment — they require a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            const audit = await deps.sessionAudit(sessionId);
-            if (!audit) {
-                sendError(res, 404, "not_found.session", "session not found");
-                return;
-            }
-            if (!runOwnerOk(req, res, audit.owner, "session"))
+            if ((await readOwnedSessionView(deps.sessionAudit, sessionId, "session")) === undefined)
                 return;
             const faces = deps.memoryCompliance;
             if (faces === undefined) {
@@ -532,12 +558,7 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 501, "capability.memory_engine_required", "session memory status is not available on this deployment — it requires a wired memory engine (MEMORY_ENGINE=on) whose backend owns the engine control plane (controlPlaneRoot); the file memory backend does, the pg/tidb memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            const audit = await deps.sessionAudit(sessionId);
-            if (!audit) {
-                sendError(res, 404, "not_found.session", "session not found");
-                return;
-            }
-            if (!runOwnerOk(req, res, audit.owner, "session"))
+            if ((await readOwnedSessionView(deps.sessionAudit, sessionId, "session")) === undefined)
                 return;
             const face = deps.sessionMemoryStatus;
             if (face === undefined) {
@@ -581,12 +602,8 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 404, "not_found.route", "not found");
                 return;
             }
-            const audit = await deps.sessionAudit(match.params.sessionId);
-            if (!audit) {
-                sendError(res, 404, "not_found.session", "session not found");
-                return;
-            }
-            if (!runOwnerOk(req, res, audit.owner))
+            const audit = await readOwnedSessionView(deps.sessionAudit, match.params.sessionId, "run");
+            if (audit === undefined)
                 return;
             const q = new URLSearchParams(match.search);
             const qi = (k) => {
@@ -636,7 +653,7 @@ export async function handleSessions(req, res, match, ctx) {
             }
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const sourceId = safeDecode(match.params.sessionId);
@@ -673,7 +690,7 @@ export async function handleSessions(req, res, match, ctx) {
             }
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const sessionId = safeDecode(match.params.sessionId);
@@ -700,6 +717,10 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 409, "conflict.session_active_run", "session has an active run; cancel it before deleting", { activeTaskId: result.active });
                 return;
             }
+            if ("childrenAlive" in result) {
+                sendError(res, 409, "conflict.session_children_alive", "this session still has background agents running where this replica cannot stop them (on another replica, for example), so the delete was refused before anything was deleted — `remaining` lists their ids (the same ids `GET /v1/agents/roster` shows); retry the delete once they finish, or stop them where they run", { remaining: result.childrenAlive.map((handle) => rosterAgentId({ handle })) });
+                return;
+            }
             sendJson(res, 200, result);
             return;
         }
@@ -714,7 +735,7 @@ export async function handleSessions(req, res, match, ctx) {
             }
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const sessionId = safeDecode(match.params.sessionId);

package/dist/http/routes/shared-memory.js

@@ -1,6 +1,6 @@
 import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 const RETRY_AFTER_SEC = 10;
 const HTTP_LIST_LIMIT = 100;
@@ -29,7 +29,7 @@ async function bindSnapshot(req, res, ctx) {
     const { deps } = ctx;
     const principal = gatedPrincipal(req, deps.config);
     if (!principal && deps.config.requirePrincipal === true) {
-        sendError(res, 401, "auth.unauthorized", "unauthorized");
+        sendUnauthorized(res, "identity");
         return undefined;
     }
     const provider = deps.sharedMemoryStore;