@sema-agent/server 7.146.0 → 7.148.0

package/dist/http/routes/sessions.js

@@ -1,31 +1,37 @@
 import { SessionError, materializeA2aTools, materializeMcpTools, sanitizePathComponent } from "@sema-agent/core";
 import { a2aForScenario, mcpForScenario } from "../../web-admin-client/facade.js";
-import { HttpError, isUuidShape, legacyUnownedSessionOk, sessionOwnerCellOf } from "../../security.js";
+import { HttpError, isUuidShape } from "../../security.js";
 import { windowMessages, truncateMessageBlobs, redactSessionViewForRead } from "../../audit.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { seatText } from "../../trace/exit-seat.js";
 import { recordFailOpen } from "../../observability/fail-open.js";
 import { MCP_DIAL_DEADLINE_MS, raceDeadline } from "../mcp-dial-deadline.js";
 import { sentMemoryComplianceFailure } from "../memory-compliance-failure-reply.js";
-import { readLayerSeat, sentMemoryLayerRefusal } from "../memory-layer-reply.js";
+import { readLayerSeat, sentMemoryFaceFault } from "../memory-face-fault-reply.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../../deployment-shape.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../../task-settings.js";
 import { readWritableSessionPermissionRules } from "../../session-policy-wire.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, sseHeaders, httpErrorBody } from "../send.js";
-import { fleetViewOf, gatedPrincipal, explicitOperatorOk, sessionCallerOf, sessionOwnerReadable, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
+import { gatedPerson, gatedSubject, sendPrincipalRefusal } from "../principal-gate.js";
+import { personOf } from "../../owner-brands.js";
 import { headReadOf, leafOfAdmittedHead, sessionFaceOfHead } from "../../session-incarnation.js";
-import { foldOwnerUnreadable, runRowReadableOnSessionFace } from "../owner-access.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { admitSessionById, admitSessionRow, admittedAsFleet, callerEntry, callerOf, deliverVerdict, enter, judgeSessionRow, protocolEntry, readOwnerCell, refuse, seesRun, sessionRowPresent } from "../owner-access.js";
+import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { rosterAgentId } from "./agents-roster.js";
 import { projectSessionListRow } from "./sessions-list.js";
 import { readSessionRowPatch } from "../../session-row.js";
-import { forkPathOf } from "../execution-context.js";
+import { forkPathOf, resolveExecutionContext } from "../execution-context.js";
 import { executionPlacementView } from "../../execution-placement.js";
+import { anchorReaderOf, resolveHistoryAnchor } from "../../history-anchor.js";
+import { engineRefusalAnswerOf } from "../engine-refusal.js";
+import { buildRewindFilesReply } from "../rewind-files-reply.js";
 import { ForkTargetUnsettledError, forkKeyOf } from "../../plugins/session-fork.js";
 import { fieldConflictFacts } from "../../field-conflict.js";
 import { buildBoundedToolNames } from "../../panel-tool-names.js";
 import { projectMcpAuthorization } from "../../mcp-authorization-face.js";
+import { presentHostWorkspaceOf } from "../../task-cwd.js";
+import { rewindFilesUnderPurpose } from "../../execution-env-purpose.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const A2A_STATUS_TTL_MS = 5_000;
 const A2A_MATERIALIZE_TIMEOUT_MS = 10_000;
@@ -40,11 +46,11 @@ export function createSessionsLocal() {
         memoryStatusCache: new Map(),
     };
 }
