@sema-agent/server 7.146.0 → 7.148.0

package/dist/capabilities/scenarios.js

@@ -7,6 +7,7 @@ import { createWebSearchBackend, judgeRequestWebSearch } from "../plugins/web-se
 import { scenarioSkillEntries, skillsForScenario } from "./skills.js";
 import { OFFICE_EXCLUDED_TOOL_NAMES, runHasWorkspace } from "./hands-lane.js";
 import { BRAND_IDENTITY_SCENARIOS } from "./brand-identity.js";
+import { SCENARIO_NAME_RE } from "../owner-brands.js";
 export function buildPromptSeats(scenarioName, prompt, callerSystemPrompt) {
     const parts = [prompt?.roleText, callerSystemPrompt].filter((t) => typeof t === "string" && t.length > 0);
     const systemPrompt = parts.length > 0 ? parts.join("\n\n") : callerSystemPrompt;
@@ -69,7 +70,7 @@ export function buildScenarios(deps) {
                 }).filter((t) => t.name !== WEB_FETCH_TOOL_NAME || deps.requirePrincipal !== true),
             ],
             hands: BUILTIN_SCENARIO_HANDS.default,
-            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.default),
+            skills: skillsForScenario(deps.skills, "default"),
         };
     };
     return {
@@ -77,7 +78,7 @@ export function buildScenarios(deps) {
         code: (req, principal, ctx) => ({
             ...defaultScenario(req, principal, ctx),
             hands: BUILTIN_SCENARIO_HANDS.code,
-            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.code),
+            skills: skillsForScenario(deps.skills, "code"),
             prompt: { role: "code" },
         }),
         "code-review": (req) => codeReview(deps, req),
@@ -89,13 +90,13 @@ export function buildScenarios(deps) {
             return {
                 tools: [...repoToolsFor(repoClient, parseRepo(req.repo)), nowTool()],
                 hands: BUILTIN_SCENARIO_HANDS.scan,
-                skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.scan),
+                skills: skillsForScenario(deps.skills, "scan"),
             };
         },
         cowork: (req, principal, ctx) => ({
             ...defaultScenario(req, principal, ctx),
             hands: BUILTIN_SCENARIO_HANDS.cowork,
-            skills: skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE.cowork),
+            skills: skillsForScenario(deps.skills, "cowork"),
             excludeTools: OFFICE_EXCLUDED_TOOL_NAMES,
             prompt: { role: "cowork" },
         }),
@@ -125,13 +126,6 @@ export const BUILTIN_SCENARIO_HANDS = {
     scan: "none",
     cowork: "full",
 };
-export const BUILTIN_SCENARIO_SKILL_SCOPE = {
-    code: "default",
-    default: "default",
-    "code-review": "code-review",
-    scan: "scan",
-    cowork: "cowork",
-};
 export function builtinScenarioDetails(scenarios, deps, branded) {
     const probe = (name, req, principal, fallback) => {
         try {
@@ -146,7 +140,7 @@ export function builtinScenarioDetails(scenarios, deps, branded) {
         name, source: "builtin", builtin: true, summary, toolset, tools, promptSummary, enabled: true,
         ...availabilityFields(deps, toolset),
         attachmentSupplies: attachmentSuppliesFor(BUILTIN_SCENARIO_HANDS[name], deps.handsLane === true),
-        skills: scenarioSkillEntries(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE[name]),
+        skills: scenarioSkillEntries(deps.skills, name),
     });
     const brandedScenario = (name) => branded && BRAND_IDENTITY_SCENARIOS.includes(name);
     const details = {
@@ -220,7 +214,6 @@ function requireRepoClient(deps, scenarioLabel) {
         ? `${scenarioLabel} scenario has no repo client although the availability owner reports it available (wiring defect)`
         : scenarioUnavailableMessage(verdict.reason, scenarioLabel));
 }
-export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
 export function centerScenarios(deps, specs, builtinNames, logger) {
     const overlay = {};
     const shadows = [];
@@ -254,7 +247,7 @@ function codeReview(deps, req) {
     }
     const coords = parseRepo(req.repo);
     const repoTools = repoToolsFor(repoClient, coords);
-    const skills = skillsForScenario(deps.skills, BUILTIN_SCENARIO_SKILL_SCOPE["code-review"]);
+    const skills = skillsForScenario(deps.skills, "code-review");
     const hands = BUILTIN_SCENARIO_HANDS["code-review"];
     return { tools: [...repoTools, nowTool()], hands, skills, prompt: { roleText: REVIEWER_ROLE_TEXT } };
 }
@@ -285,6 +278,7 @@ export function buildRunSkills(args, logger) {
         logger?.warn("user_skills_dropped", { reason: "name reserved by scenario (or duplicate)", names: dropped });
     return { specs, roster };
 }
+const SCENARIO_ASSIGNMENT_UNAVAILABLE_REFUSAL = "this principal's scenario assignment could not be read — the configuration center did not answer (unreachable, timed out, or an unreadable reply), so no scenario was assigned and nothing ran — retry once the center answers again (the operator restores the link from this deployment to its configuration center)";
 function registeredScenariosClause(known) {
     return `this deployment's scenarios are: ${known.join(", ")}`;
 }
@@ -303,28 +297,31 @@ export function danglingScenarioRefusal(name, source, known) {
     }
 }
 export function gateScenarioRequest(ruling, bodyScenario, defaultScenario, known, logger, principal) {
+    if (typeof bodyScenario === "string" && !known.includes(bodyScenario)) {
+        throw new HttpError(400, `unknown scenario "${bodyScenario}" — ${registeredScenariosClause(known)}`, {
+            code: "scenario_unknown",
+            extra: { known: [...known] },
+        });
+    }
+    if (ruling === "unavailable") {
+        logger?.warn("scenario_assignment_unavailable", principal !== undefined ? { principal } : {});
+        throw createCodedHttpError(503, "state.scenario_assignment_unavailable", SCENARIO_ASSIGNMENT_UNAVAILABLE_REFUSAL, { permanence: "transient" });
+    }
     if (typeof bodyScenario === "string") {
-        const requested = bodyScenario;
-        if (!known.includes(requested)) {
-            throw new HttpError(400, `unknown scenario "${bodyScenario}" — ${registeredScenariosClause(known)}`, {
-                code: "scenario_unknown",
-                extra: { known: [...known] },
-            });
-        }
         const allowed = ruling?.allowlist ?? [];
-        if (allowed.length > 0 && !allowed.includes(requested)) {
+        if (allowed.length > 0 && !allowed.includes(bodyScenario)) {
             throw new HttpError(400, `scenario "${bodyScenario}" is not in this principal's assigned allowlist`, {
                 code: "scenario_not_allowed",
                 extra: { allowlist: allowed },
             });
         }
-        return requested;
+        return bodyScenario;
     }
     const [name, source] = ruling?.scenario != null ? [ruling.scenario, "ruling"] : [defaultScenario, "deployment"];
     const refusal = danglingScenarioRefusal(name, source, known);
     if (refusal !== undefined) {
         logger?.warn("scenario_assignment_unknown", { scenario: name, source, ...(principal !== undefined ? { principal } : {}) });
-        throw createCodedHttpError(503, "state.scenario_assignment_unknown", refusal, { detail: { scenario: name, source } });
+        throw createCodedHttpError(503, "state.scenario_assignment_unknown", refusal, { scenario: name, source });
     }
     return name;
 }
@@ -341,6 +338,8 @@ export function createScenarioGate(sources, leg) {
             }
         }
     };
