@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/routes/adoption.js

@@ -4,7 +4,7 @@ import { checkAdoptionPrincipalShape, checkAdoptionWidths } from "../../adoption
 import { judgeAdoptionImportBinding, readAdoptionImportBody, runAdoptionImport } from "../../adoption/import.js";
 import { limitRefusal } from "../../limit-refusal.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 function sendOutcome(res, out) {
@@ -19,19 +19,23 @@ function sendOutcome(res, out) {
                 boundTo: out.boundTo,
             });
             return;
+        case "tables_missing":
+            sendError(res, 409, "adoption.table_missing", `this deployment wires stores whose tables are absent from the database (${out.tables.join(", ")}): nothing was migrated — restart a replica so its boot creates the missing tables, then resend the same request`, {
+                adoptionId: out.adoptionId,
+                tables: out.tables,
+            });
+            return;
         case "rejected":
             switch (out.code) {
                 case "adoption.destination_conflict":
-                    sendError(res, 409, "adoption.destination_conflict", "the destination principal already holds rows sharing a logical key with the source", {
+                    sendError(res, 409, "adoption.destination_conflict", `the destination principal already holds rows sharing a logical key with the source: ${out.detail}`, {
                         adoptionId: out.adoptionId,
-                        detail: out.detail,
                         conflicts: out.conflicts,
                     });
                     return;
                 case "adoption.destination_unrepresentable":
-                    sendError(res, 409, "adoption.destination_unrepresentable", "the destination principal does not fit every key this adoption would derive from it", {
+                    sendError(res, 409, "adoption.destination_unrepresentable", `the destination principal does not fit every key this adoption would derive from it: ${out.detail}`, {
                         adoptionId: out.adoptionId,
-                        detail: out.detail,
                     });
                     return;
             }
@@ -58,7 +62,7 @@ export async function handleAdoption(req, res, match, ctx) {
 async function operatorLane(req, res, id, params, ctx) {
     const { deps } = ctx;
     const { readJson } = ctx.helpers;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -85,7 +89,8 @@ async function operatorLane(req, res, id, params, ctx) {
         }
     }
     const store = fact.backend.adoptionLog();
-    const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "mysql", now: Date.now, logger: deps.logger });
+    const wiring = { memoryEngine: facts.memoryExport(deps).available, taskAttachment: deps.taskAttachmentStore !== undefined };
+    const runner = createAdoptionRunner({ store, dialect: deps.backend?.kind === "pg" ? "pg" : "mysql", now: Date.now, wiring, logger: deps.logger });
     switch (id) {
         case "adoption-detail": {
             const adoptionId = ctx.helpers.safeDecode(params.id);
@@ -111,12 +116,12 @@ async function operatorLane(req, res, id, params, ctx) {
             const { fromPrincipal, toPrincipal } = parsed.data;
             const badShape = checkAdoptionPrincipalShape(fromPrincipal, toPrincipal);
             if (badShape !== undefined) {
-                sendError(res, 400, "request.field_invalid", "the adoption principals are not in a portable identity shape", { detail: badShape });
+                sendError(res, 400, "request.field_invalid", `the adoption principals are not in a portable identity shape: ${badShape}`);
                 return;
             }
             const tooWide = checkAdoptionWidths(fromPrincipal, toPrincipal);
             if (tooWide !== undefined) {
-                sendError(res, 400, "request.field_invalid", "the adoption principals do not fit every identity column and derived key this adoption must write", { detail: tooWide });
+                sendError(res, 400, "request.field_invalid", `the adoption principals do not fit every identity column and derived key this adoption must write: ${tooWide}`);
                 return;
             }
             if (fromPrincipal === toPrincipal) {
@@ -124,6 +129,8 @@ async function operatorLane(req, res, id, params, ctx) {
                 return;
             }
             const out = await runner.start(fromPrincipal, toPrincipal);
+            if (out.kind === "receipt")
+                await deps.toolApproval?.followRowOwners();
             sendOutcome(res, out);
             return;
         }
@@ -135,7 +142,7 @@ async function sourceLane(req, res, params, ctx) {
     const { deps } = ctx;
     if (ctx.helpers.rateLimited(req, res))
         return;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (principal === undefined) {
         sendPrincipalRefusal(res, req, deps.config);
         return;

package/dist/http/routes/agents-roster.js

@@ -1,6 +1,10 @@
 import { chosenAgentName } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
+import { gatedSubject, sendUnauthorized } from "../principal-gate.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
+import { partsOf } from "../../owner-brands.js";
+import { taskSpecIdentityOf } from "../../engine-identity.js";
+import { routeListFilter } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { backgroundAgentNameOf } from "../../background-agent-name.js";
@@ -63,7 +67,7 @@ export async function handleAgentRoster(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "agents-roster": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -84,7 +88,7 @@ export async function handleAgentRoster(req, res, match, ctx) {
             const beforeRaw = q.get("before");
             const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
             if (decoded !== undefined && !decoded.ok) {
-                sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+                sendError(res, 400, "request.query_invalid", `before must be the opaque \`nextBefore\` cursor from a previous page of this endpoint: ${decoded.why}`);
                 return;
             }
             const cursor = decoded?.ok === true ? decoded.cursor : undefined;
@@ -94,19 +98,21 @@ export async function handleAgentRoster(req, res, match, ctx) {
                 return;
             }
             const status = statusRaw === null ? undefined : statusRaw;
+            const subject = gatedSubject(req, deps.config);
+            const ownScope = taskSpecIdentityOf(subject === undefined ? undefined : partsOf(subject)).principal ?? "default";
             let scope;
             if (gateOwner !== null) {
-                scope = gateOwner;
+                scope = ownScope;
             }
             else {
                 const raw = q.get("scope");
                 if (raw === null) {
-                    scope = "default";
+                    scope = ownScope;
                 }
                 else {
                     const s = raw.trim();
-                    if (s === "" || s.length > 190) {
-                        sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters");
+                    if (s === "" || Buffer.byteLength(s, "utf8") > PRINCIPAL_MAX_BYTES) {
+                        sendError(res, 400, "request.query_invalid", `scope must be a non-blank tenant principal of at most ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the principal length every identity column holds)`);
                         return;
                     }
                     scope = s;

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";
@@ -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;
@@ -334,10 +334,11 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 return;
             }
             const pending = [...(await projectDurableQueue(durableRows, deps.config, deps.sessionStorage)), ...peerInboundRowsFor(defaultPeerInboundFace, principal, ownerParam)()];
+            const livePending = deps.toolApproval ? await deps.toolApproval.listLivePending(scope) : undefined;
             sendJson(res, 200, {
                 pending,
                 serverNowMs: Date.now(),
-                ...(deps.toolApproval ? { livePending: deps.toolApproval.listLivePending(scope) } : {}),
+                ...(livePending !== undefined ? { livePending } : {}),
                 ...(deps.approvalAskAudit ? { crashConverged: deps.approvalAskAudit.listCrashConverged(scope) } : {}),
             });
             return;
@@ -354,16 +355,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 +398,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 +429,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 +455,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 +490,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 +547,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 +660,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 +693,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, restated.restatement);
+            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;
@@ -862,7 +862,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,19 +881,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;
                 }
             }
-            const out = await resumeCheckpoint(sessionId, decision, body.reason ?? undefined, hostDecisionFacts(decider, deciderPrincipal), req, answer, binding, remember ? { grantedBy: deciderPrincipal ?? null, laneCannotRecord: "refuse" } : undefined, true, { principal: deciderPrincipal, explicitOperator }, restated.restatement);
+            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,
@@ -905,8 +903,7 @@ 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) {
@@ -983,6 +980,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)}`);
@@ -990,15 +989,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)}`);
@@ -1121,7 +1123,7 @@ export async function streamApprovals(req, res, cs, live, peerInbound, sessions,
         let snapshot;
         try {
             const pending = [...(await projectDurableQueue(await cs.listPending(scope), governance, sessions)), ...(peerInbound?.() ?? [])];
-            snapshot = { pending, livePending: live ? live.listLivePending(scope) : [] };
+            snapshot = { pending, livePending: live ? await live.listLivePending(scope) : [] };
         }
         catch (err) {
             const failure = approvalsReadFailureOf(err);
@@ -1136,6 +1138,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);