-async function lastLegMcpFor(deps, sessionId, caller) {
+async function lastLegMcpFor(deps, sessionId, entry) {
     let timer;
     try {
         return await Promise.race([
-            readLastLegMcp(deps, sessionId, caller),
+            readLastLegMcp(deps, sessionId, entry),
             new Promise((r) => { timer = setTimeout(() => { recordFailOpen("server.mcp-panel.last-leg-unreadable", `ledger read exceeded ${LAST_LEG_LEDGER_TIMEOUT_MS}ms`); r(undefined); }, LAST_LEG_LEDGER_TIMEOUT_MS); }),
         ]);
     }
@@ -57,14 +63,14 @@ async function lastLegMcpFor(deps, sessionId, caller) {
             clearTimeout(timer);
     }
 }
-async function readLastLegMcp(deps, sessionId, caller) {
+async function readLastLegMcp(deps, sessionId, entry) {
     const runStore = deps.runStore;
     if (!runStore || sessionId === null)
         return undefined;
     const latest = await runStore.latestRunForSession(sessionId);
     if (latest === undefined)
         return undefined;
-    if (!runRowReadableOnSessionFace(deps, caller, latest.owner, "owner_or_operator"))
+    if (!seesRun(entry, latest.owner))
         return undefined;
     const events = await runStore.getEvents(latest.taskId, 0);
     for (let i = events.length - 1; i >= 0; i--) {
@@ -80,16 +86,12 @@ async function readLastLegMcp(deps, sessionId, caller) {
 }
 export async function handleSessions(req, res, match, ctx) {
     const { deps } = ctx;
-    const { readJson, safeDecode, sessionOwnerOk } = ctx.helpers;
-    const readOwnedSessionView = async (sessionAudit, sessionId, readOpts) => {
+    const { readJson, safeDecode } = ctx.helpers;
+    const readOwnedSessionView = async (entry, sessionAudit, sessionId, readOpts) => {
         const headOf = headReadOf(deps.sessionStorage);
         if (headOf !== undefined) {
-            const owner = (await foldOwnerUnreadable(deps.logger, match.decl.id, sessionId, () => headOf(sessionId)))?.owner;
-            if (owner === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return undefined;
-            }
-            if (!sessionOwnerOk(req, res, await sessionOwnerCellOf(deps.sessionStorage, sessionId, owner)))
+            const head = await readOwnerCell(entry, sessionId, () => headOf(sessionId));
+            if ((await admitSessionRow(entry, res, deps.sessionStorage, sessionId, head)) === undefined)
                 return undefined;
         }
         let audit;
@@ -101,11 +103,7 @@ export async function handleSessions(req, res, match, ctx) {
                 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_MESSAGE);
-            return undefined;
-        }
-        if (!sessionOwnerOk(req, res, await sessionOwnerCellOf(deps.sessionStorage, sessionId, audit.owner)))
+        if ((await admitSessionRow(entry, res, deps.sessionStorage, sessionId, audit)) === undefined)
             return undefined;
         return audit;
     };
@@ -113,7 +111,7 @@ export async function handleSessions(req, res, match, ctx) {
     const { mcpStatusCache, a2aStatusCache } = ctx.local.sessions;
     {
         if (match.decl.id === "session-init") {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedSubject(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -128,7 +126,7 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-settings") {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedSubject(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -148,13 +146,13 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-mcp") {
-            const caller = sessionCallerOf(req, deps);
-            const principal = caller.principal;
+            const caller = callerOf(req, deps);
+            const principal = caller.subject === undefined ? undefined : personOf(caller.subject);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
-            const lastLegMcp = await lastLegMcpFor(deps, safeDecode(match.params.sessionId), caller);
+            const lastLegMcp = await lastLegMcpFor(deps, safeDecode(match.params.sessionId), protocolEntry(req, deps, "run.panel", caller));
             const ledgerHalf = lastLegMcp === undefined ? {} : { lastLegMcp };
             let scenarioName;
             try {
@@ -210,7 +208,7 @@ export async function handleSessions(req, res, match, ctx) {
     }
     {
         if (match.decl.id === "session-a2a") {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -274,14 +272,12 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
                 return;
             }
-            const head = await foldOwnerUnreadable(deps.logger, match.decl.id, headSession, () => headOf(headSession));
-            if (head === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const headEntry = callerEntry(req, deps, match.decl.id);
+            const headRead = await readOwnerCell(headEntry, headSession, () => headOf(headSession));
+            const admittedHead = await admitSessionRow(headEntry, res, deps.sessionStorage, headSession, headRead);
+            if (admittedHead === undefined)
                 return;
-            }
-            if (!sessionOwnerOk(req, res, await sessionOwnerCellOf(deps.sessionStorage, headSession, head.owner)))
-                return;
-            const leafId = leafOfAdmittedHead(head);
+            const leafId = leafOfAdmittedHead(admittedHead.row);
             const etag = `"${leafId ?? "empty"}"`;
             if (req.headers["if-none-match"] === etag) {
                 res.writeHead(304, { etag }).end();
@@ -304,14 +300,12 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
                 return;
             }
-            const reading = await foldOwnerUnreadable(deps.logger, match.decl.id, placementSession, () => placementFact.seat.read(placementSession));
-            if (reading === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return;
-            }
-            if (!explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config) && !sessionOwnerOk(req, res, await sessionOwnerCellOf(deps.sessionStorage, placementSession, reading.occupant.owner)))
+            const placementEntry = callerEntry(req, deps, match.decl.id);
+            const reading = await readOwnerCell(placementEntry, placementSession, () => placementFact.seat.read(placementSession));
+            const admittedPlacement = await admitSessionRow(placementEntry, res, deps.sessionStorage, placementSession, reading === undefined ? undefined : { owner: reading.occupant.owner, cell: reading.cell });
+            if (admittedPlacement === undefined)
                 return;
-            sendJson(res, 200, executionPlacementView(reading.cell));
+            sendJson(res, 200, executionPlacementView(admittedPlacement.row.cell));
             return;
         }
     }
@@ -322,7 +316,8 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 501, "capability.session_store_required", "session events require a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
-            const readHead = (id) => foldOwnerUnreadable(deps.logger, match.decl.id, id, () => evFact.sessionStorage.headOf(id));
+            const evEntry = callerEntry(req, deps, match.decl.id);
+            const readHead = (id) => readOwnerCell(evEntry, id, () => evFact.sessionStorage.headOf(id));
             const readOwner = async (id) => (await readHead(id))?.owner;
             const watch = evFact.watch;
             const evSession = safeDecode(match.params.sessionId);
@@ -359,7 +354,7 @@ export async function handleSessions(req, res, match, ctx) {
                     return;
                 }
                 sse.sseOwnerLookups++;
-                const admissionP = readHead(evSession).then(async (head) => (head === undefined ? undefined : { head, cell: await sessionOwnerCellOf(evFact.sessionStorage, evSession, head.owner) }));
+                const admissionP = readHead(evSession).then(async (head) => (!sessionRowPresent(head) ? undefined : { head, verdict: await judgeSessionRow(evEntry, evFact.sessionStorage, evSession, head) }));
                 void admissionP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; });
                 let stallTimer;
                 let admission;
@@ -383,15 +378,15 @@ export async function handleSessions(req, res, match, ctx) {
                 }
                 if (admission === undefined) {
                     cleanup();
-                    sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                    refuse(evEntry, res, "missing");
                     return;
                 }
-                if (!sessionOwnerOk(req, res, admission.cell)) {
+                if (deliverVerdict(evEntry, res, admission.verdict) === undefined) {
                     cleanup();
                     return;
                 }
                 leafOfAdmittedHead(admission.head);
-                const owner = admission.cell.owner;
+                const owner = admission.head.owner;
                 const q = new URLSearchParams(match.search);
                 const lastLeafId = q.get("lastLeafId");
                 let first = true;
@@ -520,16 +515,15 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
                 return;
             }
-            if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             const auditFact = facts.sessionAuditView(deps);
             if (!auditFact.available) {
                 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/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
+            if ((await readOwnedSessionView(entry, auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const faces = deps.memoryCompliance;
             if (faces === undefined) {
@@ -563,7 +557,9 @@ export async function handleSessions(req, res, match, ctx) {
                 sendJson(res, 200, await faces.erase(input));
             }
             catch (err) {
-                if (sentMemoryComplianceFailure(res, err, { kind: "session_owner", withheld }, deps.logger))
+                if (sentMemoryFaceFault(res, err, { kind: "session_owner", face: "erase", withheld }))
+                    return;
+                if (sentMemoryComplianceFailure(res, err, { kind: "session_owner", face: "erase", withheld }, deps.logger))
                     return;
                 deps.logger?.warn?.("session_memory_erase_failed", { sessionId, err: String(err) });
                 sendError(res, 500, "internal.error", "session memory erasure failed");
@@ -578,16 +574,15 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
                 return;
             }
-            if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             const auditFact = facts.sessionAuditView(deps);
             if (!auditFact.available) {
                 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/mysql memory backends do not (their control plane would land on a replica's local disk)");
                 return;
             }
-            if ((await readOwnedSessionView(auditFact.sessionAudit, sessionId)) === undefined)
+            if ((await readOwnedSessionView(entry, auditFact.sessionAudit, sessionId)) === undefined)
                 return;
             const face = deps.sessionMemoryStatus;
             if (face === undefined) {
@@ -631,7 +626,7 @@ export async function handleSessions(req, res, match, ctx) {
                 });
             }
             catch (err) {
-                if (sentMemoryLayerRefusal(res, err, { kind: "session_owner", withheld: (message) => deps.logger?.warn?.("session_memory_status_refused", { sessionId, err: message }) }))
+                if (sentMemoryFaceFault(res, err, { kind: "session_owner", face: "status", withheld: (message) => deps.logger?.warn?.("session_memory_status_refused", { sessionId, err: message }) }))
                     return;
                 deps.logger?.warn?.("session_memory_status_failed", { sessionId, err: String(err) });
                 sendError(res, 500, "internal.error", "session memory status read failed");
@@ -646,7 +641,8 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 501, "capability.session_store_required", "the session audit view requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
-            const owned = await readOwnedSessionView(auditFact.sessionAudit, match.params.sessionId, { reader: gatedPrincipal(req, deps.config) ?? null });
+            const viewEntry = callerEntry(req, deps, match.decl.id);
+            const owned = await readOwnedSessionView(viewEntry, auditFact.sessionAudit, match.params.sessionId, { reader: viewEntry.caller.subject ?? null });
             if (owned === undefined)
                 return;
             if (!Array.isArray(owned.messages)) {
@@ -709,13 +705,14 @@ export async function handleSessions(req, res, match, ctx) {
         }
         const store = rowFact.sessionStorage;
         const sessionId = match.params.sessionId;
+        const patchEntry = callerEntry(req, deps, match.decl.id);
         const head = await store.headOf(sessionId);
         if (head === undefined) {
-            sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            refuse(patchEntry, res, "missing");
             return;
         }
         const face = sessionFaceOfHead(sessionId, head);
-        if (!sessionOwnerOk(req, res, await sessionOwnerCellOf(store, sessionId, face.owner)))
+        if ((await admitSessionRow(patchEntry, res, store, sessionId, face)) === undefined)
             return;
         leafOfAdmittedHead(head);
         const read = readSessionRowPatch(await readJson(req));
@@ -735,7 +732,7 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 409, "conflict.session_mirror", "this session is a read-only mirror of a session whose writer is elsewhere — it cannot be renamed or pinned here; fork it (forkPath) to continue here; nothing was written", { forkPath: forkPathOf(sessionId) });
                 return;
             case "absent":
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                refuse(patchEntry, res, "missing");
                 return;
             default: {
                 const unknownOutcome = outcome;
@@ -743,6 +740,78 @@ export async function handleSessions(req, res, match, ctx) {
             }
         }
     }
+    if (match.decl.id === "session-rewind-files") {
+        if (ctx.helpers.rateLimited(req, res))
+            return;
+        const rewind = facts.sessionRewindFiles(deps);
+        if (!rewind.available) {
+            switch (rewind.why) {
+                case "file_history_store_absent":
+                    sendError(res, 501, "capability.snapshot_store_required", "rewinding a session's files is not available on this deployment: no file-history store is wired, so no file history was ever recorded");
+                    return;
+                case "session_head_face_absent":
+                    sendError(res, 501, "capability.session_store_required", "rewinding a session's files requires a durable session store (DB_BACKEND=mysql|pg|local)");
+                    return;
+                case "resume_anchor_store_absent":
+                    sendError(res, 501, "capability.session_store_required", "rewinding a session's files is not available on this deployment: no session-store backend holds the rewind anchor map");
+                    return;
+                case "execution_lane_handless":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment: it mounts no execution environment (REMOTE_EXEC=none), so a session has no working tree to rewind");
+                    return;
+                case "workspace_rebuilt_per_task":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment: each task's workspace is rebuilt when the task starts (fresh, or restored from a saved copy that a rewind cannot yet write into), so a rewind would not reach the files the next task works on");
+                    return;
+                case "session_store_shared":
+                    sendError(res, 501, "capability.unavailable", "rewinding a session's files is not available on this deployment yet: its session store is shared by several server instances (DB_BACKEND=mysql|pg), and a rewind cannot yet keep runs started on another instance off the session while it restores");
+                    return;
+                default:
+                    return assertNever(rewind.why);
+            }
+        }
+        const { anchors, sessionStorage } = rewind;
+        const sessionId = safeDecode(match.params.sessionId);
+        if (sessionId === null || !isUuidShape(sessionId)) {
+            sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
+            return;
+        }
+        const rewindEntry = enter(req, res, deps, match.decl.id);
+        if (rewindEntry === undefined)
+            return;
+        const owned = await admitSessionById(rewindEntry, res, sessionStorage, sessionId);
+        if (owned === undefined)
+            return;
+        const sessionOwner = owned.row.owner;
+        leafOfAdmittedHead(owned.row);
+        const read = readRewindFilesBody(await readJson(req));
+        if (read.kind === "refused") {
+            sendError(res, 400, read.errorCode, read.message);
+            return;
+        }
+        const execution = await resolveExecutionContext(deps, { kind: "continuation", root: sessionId, principal: sessionOwner === null || sessionOwner === undefined ? undefined : personOf(sessionOwner) });
+        if (execution.lane === "host" && (await presentHostWorkspaceOf(deps.perSessionCwd?.get(sessionId))) === undefined) {
+            sendError(res, 409, "conflict.session_workspace_unknown", "this server process does not know a working directory for this session that it can rewind into (no prompt carrying its cwd has been submitted since the server started, or the directory that prompt named no longer exists), so nothing was rewound; submit a prompt with its cwd first, then rewind");
+            return;
+        }
+        const entryId = await resolveHistoryAnchor("rewindFilesTo", anchors, anchorReaderOf(req, deps, rewindEntry.caller), sessionId, read.to, sessionOwner, "to");
+        const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
+        if (activeTaskId) {
+            sendError(res, 409, "conflict.session_active_run", `session has an active run (${activeTaskId}); its files cannot be rewound under it — wait for that run to end (or cancel it), then rewind`, { activeTaskId });
+            return;
+        }
+        let result;
+        try {
+            result = await rewindFilesUnderPurpose(deps.runner, { sessionId, to: entryId, dryRun: read.dryRun });
+        }
+        catch (e) {
+            const answer = engineRefusalAnswerOf(e);
+            if (answer === undefined)
+                throw e;
+            sendError(res, answer.status, answer.refusal.errorCode, answer.refusal.message);
+            return;
+        }
+        sendJson(res, 200, buildRewindFilesReply(result));
+        return;
+    }
     {
         if (match.decl.id === "session-fork") {
             const forkFact = facts.sessionFork(deps);
@@ -751,27 +820,19 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const fork = forkFact.sessionStorage.fork.bind(forkFact.sessionStorage);
-            const readOwner = async (id) => (await forkFact.sessionStorage.headOf(id))?.owner;
-            const scope = fleetViewOf(req, deps, "write");
-            if (!scope.fleetWide && scope.gateOwner === null) {
-                sendUnauthorized(res, "identity");
+            const forkEntry = enter(req, res, deps, match.decl.id);
+            if (forkEntry === undefined)
                 return;
-            }
             const sourceId = safeDecode(match.params.sessionId);
             if (sourceId === null || !isUuidShape(sourceId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
-            const owner = await readOwner(sourceId);
-            if (owner === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const forkAdmitted = await admitSessionById(forkEntry, res, forkFact.sessionStorage, sourceId);
+            if (forkAdmitted === undefined)
                 return;
-            }
-            if (!scope.fleetWide && owner !== scope.gateOwner && !legacyUnownedSessionOk(deps.config, sessionCallerOf(req, deps), await sessionOwnerCellOf(forkFact.sessionStorage, sourceId, owner))) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return;
-            }
-            const newOwner = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
+            const owner = forkAdmitted.row.owner;
+            const newOwner = admittedAsFleet(forkEntry, forkAdmitted) ? owner : (forkEntry.caller.subject ?? null);
             const keyed = readForkTarget(await readJson(req), sourceId);
             if (keyed.kind === "refused") {
                 sendError(res, 400, keyed.errorCode, keyed.message, keyed.facts);
@@ -780,7 +841,7 @@ export async function handleSessions(req, res, match, ctx) {
             if (keyed.kind === "none") {
                 const newId = await fork(sourceId, newOwner);
                 if (newId === null) {
-                    sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                    refuse(forkEntry, res, "missing");
                     return;
                 }
                 sendJson(res, 200, { sessionId: newId });
@@ -803,7 +864,7 @@ export async function handleSessions(req, res, match, ctx) {
                 throw e;
             }
             if (outcome === null) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                refuse(forkEntry, res, "missing");
                 return;
             }
             switch (outcome.outcome) {
@@ -815,7 +876,7 @@ export async function handleSessions(req, res, match, ctx) {
                     return;
                 case "occupied":
                     if (!outcome.sameOwner) {
-                        sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                        refuse(forkEntry, res, "not_visible");
                         return;
                     }
                     sendError(res, 409, "conflict.fork_id_taken", "forkId already names another session of yours (a different fork, or a session that was not created by this fork request) — pick a new forkId and forkNonce; nothing was forked", { forkId: keyed.forkId });
@@ -834,36 +895,27 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const purge = deleteFact.purge;
-            const readOwner = async (id) => (await deleteFact.sessionStorage.headOf(id))?.owner;
-            const scope = fleetViewOf(req, deps, "write");
-            if (!scope.fleetWide && scope.gateOwner === null) {
-                sendUnauthorized(res, "identity");
+            const deleteEntry = enter(req, res, deps, match.decl.id);
+            if (deleteEntry === undefined)
                 return;
-            }
             const sessionId = safeDecode(match.params.sessionId);
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
-            const owner = await readOwner(sessionId);
-            if (owner === undefined) {
-                sendJson(res, 200, { deleted: false });
+            const deleteAdmitted = await admitSessionById(deleteEntry, res, deleteFact.gateStore, sessionId);
+            if (deleteAdmitted === undefined)
                 return;
-            }
-            if (!scope.fleetWide && owner !== scope.gateOwner && !legacyUnownedSessionOk(deps.config, sessionCallerOf(req, deps), await sessionOwnerCellOf(deleteFact.sessionStorage, sessionId, owner))) {
-                sendJson(res, 200, { deleted: false });
-                return;
-            }
-            const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
-            if (activeTaskId) {
-                sendError(res, 409, "conflict.session_active_run", "session has an active run; cancel it before deleting", { activeTaskId });
-                return;
-            }
+            const owner = deleteAdmitted.row.owner;
             const result = await purge(sessionId, owner);
             if ("active" in result) {
                 sendError(res, 409, "conflict.session_active_run", "session has an active run; cancel it before deleting", { activeTaskId: result.active });
                 return;
             }
+            if ("inProgress" in result) {
+                sendError(res, 409, "conflict.session_deleting", "the delete of this session is already under way in another request, which finishes it — the session already reads as gone and this request returns without waiting; a retry answers {deleted:false} once the delete has finished");
+                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;
@@ -880,31 +932,23 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const store = policyFact.policyStore;
-            const readOwner = async (id) => (await policyFact.sessionStorage.headOf(id))?.owner;
-            const principal = gatedPrincipal(req, deps.config);
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendUnauthorized(res, "identity");
+            const policyEntry = enter(req, res, deps, match.decl.id);
+            if (policyEntry === undefined)
                 return;
-            }
             const sessionId = safeDecode(match.params.sessionId);
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
-            const owner = await readOwner(sessionId);
-            if (owner === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const policyAdmitted = await admitSessionById(policyEntry, res, policyFact.sessionStorage, sessionId);
+            if (policyAdmitted === undefined)
                 return;
-            }
+            const owner = policyAdmitted.row.owner;
             if (owner === null) {
-                sendError(res, 409, "conflict.session_ownerless", "this session has no recorded owner, so its rules can be neither read nor changed through this route; rules already stored for it keep applying to the runs of the principal they were stored under. Ways out: on the local backend, during the upgrade window, the first task submitted with a principal on a session written by an earlier version claims it for that principal (this route then serves its owner); or delete the session (DELETE /v1/sessions/:id), which removes its rules with it");
-                return;
-            }
-            const operator = explicitOperatorOk(principal, deps.config);
-            if (!operator && owner !== (principal ?? null)) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                sendError(res, 409, "conflict.session_ownerless", "this session has no recorded owner, so its rules can be neither read nor changed through this route; rules already stored for it keep applying to the runs of the principal they were stored under. Way out: delete the session (DELETE /v1/sessions/:id), which removes its rules with it");
                 return;
             }
+            const operator = policyAdmitted.quals.has("operator");
             const target = owner;
             if (match.decl.id === "session-policy-get") {
                 try {
@@ -967,6 +1011,7 @@ export const SESSIONS_ROUTES = [
     { id: "session-memory-status", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/memory-status$/, label: "/v1/sessions/:id/memory-status", methods: ["GET"] },
     { id: "session-workspace", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/workspace(?:\/(?<key>[^/]+)(?:\/(?<sub>tree|file|archive))?)?$/, label: "/v1/sessions/:id/workspace", methods: ["GET"] },
     { id: "session-detail", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["GET"] },
+    { id: "session-rewind-files", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/rewind-files$/, label: "/v1/sessions/:id/rewind-files", credentialGated: ["POST"], methods: ["POST"] },
     { id: "session-patch", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["PATCH"] },
     { id: "session-delete", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["DELETE"] },
 ];
@@ -989,4 +1034,24 @@ function readForkTarget(raw, sourceId) {
     return { kind: "keyed", forkId, forkNonce };
 }
 const FORK_NONCE_MAX_CHARS = 255;
+const REWIND_TO_MAX_CHARS = 255;
+function readRewindFilesBody(raw) {
+    const shape = {
+        kind: "refused",
+        errorCode: "request.body_shape",
+        message: 'the rewind-files body must be an object { to: string, dryRun?: boolean } — acceptPartialRestore is not accepted: the engine\'s out-of-run rewind has no partial-restore policy, so a partial restore answers 200 with restore.outcome "partial" and every refused or failed file on its ledger',
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return shape;
+    const keys = Object.keys(raw);
+    if (!keys.includes("to") || keys.some((k) => k !== "to" && k !== "dryRun"))
+        return shape;
+    const { to, dryRun } = raw;
+    if (typeof to !== "string" || to.length === 0 || to.length > REWIND_TO_MAX_CHARS) {
+        return { kind: "refused", errorCode: "request.field_invalid", message: `to must be a non-empty string of at most ${REWIND_TO_MAX_CHARS} characters: the handle of a prompt in this session (the handle rewindFilesTo takes)` };
+    }
+    if (dryRun !== undefined && typeof dryRun !== "boolean")
+        return { kind: "refused", errorCode: "request.field_invalid", message: "dryRun must be a boolean when given" };
+    return { kind: "read", to, dryRun: dryRun === true };
+}
 //# sourceMappingURL=sessions.js.map

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

@@ -1,6 +1,6 @@
 import { isSharedMemoryDocumentPath, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendUnauthorized } from "../principal-gate.js";
+import { gatedPerson, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 const RETRY_AFTER_SEC = 10;
@@ -10,14 +10,14 @@ function refuseStore(res) {
 }
 function refuseUnavailable(res, message) {
     res.setHeader("retry-after", String(RETRY_AFTER_SEC));
-    sendError(res, 503, "memory.shared_unavailable", "shared memory stores are unavailable", {
-        retryAfterSec: RETRY_AFTER_SEC,
-        ...(message !== undefined ? { detail: message } : {}),
-    });
+    if (message === undefined)
+        sendError(res, 503, "memory.shared_unavailable", "shared memory stores are unavailable", { retryAfterSec: RETRY_AFTER_SEC });
+    else
+        sendError(res, 503, "memory.shared_unavailable", `shared memory stores are unavailable: ${message}`, { retryAfterSec: RETRY_AFTER_SEC });
 }
 async function bindSnapshot(req, res, ctx) {
     const { deps } = ctx;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (!principal && deps.config.requirePrincipal === true) {
         sendUnauthorized(res, "identity");
         return undefined;

package/dist/http/routes/side-query.js

@@ -7,7 +7,7 @@ import { redactSecrets } from "../../trace/redact.js";
 import { errorCodeOf } from "../../observability/err-text.js";
 import { admitProviderEcho, redactErrorMessage } from "../../observability/run-terminal.js";
 import { sendJson, sendError, sendHttpError, msg } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 export function isCorePreflightValidationError(err) {
     return errorCodeOf(err) === "config.unknown_role";
@@ -38,7 +38,7 @@ export async function handleSideQuery(req, res, match, ctx) {
             try {
                 if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
                     return;
-                const principal = gatedPrincipal(req, deps.config);
+                const principal = gatedPerson(req, deps.config);
                 if (deps.config.requirePrincipal && !principal) {
                     sendPrincipalRefusal(res, req, deps.config);
                     return;