-    return async (principal, requested) => gateScenarioRequest(await rulingOf(principal), requested, sources.config.defaultScenario, Object.keys(sources.scenarios), sources.logger, principal);
+    const known = () => Object.keys(sources.scenarios);
+    const gate = async (principal, requested) => gateScenarioRequest(await rulingOf(principal), requested, sources.config.defaultScenario, known(), sources.logger, principal);
+    return Object.assign(gate, { known });
 }
 //# sourceMappingURL=scenarios.js.map

package/dist/capabilities/settings-contract.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `GET /v1/capabilities` 的 `settingsContract` 位 —— **本服务内嵌的设置契约是哪一版、它的读者对每一型 hook 条目携带哪些字段**(版本位:恒在场,不随部署形变)。
+ *
+ * ## 病
+ * 一个键会不会被本服务的读者当契约外键剥掉(续跑重放腿)/ 在新提交面 400(键闭集门),今天消费方只能靠自己维护的「哪一版服务端认哪些键」代际表猜 ——
+ * 契约包一升版(例:19.0.0 起 command 条目承运 `args` / `onFailure`、http 条目承运 `onFailure`),那张表就漂。答案的真源在读者这一侧,所以由读者说。
+ *
+ * ## 形
+ * `{ version: string, hookEntryFields: { command | prompt | agent | http | mcp_tool: string[] } }`:
+ *  · `version` —— 已装 `@sema-agent/settings-schema` 的 package.json 版本号,读口唯一(`web-admin-client/center-request.ts` 的 {@link SETTINGS_SCHEMA_VERSION},对中心协商的 major 也由它派生);
+ *  · `hookEntryFields` —— 契约条目字段表按型的投影,**只投键名,不投取值类**;列序 = 契约分类器装上的条目的键序(判别位 `type` 不在列里)。
+ *    值源 = 契约包导出的字段表 {@link HOOK_ENTRY_FIELDS}(深冻结;本仓零镜像)—— 本模块不手抄、不另持。
+ * 「读者携带 ≠ 本服务执行」:本服务只跑 command / http / prompt / agent 四型(`mcp_tool` 整份拒,见 `hooks/hook-runner.ts` 的 `HOOK_ENTRY_TYPE_RUNS`),
+ * 列里也有本服务如实带、不执行的键(command 的 `rewakeMessage` / `rewakeSummary` / `cloud`、http 的 `cloud`、prompt 的 `continueOnBlock`);
+ * hooks 整只是否被采纳看 `taskSettings.hooks`;本位只答「契约面上这一型有哪些字段」。
+ */
+import { type HookEntryFields, type HookEntryType } from "@sema-agent/settings-schema/hooks";
+/** 一型的契约字段名(导出字段表那一行的键;判别位 `type` 不在表里)。 */
+export type HookContractEntryField<T extends HookEntryType> = Extract<keyof HookEntryFields[T], string>;
+/** 能力位 `settingsContract` 的形。 */
+export interface SettingsContractCapability {
+    readonly version: string;
+    readonly hookEntryFields: {
+        readonly [T in HookEntryType]: readonly HookContractEntryField<T>[];
+    };
+}
+/** 能力位的值(纯数据;进程内不变,装载时投影一次)。列的顺序随导出表的型序。 */
+export declare const SETTINGS_CONTRACT_CAPABILITY: SettingsContractCapability;
+//# sourceMappingURL=settings-contract.d.ts.map

package/dist/capabilities/settings-contract.js

@@ -0,0 +1,14 @@
+import { HOOK_ENTRY_FIELDS } from "@sema-agent/settings-schema/hooks";
+import { SETTINGS_SCHEMA_VERSION } from "../web-admin-client/center-request.js";
+const columnOf = (type) => Object.keys(HOOK_ENTRY_FIELDS[type]);
+export const SETTINGS_CONTRACT_CAPABILITY = {
+    version: SETTINGS_SCHEMA_VERSION,
+    hookEntryFields: {
+        command: columnOf("command"),
+        prompt: columnOf("prompt"),
+        agent: columnOf("agent"),
+        http: columnOf("http"),
+        mcp_tool: columnOf("mcp_tool"),
+    },
+};
+//# sourceMappingURL=settings-contract.js.map

