@sema-agent/server 7.146.0 → 7.147.0

package/dist/boot/resolve-spec.js

@@ -2,7 +2,7 @@ import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { NodeExecutionEnv, QUESTION_AWAITS_RESUME, deriveAskEffective, expandTiers, resolveAskSeamForm } from "@sema-agent/core";
 import { cappedCeiling } from "../budget.js";
-import { recordFailOpen } from "../observability/fail-open.js";
+import { unreadRequestMembers, unreadRequestMembersRefusal } from "../unread-request-members.js";
 import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
 import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { buildExcludeToolsSeat, buildPromptSeats, buildRunSkills, createScenarioGate, selectScenario } from "../capabilities/scenarios.js";
@@ -27,6 +27,7 @@ import { routeServiceTask, supPostureOverrides } from "../router/route-orchestra
 import { tightenGoverned } from "../governance-overrides.js";
 import { applyRuntimeGovernance } from "../runtime-governance.js";
 import { HttpError, createCodedHttpError, encodeCheckpointScope } from "../security.js";
+import { resolveHistoryAnchor } from "../history-anchor.js";
 import { headReadOf, sessionFaceOfHead } from "../session-incarnation.js";
 import { legProjectIdOf, sessionWorkspaceStoreOf } from "../session-workspace.js";
 import { memorySpecForRequest } from "../memory-scope.js";
@@ -71,11 +72,11 @@ export function createResolveSpec(ctx) {
         approvalSeat: durableEnabled ? "durable" : "absent",
         singleUserAutoAcceptBaseline: singleUserAutoAcceptBaselineApplies(config),
     });
