@sema-agent/server 7.146.0 → 7.148.0

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

@@ -3,13 +3,16 @@ import { skillCardFacts } from "../../approval-card.js";
 import { hostDecisionFacts, readDecider, retiredDecisionKeyFacts, DECIDED_BY_NOT_IN_PROOF } from "../../host-decision.js";
 import { sameExecutionRecord } from "@sema-agent/core";
 import { findParkedAgentForCheckpoint } from "../../parked-decide.js";
-import { DECIDED_REPLAY_SCAN_CAP } from "../../plugins/checkpoint-store-face.js";
+import { DECIDED_REPLAY_SCAN_CAP, pendingTriageOrder } from "../../plugins/checkpoint-store-face.js";
 import { approvalPayloadFingerprint } from "../../plugins/approval-payload-fingerprint.js";
 import { carriesDeploymentListQuestion, standingAnswerDurablyRecordable } from "../../tool-approval.js";
 import { APPROVAL_GATE_KINDS } from "../../approval-content-kind.js";
 import { isParkedRunStatus } from "../../plugins/store-contracts.js";
-import { principalFrom, decodeCheckpointScope, ownerOfCheckpointScope, CHECKPOINT_PUBLIC_SCOPE, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
-import { editedPlanBinding, isWellFormedUnicode, verifyDirectDoorProof } from "../../principal-jwt.js";
+import { principalFrom, ownerOfCheckpointScope, scopeCellOf, CHECKPOINT_PUBLIC_SCOPE, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
+import { keyAdmits } from "../../owner-faces.js";
+import { personOf } from "../../owner-brands.js";
+import { editedPlanBinding, verifyDirectDoorProof } from "../../principal-jwt.js";
+import { isWellFormedUnicode } from "../../principal-shape.js";
 import { MAX_APPROVAL_REASON_CHARS, projectQuestionAnswer, questionAnswerFromProjection } from "../../approval-hmac.js";
 import { PLAN_APPROVE_PERMISSION_MODES_AFTER, isPlanApprovePermissionModeAfter, planReviewDecisionExitsPlan, storedBodyPermissionMode } from "../../task-settings.js";
 import { MAX_APPROVAL_NONCE_CHARS } from "../../plugins/approval-nonce-store.js";
@@ -19,8 +22,8 @@ import { buildRunName } from "../../fleet/fleet-bus.js";
 import { sleep } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { sendJson, sendError, sseHeaders, logRequestError, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal, sessionCallerOf } from "../principal-gate.js";
-import { readOwnedRun, readOwnedSession } from "../owner-access.js";
+import { gatedSubject, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
+import { admitRunById, admitSessionById, callerEntry, callerOf, callerOfDecision, deciderSubjectOf, enter, judgeRun, protocolEntry, readVisibleRun, refuse, withCaller } from "../owner-access.js";
 import { governanceOriginOf } from "../../runtime-governance.js";
 import { deploymentListAsks } from "../../approval.js";
 import { grantBindingOf } from "../../standing-answer-grant.js";
@@ -32,7 +35,7 @@ import { recordFailOpen } from "../../observability/fail-open.js";
 import { MAX_CHECKPOINT_ID_CHARS, durableRowIdentity } from "../../checkpoint-identity.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "../../request-key-closure.js";
 import { fieldConflictFacts } from "../../field-conflict.js";
-import { buildSettlementEvidence, decisionCommittedOf } from "../../gate-settlement.js";
+import { buildSettlementEvidence } from "../../gate-settlement.js";
 import { seatText } from "../../trace/exit-seat.js";
 import { approvalQueueKindOfDoorId } from "../../approval-queue-kind.js";
 import { defaultPeerInboundFace, parsePeerInboundId, peerBoxScope } from "../../peer-inbound-face.js";
@@ -215,7 +218,7 @@ export function checkQuestionAnswer(v) {
     return shapeOk ? { ok: true, value: v } : { ok: false, kind: "shape" };
 }
 async function decideIdempotentReplay(cs, args) {
-    const { sessionId, out, binding, decision, payload, deciderPrincipal, explicitOperator, warn } = args;
+    const { sessionId, out, binding, decision, payload, decider, warn } = args;
     if (out.status !== 404 || out.body.errorCode !== "not_found.approval")
         return undefined;
     const boundCallId = binding.boundCallId;
@@ -238,12 +241,9 @@ async function decideIdempotentReplay(cs, args) {
     for (const row of rows) {
         if (row.decision === null)
             return undefined;
-        if (!explicitOperator) {
-            const owner = decodeCheckpointScope(row.scope);
-            if (owner !== undefined && owner !== deciderPrincipal) {
-                warn("decide_replay_scope_mismatch", { sessionId });
-                return undefined;
-            }
+        if (!keyAdmits("scope.decide", decider, scopeCellOf(row.scope))) {
+            warn("decide_replay_scope_mismatch", { sessionId });
+            return undefined;
         }
         if (binding.boundInputHash === undefined || row.boundInputHash !== binding.boundInputHash)
             return undefined;
@@ -279,9 +279,9 @@ async function decideIdempotentReplay(cs, args) {
         },
     };
 }
-async function gateObjectivePreview(reader, runStore, agentStore, gate) {
-    const previewOf = async (taskId) => readOwnedRun(reader.config, runStore, reader.principal, taskId, "owner_or_operator");
-    const own = (await runStore.getActiveTaskId(gate.sessionId)) ?? (await runStore.latestRunForSession(gate.sessionId))?.taskId;
+async function gateObjectivePreview(reader, runStore, agentStore, gate, runSessionId) {
+    const previewOf = (taskId) => readVisibleRun(reader, runStore, taskId);
+    const own = typeof runSessionId === "string" ? ((await runStore.getActiveTaskId(runSessionId)) ?? (await runStore.latestRunForSession(runSessionId))?.taskId) : undefined;
     if (own !== undefined)
         return (await previewOf(own))?.objectivePreview ?? null;
     if (agentStore === undefined)
@@ -311,8 +311,8 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
             return;
         }
         const cs = park.checkpointStore;
-        const principal = gatedPrincipal(req, deps.config);
-        const operator = explicitOperatorOk(principal, deps.config);
+        const principal = gatedSubject(req, deps.config);
+        const operator = explicitOperatorOk(principal === undefined ? undefined : personOf(principal), deps.config);
         const ownScope = principal ?? CHECKPOINT_PUBLIC_SCOPE;
         if (match.decl.id === "approvals-stream") {
             const ownerParam = operator ? (new URLSearchParams(match.search).get("owner") ?? undefined) : undefined;
@@ -354,16 +354,15 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     sendError(res, 400, "request.path_malformed", "malformed id (invalid percent-encoding)");
                     return;
                 }
-                if (!explicitOperatorOk(principal, deps.config)) {
+                const exEntry = callerEntry(req, deps, match.decl.id);
+                if (!exEntry.caller.operator) {
                     const owned = facts.sessionOwnership(deps);
                     if (!owned.available) {
                         sendError(res, 501, "capability.session_store_required", "approval exemptions require a session-store backend");
                         return;
                     }
-                    if ((await readOwnedSession(deps, owned.sessionStorage, sessionCallerOf(req, deps), exSessionId, "owner")) === undefined) {
-                        sendError(res, 404, "not_found.session", "not found");
+                    if ((await admitSessionById(exEntry, res, owned.sessionStorage, exSessionId)) === undefined)
                         return;
-                    }
                 }
                 if (match.decl.id === "approval-exemptions-list") {
                     if (exToolName !== undefined) {
@@ -398,11 +397,12 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
             }
             const ledger = facts.durableRuns(deps);
             const agentStore = deps.backgroundAgentStore;
+            const previewEntry = protocolEntry(req, deps, "run.preview", callerOf(req, deps));
             const inbox = (await Promise.all(summaries.map(async (s) => {
                 let objective = null;
                 if (ledger.available) {
                     try {
-                        objective = await gateObjectivePreview({ config: deps.config, principal }, ledger.runStore, agentStore, s);
+                        objective = await gateObjectivePreview(previewEntry, ledger.runStore, agentStore, s, await cs.hostSessionOfCard(s.token));
                     }
                     catch (err) {
                         recordFailOpen("server.assistant-inbox.objective-preview-unreadable", `run row read for the inbox row of session ${JSON.stringify(s.sessionId)} failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -428,11 +428,12 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     ...(s.boundGrantDigest !== undefined ? { boundGrantDigest: s.boundGrantDigest } : {}),
                     ...skillCardFacts(s),
                     ...(s.boundGrantAbsence !== undefined ? { boundGrantAbsence: s.boundGrantAbsence } : {}),
+                    ...(s.runOrigin !== undefined ? { runOrigin: s.runOrigin } : {}),
                     objective,
                     input,
                 };
             })))
-                .sort((a, b) => (b.severity ?? 0) - (a.severity ?? 0) || (a.createdAt ?? 0) - (b.createdAt ?? 0));
+                .sort(pendingTriageOrder);
             sendJson(res, 200, { inbox });
             return;
         }
@@ -453,7 +454,13 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 sendApprovalsReadFailure(req, res, deps.logger, err);
                 return;
             }
-            const byGate = new Map(summaries.map((s) => [s.sessionId, s]));
+            const hosts = await Promise.all(summaries.map((s) => cs.hostSessionOfCard(s.token)));
+            const byGate = new Map();
+            summaries.forEach((s, i) => {
+                const host = hosts[i];
+                if (typeof host === "string")
+                    byGate.set(host, s);
+            });
             const runs = await runStore.listRuns({ owner: ownerOfCheckpointScope(scope), limit: 100 });
             const tasks = runs
                 .filter((r) => r.status === "running" || isParkedRunStatus(r.status))
@@ -482,20 +489,18 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 return;
             }
             const runStore = runs.runStore;
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const preemptEntry = enter(req, res, deps, match.decl.id);
+            if (preemptEntry === undefined)
                 return;
-            }
             if (!deps.config.resourceSuspend) {
                 sendError(res, 501, "feature.preemption_disabled", "preemption not enabled on this worker (needs RESOURCE_SUSPEND=true + a durable checkpoint store)");
                 return;
             }
             const taskId = match.params.taskId;
-            const run = await readOwnedRun(deps.config, runStore, principal, taskId, "owner_or_operator");
-            if (!run) {
-                sendError(res, 404, "not_found.run", "task not found");
+            const preemptAdmitted = (await admitRunById(preemptEntry, res, runStore, taskId));
+            if (preemptAdmitted === undefined)
                 return;
-            }
+            const run = preemptAdmitted.row;
             if (run.status === "running") {
                 const ownedHere = run.instanceId != null && run.instanceId === deps.instanceId;
                 if (ownedHere && !preemptableRuns.has(taskId)) {
@@ -541,23 +546,17 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 return;
             }
             const runStore = runs.runStore;
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const resumeEntry = enter(req, res, deps, match.decl.id);
+            if (resumeEntry === undefined)
                 return;
-            }
             const restatement = readResumeRestatement(await readJson(req));
             const taskId = match.params.taskId;
-            const run = await runStore.getRun(taskId);
-            if (!run) {
-                sendError(res, 404, "not_found.run", "task not found");
-                return;
-            }
-            const explicitOperator = explicitOperatorOk(principal, deps.config);
-            if (!explicitOperator && run.owner !== null && run.owner !== principal) {
-                sendError(res, 404, "not_found.run", "task not found");
+            const resumeAdmitted = (await admitRunById(resumeEntry, res, runStore, taskId));
+            if (resumeAdmitted === undefined)
                 return;
-            }
-            const out = await resumePreempted(run.sessionId, req, true, { principal, explicitOperator }, restatement);
+            const run = resumeAdmitted.row;
+            const explicitOperator = resumeAdmitted.quals.has("operator");
+            const out = await resumePreempted(run.sessionId, req, true, { subject: resumeEntry.caller.subject, operator: explicitOperator }, restatement);
             sendResumeOutcome(res, out, deps.logger);
             return;
         }
@@ -660,17 +659,15 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 }
             }
             const sighting = typeof body.checkpointId === "string" ? { face: "checkpointId", value: body.checkpointId } : undefined;
+            const decisionEntry = callerEntry(req, deps, match.decl.id);
             const run = await runStore.getRun(taskId);
             if (!run) {
-                if (deps.config.directDoorActive) {
-                    sendError(res, 401, "principal_unverified", "principal proof required");
-                    return;
-                }
-                deps.logger?.info?.("decide_404", { reason: "no-row", taskId, principalPresent: principal !== undefined });
-                sendError(res, 404, "not_found.run", "task not found");
+                if (!deps.config.directDoorActive)
+                    deps.logger?.info?.("decide_404", { reason: "no-row", taskId, principalPresent: principal !== undefined });
+                refuse(decisionEntry, res, "missing");
                 return;
             }
-            let deciderPrincipal = principal;
+            let deciderPrincipal = principal === undefined ? undefined : personOf(principal);
             let singleUse;
             if (deps.config.directDoorActive) {
                 const store = deps.approvalNonceStore;
@@ -695,13 +692,15 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 deciderPrincipal = proof.principal;
                 singleUse = proof.singleUse === undefined ? undefined : { proof: proof.singleUse, store };
             }
-            const explicitOperator = explicitOperatorOk(deciderPrincipal, deps.config);
-            if (!explicitOperator && run.owner !== null && run.owner !== deciderPrincipal) {
+            const deciderEntry = withCaller(decisionEntry, callerOfDecision(decisionEntry.caller, deciderPrincipal, deps.config));
+            const decisionAdmitted = judgeRun(deciderEntry, run);
+            if (decisionAdmitted === undefined) {
                 deps.logger?.info?.("decide_404", { reason: "owner-mismatch", taskId, principalPresent: principal !== undefined });
-                sendError(res, 404, "not_found.run", "task not found");
+                refuse(deciderEntry, res, "not_visible");
                 return;
             }
-            const plan = await preparePlanReview(run.sessionId, { taskId, principalPresent: principal !== undefined }, { principal: deciderPrincipal, explicitOperator }, sighting);
+            const explicitOperator = decisionAdmitted.quals.has("operator");
+            const plan = await preparePlanReview(run.sessionId, { taskId, principalPresent: principal !== undefined }, { subject: deciderSubjectOf(principal, deciderPrincipal), operator: explicitOperator }, sighting, restated.restatement);
             if (!plan.ok) {
                 sendResumeOutcome(res, plan.answer, deps.logger);
                 return;
@@ -725,7 +724,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     return;
                 }
             }
-            const out = await drivePlanReview(plan.prepared, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, hostDecisionFacts(decidedByReading.decider, deciderPrincipal), req, true, isPlanApprovePermissionModeAfter(body.permissionModeAfter) ? body.permissionModeAfter : undefined, restated.restatement);
+            const out = await drivePlanReview(plan.prepared, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, hostDecisionFacts(decidedByReading.decider, deciderPrincipal), req, true, isPlanApprovePermissionModeAfter(body.permissionModeAfter) ? body.permissionModeAfter : undefined);
             sendResumeOutcome(res, out, deps.logger);
             return;
         }
@@ -862,7 +861,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 updatedInput: body.updatedInput,
                 ...(typeof body.feedback === "string" ? { feedback: body.feedback } : {}),
             };
-            let deciderPrincipal = principal;
+            let deciderPrincipal = principal === undefined ? undefined : personOf(principal);
             if (deps.config.directDoorActive) {
                 const hdr = (n) => {
                     const h = req.headers[n];
@@ -881,39 +880,17 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 }
                 deciderPrincipal = proof.principal;
             }
-            const explicitOperator = explicitOperatorOk(deciderPrincipal, deps.config);
-            if (!explicitOperator) {
+            const deciderCaller = { subject: deciderSubjectOf(principal, deciderPrincipal), operator: explicitOperatorOk(deciderPrincipal, deps.config) };
+            if (!deciderCaller.operator) {
                 const cpScope = await cs
                     .peekPendingScope(sessionId, { gateKinds: APPROVAL_GATE_KINDS })
                     .then((s) => (s === undefined ? cs.peekPendingScope(sessionId) : s));
-                const decodedCpScope = cpScope != null ? decodeCheckpointScope(cpScope) : undefined;
-                const ownsIt = cpScope == null || decodedCpScope === undefined || decodedCpScope === deciderPrincipal;
-                if (!ownsIt) {
+                if (!keyAdmits("scope.decide", deciderCaller, scopeCellOf(cpScope ?? CHECKPOINT_PUBLIC_SCOPE))) {
                     sendError(res, 404, "not_found.approval", "approval not found");
                     return;
                 }
             }
-            let rememberApplied = false;
-            let pendingGrant;
-            const grantOnCommit = remember && deps.approvalExemptionStore
-                ? async (grant) => {
-                    const canonical = grant.rememberableToolName;
-                    if (!canonical)
-                        return;
-                    pendingGrant = { sessionId: grant.overrideSessionId ?? sessionId, toolName: canonical };
-                }
-                : undefined;
-            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, hostDecisionFacts(decider, deciderPrincipal), req, answer, binding, grantOnCommit, true, { principal: deciderPrincipal, explicitOperator }, restated.restatement);
-            if (pendingGrant !== undefined && decisionCommittedOf(out) && deps.approvalExemptionStore) {
-                try {
-                    await deps.approvalExemptionStore.grant(pendingGrant.sessionId, pendingGrant.toolName, deciderPrincipal ?? null);
-                    rememberApplied = true;
-                    deps.logger?.info?.("approval_exemption_granted", { sessionId: pendingGrant.sessionId, toolName: pendingGrant.toolName, grantedBy: deciderPrincipal ?? null });
-                }
-                catch (e) {
-                    deps.logger?.warn?.("approval_exemption_grant_failed", { sessionId: pendingGrant.sessionId, toolName: pendingGrant.toolName, error: String(e).slice(0, 200) });
-                }
-            }
+            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, hostDecisionFacts(decider, deciderPrincipal), req, answer, binding, remember ? { grantedBy: deciderPrincipal ?? null, laneCannotRecord: "refuse" } : undefined, true, deciderCaller, restated.restatement);
             const replay = await decideIdempotentReplay(cs, {
                 sessionId,
                 out,
@@ -925,15 +902,14 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     ...((r) => (r !== undefined ? { reason: r } : {}))(decisionReasonOf(body)),
                     ...(binding.feedback !== undefined ? { feedback: binding.feedback } : {}),
                 },
-                deciderPrincipal,
-                explicitOperator,
+                decider: deciderCaller,
                 warn: (event, fields) => deps.logger?.warn?.(event, fields),
             });
             if (replay !== undefined) {
                 sendResumeOutcome(res, replay, deps.logger);
                 return;
             }
-            sendResumeOutcome(res, out, deps.logger, remember && deps.approvalExemptionStore ? { rememberApplied } : undefined);
+            sendResumeOutcome(res, out, deps.logger, remember ? { rememberApplied: out.rememberApplied === true } : undefined);
             return;
         }
     }
@@ -1003,6 +979,8 @@ function approvalsReadFailureOf(err) {
         case "deployment":
         case "unclassified":
             return "approvals.read_unavailable";
+        case "defect":
+            return "internal.error";
         default: {
             const unhandled = fault;
             throw new Error(`store fault class without an approvals read answer: ${String(unhandled)}`);
@@ -1010,15 +988,18 @@ function approvalsReadFailureOf(err) {
     }
 }
 function sendApprovalsReadFailure(req, res, logger, err) {
-    logRequestError(logger, req, err);
     const failure = approvalsReadFailureOf(err);
     switch (failure) {
         case "approvals.read_corrupt":
+            logRequestError(logger, req, err);
             sendError(res, 500, "approvals.read_corrupt", "a stored approval row cannot be read - retrying this request will fail the same way until an operator repairs or removes the row");
             return;
         case "approvals.read_unavailable":
+            logRequestError(logger, req, err);
             sendError(res, 503, "approvals.read_unavailable", "the approvals queue could not be read right now - retry this request; until a read succeeds, this answer does not mean nothing is pending");
             return;
+        case "internal.error":
+            throw err;
         default: {
             const unhandled = failure;
             throw new Error(`approvals read failure word without an answer: ${String(unhandled)}`);
@@ -1156,6 +1137,10 @@ export async function streamApprovals(req, res, cs, live, peerInbound, sessions,
                     if (!res.writableEnded)
                         res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "approvals.read_unavailable", message: "the approvals queue could not be read - this stream stays open and retries on its next poll; until a read succeeds, silence here does not mean nothing is pending" })}\n\n`);
                     break;
+                case "internal.error":
+                    if (!res.writableEnded)
+                        res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "internal.error", message: "the approvals queue could not be read because of an internal error - this stream is closing; reconnecting will fail the same way until the server is fixed" })}\n\n`);
+                    throw err;
                 default: {
                     const unhandled = failure;
                     throw new Error(`approvals read failure word without a stream answer: ${String(unhandled)}`);

package/dist/http/routes/attachments.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { uuidv7, sanitizePathComponent } from "@sema-agent/core";
 import { HttpError } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedSubject, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import { attachmentKindOf, readProjectBundle } from "../../project-bundle.js";
 export async function handleAttachments(req, res, match, ctx) {
@@ -17,7 +17,7 @@ export async function handleAttachments(req, res, match, ctx) {
                 sendError(res, 501, "capability.attachment_store_required", "attachment store not configured");
                 return;
             }
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedSubject(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

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

@@ -31,7 +31,7 @@
  * ── 结清口:子代结清只有一只协调器 ─────────────────────────────────────────────────────────────────
  * `POST /v1/sessions/:id/children/retire`(无体)→ 200 `{ children: string[] }`:**显式**结清以本会话为根的后台子代(running 停掉、parked
  * 作废卡并对账翻终态),与 `DELETE /v1/sessions/:id` 同调**一只**预检 `probeSessionChildren` 与**一只**协调器 `retireSessionChildren`
- * (`session-children-retire.ts`)、同一个 scope(`sessionChildrenScope`)。预检有本副本结束不了的 ⇒ 409 `conflict.session_children_alive{remaining}`
+ * (`session-children-retire.ts`)、同一个 scope(`sessionTenantScope`)。预检有本副本结束不了的 ⇒ 409 `conflict.session_children_alive{remaining}`
  * (与删除门同码同投影,一只都不动);停不净(时序失败)⇒ 与删除门同一失败契约(通用 500,重试收敛)。`children` = 首轮观察到、且已全部
  * 结清的子代,每项经名册的 id 投影 `rosterAgentId`(与换绑 / 导入两门 409 体的 `children` 同形同投影)。它不判根认领(停止口也不判):
  * 根 run 活着时它可再派子代 —— 由换绑 / 导入门写事务内的认领读兜。鉴权 / 限流 / 无凭据写门与停止口同。
@@ -39,7 +39,7 @@
  * 「把树结清」是两个意图、两只口。
  *
  * 🔴 **停止口在无凭据写门内**(`credentialGated: ["POST"]`;车OL F1 = 7.102.0 合并复审 gpt-6 腿 [high]):门的两个合取项它都中
- *   —— ① 授权的唯一输入是 principal 头(属主判 `sessionOwnerOk` 与 operator 臂 `explicitOperatorOk` 读的都是 `gatedPrincipal`,
+ *   —— ① 授权的唯一输入是 principal 头(属主判 `admitSessionRow` 与 operator 臂 `explicitOperatorOk` 读的都是 `gatedSubject`,
  *   无 service 凭证的部署上它收调用方自报的头);② 不可撤销、爆炸半径跨租户(知道会话 id + 自报它的属主 ⇒ 停掉那个会话的后台
  *   进程,`includeRetained:true` 连显式 retain 的活服务一起停)。于是无 service 凭证且未开 `ALLOW_UNAUTHED_WRITES` 的部署上它与
  *   其余改写门同码同句 503 `auth.service_token_required`(在路由之前,`dispatch.ts` 那一道),同一只会话级收敛函数的另一个调用点
@@ -49,7 +49,7 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type TaskRegistry, type BackgroundShellHardKillReceipt } from "@sema-agent/core";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** `description` 的显示截断(模型描述通常一句话;回落的命令文本可能是一整段脚本)。 */
 export declare const DESCRIPTION_MAX = 500;
 /** core `list()` 的行型(从唯一的消费位取,不抄结构)。 */

package/dist/http/routes/background.js

@@ -1,15 +1,13 @@
 import { z } from "zod";
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { reapSessionBackgroundHard } from "../../background-session-reap.js";
-import { probeSessionChildren, retireSessionChildren, sessionChildrenScope, SessionChildrenStopIncompleteError } from "../../session-children-retire.js";
+import { probeSessionChildren, retireSessionChildren, sessionTenantScope, SessionChildrenStopIncompleteError } from "../../session-children-retire.js";
 import { rosterAgentId } from "./agents-roster.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
-import {} from "../route-ctx.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { admitSessionById, enter } from "../owner-access.js";
+import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
-import { sessionOwnerCellOf } from "../../security.js";
 const LIST_LIMIT = 500;
 export const DESCRIPTION_MAX = 500;
 const ROW_KEY_DISPOSITION = {
@@ -50,11 +48,9 @@ export async function handleBackground(req, res, match, ctx) {
     const id = match.decl.id;
     if ((id === "session-background-stop" || id === "session-children-retire") && ctx.helpers.rateLimited(req, res))
         return;
-    const principal = gatedPrincipal(req, deps.config);
-    if (deps.config.requirePrincipal && principal === undefined) {
-        sendPrincipalRefusal(res, req, deps.config);
+    const entry = enter(req, res, deps, id);
+    if (entry === undefined)
         return;
-    }
     let includeRetained = false;
     if (id === "session-background-stop") {
         const parsed = StopBodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
@@ -74,15 +70,11 @@ export async function handleBackground(req, res, match, ctx) {
         sendError(res, 501, "capability.session_ownership_required", "the session background faces require the session-ownership face (sessionStorage.headOf)");
         return;
     }
-    const owner = (await owned.sessionStorage.headOf(sessionId))?.owner;
-    if (owner === undefined) {
-        sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-        return;
-    }
-    const operator = explicitOperatorOk(principal, deps.config);
-    if (!operator && !ctx.helpers.sessionOwnerOk(req, res, await sessionOwnerCellOf(owned.sessionStorage, sessionId, owner)))
+    const admitted = await admitSessionById(entry, res, owned.sessionStorage, sessionId);
+    if (admitted === undefined)
         return;
-    const scope = sessionChildrenScope(owner);
+    const owner = admitted.row.owner;
+    const scope = sessionTenantScope(owner);
     switch (id) {
         case "session-background-list": {
             const rows = defaultTaskRegistry.list({ owner: sessionId, sessionId, scope }, { limit: LIST_LIMIT }).map(projectRow);

package/dist/http/routes/capabilities.js

@@ -2,10 +2,10 @@ import { PERMISSION_MODES, USER_ATTACHMENT_SEAT, expandTiers, reasoningEffortLev
 import { modelImageInput, modelReasoningDecl, isAtMentionable, selectableAliasNames, selectableCatalog } from "../../model-select.js";
 import { buildDroppedEntriesWire } from "../../web-admin-client/read-warnings.js";
 import { buildCandidateRejectedWire } from "../../web-admin-client/candidate-gate.js";
-import { buildModelPlaneFace } from "../../model-plane-face.js";
-import { isRosterGateArmed } from "../../config.js";
+import { readModelPlaneFace } from "../../model-plane-face.js";
 import { modelKeyPoisonOf, resolveModelApiKey } from "../../key-resolver.js";
 import { projectSealedKeyCapability } from "../../sealed-key.js";
+import { SESSION_READ_REDACTED_LEAVES } from "../../audit.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../../deployment-shape.js";
 import { taskWriteFaceRefusal } from "../../hosted-posture.js";
 import { leaderEntryRefusal, leaderRunEntry } from "../../leader/run-entry.js";
@@ -22,9 +22,10 @@ import { assertNever } from "../route-ctx.js";
 import { fileHistoryCaptureOf } from "../../file-history-capture.js";
 import { projectMemoryEngineCapability } from "../../memory-posture.js";
 import { projectWriteProtectionCapability } from "../../write-protection.js";
-import { projectStoreCapability } from "../../store-posture.js";
+import { projectStoreCapability, unwiredStorePosture } from "../../store-posture.js";
 import { projectWebSearchCapability } from "../../plugins/web-search.js";
 import { projectExecutionLaneCapability } from "../../capabilities/execution-lane.js";
+import { SETTINGS_CONTRACT_CAPABILITY } from "../../capabilities/settings-contract.js";
 import { judgeSandboxGitPlane, sandboxGitPlanePremisesOf } from "../../sandbox-git-plane.js";
 import { MCP_ASSERTION_HEADER_SENT, MCP_REQUEST_TRANSPORT_KINDS } from "../../mcp-assertion-header.js";
 import { gateCompositeMembers } from "../../capabilities/composite-members.js";
@@ -34,7 +35,7 @@ import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import * as facts from "../../capability-facts.js";
 import { judgeAutoModeArming } from "../../auto-mode-face.js";
 import { coercePermissionModeStrict, PERMISSION_MODE_WORDS, taskHooksHonored } from "../../task-settings.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, sendPrincipalRefusal } from "../principal-gate.js";
 import { readAdoptionImportCapability } from "../../adoption/import.js";
 import { headReadOf } from "../../session-incarnation.js";
 import { callerTrust } from "../caller-trust.js";
@@ -78,10 +79,10 @@ export async function handleCapabilities(req, res, match, ctx) {
                 return;
             }
             const entitlementSource = centerEntitlementSourceWired(deps.config);
-            const { fault: autoModeFault, ...autoMode } = await judgeAutoModeArming(deps.autoModeFace, { requestedMode, floor: autonomyModeFloor(deps.config.autonomy), principal: gatedPrincipal(req, deps.config), localDeny: deps.config.permissionsDisableAutoMode });
+            const { fault: autoModeFault, ...autoMode } = await judgeAutoModeArming(deps.autoModeFace, { requestedMode, floor: autonomyModeFloor(deps.config.autonomy), principal: gatedPerson(req, deps.config), localDeny: deps.config.permissionsDisableAutoMode });
             if (autoModeFault !== undefined)
                 deps.logger?.warn("auto_mode_face_resolver_fault", { fault: autoModeFault });
-            const rulesLaneForCaller = facts.ruleLaneForCaller(deps, gatedPrincipal(req, deps.config)).available;
+            const rulesLaneForCaller = facts.ruleLaneForCaller(deps, gatedPerson(req, deps.config)).available;
             const streamApprovalFact = facts.streamApproval(deps);
             sendJson(res, 200, gateCompositeMembers({
                 ...deps.capabilities,
@@ -96,10 +97,10 @@ export async function handleCapabilities(req, res, match, ctx) {
                     ? {
                         enabled: true,
                         protocolVersion: DEVICE_PROTOCOL_VERSION,
-                        maxInflightPerDevice: deps.config.remoteExec?.provider === "device" ? (deps.config.remoteExec.maxInflightPerDevice ?? 4) : 4,
+                        maxInflightPerDevice: deps.config.remoteExec.provider === "device" ? (deps.config.remoteExec.maxInflightPerDevice ?? 4) : 4,
                         wsPath: DEVICE_WS_PATH,
                         management: facts.deviceManagement(deps).available,
-                        ...(deps.config.remoteExec?.provider === "device" && deps.config.remoteExec.relay.kind === "url" ? { relayUrl: deps.config.remoteExec.relay.url } : {}),
+                        ...(deps.config.remoteExec.provider === "device" && deps.config.remoteExec.relay.kind === "url" ? { relayUrl: deps.config.remoteExec.relay.url } : {}),
                     }
                     : false,
                 sessionEvents: facts.sessionEventStream(deps).available,
@@ -112,8 +113,8 @@ export async function handleCapabilities(req, res, match, ctx) {
                 memory: false,
                 memoryWrite: false,
                 memoryEngine: projectMemoryEngineCapability(deps.memoryPosture),
-                store: projectStoreCapability(deps.storePosture ?? { declared: deps.config.dbBackend, backend: "memory" }, deps.sqlEngine?.facts),
-                centerWiring: deps.centerWiring?.(gatedPrincipal(req, deps.config)),
+                store: projectStoreCapability(deps.storePosture ?? unwiredStorePosture(deps.config.dbBackend), deps.sqlEngine?.facts),
+                centerWiring: deps.centerWiring?.(gatedPerson(req, deps.config)),
                 webSearch: projectWebSearchCapability(deps.webSearchProvider),
                 sessionBackgroundable: facts.durableRuns(deps).available,
                 runMemoryCaptureOptOut: facts.durableRuns(deps).available,
@@ -122,7 +123,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 sharedMemory: facts.sharedMemoryRead(deps).available,
                 principalInboxDelivery: facts.principalInboxDelivery(deps).available,
                 adoption: facts.adoption(deps).available,
-                adoptionImport: await readAdoptionImportCapability(facts.adoptionSessionImport(deps), gatedPrincipal(req, deps.config), deps.config),
+                adoptionImport: await readAdoptionImportCapability(facts.adoptionSessionImport(deps), gatedPerson(req, deps.config), deps.config),
                 memoryBundle: facts.memoryBundle(deps).available,
                 memoryCompliance: facts.memoryCompliance(deps).available,
                 memoryOrigin: facts.memoryOrigin(deps).available,
@@ -151,6 +152,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 subagentResume: facts.subagentSteer(deps).available,
                 taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: DEPLOYMENT_SHAPE_PREDICATES.callerCwd.holds(deps.config), hooks: taskHooksHonored(deps.config), pluginHooks: taskHooksHonored(deps.config), managedHookGroups: taskHooksHonored(deps.config), httpHookAllowlists: taskHooksHonored(deps.config), tightenOnlySeats: true, approvalFrameFamilies: true, autoCompactEnabled: true },
                 settings: { permissions: { allowGrant: true, allowLayer: true, layers: true, layeredAllow: true, callerTrust: callerTrust(req, deps.config).trust } },
+                settingsContract: SETTINGS_CONTRACT_CAPABILITY,
                 permissionModeAuto: {
                     accepted: true,
                     classifierSeat: deps.autoModeFace?.seatMounted === true,
@@ -201,11 +203,13 @@ export async function handleCapabilities(req, res, match, ctx) {
                 approvalDecidedVia: true,
                 planReviewCheckpointId: true,
                 permissionModes: [...PERMISSION_MODES],
-                sessionReadRedaction: true,
+                sessionReadRedaction: [...SESSION_READ_REDACTED_LEAVES],
                 sideQuery: true,
                 agentRoster: facts.agentRoster(deps).available,
+                projects: facts.projectRegistry(deps).available,
                 retention: retentionAdvertisement(deps.config),
                 peerLane: Boolean(deps.peerDirectory),
+                scenarioSubject: true,
                 sessionList: facts.sessionList(deps).available,
                 sessionSearch: facts.sessionList(deps).available,
                 sessionFork: facts.sessionFork(deps).available,
@@ -214,9 +218,10 @@ export async function handleCapabilities(req, res, match, ctx) {
                 promptSuggestions: true,
                 sessionPolicy: facts.sessionPolicy(deps).available,
                 sessionRulesNamespaceForms: sessionRulesNamespaceFormsHonored(),
-                rewindFiles: Boolean(deps.fileHistoryStore),
                 restoreFiles: Boolean(deps.fileHistoryStore),
                 rewindFilesTo: Boolean(deps.fileHistoryStore && deps.resumeAnchorStore && headReadOf(deps.sessionStorage)),
+                sessionRewindFiles: facts.sessionRewindFiles(deps).available,
+                sessionRewindFilesPreview: facts.sessionRewindFilesPreview(deps).available,
                 fileHistoryCapture: fileHistoryCaptureOf(deps.fileHistoryStore, deps.config.fileHistoryCapture),
                 scheduler: facts.hostScheduler(deps.config).available,
                 sessionSync: facts.sessionSync(deps).available,
@@ -249,7 +254,7 @@ export async function handleCapabilities(req, res, match, ctx) {
             return;
         }
         case "capability-mcp": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -264,7 +269,7 @@ export async function handleCapabilities(req, res, match, ctx) {
             return;
         }
         case "capability-mcp-probe": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -298,6 +303,8 @@ export async function handleCapabilities(req, res, match, ctx) {
                 ...(m.maxTokens ? { maxOutputTokens: m.maxTokens } : {}),
                 ...((levels) => (levels !== undefined ? { supportedEffortLevels: [...levels] } : {}))(reasoningEffortLevelsOf(m)),
                 ...(m.compat !== undefined ? { compat: m.compat } : {}),
+                ...(m.thinkingLevelMap !== undefined ? { thinkingLevelMap: m.thinkingLevelMap } : {}),
+                ...(m.defaultThinking !== undefined ? { defaultThinking: m.defaultThinking } : {}),
                 ...mentionBit(name),
                 routePairing: routePairingOf(deps, name, m),
             }));
@@ -310,11 +317,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 defaultModel: { id: deps.config.model.id, ...(defaultName ? { name: defaultName } : {}) },
                 droppedEntries: buildDroppedEntriesWire(deps.config.droppedCatalogEntries),
                 ...(candidateRejection !== undefined ? { candidateRejected: buildCandidateRejectedWire(candidateRejection) } : {}),
-                modelPlane: buildModelPlaneFace(deps.config, {
-                    envTableIsPlaceholder: isRosterGateArmed(deps.config.webAdmin),
-                    candidateRejection,
-                    latestPlaneRefusal: deps.latestPlaneRefusalState?.(),
-                }),
+                modelPlane: readModelPlaneFace(deps.config, deps),
                 aliases: selectableAliasNames(deps.config.models, atCatalog, deps.config.modelRefusals).map((name) => ({ name, ...mentionBit(name) })),
             });
             return;