package/dist/capabilities/skills.d.ts

@@ -1,5 +1,5 @@
 import type { SkillSpec } from "@sema-agent/core";
-import type { RemoteExecProvider } from "../execution-lane-caps.js";
+import type { ExecutionLane } from "../execution-lane-caps.js";
 import { type Logger } from "../observability/logger.js";
 /**
  * Built-in skills baked into the image, loaded ONCE at startup (no per-task disk IO). A skill is a
@@ -79,15 +79,15 @@ export declare function loadSkills(dir: string, opts: LoadSkillsOptions): Loaded
  * 各写一遍 `loadSkills(config.skillsDir, { toolsShareThisFilesystem: <车道判据>(config) })`,测试只能
  * 直传布尔去证 `loadSkills`(`baked-skills.test.ts`),证不到「config → 装配腿 → baseDir」这一段;收成一只
  * 之后,联合格从 config 走到 `baseDir`(`test/capabilities-http.test.ts` [ref] 段)证的就是两处装配点本人。
- * 判据属主:部署形表行 `toolsOnThisHost`([ref];[ref] 起 in-process ⇒ 假 ⇒ 目录形技能不带 `baseDir`)。
+ * 判据属主:部署形表行 `toolsOnThisHost`([ref];无手车道 `none` ⇒ 假 ⇒ 目录形技能不带 `baseDir`)。
  */
 export declare function loadDeploymentSkills(config: {
     readonly skillsDir: string;
-    readonly remoteExec?: {
-        readonly provider: RemoteExecProvider;
-    } | undefined;
+    readonly remoteExec: {
+        readonly provider: ExecutionLane;
+    };
 }, logger?: Logger): LoadedSkill[];
-/** 一个技能范围交进 `TaskSpec` 的技能(场景工厂的 `skills`)。范围从哪来见 `scenarios.ts` 的 `BUILTIN_SCENARIO_SKILL_SCOPE`(center 场景 = 它自己的名字)。 */
+/** 一个技能范围交进 `TaskSpec` 的技能(场景工厂的 `skills`)。**技能范围 = 场景名**,内建与 center 声明的场景一律如此、一处读法(没有范围表):各工厂与场景卡直传自己的场景名。 */
 export declare function skillsForScenario(loaded: readonly LoadedSkill[], scope: string): SkillSpec[];
 /**
  * 技能清单的一条 —— **一张形,两个面**:场景卡(`GET /v1/capabilities/scenarios/:name` 的 `skills[]`,[ref])与 run 级名册

package/dist/capabilities/tool-defer.d.ts

@@ -12,7 +12,7 @@
  *  - 🔴 **候选 ≠ 延迟**(core 7.15.0 [ref] 的行为面收窄,本仓两条真后果见下):候选集整体受**一道**
  *    阈值门,全或无 —— 候选的内联字节(name+description+schema)≥ `floor(上下文 token × 10%) × 3`
  *    才延迟,否则**全内联且不挂 `ToolSearch`**。远端协议铸名因此**不再无条件占位**:本仓缺省窗
- *    (`MODEL_CONTEXT_WINDOW=262144`)下阈值 = 78 642 字符,一个中小 MCP 名册够不着 ⇒ 首请求带全 schema。
+ *    (`ASSUMED_CONTEXT_WINDOW`,今天 262144 token)下阈值 = 78 642 字符,一个中小 MCP 名册够不着 ⇒ 首请求带全 schema。
  *    唯一不受门的是调用方的 `TaskSpec.deferTools` 字面名单(按字面恒延迟、不计量)。
  *  - `RunnerDeps.deferMode:"auto"` 不是第二道门,而是把候选集**拓宽**到全部 caller spec 后走同一道门 ——
  *    在本仓缺省场景下那会连 Agent 与 Task 四件一起卷进候选(与 CC 姿态相反),所以我们**刻意不开**;

package/dist/capability-facts.d.ts

@@ -25,6 +25,8 @@ import type { ServiceBlobExchange, ServiceFileHistoryStore } from "./plugins/sto
 import { resolveStreamApprovalGate, type ApprovalFrameFamily } from "./tool-approval.js";
 import { type WorkspaceSyncCapability } from "./workspace-space.js";
 import type { WorkspaceCacheCapability } from "./workspace-cache.js";
+import { type HeadRead } from "./session-incarnation.js";
+import type { HistoryAnchorReaders } from "./history-anchor.js";
 import type { EngineHandoverDoor } from "./boot/engine-lease.js";
 /** why 闭集:词 → 给运维看的一句义(诊断 / 测试读它;wire 上的拒句由各门自写)。 */
 export declare const CAPABILITY_FACT_WHY: {
@@ -37,13 +39,18 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly checkpoint_store_absent: "no durable checkpoint store is wired (DURABLE_APPROVAL)";
     readonly session_audit_absent: "no session audit view is wired (needs a durable session store)";
     readonly session_watch_absent: "the session watch registry is not wired";
-    readonly session_lister_absent: "no session enumerator is wired (session store or run store listSessions)";
+    readonly session_lister_absent: "no session enumerator is wired (the session store has no listSessions)";
     readonly session_fork_face_absent: "the session store has no fork face";
     readonly session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / writeSessionRowCells)";
     readonly session_purge_absent: "no session purge coordinator is wired";
     readonly session_policy_store_absent: "no session policy store is wired";
     readonly store_backend_absent: "no store backend is wired (DB_BACKEND=memory, multi-tenant bare boot, or half-configured SQL)";
     readonly file_history_store_absent: "no file-history store is wired";