-    const realTaskRootOf = (auth) => {
+    const realTaskRootOf = (root) => {
         if (DEPLOYMENT_SHAPE_PREDICATES.sandboxPathAdjudication.holds(config))
             return undefined;
-        const sessionCwd = auth?.sessionId ? effectiveHostWorkspace(perSessionCwd.get(auth.sessionId), {}) : undefined;
-        return sessionCwd ?? (executionLaneOf(config.remoteExec?.provider) === "in-process" ? process.cwd() : undefined);
+        const sessionCwd = effectiveHostWorkspace(perSessionCwd.get(root), {});
+        return sessionCwd ?? (laneWiresExecutionEnv(config.remoteExec.provider) ? undefined : process.cwd());
     };
     const memoryProjectLayers = createMemoryProjectLayers({ stores: memoryEngine, syncRunner: memorySyncRunner, log: logger });
     if (onlySensitiveBaseline)
@@ -84,6 +85,7 @@ export function createResolveSpec(ctx) {
     if (approvalGrantNotice)
         logger.info(approvalGrantNotice.event, approvalGrantNotice.fields);
     const resolveSpec = async (body, req, auth, opts) => {
+        const root = opts.execution.root;
         const seatRefusal = gateIntentUnserviceableReason(config, checkpointStore !== undefined);
         if (seatRefusal !== undefined)
             throw createCodedHttpError(501, "capability.checkpoint_store_required", seatRefusal);
@@ -102,7 +104,7 @@ export function createResolveSpec(ctx) {
                 cwd: body.cwd,
                 shellScratchpadDir: body.scratchpadDir,
                 localDataRoot: config.localDataRoot ?? localRoot,
-                sessionId: auth?.sessionId,
+                sessionId: root,
                 requirePrincipal: config.requirePrincipal,
                 callerOwnsWorkerDisk: DEPLOYMENT_SHAPE_PREDICATES.callerOwnsWorkerDisk.holds(config),
             });
@@ -119,15 +121,13 @@ export function createResolveSpec(ctx) {
             if (inheritEnvIssue)
                 throw new HttpError(400, inheritEnvIssue.message, { code: "request.field_invalid", extra: inheritEnvIssue.facts });
             if (body.inheritEnv === "all") {
-                const lane = executionLaneOf(config.remoteExec?.provider);
+                const lane = config.remoteExec.provider;
                 if (lane !== "host") {
                     throw new HttpError(400, `inheritEnv:"all" applies to the host lane only (this deployment runs ${lane}) — only the host lane builds the model-driven shell's environment from this machine's own, so the declaration has no effect here; omit it (or send "scrub", the default, which every lane accepts)`, { code: "request.field_invalid", extra: inheritEnvFacts("lane_not_host") });
                 }
                 const why = taskInheritEnvRefusal(config);
                 if (why !== undefined)
                     throw new HttpError(422, why, { code: HOST_POSTURE_REFUSED_CODE });
-                if (!auth?.sessionId)
-                    throw new HttpError(400, `inheritEnv:"all" requires a session-resolving deployment (no authorizer session) — the host shell's environment is bound per session`, { code: "request.field_invalid", extra: inheritEnvFacts("no_authorizer_session") });
             }
         }
         {
@@ -151,7 +151,7 @@ export function createResolveSpec(ctx) {
                         dropped[e.match]++;
                     logger.warn("settings_env_credentials_dropped", {
                         migration: "M38",
-                        sessionId: auth?.sessionId ?? null,
+                        sessionId: root,
                         dropped,
                         note: "this replayed request was stored before the upgrade and its settings.env carries credentials (a credential variable name of this engine, or a value shaped like a secret); while one-time migration M38 is open they are dropped from what the session's shell and hooks receive and the task resumes — the engine's own credentials come from its process environment and are unaffected; once the window closes the same request is refused",
                     });
@@ -169,7 +169,7 @@ export function createResolveSpec(ctx) {
                 const stale = inertToolListEntryOf(body, ["allow"]);
                 if (stale !== undefined) {
                     logger.warn("stored_allow_list_inert_resumed", {
-                        sessionId: auth?.sessionId ?? null,
+                        sessionId: root,
                         layer: stale.layer,
                         sentence: stale.message,
                         note: "this resumed task's stored request carries an allow-list entry the engine reads as nothing (a retired name, a case twin, an unreadable spelling or a content form): the entry stays as written and grants nothing — the task ran that way before the upgrade, so it continues; fix the entry in a new submission to get what it was meant to allow",
@@ -179,54 +179,54 @@ export function createResolveSpec(ctx) {
         }
         if (opts?.leg === "fresh")
             assertRequestA2aEntries(a2aPeers);
+        {
+            const unread = unreadRequestMembers({ settings: body.settings, mcpServers: body.mcpServers, a2aPeers }, config, opts?.leg === "fresh" ? { replay: false, settingsEnv } : { replay: true, today: new Date().toISOString().slice(0, 10), storedToolAxes, settingsEnv });
+            if (unread.length > 0) {
+                const refusal = unreadRequestMembersRefusal(unread);
+                throw new HttpError(400, refusal.message, { code: refusal.errorCode, ...(refusal.facts !== undefined ? { extra: { ...refusal.facts } } : {}) });
+            }
+        }
         if (opts?.leg === "fresh")
             assertRequestImageUrls(body.images);
-        const gated = await gateScenarioAndAppend(body, auth, opts, settingsEnv);
+        const gated = await gateScenarioAndAppend(body, auth, root, opts, settingsEnv);
         const effMode = effectivePermissionMode(body, gated.parsedSettings.settings);
         {
             const why = permissionModeWriteFaceRefusal(effMode, config);
             if (why !== undefined)
                 throw new HttpError(422, why, { code: HOST_POSTURE_REFUSED_CODE });
         }
-        const lane = bindSettingsCwdEnvAndModel(body, auth, gated, opts);
-        const anchors = await resolveHistoryAnchors(body, auth);
-        const projectKey = memoryEngine ? await memoryProjectLayers.prepare(config, auth?.memoryScope, realTaskRootOf(auth)) : undefined;
+        const lane = bindSettingsCwdEnvAndModel(body, auth, root, gated, opts);
+        const anchors = await resolveHistoryAnchors(body, auth, root);
+        const projectKey = memoryEngine ? await memoryProjectLayers.prepare(config, auth?.memoryScope, realTaskRootOf(root)) : undefined;
         const runSkills = buildRunSkills({ scenario: gated.cap.skills, request: body.skills, disable: body.disableSkills === true, deploymentSources: deploymentSkillSources }, logger);
-        const spec = assembleSpecLiteral(body, auth, req, opts, { ...gated, ...lane, ...anchors, projectKey, a2aPeers, storedToolAxes, runSkills }, effMode);
-        const folded = await foldGovernanceAndSettings(body, auth, spec, gated);
-        const final = await applyImageFactsAndRouting(body, auth, folded.governed, {
+        const spec = assembleSpecLiteral(body, auth, root, req, opts, { ...gated, ...lane, ...anchors, projectKey, a2aPeers, storedToolAxes, runSkills }, effMode);
+        const folded = await foldGovernanceAndSettings(body, auth, root, spec, gated);
+        const final = await applyImageFactsAndRouting(body, auth, root, folded.governed, {
             scenarioName: gated.scenarioName,
             scratchpadDir: folded.scratchpadDir,
             hostSemanticsLane: folded.hostSemanticsLane,
         });
         return { spec: final, facts: { hands: gated.hands, skills: runSkills.roster, sessionWitness: gated.sessionWitness } };
     };
-    const gateScenarioAndAppend = async (body, auth, opts, settingsEnv) => {
+    const gateScenarioAndAppend = async (body, auth, root, opts, settingsEnv) => {
         const scenarioName = await scenarioGate(auth?.principal, body.scenario);
-        const root = opts.execution.root;
         const rootFace = sessionHeadOf === undefined ? undefined : sessionFaceOfHead(root, await sessionHeadOf(root));
         const sessionWitness = { sessionId: root, owner: rootFace?.owner ?? null, incarnation: rootFace?.incarnation ?? null };
         const cap = selectScenario(scenarios, scenarioName)(body, auth?.principal, { sessionId: sessionWitness.sessionId, delegationRoot: sessionWitness });
-        const acceptedAppend = acceptAppendSystemPrompt(body.appendSystemPrompt, (detail) => logger.warn("append_system_prompt_dropped", { detail, sessionId: auth?.sessionId ?? null }));
+        const acceptedAppend = acceptAppendSystemPrompt(body.appendSystemPrompt, (detail) => logger.warn("append_system_prompt_dropped", { detail, sessionId: root }));
         const objective = typeof body.objective === "string" ? body.objective : "";
         const parsedSettings = parseTaskSettings(body.settings, {
             ...(opts?.leg === "fresh" || !taskHooksHonored(config) ? {} : { storedHooksReread: storedHooksRereadM20(new Date().toISOString().slice(0, 10)) }),
             settingsEnv,
         });
-        if (parsedSettings.deferred.length > 0) {
-            logger.warn("task_settings_deferred", { fields: parsedSettings.deferred, sessionId: auth?.sessionId ?? null });
-        }
         if (parsedSettings.hooksReread !== undefined) {
             logger.warn("hooks_read_as_before_upgrade", {
                 migration: "M20",
-                sessionId: auth?.sessionId ?? null,
+                sessionId: root,
                 stripped: parsedSettings.hooksReread.stripped,
-                note: "this replayed request was stored before the upgrade and its settings.hooks carries a shape the hooks reader now refuses (a key the reader does not know that hides a guard-event member, or a JSON `__proto__` event key); while one-time migration M20 is open the keys named in `stripped` are dropped — what the pre-upgrade reader dropped — and the rest goes through the same reader again, so the guard hooks keep running; once the window closes the same request has its whole settings.hooks left out",
+                note: "this replayed request was stored before the upgrade and its settings.hooks carries a shape the hooks reader now refuses (a key the reader does not know that hides a guard-event member, or a JSON `__proto__` event key); while one-time migration M20 is open the keys named in `stripped` are dropped — what the pre-upgrade reader dropped — and the rest goes through the same reader again, so the guard hooks keep running; once the window closes the same request is refused on resume (409 resume_blocked_by_policy)",
             });
         }
-        if (parsedSettings.deferred.includes("hooks") && taskHooksHonored(config)) {
-            recordFailOpen("server.hooks.resume-reader-refused", `leg=${opts?.leg ?? "resume"}`);
-        }
         let attachmentNotice;
         {
             const reqAtt = body.attachmentIds;
@@ -239,28 +239,25 @@ export function createResolveSpec(ctx) {
                 if (reqAtt.length > 0) {
                     if (!taskAttachmentStore)
                         throw new HttpError(501, "attachmentIds require a store backend (DB_BACKEND=mysql|pg|local)");
-                    if (!auth?.sessionId)
-                        throw new HttpError(400, "`attachmentIds` requires a session-resolving deployment (no authorizer session)");
-                    const sid = auth.sessionId;
                     const lane = opts.execution.lane;
                     const r = await bindAttachmentsForTask({
                         store: taskAttachmentStore,
                         owner: auth?.principal ?? "default",
                         ids: reqAtt,
-                        sessionId: sid,
+                        sessionId: root,
                         lane: { word: lane, isolated: laneIsolated(lane) },
                         leg: opts?.leg === "fresh" ? "fresh" : "resume",
                         nowMs: Date.now(),
                         onMissing: (id) => {
                             if (opts?.leg === "fresh")
                                 throw new HttpError(400, `attachment not found: ${id}`);
-                            logger.warn("attachment_missing_on_resume", { sessionId: sid, id });
+                            logger.warn("attachment_missing_on_resume", { sessionId: root, id });
                         },
                         onRefused: (refusal) => {
                             const answer = attachmentBindRefusalAnswer(refusal);
                             if (opts?.leg === "fresh")
                                 throw createCodedHttpError(answer.status, answer.errorCode, answer.message, answer.extra);
-                            logger.warn("attachment_refused_on_resume", { sessionId: sid, errorCode: answer.errorCode, ...answer.extra });
+                            logger.warn("attachment_refused_on_resume", { sessionId: root, errorCode: answer.errorCode, ...answer.extra });
                         },
                     });
                     attachmentNotice = r.notice;
@@ -269,46 +266,45 @@ export function createResolveSpec(ctx) {
         }
         return { scenarioName, cap, hands: cap.hands, acceptedAppend, objective, parsedSettings, attachmentNotice, sessionWitness };
     };
-    const bindSettingsCwdEnvAndModel = (body, auth, gated, opts) => {
+    const bindSettingsCwdEnvAndModel = (body, auth, root, gated, opts) => {
         const { objective, parsedSettings } = gated;
         const cwdWriteGate = DEPLOYMENT_SHAPE_PREDICATES.callerCwd.holds(config);
-        const execLane = executionLaneOf(config.remoteExec?.provider);
-        if (auth?.sessionId)
-            fenceSessionOwner(auth.sessionId, auth.principal ?? null);
-        if (typeof body.cwd === "string" && body.cwd.length > 0 && auth?.sessionId) {
+        const execLane = config.remoteExec.provider;
+        fenceSessionOwner(root, auth?.principal ?? null);
+        if (typeof body.cwd === "string" && body.cwd.length > 0) {
             if (cwdWriteGate && isAbsoluteHostPath(body.cwd))
-                setSessionCwd(auth.sessionId, body.cwd);
-            else if (DEPLOYMENT_SHAPE_PREDICATES.inProcessSingleUser.holds(config) && isAbsoluteHostPath(body.cwd) && satisfiedByProcessCwd(body.cwd, realpathSync))
-                logger.debug("task_cwd_inherited", { lane: execLane, sessionId: auth.sessionId });
+                setSessionCwd(root, body.cwd);
+            else if (DEPLOYMENT_SHAPE_PREDICATES.noHandsSingleUser.holds(config) && isAbsoluteHostPath(body.cwd) && satisfiedByProcessCwd(body.cwd, realpathSync))
+                logger.debug("task_cwd_inherited", { lane: execLane, sessionId: root });
             else
-                logger.warn("task_cwd_ignored", { honored: cwdWriteGate, lane: execLane, sessionId: auth.sessionId });
+                logger.warn("task_cwd_ignored", { honored: cwdWriteGate, lane: execLane, sessionId: root });
         }
-        if (parsedSettings.settings?.shellEnv && auth?.sessionId) {
+        if (parsedSettings.settings?.shellEnv) {
             if (cwdWriteGate)
-                setSessionShellEnv(auth.sessionId, parsedSettings.settings.shellEnv);
-            else if (DEPLOYMENT_SHAPE_PREDICATES.inProcessSingleUser.holds(config)) {
+                setSessionShellEnv(root, parsedSettings.settings.shellEnv);
+            else if (DEPLOYMENT_SHAPE_PREDICATES.noHandsSingleUser.holds(config)) {
                 const requested = parsedSettings.settings.shellEnv;
                 const mismatched = shellEnvMismatchCount(requested, process.env);
                 if (mismatched === 0)
-                    logger.debug("task_shell_env_inherited", { lane: execLane, keys: Object.keys(requested).length, sessionId: auth.sessionId });
+                    logger.debug("task_shell_env_inherited", { lane: execLane, keys: Object.keys(requested).length, sessionId: root });
                 else
-                    logger.warn("task_shell_env_ignored", { honored: false, lane: execLane, mismatchedKeys: mismatched, sessionId: auth.sessionId });
+                    logger.warn("task_shell_env_ignored", { honored: false, lane: execLane, mismatchedKeys: mismatched, sessionId: root });
             }
             else
-                logger.warn("task_shell_env_ignored", { honored: false, lane: execLane, sessionId: auth.sessionId });
+                logger.warn("task_shell_env_ignored", { honored: false, lane: execLane, sessionId: root });
         }
         const taskHooks = (() => {
             const hc = parsedSettings.settings?.hooks;
             if (!hc)
                 return [];
             if (!taskHooksHonored(config)) {
-                logger.warn("task_hooks_ignored", { honored: false, sessionId: auth?.sessionId ?? null });
+                logger.warn("task_hooks_ignored", { honored: false, sessionId: root });
                 return [];
             }
             return createSettingsHooksRegistrations(hc, {
                 logger,
-                sessionId: auth?.sessionId ?? "",
-                cwd: (auth?.sessionId ? perSessionCwd.get(auth.sessionId) : undefined) ?? process.cwd(),
+                sessionId: root,
+                cwd: perSessionCwd.get(root) ?? process.cwd(),
                 ...(parsedSettings.settings?.shellEnv ? { shellEnv: parsedSettings.settings.shellEnv } : {}),
                 httpHookAllowlistLayers: parsedSettings.settings?.httpHookAllowlist !== undefined ? [parsedSettings.settings.httpHookAllowlist] : [],
                 belowTaskChainPatterns,
@@ -317,28 +313,24 @@ export function createResolveSpec(ctx) {
                 onHookNotice: (n) => fleetBus.publishHookNotice({
                     ...n,
                     ...(auth?.principal ? { ownerScope: auth.principal } : {}),
-                    ...(auth?.sessionId ? { ownerSessionId: auth.sessionId } : {}),
+                    ownerSessionId: root,
                 }),
-                ...(auth?.sessionId
-                    ? {
-                        wake: async (text) => hookWakeBus.deliver
-                            ?
-                                hookWakeBus.deliver(auth.sessionId, `[hook asyncRewake] ${redactSecrets(text)}`)
-                            : false,
-                    }
-                    : {}),
+                wake: async (text) => hookWakeBus.deliver
+                    ?
+                        hookWakeBus.deliver(root, `[hook asyncRewake] ${redactSecrets(text)}`)
+                    : false,
             }, settingsHooksBudgetMs(config));
         })();
         const rawAddDirs = body.additionalDirectories;
         const callerOwnsWorkerDisk = DEPLOYMENT_SHAPE_PREDICATES.callerOwnsWorkerDisk.holds(config);
         const additionalDirectories = callerOwnsWorkerDisk ? parseAdditionalDirectories(rawAddDirs) : undefined;
         if (rawAddDirs !== undefined && !callerOwnsWorkerDisk) {
-            logger.warn("task_additional_directories_ignored", { honored: false, sessionId: auth?.sessionId ?? null });
+            logger.warn("task_additional_directories_ignored", { honored: false, sessionId: root });
         }
         const rawAddReadDirs = body.additionalReadDirectories;
         const additionalReadDirectories = callerOwnsWorkerDisk ? parseAdditionalDirectories(rawAddReadDirs) : undefined;
         if (rawAddReadDirs !== undefined && !callerOwnsWorkerDisk) {
-            logger.warn("task_additional_read_directories_ignored", { honored: false, sessionId: auth?.sessionId ?? null });
+            logger.warn("task_additional_read_directories_ignored", { honored: false, sessionId: root });
         }
         const wireCatalog = selectableCatalog(config.models, config.tiers, config.modelRefusals);
         const picked = resolveTaskModel(body.model ?? parsedSettings.settings?.model, objective, wireCatalog, config.atMention, config.modelRefusals);
@@ -348,7 +340,7 @@ export function createResolveSpec(ctx) {
                 throw new HttpError(400, modelUnavailableMessage(source === "mention" ? "@-mention" : "model", requested, name, refusal), { code: "request.model_unavailable" });
             }
             metrics.inc("task_model_unavailable_fallback_total");
-            logger.warn("task_model_unavailable_fallback", { requested: echoModelRef(requested), name, code: refusal.code, source, fallback: picked.model, sessionId: auth?.sessionId ?? null });
+            logger.warn("task_model_unavailable_fallback", { requested: echoModelRef(requested), name, code: refusal.code, source, fallback: picked.model, sessionId: root });
         }
         if (picked.notAllowed !== undefined) {
             const { requested, resolved, source } = picked.notAllowed;
@@ -356,39 +348,30 @@ export function createResolveSpec(ctx) {
                 throw new HttpError(400, `model "${echoModelRef(requested)}" is not @-mentionable on this deployment (it resolves to catalog model "${resolved}") — which models can be @-mentioned is configured by the operator (models.atMention)`, { code: "request.model_not_allowed" });
             }
             metrics.inc("task_model_not_allowlisted_resume_total");
-            logger.warn("task_model_not_allowlisted_resume", { requested: echoModelRef(requested), resolved, source, sessionId: auth?.sessionId ?? null, note: "resumed leg keeps running the model it was started on — the allowlist gates fresh picks only" });
+            logger.warn("task_model_not_allowlisted_resume", { requested: echoModelRef(requested), resolved, source, sessionId: root, note: "resumed leg keeps running the model it was started on — the allowlist gates fresh picks only" });
         }
         if (picked.unknownExplicit !== undefined) {
             metrics.inc("task_model_unknown_fallback_total");
-            logger.warn("task_model_unknown_fallback", { requested: echoModelRef(picked.unknownExplicit), fallback: picked.model, sessionId: auth?.sessionId ?? null });
+            logger.warn("task_model_unknown_fallback", { requested: echoModelRef(picked.unknownExplicit), fallback: picked.model, sessionId: root });
         }
         return { taskHooks, additionalDirectories, additionalReadDirectories, wireCatalog, picked };
     };
-    const NO_ANCHOR_HINT = "no rewind anchor is recorded under that handle (a prompt that carried attachments records none when its attachment frames were interrupted or their count did not match)";
-    const resolveHistoryAnchors = async (body, auth) => {
+    const resolveHistoryAnchors = async (body, auth, root) => {
         let resumeAtEntryId;
         if (typeof body.resumeAt === "string" && body.resumeAt.length > 0) {
-            if (!auth?.sessionId)
-                throw new HttpError(422, "resumeAt requires a session to branch (resume_at.no_session)", { code: "resume_at.no_session" });
             if (!resumeAnchorStore || !sessionHeadOf)
                 throw new HttpError(501, "resume-at is not available on this worker (no session-store backend for the anchor map)");
-            resumeAtEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.resumeAt, auth.principal ?? null);
-            if (resumeAtEntryId === undefined)
-                throw new HttpError(404, `resumeAt: no such message in this session (resume_at.unknown_event) — ${NO_ANCHOR_HINT}; give an explicit resumeAt`, { code: "resume_at.unknown_event" });
+            resumeAtEntryId = await resolveHistoryAnchor("resumeAt", resumeAnchorStore, root, body.resumeAt, auth?.principal ?? null, "resumeAt");
         }
         let rewindFilesToEntryId;
         if (resumeAtEntryId === undefined && typeof body.rewindFilesTo === "string" && body.rewindFilesTo.length > 0) {
-            if (!auth?.sessionId)
-                throw new HttpError(422, "rewindFilesTo requires a session (rewind_files_to.no_session)", { code: "rewind_files_to.no_session" });
             if (!resumeAnchorStore || !sessionHeadOf)
                 throw new HttpError(501, "rewind-files-to is not available on this worker (no session-store backend for the anchor map)");
-            rewindFilesToEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.rewindFilesTo, auth.principal ?? null);
-            if (rewindFilesToEntryId === undefined)
-                throw new HttpError(404, `rewindFilesTo: no such message in this session (rewind_files_to.unknown_event) — ${NO_ANCHOR_HINT}; name another prompt`, { code: "rewind_files_to.unknown_event" });
+            rewindFilesToEntryId = await resolveHistoryAnchor("rewindFilesTo", resumeAnchorStore, root, body.rewindFilesTo, auth?.principal ?? null, "rewindFilesTo");
         }
         const submittedProjectId = auth?.resolvedProjectId ?? (typeof body.projectId === "string" && body.projectId ? body.projectId.toLowerCase() : undefined);
         const s4DefaultScopes = submittedProjectId ? config.projects[submittedProjectId]?.defaultScopes : undefined;
-        const legProjectId = await legProjectIdOf(submittedProjectId, sessionWorkspace, auth?.sessionId);
+        const legProjectId = await legProjectIdOf(submittedProjectId, sessionWorkspace, root);
         return { resumeAtEntryId, rewindFilesToEntryId, s4DefaultScopes, legProjectId };
     };
     const declaresInteractivePosture = (body, req, opts) => {
@@ -405,7 +388,7 @@ export function createResolveSpec(ctx) {
         const askForm = resolveAskSeamForm(body.approvalReach !== undefined ? { approvalReach: body.approvalReach } : {}, approverSeat !== undefined ? { onAsk: approverSeat } : {});
         return deriveAskEffective(askForm.form, "unresolved") === "human_reachable";
     };
-    const assembleSpecLiteral = (body, auth, req, opts, parts, effMode) => {
+    const assembleSpecLiteral = (body, auth, root, req, opts, parts, effMode) => {
         const { scenarioName, cap, hands, acceptedAppend, parsedSettings, attachmentNotice, taskHooks, additionalDirectories, additionalReadDirectories, wireCatalog, picked, resumeAtEntryId, rewindFilesToEntryId, s4DefaultScopes, legProjectId, projectKey, a2aPeers, storedToolAxes, runSkills, } = parts;
         const spec = {
             objective: attachmentNotice ? `${picked.cleanedObjective}\n\n${attachmentNotice}` : picked.cleanedObjective,
@@ -439,8 +422,8 @@ export function createResolveSpec(ctx) {
             selfOrchestration: selfOrchestrationFromBody({ selfOrchestration: body.selfOrchestration === true || parsedSettings.settings?.ultracode === true }, config, Boolean(centerRuntimeCapsResolver)),
             forwardSubagentEvents: body.forwardSubagentEvents === true ? true : undefined,
             retainSubagentSessions: normalizeRetainSubagentSessions(body.retainSubagentSessions),
-            ...taskAgentsSpecFragment(body.agents, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: auth?.sessionId ?? null })),
-            ...(retainBackgroundProcessesFromBody(body.retainBackgroundProcesses, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: auth?.sessionId ?? null })) === true
+            ...taskAgentsSpecFragment(body.agents, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: root })),
+            ...(retainBackgroundProcessesFromBody(body.retainBackgroundProcesses, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: root })) === true
                 ? { retainBackgroundProcesses: true }
                 : {}),
             ...(body.excludeAllTools === true ? { excludeAllTools: true } : {}),
@@ -471,7 +454,7 @@ export function createResolveSpec(ctx) {
                         throw new HttpError(400, `unknown compactionModel "${echoModelRef(body.compactionModel)}" — not in the configured catalog (name, tier word, or id; a catalog refresh may have removed it mid-request)`);
                     }
                     metrics.inc("task_model_unknown_fallback_total");
-                    logger.warn("compaction_model_unknown_fallback", { requested: echoModelRef(body.compactionModel), sessionId: auth?.sessionId ?? null });
+                    logger.warn("compaction_model_unknown_fallback", { requested: echoModelRef(body.compactionModel), sessionId: root });
                     return {};
                 }
                 if (!isAtMentionable(cm, wireCatalog, config.atMention, config.modelRefusals)) {
@@ -480,14 +463,14 @@ export function createResolveSpec(ctx) {
                         throw new HttpError(400, `compactionModel "${echoModelRef(body.compactionModel)}" is not @-mentionable on this deployment (it resolves to catalog model "${terminal}") — which models can be @-mentioned is configured by the operator (models.atMention)`, { code: "request.model_not_allowed" });
                     }
                     metrics.inc("task_model_not_allowlisted_resume_total");
-                    logger.warn("task_model_not_allowlisted_resume", { requested: echoModelRef(body.compactionModel), resolved: terminal, source: "compaction", sessionId: auth?.sessionId ?? null, note: "resumed leg keeps the compaction model it was started with — the allowlist gates fresh picks only" });
+                    logger.warn("task_model_not_allowlisted_resume", { requested: echoModelRef(body.compactionModel), resolved: terminal, source: "compaction", sessionId: root, note: "resumed leg keeps the compaction model it was started with — the allowlist gates fresh picks only" });
                 }
                 return { compactionModel: cm };
             })()),
             thinking: effectiveThinking(body.reasoningEffort, parsedSettings.settings?.ultracode === true),
             getApiKeyAndHeaders: getKeyResolver(),
             ...(() => {
-                const limits = resolveTaskLimits(body.limits, taskLimitCaps, taskTimeoutSec, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: auth?.sessionId ?? null }));
+                const limits = resolveTaskLimits(body.limits, taskLimitCaps, taskTimeoutSec, config.requirePrincipal, (event, fields) => logger.warn(event, { ...fields, sessionId: root }));
                 const declarations = [];
                 if (taskLimitCaps.timeoutSec !== undefined)
                     declarations.push({ key: "server.limits.timeoutSecCap", value: String(taskLimitCaps.timeoutSec), reason: "env TASK_TIMEOUT_MAX_SEC (seconds; operator ceiling applied to caller limits.maxWalltimeMs as cap×1000)" });
@@ -535,13 +518,13 @@ export function createResolveSpec(ctx) {
             ...(() => { const v = toolNameListFromBody(body.userInvokedSkills); return v ? { userInvokedSkills: v } : {}; })(),
             ...(parsedSettings.settings?.skillListingBudgetFraction !== undefined ? { skillListingBudgetFraction: parsedSettings.settings.skillListingBudgetFraction } : {}),
             ...(parsedSettings.settings?.skillListingMaxDescChars !== undefined ? { skillListingMaxDescChars: parsedSettings.settings.skillListingMaxDescChars } : {}),
-            mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, peerDesk, opts.lease, logger, opts?.onNotice !== undefined ? { sessionId: auth?.sessionId, emit: opts.onNotice } : undefined, storedToolAxes),
+            mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, peerDesk, opts.lease, logger, opts?.onNotice !== undefined ? { sessionId: root, emit: opts.onNotice } : undefined, storedToolAxes),
             a2a: resolveRequestA2a(a2aForScenario(config.a2aPeers, scenarioName), a2aPeers, config, peerDesk, opts.lease, logger, opts?.leg === "fresh" ? "fresh" : "resume", storedToolAxes),
             toolPolicy: toolPolicyForHands(hands, durableEnabled
                 ? createApprovalBaselinePolicy(config, {
                     kind: "durable",
                     question: liveQuestionFace,
-                    ...(approvalExemptionStore !== undefined && auth?.sessionId ? { exemption: createDeploymentListExemption(approvalExemptionStore, auth.sessionId, logger) } : {}),
+                    ...(approvalExemptionStore !== undefined ? { exemption: createDeploymentListExemption(approvalExemptionStore, root, logger) } : {}),
                 })
                 : singleUserAutoAcceptBaselineApplies(config)
                     ? createApprovalBaselinePolicy(config, { kind: "absent" })
@@ -568,7 +551,7 @@ export function createResolveSpec(ctx) {
         };
         return spec;
     };
-    const foldGovernanceAndSettings = async (body, auth, spec, gated) => {
+    const foldGovernanceAndSettings = async (body, auth, root, spec, gated) => {
         const { acceptedAppend, parsedSettings } = gated;
         const hostSemanticsLane = !DEPLOYMENT_SHAPE_PREDICATES.sandboxPathAdjudication.holds(config);
         const laneHomeBase = () => {
@@ -577,7 +560,7 @@ export function createResolveSpec(ctx) {
         };
         const pathAdjudication = hostSemanticsLane
             ? (() => {
-                const realRoot = realTaskRootOf(auth);
+                const realRoot = realTaskRootOf(root);
                 const gateCwd = realRoot ?? join(config.localDataRoot ?? localRoot, "fs-write-gate-unrooted");
                 return {
                     env: new NodeExecutionEnv({ cwd: gateCwd }),
@@ -588,9 +571,9 @@ export function createResolveSpec(ctx) {
             })()
             : {
                 env: new DeferredSandboxPathEnv({
-                    sessionId: auth?.sessionId,
+                    sessionId: root,
                     slots: sandboxPathEnvSlots,
-                    logger: { warn: (event, fields) => logger.warn(event, { ...(fields ?? {}), lane: config.remoteExec?.provider }) },
+                    logger: { warn: (event, fields) => logger.warn(event, { ...(fields ?? {}), lane: config.remoteExec.provider }) },
                 }),
                 ...laneHomeBase(),
             };
@@ -598,18 +581,18 @@ export function createResolveSpec(ctx) {
         let governed = governedBase;
         let effectiveSettings = parsedSettings.settings;
         if (effectiveSettings?.outputStyle && acceptedAppend && acceptedAppend.length + 2 + effectiveSettings.outputStyle.length > MAX_SETTINGS_OUTPUT_STYLE_CHARS) {
-            logger.warn("output_style_dropped", { detail: `combined append carriers exceed the ${MAX_SETTINGS_OUTPUT_STYLE_CHARS} cap (rider ${acceptedAppend.length} + style ${effectiveSettings.outputStyle.length}) — style dropped (pre-cap stored body on a resume leg?)`, sessionId: auth?.sessionId ?? null });
+            logger.warn("output_style_dropped", { detail: `combined append carriers exceed the ${MAX_SETTINGS_OUTPUT_STYLE_CHARS} cap (rider ${acceptedAppend.length} + style ${effectiveSettings.outputStyle.length}) — style dropped (pre-cap stored body on a resume leg?)`, sessionId: root });
             const { outputStyle: _dropped2, ...rest2 } = effectiveSettings;
             effectiveSettings = Object.keys(rest2).length > 0 ? rest2 : undefined;
         }
         const shellScratchpad = await acceptShellScratchpadDir(body.scratchpadDir, {
             requirePrincipal: config.requirePrincipal,
             hostSemanticsLane,
-            warn: (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: auth?.sessionId ?? null }),
+            warn: (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: root }),
         });
         const scratchpadDir = shellScratchpad ??
-            (hostSemanticsLane && auth?.sessionId
-                ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId, (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: auth.sessionId }))
+            (hostSemanticsLane
+                ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, root, (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: root }))
                 : undefined);
         if (effectiveSettings) {
             const configRoot = executionConfigRootOf(config);
@@ -629,11 +612,11 @@ export function createResolveSpec(ctx) {
         }
         if (governed.selfOrchestration === true) {
             governed = tightenGoverned(governed, {
-                toolPolicy: createWorkflowAskPolicy(approvalExemptionStore && auth?.sessionId
+                toolPolicy: createWorkflowAskPolicy(approvalExemptionStore
                     ? async (toolName) => {
-                        const hit = await approvalExemptionStore.has(auth.sessionId, toolName);
+                        const hit = await approvalExemptionStore.has(root, toolName);
                         if (hit)
-                            logger.info("workflow_gate_exempted", { toolName, sessionId: auth.sessionId });
+                            logger.info("workflow_gate_exempted", { toolName, sessionId: root });
                         return hit;
                     }
                     : undefined),
@@ -641,40 +624,37 @@ export function createResolveSpec(ctx) {
         }
         return { governed, scratchpadDir, hostSemanticsLane };
     };
-    const applyImageFactsAndRouting = async (body, auth, governed, folded) => {
+    const applyImageFactsAndRouting = async (body, auth, root, governed, folded) => {
         const { scenarioName, scratchpadDir, hostSemanticsLane } = folded;
         const bodyProfile = typeof body.sandboxImageProfile === "string" && body.sandboxImageProfile.length > 0 ? body.sandboxImageProfile : undefined;
-        const taskImageProfile = bodyProfile ?? (body.cascade === true || body.verify === true ? undefined : sessionEnvSelection.get(auth?.sessionId));
+        const taskImageProfile = bodyProfile ?? (body.cascade === true || body.verify === true ? undefined : sessionEnvSelection.get(root));
         let resolvedImageCaps;
         if (taskImageProfile !== undefined) {
-            if (config.remoteExec?.provider !== "k8s") {
+            if (config.remoteExec.provider !== "k8s") {
                 throw createCodedHttpError(501, "capability.k8s_lane_required", "sandboxImageProfile is only supported on the k8s sandbox backend");
             }
             if (!imageIndex) {
                 throw createCodedHttpError(501, "capability.image_index_required", "sandboxImageProfile requires the sandbox-image-pool, which needs a SQL store backend (DB_BACKEND=mysql|pg) — this deployment's store wires no image index");
             }
-            if (!auth?.sessionId) {
-                throw createCodedHttpError(400, "request.precondition_unmet", "sandboxImageProfile requires a resolved session");
-            }
             const capsNeeded = Array.isArray(body.capabilitiesNeeded)
                 ? body.capabilitiesNeeded.filter((c) => typeof c === "string")
                 : undefined;
             const resolved = await resolveSandboxImageRef({
                 profile: taskImageProfile,
                 ...(capsNeeded && capsNeeded.length > 0 ? { capabilitiesNeeded: capsNeeded } : {}),
-                viewer: { operator: explicitOperatorOk(auth.principal, config), tenantId: auth.principal ?? null },
+                viewer: { operator: explicitOperatorOk(auth?.principal, config), tenantId: auth?.principal ?? null },
                 index: imageIndex,
             });
             if (!resolved.ok)
                 throw createCodedHttpError(resolved.status, resolved.errorCode, resolved.message);
-            perTaskImage.set(auth.sessionId, resolved.ref);
+            perTaskImage.set(root, resolved.ref);
             resolvedImageCaps = resolved.capabilities;
         }
         const remoteScratchpadDir = !hostSemanticsLane && DEPLOYMENT_SHAPE_PREDICATES.remoteScratchpad.holds(config)
-            ? remoteScratchpadDirFor(auth?.sessionId)
+            ? remoteScratchpadDirFor(root)
             : undefined;
         const declaredScratchpadDir = scratchpadDir ?? remoteScratchpadDir;
-        const pkgSourceLane = config.remoteExec?.provider === "e2b" || config.remoteExec?.provider === "k8s";
+        const pkgSourceLane = config.remoteExec.provider === "e2b" || config.remoteExec.provider === "k8s";
         const facts = buildEnvFacts({
             ...(declaredScratchpadDir ? { scratchpadDir: declaredScratchpadDir } : {}),
             ...(config.envFactsEnabled
@@ -683,7 +663,7 @@ export function createResolveSpec(ctx) {
                     capabilities: resolvedImageCaps,
                     ...(pkgSourceLane ? { pkgSource: config.sandboxPkgSource } : {}),
                     egress: egressForRemoteExec(config.remoteExec),
-                    resumeFacts: resumeFactsForLane(config.remoteExec?.provider, config.remoteExec?.provider === "k8s" ? { k8sSnapshot: Boolean(config.remoteExec.s3Snapshot) } : undefined),
+                    resumeFacts: resumeFactsForLane(config.remoteExec.provider, config.remoteExec.provider === "k8s" ? { k8sSnapshot: Boolean(config.remoteExec.s3Snapshot) } : undefined),
                 }
                 : {}),
         });
@@ -692,10 +672,10 @@ export function createResolveSpec(ctx) {
         if (config.routerEnabled) {
             const decision = routeServiceTask({
                 vmIsolatedExecEnv: DEPLOYMENT_SHAPE_PREDICATES.vmIsolatedHands.holds(config),
-                hasExecutionEnv: laneWiresExecutionEnv(executionLaneOf(config.remoteExec?.provider)),
+                hasExecutionEnv: laneWiresExecutionEnv(config.remoteExec.provider),
                 ...(config.autonomy ? { autonomy: config.autonomy } : {}),
             });
-            logger.info("orchestration_routed", { mode: decision.mode, reason: decision.reason, sessionId: auth?.sessionId ?? null });
+            logger.info("orchestration_routed", { mode: decision.mode, reason: decision.reason, sessionId: root });
             if (decision.mode === "supervisor") {
                 return tightenGoverned(governed, supPostureOverrides());
             }

package/dist/boot/retention-lane.d.ts

@@ -29,47 +29,16 @@
  * (车1 已实现)。lane **不补记**它们 —— 补记 = 「删了但审计没落地」的窗口重新打开。receipt 在本文件里
  * 只做两件事:二次确认(日志/指标)与「本轮到底动了多少」的读数。
  */
-import type { RetentionPolicy, RetentionReceipt } from "@sema-agent/core";
+import type { RetentionPolicy } from "@sema-agent/core";
 import type { RetentionMode } from "../config-types.js";
-import type { EndedSpace, SpaceReclaimer } from "../workspace-space.js";
+import type { SpaceReclaimer } from "../workspace-space.js";
+import type { RetentionExecutor } from "../plugins/retention-deployment.js";
 /** 同 domain 连续失败多少次算「卡住了」(fail-loud 的阈值)。`5` 与 reaper 家族的
  *  `REAPER_FAILURE_WARN_THRESHOLD` 同值同理由:一次抖动(一次重连、一次超时)正是容错要吸收的,
  *  只有**连败**才越过「可诊断」这条线。 */
 export declare const RETENTION_SWEEP_STUCK_THRESHOLD = 5;
 /** 租约 TTL = 本倍数 × sweep 间隔(设计稿 §3)。`2` = 允许一轮跑满一个完整间隔还有余量,再多就该让位。 */
 export declare const RETENTION_LEASE_TTL_FACTOR = 2;
-/**
- * lane 消费的**执行器**面 —— core `ManagedRetentionCapability` 的三方法 + 车1 的非契约窄读口
- * `previewRetention`(audit-only 档的读数源;core 契约无 count 面)+ 声明位。
- *
- * 🔴 三方法的入参是 core 契约形的**超集**(多一个 `audit`):车1 的店在运行期对缺席的审计上下文
- * fail-closed 抛错,所以这里把它写进类型 —— 让「忘了传」变成编译错,而不是一次运行期的破坏性调用被拒。
- */
-export interface RetentionExecutor {
-    readonly retention?: "managed" | "none";
-    listRetentionDomains(): Promise<readonly string[]>;
-    previewRetention(input: {
-        domain: string;
-        cutoffMs: number;
-    }): Promise<{
-        checkpoints: number;
-        sessions: number;
-        toolResults: number;
-    }>;
-    expireCheckpoints(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
-    deleteExpiredSessions(input: RetentionDestructiveInput): Promise<RetentionSessionsReceipt>;
-    deleteOrphanToolResults(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
-}
-/** 破坏性调用的入参(判定时点的三格随行 —— 理由逐字见车1 `RetentionAuditContext` 的头注)。 */
-export interface RetentionDestructiveInput {
-    domain: string;
-    cutoffMs: number;
-    audit: {
-        mode: RetentionMode;
-        policyDays: number;
-        fencingToken: number | null;
-    };
-}
 /** 非破坏性审计行的写口(lane 侧属主的那五个词)。 */
 export interface RetentionAuditSink {
     append(row: {
@@ -132,13 +101,6 @@ export interface RetentionSweepCtx {
      *  (缓存卷、`space/` 快照、该会话停驻车道的快照一并回收)。它从不抛(失败 = 一行 + fail-open 计数);缺席 = 本部署没有可回收的东西。 */
     spaceReclaimer?: SpaceReclaimer;
 }
-/**
- * 会话树 sweep 的回执 = core 契约的 `RetentionReceipt` + 本仓一位:`endedSpaces` = 本次删掉的会话树里**结束了的空间**(会话 id + 住客空间键 = 会话化身;
- * 读不出住客的空化身不算),present-iff 非空。lane 把它交给空间的回收座(与会话删除协调器同一只),缓存卷与快照随空间的终结回收。
- */
-export type RetentionSessionsReceipt = RetentionReceipt & {
-    readonly endedSpaces?: readonly EndedSpace[];
-};
 /** 一轮的读数(给日志与判据用;lane 自己不做任何决策依赖它)。 */
 export interface RetentionSweepOutcome {
     /** 本轮真正处理完的 domain 数(丢租中止时 = 中止之前那些)。 */
@@ -168,7 +130,7 @@ export interface RetentionSweepOutcome {
  * 为什么本道必须存在:引擎的门不拦
  *  · 没锁时,执行器在场 × 一只 `"none"` 的店 —— 部署于是**广告了一个不执行的留存面**:能力位说
  *     `{mode,maxAgeDays}`、审计表也在长,而那只店的行谁都没在删。
- *     本仓的 SQL 后端按同一个事实(扫车道开不开,`plugins/retention-store-sql.ts` 的 `retentionSweepRuns`)给它铸的三只店声明词,所以 lane 开着时
+ *     本仓的 SQL 后端按同一个事实(扫车道开不开,`plugins/retention-declaration.ts` 的 `retentionSweepRuns`)给它铸的三只店声明词,所以 lane 开着时
  *     这三只店在这一格上恒是 `managed`;这一格防的是声明与 lane 脱钩的店(别的后端、替身)。
  * 这些都在**启动期**拒(安全控件不得半开),不是让运维从一台"启动成功、什么也没删"的机器上猜。
  *