+    readonly resume_anchor_store_absent: "no rewind anchor map is wired (the handle → session-entry map a rewind target is read through, with the run store an unknown handle is checked against — both come from the store backend)";
+    readonly execution_lane_handless: "the execution lane mounts no execution environment (REMOTE_EXEC=none), so a session has no working tree to rewind";
+    readonly workspace_rebuilt_per_task: "each task's workspace is rebuilt when the task starts on this deployment (a fresh directory, container or sandbox, or a restore from the workspace snapshot store that a rewind cannot yet take part in), so a rewind would not land in the tree the next task starts from";
+    readonly session_store_shared: "the session store is shared by several server instances (DB_BACKEND=mysql|pg) and no durable claim spans an out-of-run rewind yet, so a rewind could interleave with a run or another rewind started on another instance";
+    readonly file_history_preview_absent: "the file-history store implements no diffStats preview (the SQL backends)";
     readonly session_export_absent: "the session store has no entry export faces (exportEntries / exportEntriesStream)";
     readonly session_import_staging_absent: "the session store has no staged-import face (beginImportStaging)";
     readonly policy_purge_absent: "the session policy store has no deleteBySession purge verb";
@@ -81,6 +88,7 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly read_root_grant_posture_refused: "this is not a single-user host-lane deployment (REMOTE_EXEC=host without REQUIRE_PRINCIPAL), the only posture that honors a read-directory grant";
     readonly background_agent_store_absent: "no background-agent store is wired";
     readonly sendfile_ledger_absent: "no SendUserFile ledger is wired";
+    readonly project_registry_absent: "no project registry is served here: projects are published only by the configuration center (settings-schema does not read the projects domain from the local config.d), and no center configuration is applied (SEMA_WEB_ADMIN_URL unset, or SEMA_WEB_ADMIN_DRY_RUN on)";
     readonly workflow_engine_absent: "the workflow engine is not available on this worker";
     readonly entitlement_resolver_absent: "self-orchestration is on for a multi-tenant worker with no per-principal entitlement source";
     readonly workflow_run_store_absent: "no workflow run store is wired (SELF_ORCHESTRATION_ENABLED)";
@@ -94,6 +102,8 @@ export declare const CAPABILITY_FACT_WHY: {
     readonly deployment_mod_packages_absent: "no operator-declared mod package was loaded at boot (MODS_ROOT / MODS_PACKAGES)";
     readonly engine_handover_lane_absent: "the attachment lease has no handover lane here: the lease is not armed (neither ENGINE_AUTO_EXIT nor SEMA_PARENT_PID), or the deployment is multi-tenant (REQUIRE_PRINCIPAL=true)";
     readonly engine_lease_stopped: "the attachment lease has stopped observing (this engine is shutting down)";
+    readonly auto_background_off: "AUTO_BACKGROUND_ON_TIMEOUT=false: a foreground command that outruns its own timeout is killed";
+    readonly lane_cannot_adopt_running_command: "the execution lane's environment cannot move a running command to the background (only the single-user host lane with HOST_BG_ENABLED on, k8s and e2b can), so a command that outruns its timeout is killed whatever AUTO_BACKGROUND_ON_TIMEOUT says";
 };
 export type CapabilityFactWhy = keyof typeof CAPABILITY_FACT_WHY;
 /** 不可用臂。 */
@@ -163,8 +173,8 @@ export declare function sessionEventStream(d: Pick<Deps, "sessionWatch" | "sessi
     sessionStorage: HeadReadingSessionStore;
 }>;
 type SessionLister = NonNullable<OwnerAwareSessionStore["listSessions"]>;
-/** 会话枚举面:session 店的 `listSessions`,否则老形 run 店聚合。见证 = 已绑好宿主的那一只。 */
-export declare function sessionList(d: Pick<Deps, "sessionStorage" | "runStore">): Fact<"session_lister_absent", {
+/** 会话枚举面:会话店的 `listSessions` —— 唯一的会话 lister(run 店不列会话:只有 run 行、没有会话行的面答不了「有哪些会话」)。见证 = 已绑好宿主的那一只。 */
+export declare function sessionList(d: Pick<Deps, "sessionStorage">): Fact<"session_lister_absent", {
     lister: SessionLister;
 }>;
 export declare function sessionFork(d: Pick<Deps, "sessionStorage">): Fact<"session_fork_face_absent" | "session_head_face_absent", {
@@ -176,9 +186,17 @@ export declare function sessionFork(d: Pick<Deps, "sessionStorage">): Fact<"sess
 export declare function sessionPatch(d: Pick<Deps, "sessionStorage">): Fact<"session_row_faces_absent", {
     sessionStorage: WithMethods<OwnerAwareSessionStore, "headOf" | "writeSessionRowCells">;
 }>;
+/** 删除门读的会话店视图:按 id 读 = 删除门那一只头读,行格的 placement 问询 = 店自己的那一只。门照旧由属主存取器读头(`admitSessionById`),读的就是这一只。 */
+type DeletionGateStore = Pick<OwnerAwareSessionStore, "placementOf"> & {
+    readonly headOf: HeadRead;
+};
+/**
+ * 会话删除面(purge 协调器 ∧ 删除门的头读)。见证 = 协调器 + 删除门的店视图 {@link DeletionGateStore}:按 id 读是 `deletionHeadReadOf`(local 店删到一半的行也答得出属主,
+ * 开始删它的那位重发收得完;别的店 = `headOf`)—— 与协调器围栏读同一只。
+ */
 export declare function sessionDelete(d: Pick<Deps, "purgeSession" | "sessionStorage">): Fact<"session_purge_absent" | "session_head_face_absent", {
     purge: Store<"purgeSession">;
-    sessionStorage: HeadReadingSessionStore;
+    gateStore: DeletionGateStore;
 }>;
 export declare function sessionPolicy(d: Pick<Deps, "sessionPolicyStore" | "sessionStorage">): Fact<"session_policy_store_absent" | "session_head_face_absent", {
     policyStore: Store<"sessionPolicyStore">;
@@ -201,6 +219,30 @@ export declare function sessionSyncFileHistory(d: Pick<Deps, "backend" | "sessio
     historyStore: ServiceFileHistoryStore;
     blobExchange: ServiceBlobExchange;
 }>;
+type RewindFilesWhy = "file_history_store_absent" | "session_head_face_absent" | "resume_anchor_store_absent" | "execution_lane_handless" | "workspace_rebuilt_per_task" | "session_store_shared";
+/**
+ * run 外的「只恢复代码」口(`POST /v1/sessions/:id/rewind-files`,[ref])这台部署**解不解得出** —— 能力位 `sessionRewindFiles` 与该口的 501 读这一只。
+ * 四格缺一不可,每格都是那一口真要用的设施:文件历史店(引擎 `Runner.rewindFiles` 读的同一只;旋钮 `FILE_HISTORY_CAPTURE` 只关捕获、不摘店,
+ * 所以与它无关 —— 已存边界照常可回退)∧ 会话头读(属主门 + 坏档判据)∧ 锚店与 run 店(`to` 手柄经锚店翻成 entry id,未知手柄的 404 成因半句读 run 店,
+ * `history-anchor.ts`;两只同出存储后端,所以是同一格)∧ 执行车道有手
+ * (无手车道上引擎恒拒 `rewind.files_env_unsupported`:没有工作区可回退 —— 位说有而口恒拒不许发生)∧ 即时回退的工作区活过一次执行(部署形表行 `rewindableWorkspace`;
+ * 否则恢复的结果到不了下一次执行)∧ 会话店由本进程独占(local 后端:数据根被一个活进程锁住 ⇒ 引擎的进程内会话锁就是全局互斥;
+ * SQL 后端被多副本共用,而 run 外回退还没有一只跨副本的持久认领 —— 「先查认领再交引擎」只是检查不是互斥,所以在共享店上位为假、口 501,不留「检查即放行」)。
+ * 动词本身是引擎 `Runner` 的必有成员(型上必在),不是一格。
+ * 见证 = 判过在场的设施(历史店 · 手柄翻译的两只读店 · 会话店);路由在拒臂之后只读见证。
+ */
+export declare function sessionRewindFiles(d: Pick<Deps, "fileHistoryStore" | "resumeAnchorStore" | "runStore" | "sessionStorage" | "config" | "backend">): Fact<RewindFilesWhy, {
+    historyStore: ServiceFileHistoryStore;
+    anchors: HistoryAnchorReaders;
+    sessionStorage: HeadReadingSessionStore;
+}>;
+/**
+ * 同一口的 `dryRun` **带不带改动统计** —— 能力位 `sessionRewindFilesPreview`。= 立即回退可用 ∧ 店实现了 core 契约的可选座 `diffStats`
+ * (引擎在 `dryRun` 上读的就是这一座:缺座 ⇒ 应答 `preview: null`)。逐后端如实:core 的文件店有,SQL 双生没有(那一座要的逐文件预览判官
+ * `previewFileDelta` 不在 core 包根导出面上,本仓不另写一份 —— 等 core 导出它,SQL 店补这一座、本位随之转真,路由零改)。本位为假**不是**口不收 `dryRun`:口照收,答 `preview: null`
+ * (「这台给不出统计」≠「什么都不会变」);所以本事实没有 501 拒点,只有能力位读它。
+ */
+export declare function sessionRewindFilesPreview(d: Pick<Deps, "fileHistoryStore" | "resumeAnchorStore" | "runStore" | "sessionStorage" | "config" | "backend">): Fact<RewindFilesWhy | "file_history_preview_absent">;
 /** 持久审批底座(checkpoint 店)在场 —— `/v1/approvals/*` 与 `/v1/assistant/*` 整条车道、会话 wake 都站在它上面。 */
 export declare function checkpointPark(d: Pick<Deps, "checkpointStore">): Fact<"checkpoint_store_absent", {
     checkpointStore: Store<"checkpointStore">;
@@ -270,6 +312,14 @@ export declare function imagePool(d: Pick<Deps, "imageIndex">): Fact<"image_inde
 export declare function agentRoster(d: Pick<Deps, "backgroundAgentStore">): Fact<"background_agent_store_absent", {
     store: Store<"backgroundAgentStore">;
 }>;
+/**
+ * 项目登记簿在不在(`GET /v1/projects*` 的 501 与 `capabilities.projects` 同读)。登记簿只由配置中心下发(settings-schema 的本地读取集不收
+ * `projects` 域)⇒ 在场 ⟺ 中心腿在应用配置(配了中心 ∧ 非 dry-run)。这条判据住在 `centerEntitlementSourceWired`(同一件事:中心的配置
+ * 在这台部署上生效),这里读它,不写第二份条件。见证 = 登记簿那张表(`config.projects`,applyEffective 就地换代,引用恒定)。
+ */
+export declare function projectRegistry(d: Pick<Deps, "config">): Fact<"project_registry_absent", {
+    registry: ServiceConfig["projects"];
+}>;
 export declare function sendFileLedger(d: Pick<Deps, "sendFileLedger">): Fact<"sendfile_ledger_absent", {
     ledger: Store<"sendFileLedger">;
 }>;
@@ -421,6 +471,21 @@ export declare function deploymentModPackages(d: Pick<Deps, "deploymentModPackag
 }>;
 /** 自唤醒调度器挂在宿主 env 上:`SCHEDULER_ENABLED` ∧ 单用户 ∧ host 车道。装配(`boot/execution-env.ts`)与能力位同调。 */
 export declare function hostScheduler(c: Pick<ServiceConfig, "schedulerEnabled" | "requirePrincipal" | "remoteExec">): Fact<"scheduler_disabled" | "multi_tenant_deployment" | "not_host_lane">;
+/**
+ * 前台命令超时转后台(`AUTO_BACKGROUND_ON_TIMEOUT`)在这台部署上生不生效:旋钮开 ∧ 本车道的执行环境能把**运行中的**命令领养成后台任务。
+ * 「能领养」就是执行环境的 `backgroundCapabilities.supportsDetach`,三只声明它的适配器(host / k8s / e2b)上它与后台 shell 的 `supported` 是同一个值 ——
+ * 所以按能力表的 `backgroundShell` 一位读:`supported`(k8s / e2b)⇒ 能;`single-user-only`(只有 host 一行)⇒ 单用户且 host 后台 shell 开关开着才能 ——
+ * 开关是第二参 `hostBackgroundShellOn`,调用方交 `hostBackgroundShellEnabled()`(`HOST_BG_ENABLED`;host 适配器的能力位读同一只;本模块零 I/O,不自己读 env)。
+ * 对账钉 `test/auto-background-on-timeout.test.ts` 逐车道拿装配出的真执行环境的 `supportsDetach` 与本事实对拍。
+ * 旋钮先判:关着的部署不论车道都答 `auto_background_off`(运维旋钮无条件,不支持的车道不拒启,只如实报)。
+ * `/health.autoBackgroundOnTimeout` 投它的三词({@link autoBackgroundOnTimeoutWord})。
+ */
+export declare function autoBackgroundOnTimeout(c: Pick<ServiceConfig, "autoBackgroundOnTimeout" | "requirePrincipal" | "remoteExec">, hostBackgroundShellOn: boolean): Fact<"auto_background_off" | "lane_cannot_adopt_running_command">;
+/** `/health.autoBackgroundOnTimeout` 的三词闭集(顺序无语义):`armed` = 生效 · `off` = 部署关了 · `unsupported` = 旋钮开着,但本车道不能把运行中的命令转后台。 */
+export declare const AUTO_BACKGROUND_ON_TIMEOUT_WORDS: readonly ["armed", "off", "unsupported"];
+export type AutoBackgroundOnTimeoutWord = (typeof AUTO_BACKGROUND_ON_TIMEOUT_WORDS)[number];
+/** 事实 → 三词(穷举:事实多一个 why 而这里不接 = 编译红)。 */
+export declare function autoBackgroundOnTimeoutWord(f: ReturnType<typeof autoBackgroundOnTimeout>): AutoBackgroundOnTimeoutWord;
 /** 引擎能力词的事实(core `ENGINE_CAPABILITIES` 每词一只谓词,值 = 本进程的事实;`/v1/capabilities` 以顶层布尔键展开它们)—— 住在
  *  `capabilities/engine-capabilities.ts`,这里只是把它纳入「能力位只投影事实」的同一张读面,静态门认 `facts.engineCapabilityBits()` 这一只展开。 */
 export { engineCapabilityBits } from "./capabilities/engine-capabilities.js";

package/dist/capability-facts.js

@@ -4,9 +4,11 @@ import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { presentedApprovalFrameFamily, resolveStreamApprovalGate } from "./tool-approval.js";
 import { selfOrchestrationDenial } from "./task-workflow.js";
 import { centerEntitlementSourceWired } from "./runtime-caps-resolver.js";
+import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
 import { blobExchangeOf, overwriteWipeIncapable } from "./session-sync.js";
 import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, workspaceSnapshotTimeoutOf } from "./workspace-space.js";
-import { headReadOf } from "./session-incarnation.js";
+import { deletionHeadReadOf, headReadOf } from "./session-incarnation.js";
+import { executionLaneCaps, laneWiresExecutionEnv } from "./execution-lane-caps.js";
 export const CAPABILITY_FACT_WHY = {
     run_store_absent: "no durable run store is wired (DB_BACKEND=mysql|pg|local)",
     subagent_registry_absent: "the sub-agent steer registry is not wired",
@@ -17,13 +19,18 @@ export const CAPABILITY_FACT_WHY = {
     checkpoint_store_absent: "no durable checkpoint store is wired (DURABLE_APPROVAL)",
     session_audit_absent: "no session audit view is wired (needs a durable session store)",
     session_watch_absent: "the session watch registry is not wired",
-    session_lister_absent: "no session enumerator is wired (session store or run store listSessions)",
+    session_lister_absent: "no session enumerator is wired (the session store has no listSessions)",
     session_fork_face_absent: "the session store has no fork face",
     session_row_faces_absent: "the session store has no session-row faces (headOf / sessionSummaryOf / writeSessionRowCells)",
     session_purge_absent: "no session purge coordinator is wired",
     session_policy_store_absent: "no session policy store is wired",
     store_backend_absent: "no store backend is wired (DB_BACKEND=memory, multi-tenant bare boot, or half-configured SQL)",
     file_history_store_absent: "no file-history store is wired",
+    resume_anchor_store_absent: "no rewind anchor map is wired (the handle → session-entry map a rewind target is read through, with the run store an unknown handle is checked against — both come from the store backend)",
+    execution_lane_handless: "the execution lane mounts no execution environment (REMOTE_EXEC=none), so a session has no working tree to rewind",
+    workspace_rebuilt_per_task: "each task's workspace is rebuilt when the task starts on this deployment (a fresh directory, container or sandbox, or a restore from the workspace snapshot store that a rewind cannot yet take part in), so a rewind would not land in the tree the next task starts from",
+    session_store_shared: "the session store is shared by several server instances (DB_BACKEND=mysql|pg) and no durable claim spans an out-of-run rewind yet, so a rewind could interleave with a run or another rewind started on another instance",
+    file_history_preview_absent: "the file-history store implements no diffStats preview (the SQL backends)",
     session_export_absent: "the session store has no entry export faces (exportEntries / exportEntriesStream)",
     session_import_staging_absent: "the session store has no staged-import face (beginImportStaging)",
     policy_purge_absent: "the session policy store has no deleteBySession purge verb",
@@ -61,6 +68,7 @@ export const CAPABILITY_FACT_WHY = {
     read_root_grant_posture_refused: "this is not a single-user host-lane deployment (REMOTE_EXEC=host without REQUIRE_PRINCIPAL), the only posture that honors a read-directory grant",
     background_agent_store_absent: "no background-agent store is wired",
     sendfile_ledger_absent: "no SendUserFile ledger is wired",
+    project_registry_absent: `no project registry is served here: projects are published only by the configuration center (settings-schema does not read the projects domain from the local config.d), and no center configuration is applied (${WEB_ADMIN_ENV.url} unset, or ${WEB_ADMIN_ENV.dryRun} on)`,
     workflow_engine_absent: "the workflow engine is not available on this worker",
     entitlement_resolver_absent: "self-orchestration is on for a multi-tenant worker with no per-principal entitlement source",
     workflow_run_store_absent: "no workflow run store is wired (SELF_ORCHESTRATION_ENABLED)",
@@ -74,6 +82,8 @@ export const CAPABILITY_FACT_WHY = {
     deployment_mod_packages_absent: "no operator-declared mod package was loaded at boot (MODS_ROOT / MODS_PACKAGES)",
     engine_handover_lane_absent: "the attachment lease has no handover lane here: the lease is not armed (neither ENGINE_AUTO_EXIT nor SEMA_PARENT_PID), or the deployment is multi-tenant (REQUIRE_PRINCIPAL=true)",
     engine_lease_stopped: "the attachment lease has stopped observing (this engine is shutting down)",
+    auto_background_off: "AUTO_BACKGROUND_ON_TIMEOUT=false: a foreground command that outruns its own timeout is killed",
+    lane_cannot_adopt_running_command: "the execution lane's environment cannot move a running command to the background (only the single-user host lane with HOST_BG_ENABLED on, k8s and e2b can), so a command that outruns its timeout is killed whatever AUTO_BACKGROUND_ON_TIMEOUT says",
 };
 const no = (why) => ({ available: false, why });
 const yes = (w) => ({ available: true, ...w });
@@ -139,7 +149,7 @@ export function sessionEventStream(d) {
     return yes({ watch: d.sessionWatch, sessionStorage: owned.sessionStorage });
 }
 export function sessionList(d) {
-    const lister = d.sessionStorage?.listSessions?.bind(d.sessionStorage) ?? d.runStore?.listSessions?.bind(d.runStore);
+    const lister = d.sessionStorage?.listSessions?.bind(d.sessionStorage);
     return lister !== undefined ? yes({ lister }) : no("session_lister_absent");
 }
 export function sessionFork(d) {
@@ -162,7 +172,12 @@ export function sessionDelete(d) {
     const owned = sessionOwnership(d);
     if (!owned.available)
         return owned;
-    return yes({ purge: d.purgeSession, sessionStorage: owned.sessionStorage });
+    const store = owned.sessionStorage;
+    const headOf = deletionHeadReadOf(store);
+    if (headOf === undefined)
+        return no("session_head_face_absent");
+    const placementOf = store.placementOf?.bind(store);
+    return yes({ purge: d.purgeSession, gateStore: { headOf, ...(placementOf !== undefined ? { placementOf } : {}) } });
 }
 export function sessionPolicy(d) {
     if (d.sessionPolicyStore === undefined)
@@ -195,6 +210,28 @@ export function sessionSyncFileHistory(d) {
     const blobExchange = blobExchangeOf(sync.historyStore);
     return blobExchange !== undefined ? yes({ historyStore: sync.historyStore, blobExchange }) : no("blob_exchange_absent");
 }
+export function sessionRewindFiles(d) {
+    if (d.fileHistoryStore === undefined)
+        return no("file_history_store_absent");
+    const owned = sessionOwnership(d);
+    if (!owned.available)
+        return owned;
+    if (d.resumeAnchorStore === undefined || d.runStore === undefined)
+        return no("resume_anchor_store_absent");
+    if (!laneWiresExecutionEnv(d.config.remoteExec.provider))
+        return no("execution_lane_handless");
+    if (!DEPLOYMENT_SHAPE_PREDICATES.rewindableWorkspace.holds(d.config))
+        return no("workspace_rebuilt_per_task");
+    if (d.backend?.kind !== "local")
+        return no("session_store_shared");
+    return yes({ historyStore: d.fileHistoryStore, anchors: { anchors: d.resumeAnchorStore, runs: d.runStore }, sessionStorage: owned.sessionStorage });
+}
+export function sessionRewindFilesPreview(d) {
+    const rewind = sessionRewindFiles(d);
+    if (!rewind.available)
+        return rewind;
+    return rewind.historyStore.diffStats !== undefined ? YES : no("file_history_preview_absent");
+}
 export function checkpointPark(d) {
     return d.checkpointStore !== undefined ? yes({ checkpointStore: d.checkpointStore }) : no("checkpoint_store_absent");
 }
@@ -281,6 +318,9 @@ export function imagePool(d) {
 export function agentRoster(d) {
     return d.backgroundAgentStore !== undefined ? yes({ store: d.backgroundAgentStore }) : no("background_agent_store_absent");
 }
+export function projectRegistry(d) {
+    return centerEntitlementSourceWired(d.config) ? yes({ registry: d.config.projects }) : no("project_registry_absent");
+}
 export function sendFileLedger(d) {
     return d.sendFileLedger !== undefined ? yes({ ledger: d.sendFileLedger }) : no("sendfile_ledger_absent");
 }
@@ -456,9 +496,41 @@ export function hostScheduler(c) {
         return no("scheduler_disabled");
     if (c.requirePrincipal === true)
         return no("multi_tenant_deployment");
-    if (c.remoteExec?.provider !== "host")
+    if (c.remoteExec.provider !== "host")
         return no("not_host_lane");
     return YES;
 }
+export function autoBackgroundOnTimeout(c, hostBackgroundShellOn) {
+    if (c.autoBackgroundOnTimeout !== true)
+        return no("auto_background_off");
+    const cap = executionLaneCaps(c.remoteExec.provider).backgroundShell;
+    switch (cap) {
+        case "unsupported":
+            return no("lane_cannot_adopt_running_command");
+        case "supported":
+            return YES;
+        case "single-user-only":
+            return c.requirePrincipal !== true && hostBackgroundShellOn ? YES : no("lane_cannot_adopt_running_command");
+        default: {
+            const unknownCap = cap;
+            throw new Error(`auto-background fact: unknown lane capability ${String(unknownCap)}`);
+        }
+    }
+}
+export const AUTO_BACKGROUND_ON_TIMEOUT_WORDS = ["armed", "off", "unsupported"];
+export function autoBackgroundOnTimeoutWord(f) {
+    if (f.available)
+        return "armed";
+    switch (f.why) {
+        case "auto_background_off":
+            return "off";
+        case "lane_cannot_adopt_running_command":
+            return "unsupported";
+        default: {
+            const unknownWhy = f.why;
+            throw new Error(`auto-background word: unknown why ${String(unknownWhy)}`);
+        }
+    }
+}
 export { engineCapabilityBits } from "./capabilities/engine-capabilities.js";
 //# sourceMappingURL=capability-facts.js.map

package/dist/card-void.d.ts

@@ -1,5 +1,5 @@
 /**
- * **结算时作废一张本 run 自己会话上的、本服务兑现不了的卡** —— 读卡 → 卡仍 pending ∧ 卡在调用方说的那只会话上 ⇒
+ * **结算时作废一张归本 run 会话的、本服务兑现不了的卡** —— 读卡 → 卡仍 pending ∧ 卡归调用方说的那只会话(归属列,`hostSessionOf`)⇒
  * 按卡**自己的** scope 走 checkpoint 店的 `expire`(与引擎的本进程仲裁器、续跑的 resolve 同一只 CAS,恰一个赢家)。不新增任何持久态。
  *
  * 规则只有一条:**本服务兑现不了的卡不留在待决面上**。产地 = 停驻没落定就以失败收场的腿(`runs.ts` 的 `voidHeldParkCard`:后台腿与
@@ -13,16 +13,16 @@
  */
 import type { CheckpointToken } from "@sema-agent/core";
 import { type FailOpenTag } from "./observability/fail-open.js";
-/** 结算点手里那只 checkpoint 店的两个动词:读卡(取它自己的 scope / 会话 / 状态)→ 按卡自己的 scope CAS 作废。 */
+/** 结算点手里那只 checkpoint 店的三个动词:读卡(取它自己的 scope / 状态)、读它归在哪只会话上 → 按卡自己的 scope CAS 作废。 */
 export interface CardVoidPort {
     get(token: CheckpointToken): Promise<{
         readonly scope?: string;
-        readonly sessionId?: string;
         readonly status?: string;
     } | null>;
+    hostSessionOfCard(token: CheckpointToken): Promise<string | null | undefined>;
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
 }
-/** 要作废的那一张:停驻带回的凭据 + 它应在的会话(对不上就不动它 —— 只作废**这一张**)。 */
+/** 要作废的那一张:停驻带回的凭据 + 它应归的会话(本 run 的会话;对不上就不动它 —— 只作废**这一张**)。 */
 export interface CardRef {
     readonly token: CheckpointToken;
     readonly sessionId: string | undefined;

package/dist/card-void.js

@@ -10,7 +10,7 @@ export async function voidPendingCard(card, cards, tag, at) {
         const live = await cards.get(card.token);
         if (live === null || live.status !== "pending")
             return;
-        if (card.sessionId === undefined || live.sessionId !== card.sessionId || typeof live.scope !== "string") {
+        if (card.sessionId === undefined || (await cards.hostSessionOfCard(card.token)) !== card.sessionId || typeof live.scope !== "string") {
             miss("card_mismatch");
             return;
         }

package/dist/center-credential-renewer.d.ts

@@ -38,8 +38,12 @@ export interface CenterCredentialRenewer {
     renewal(): CenterCredentialRenewal;
     /** 最近一次读到的信封的访问令牌到期时刻(epoch ms;最近一次取值不是信封 ⇒ undefined)。 */
     sessionExpiresAt(): number | undefined;
-    /** 退订 + 停定时器(幂等;在飞的那一次照常落地 —— 它的结果对壳同样有用)。 */
-    stop(): void;
+    /**
+     * 退订 + 停定时器(幂等),此后不再发起续签;返回的 promise 在**已经发出**的那一次续签落定之后才 settle(新信封落盘,或按失败落定 —— 从不 reject;
+     * 没有在飞的 ⇒ 立即 settle)。进程出口(起服前探针、停机)等它:中心一旦答应了续签,旧 refresh token 就作废了,换来的新信封没落盘就退出 ⇒
+     * 下一次起服手里只剩一只被消费的令牌。续签请求本身有界(`CENTER_PULL_TIMEOUT_MS`),所以这一等有界。
+     */
+    stop(): Promise<void>;
 }
 /** `/health.centerCredential` 的 wire 形(免鉴权面:只有闭集词、时刻与计数 —— 不带路径、不带 reason 原句、不带令牌)。 */
 export interface CenterCredentialHealthView {