@sema-agent/server 7.124.1 → 7.125.1

package/dist/capability-facts.js

@@ -3,6 +3,7 @@ import { resolveStreamApprovalGate } from "./tool-approval.js";
 import { selfOrchestrationDenial } from "./task-workflow.js";
 import { centerEntitlementSourceWired } from "./runtime-caps-resolver.js";
 import { overwriteWipeIncapable } from "./session-sync.js";
+import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_DEFAULT } from "./workspace-space.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",
@@ -15,6 +16,7 @@ export const CAPABILITY_FACT_WHY = {
     session_leaf_face_absent: "the session store has no leaf-read face (sessionStorage.getLeafId)",
     session_lister_absent: "no session enumerator is wired (session store or run store listSessions)",
     session_fork_face_absent: "the session store has no fork face",
+    session_row_faces_absent: "the session store has no session-row faces (sessionFaceOf / sessionSummaryOf / patchSessionMeta)",
     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)",
@@ -58,6 +60,8 @@ export const CAPABILITY_FACT_WHY = {
     scheduler_disabled: "the self-wake scheduler is off (SCHEDULER_ENABLED)",
     multi_tenant_deployment: "this is a multi-tenant deployment (REQUIRE_PRINCIPAL=true)",
     not_host_lane: "the execution lane is not the single-user host lane (REMOTE_EXEC=host)",
+    not_k8s_lane: "the execution lane is not the k8s pod sandbox (REMOTE_EXEC=k8s)",
+    workspace_snapshot_store_absent: "no workspace snapshot store is configured (MINIO_ENDPOINT / MINIO_ACCESS_KEY / MINIO_SECRET_KEY)",
 };
 const no = (why) => ({ available: false, why });
 const yes = (w) => ({ available: true, ...w });
@@ -123,6 +127,12 @@ export function sessionFork(d) {
         return no("session_owner_face_absent");
     return yes({ sessionStorage: s });
 }
+export function sessionPatch(d) {
+    const s = d.sessionStorage;
+    if (s?.sessionFaceOf === undefined || s.patchSessionMeta === undefined)
+        return no("session_row_faces_absent");
+    return yes({ sessionStorage: s });
+}
 export function sessionDelete(d) {
     if (d.purgeSession === undefined)
         return no("session_purge_absent");
@@ -151,6 +161,8 @@ export function sessionSync(d) {
         return no("session_export_absent");
     if (s.beginImportStaging === undefined)
         return no("session_import_staging_absent");
+    if (s.sessionFaceOf === undefined || s.sessionSummaryOf === undefined || s.patchSessionMeta === undefined)
+        return no("session_row_faces_absent");
     if (overwriteWipeIncapable(d.sessionPolicyStore))
         return no("policy_purge_absent");
     return yes({ backend: d.backend, sessionStorage: s, historyStore: d.fileHistoryStore });
@@ -342,6 +354,14 @@ export function workflowsJournal(d) {
     const journal = workflowJournal(d);
     return journal.available ? yes({ store: runs.store, journal: journal.journal }) : journal;
 }
+export function workspaceSpace(c) {
+    const rx = c.remoteExec;
+    if (rx?.provider !== "k8s")
+        return no("not_k8s_lane");
+    if (!rx.s3Snapshot)
+        return no("workspace_snapshot_store_absent");
+    return yes({ policy: { persist: rx.workspacePersist ?? WORKSPACE_PERSIST_DEFAULT, keep: rx.workspaceSnapshotKeep ?? WORKSPACE_SNAPSHOT_KEEP_DEFAULT } });
+}
 export function hostScheduler(c) {
     if (c.schedulerEnabled !== true)
         return no("scheduler_disabled");

package/dist/config-catalog.js

@@ -2,6 +2,7 @@ import { CROSS_SESSION_INBOUND_SETTINGS, CROSS_SESSION_DIALOG_EXPIRY_VALUES } fr
 import { GLOBAL_SCOPE } from "@sema-agent/settings-schema/api/scopes";
 import { WEB_ADMIN_ENV, DOMAIN_SCHEMAS, buildRetiredEnvWire } from "@sema-agent/settings-schema";
 import { CENTER_CREDENTIAL_RENEW_LEAD_DEFAULT_MS, CENTER_CREDENTIAL_RENEW_LEAD_MAX_MS, CENTER_CREDENTIAL_RENEW_LEAD_MIN_MS } from "./center-credential-renewer.js";
+import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_RANGE } from "./workspace-space.js";
 import { THINKING_FORMATS } from "./model-compat.js";
 import { AUTO_MODE_CLASSIFIER_TIMEOUT_BOUNDS, CENTER_BASE_URL_RULE, CONFIG_PROVIDER_WORDS, DRAIN_SECOND_SIGNAL_MIN_GAP_BOUNDS, DRAIN_SECOND_SIGNAL_MIN_GAP_DEFAULT_MS, FIRST_BYTE_TIMEOUT_BOUNDS, FLEET_LEASE_OUTAGE_MAX_DEFAULT_MS, RESILIENCE_DEFAULTS, TASK_WRITE_FACE_ESCALATIONS } from "./config-types.js";
 import { webSearchProviderFromEnv, WEB_SEARCH_PROVIDERS } from "./plugins/web-search.js";
@@ -193,7 +194,7 @@ export const CONFIG_CATALOG = [
     r("K8S_NAMESPACE", "orchestration", "string", "沙箱 pod namespace"),
     r("K8S_RUNTIME_CLASS", "orchestration", "string", "沙箱 pod runtimeClass(Kata 等)"),
     r("K8S_SANDBOX_IMAGE", "orchestration", "string", "k8s 车道沙箱镜像(REMOTE_EXEC=k8s 必需件)"),
-    r("K8S_TIMEOUT_MS", "orchestration", "number", "k8s 单命令超时(ms)"),
+    r("K8S_TIMEOUT_MS", "orchestration", "number", "k8s 沙箱 pod 寿命(activeDeadlineSeconds,ms;整只 pod 的泄漏护栏,后台任务超时也被它钳;各条命令的超时见工具超时)"),
     r("K8S_TOKEN", "orchestration", "secret", "k8s API token(缺席走 in-cluster SA)", { danger: SEC }),
     r("KUBERNETES_SERVICE_HOST", "orchestration", "string", "平台注入的 in-cluster k8s API host(K8S_API_URL 缺席时用)"),
     r("KUBERNETES_SERVICE_PORT", "orchestration", "string", "平台注入的 in-cluster k8s API 端口(缺省 443)"),
@@ -479,7 +480,9 @@ export const CONFIG_CATALOG = [
     r("WORKFLOW_SIZE_GUIDELINE", "orchestration", "enum", "Workflow 工具卡的规模建议(advisory;typo 拒启)", { enumValues: ["small", "medium", "large", "unrestricted"], configKey: "workflowSizeGuideline" }),
     r("WORKFLOW_TOTAL_TIMEOUT_MS", "orchestration", "number", "workflow 脚本总时限(ms;0/负不是禁用 —— 无禁用臂)", { staticDefault: "3600000" }),
     r("WORKSPACE_FILE_MAX_BYTES", "limitsHttp", "number", "已随 workspace 浏览面退役(S-15):值照常校验/落值,应用于空(重启也不生效)", { envTiming: "inert", configKey: "workspaceFileMaxBytes", center: cLimits("workspaceFileMaxBytes", { timing: "inert" }) }),
+    r("WORKSPACE_PERSIST", "orchestration", "enum", "k8s 工作区跨轮保留(opt-in):space = 每条 run 结束把 /workspace 快照进本会话住客的空间、下一条 run 开始恢复最近一份(开着时有已知残窗:提交标记晚于拆环境上界落地 ⇒ 上一条的改动可能被覆盖,见 USAGE §9.3b);off = 每轮新建(缺省)。设了 space 却没配快照存储(MINIO_* 三键)⇒ 不生效,起服一行 workspace_persist_unavailable 点名缺键;前提:会话店读得出会话住客(local / SQL 会话店),内存会话店设 space(且配了快照存储)⇒ 拒启;词表外拒启", { enumValues: WORKSPACE_PERSIST_WORDS, staticDefault: WORKSPACE_PERSIST_DEFAULT, danger: DATA }),
     r("WORKSPACE_SNAPSHOT_BUCKET", "orchestration", "string", "k8s 工作区快照桶", { derivedDefaultNote: "缺席 ⇒ workspaces" }),
+    r("WORKSPACE_SNAPSHOT_KEEP", "orchestration", "number", `k8s 工作区每个空间(会话住客)保留的快照份数(整数 [${WORKSPACE_SNAPSHOT_KEEP_RANGE.min}, ${WORKSPACE_SNAPSHOT_KEEP_RANGE.max}];写新快照后删最老的;域外拒启)`, { staticDefault: String(WORKSPACE_SNAPSHOT_KEEP_DEFAULT), danger: DATA }),
     r("WORKSPACE_SNAPSHOT_PREFIX", "orchestration", "string", "k8s 工作区快照 key 前缀"),
     r("WORKSPACE_SNAPSHOT_TTL_SEC", "orchestration", "number", "k8s 工作区快照 presign TTL(秒)"),
     r("WORKTREE_ALLOWED_ROOTS", "orchestration", "csv", "worktree 隔离纵深白名单(缺省 = [repoRoot])", { danger: SEC }),

package/dist/config-d-migration.js

@@ -2,7 +2,8 @@ import { stat } from "node:fs/promises";
 import { join } from "node:path";
 import { RETIRED_DOMAINS, formatConfigPath, isRetiredDomainName } from "@sema-agent/settings-schema";
 import { PORTABLE_DOMAINS, migrateConfigDirectory, nodeConfigDirectoryIo } from "@sema-agent/settings-schema/node";
-const READ_BACK_DOCUMENTS = [...PORTABLE_DOMAINS, ...Object.keys(RETIRED_DOMAINS).filter(isRetiredDomainName)];
+import { REMOTE_EXEC_DOCUMENT } from "@sema-agent/settings-schema/remote-exec";
+const READ_BACK_DOCUMENTS = [...PORTABLE_DOMAINS, ...Object.keys(RETIRED_DOMAINS).filter(isRetiredDomainName), REMOTE_EXEC_DOCUMENT];
 const errnoOf = (err) => (err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : undefined);
 export async function migrateLocalConfigDirectory(root) {
     const dir = join(root, "config.d");

package/dist/config-lkg.d.ts

@@ -1,4 +1,5 @@
 import { type MigrationReceipt } from "@sema-agent/settings-schema/one-time-migrations";
+import type { PromptsDomainFaces } from "./prompts-domain-validate.js";
 /** 落盘信封。`effective`/`etag` 逐字=当时的 fetchEffective 返回(JSON verbatim 面)。`formatVersion` 的语义见头注(4 = 载荷是 settings-schema 11 的形)。 */
 export interface PersistedLkg {
     formatVersion: 4;
@@ -59,9 +60,11 @@ export interface LkgReadMigration {
  * 文件缺席/JSON 坏/信封形不对/worker 或凭证身份不匹配(防同名文件跨 worker / 跨账号串包;`CONFIG_LKG_PATH`
  * 单一路径时这是唯一的一道)/载荷有迁不动的旧形({@link migrateLkgPayload})/prompts 面复判失败。
  * `migrated`:读回时做过一次性迁移(信封 2 → 3 或载荷的 settings-schema 迁移)—— 调用方响亮打一行,并把交回的 4 写回原位。
+ * `prompts`:候选判官对这份载荷 prompts 面交出的已判形值(`undefined` = 载荷不带 prompts 键)—— 调用方采纳 prompts 直接用它。
  */
 export declare function loadLkg(path: string, worker: string | undefined, identity: string): Promise<{
     lkg: PersistedLkg;
+    prompts: PromptsDomainFaces | undefined;
     migrated?: LkgReadMigration;
 } | {
     lkg?: undefined;
@@ -104,7 +107,7 @@ export type LegacyLkgMigration = {
  *  2. 旧文件没有(ENOENT / ENOTDIR)或不是 formatVersion 1 信封 ⇒ `none`。旧默认路径上却读不了 / 不是 JSON ⇒
  *     `not-migrated`(响亮,不当它不存在);`CONFIG_LKG_PATH` 同路径时这两形由 loadLkg 自己报(不重复打一行)。
  *  3. v1 信封只记 worker:唯一推得出身份的形是拉取令牌(身份 = worker,`pullTokenIdentity`)。此刻身份正是它、worker
- *     对得上、载荷过 {@link migrateLkgPayload}(迁成 11 的形;迁不动 ⇒ 响亮拒、不写箱)与 {@link lkgPayloadProblem} ⇒ **先写后退役**(修复验证 N9):先按新格式把它写进 `binPath`(原子写,
+ *     对得上、载荷过 {@link migrateLkgPayload}(迁成 11 的形;迁不动 ⇒ 响亮拒、不写箱)与 {@link lkgPayloadJudged} ⇒ **先写后退役**(修复验证 N9):先按新格式把它写进 `binPath`(原子写,
  *     0600),写成了才把旧文件改名 `<legacyPath>.migrated-v1`。写失败 ⇒ `not-migrated`,旧文件原样留在原位,下一次
  *     照常可迁;写成之后改名失败 ⇒ 仍是 `migrated`(`retireError` 响一行),箱已在 ⇒ 下一次按判序 1 不再看旧文件。
  *     同路径(`CONFIG_LKG_PATH`)时新箱的写入会原子替换旧文件本身,所以旧字节在写之前留一份 `.migrated-v1` 副本

package/dist/config-lkg.js

@@ -3,7 +3,7 @@ import { migrateEffectiveSnapshot } from "@sema-agent/settings-schema/one-time-m
 import { formatConfigPath } from "@sema-agent/settings-schema";
 import { join, dirname, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
-import { validatePromptsDomain } from "./prompts-domain-validate.js";
+import { judgeConfigCandidate } from "./web-admin-client/candidate-gate.js";
 import { centerStateBin, pullTokenIdentity } from "./center-credential.js";
 import { configRootOf } from "./sema-config-dir.js";
 export function defaultSkillCacheDir(config) {
@@ -74,12 +74,12 @@ export async function loadLkg(path, worker, identity) {
     const payload = migrateLkgPayload(envelope.effective);
     if ("refused" in payload)
         return { reason: payload.refused };
-    const problem = lkgPayloadProblem(payload.effective, envelope.etag);
-    if (problem !== undefined)
-        return { reason: problem };
+    const judged = lkgPayloadJudged(payload.effective, envelope.etag);
+    if ("problem" in judged)
+        return { reason: judged.problem };
     const lkg = { ...envelope, formatVersion: 4, effective: payload.effective };
     const migrated = formatVersion !== 4 || payload.receipts.length > 0;
-    return migrated ? { lkg, migrated: { fromFormat: formatVersion, ...(note !== undefined ? { note } : {}), receipts: payload.receipts } } : { lkg };
+    return migrated ? { lkg, prompts: judged.prompts, migrated: { fromFormat: formatVersion, ...(note !== undefined ? { note } : {}), receipts: payload.receipts } } : { lkg, prompts: judged.prompts };
 }
 export function migrateLkgPayload(effective) {
     const m = migrateEffectiveSnapshot(effective);
@@ -122,7 +122,14 @@ function migrateV2Lkg(lkg) {
             (hasRetired ? "; the retired carrier models.droppedIdentities was moved to models.droppedCatalogEntries" : ""),
     };
 }
-function lkgPayloadProblem(effective, etag) {
+function lkgPayloadJudged(effective, etag) {
+    const problem = lkgPayloadShapeProblem(effective, etag);
+    if (problem !== undefined)
+        return { problem };
+    const verdict = judgeConfigCandidate({ effective: effective });
+    return verdict.verdict === "clean" ? { prompts: verdict.prompts } : { problem: "prompts face fails re-validation" };
+}
+function lkgPayloadShapeProblem(effective, etag) {
     if (effective === null || typeof effective !== "object")
         return "bad effective";
     if (etag !== undefined && typeof etag !== "string")
@@ -142,9 +149,6 @@ function lkgPayloadProblem(effective, etag) {
                 return `bad effective.${domain}.${arrayKey}`;
         }
     }
-    const promptsRaw = eff.prompts;
-    if (promptsRaw !== undefined && !validatePromptsDomain(promptsRaw).ok)
-        return "prompts face fails re-validation";
     return undefined;
 }
 export function legacyV1LkgPath(config, worker) {
@@ -197,9 +201,9 @@ export async function migrateV1Lkg(o) {
     const payload = migrateLkgPayload(v1.effective);
     if ("refused" in payload)
         return refuse(`its payload cannot be migrated to the current settings form (${payload.refused})`);
-    const problem = lkgPayloadProblem(payload.effective, v1.etag);
-    if (problem !== undefined)
-        return refuse(`its payload is unusable (${problem})`);
+    const judged = lkgPayloadJudged(payload.effective, v1.etag);
+    if ("problem" in judged)
+        return refuse(`its payload is unusable (${judged.problem})`);
     const retiredTo = `${o.legacyPath}.migrated-v1`;
     let retireError;
     if (sameFile) {

package/dist/config-provider.d.ts

@@ -1,4 +1,4 @@
-import { type DroppedConfigEntry } from "./web-admin-client/read-warnings.js";
+import { type DroppedConfigEntry, type UnreadConfigFile } from "./web-admin-client/read-warnings.js";
 import { FileConfigStore } from "@sema-agent/settings-schema/node";
 import { type EffectiveConfig as AgentConfigEffective, type EffectiveReadWarning } from "@sema-agent/settings-schema";
 import { fetchEffective as remoteFetchEffective, fetchSkillContent as remoteFetchSkillContent, type EffectiveConfig } from "./web-admin-client/facade.js";
@@ -23,6 +23,8 @@ import type { ConfigProviderWord } from "./config-types.js";
 /** `droppedEntries`(S-704 ②):schema 逐条丢掉的条目(坐标 + 字段诊断,已脱敏;S-1295 起每行带闭集词 `reasonCode`)—— **不**进候选门,
  *  调用方逐条响亮点名、其余照用;缺席 = 这次读零逐条丢弃(与 `domainErrors` 同一种缺席即无的形)。其中的目录条目同一次折叠另记进
  *  `effective.models.droppedCatalogEntries`(`GET /v1/models.droppedEntries` 的源,与 `models` 同世代)。 */
+/** `unreadFiles`:`config.d` 里读腿根本不读的文件(不是域 / 不是便携域)—— **不**进候选门(不是读的域判形失败),调用方一份一行
+ *  `config_unread_file` 点名、其余照用;缺席 = 没有(本地读腿才会有)。 */
 export type FetchEffectiveResult = {
     effective: EffectiveConfig;
     etag?: string;
@@ -31,6 +33,7 @@ export type FetchEffectiveResult = {
         error: string;
     }>;
     droppedEntries?: DroppedConfigEntry[];
+    unreadFiles?: UnreadConfigFile[];
     readWarnings: readonly EffectiveReadWarning[];
     credentialIdentity?: string;
 } | null;

package/dist/config-provider.js

@@ -107,6 +107,7 @@ export class LocalConfigProvider {
             readWarnings,
             ...(errors.length > 0 ? { domainErrors: errors } : {}),
             ...(droppedEntries.length > 0 ? { droppedEntries } : {}),
+            ...(folded.unreadFiles.length > 0 ? { unreadFiles: folded.unreadFiles } : {}),
         };
     }
     async fetchSkillContent(contentHash) {

package/dist/config-types.d.ts

@@ -907,6 +907,12 @@ export interface ServiceConfigFlat {
             keyPrefix?: string;
             presignTtlSec?: number;
         };
+        /** Workspace persistence by space key (`WORKSPACE_PERSIST`) and snapshots kept per space key (`WORKSPACE_SNAPSHOT_KEEP`).
+         *  The loader always mints both on this arm; optional only so hand-built configs may omit them. Effective policy =
+         *  the capability fact `workspaceSpace` (`capability-facts.ts`, the one reading: defaults applied there, absent store ⇒
+         *  unavailable). */
+        workspacePersist?: import("./workspace-space.js").WorkspacePersist;
+        workspaceSnapshotKeep?: number;
     } | {
         provider: "ssh";
         host: string;
@@ -1572,7 +1578,8 @@ export interface ServiceConfigFlat {
      *  per-region via the registry effective-config (shell B3) later. */
     sandboxPkgSource?: string;
     /** Auto-generate a session title at first submit (one cheap-model call per
-     *  session, write-once; the user rename layer is BFF-side). Default ON; `SESSION_AUTO_TITLE=false` opts out. */
+     *  session; fills a NULL title only — a title the user set via `PATCH /v1/sessions/:id` is never overwritten).
+     *  Default ON; `SESSION_AUTO_TITLE=false` opts out. */
     sessionAutoTitle: boolean;
     /** S-178:上面那一位的来源(同一张四词表)。本键**不进 posture**(缺省恒 true,两形同值)——
      *  报来源是为了让运维分辨「这台机器显式关了自动标题」与「它本来就开着」;壳此前注 `false` 的那条
@@ -2033,10 +2040,10 @@ export interface ServiceConfigFlat {
      *  single task from burning the shared cloud key. Enforced by core (failed + errorCode budget.*). */
     maxTaskCostUsd: number;
     maxTaskTokens: number;
-    /** Per-principal CUMULATIVE cost ceiling (USD) within a rolling window — blocks a tenant's NEXT task
+    /** Per-principal CUMULATIVE cost ceiling (USD) within a clock-aligned fixed window — blocks a tenant's NEXT task
      *  once their accumulated spend crosses it. 0/unset = no per-principal quota. */
     maxPrincipalCostUsd: number;
-    /** Rolling window (seconds) for the per-principal cost quota. Default 86400 (1 day). */
+    /** Clock-aligned fixed window (seconds, in [1, 1e10]; bucket = floor(now / window)) for the per-principal cost quota. Default 86400 (1 day). */
     costQuotaWindowSec: number;
     /** Degradation to a cheaper model `to` (a catalog name) instead of hard-failing (core 1.39/1.40):
      *  - **prospective** (1.40, `atCostFraction`): near-budget — at `atCostFraction × maxCostUsd` switch at

package/dist/config.js

@@ -20,11 +20,13 @@ import { normalizeSshFingerprint } from "./ssh-host-key.js";
 import { buildReadFacePostureNotice, readFaceForPosture } from "./read-face-posture.js";
 import { THINKING_LEVELS, THINKING_FORMATS, buildModelCompat, isThinkingFormat, isThinkingTier } from "./model-compat.js";
 import {} from "./posture-source.js";
+import { COST_QUOTA_WINDOW_SEC_RANGE, costQuotaWindowSecInRange } from "./observability/cost-quota.js";
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { describeUnmatchableRuleName, ruleEntryToolName, unmatchableRuleNameOf } from "./namespaced-rule-name.js";
 import { bakeOperatorPrincipalsRefusal, bakeRunnerCredentialRefusal, centerIdentityRefusal, halfOpenDirectDoorRefusal, leaderDurableStoreRefusal, operatorPrincipalsRequiredRefusal } from "./config-invariants.js";
 import { declaredSemaConfigDir } from "./sema-config-dir.js";
 import { lkgPathOverrideOf } from "./config-lkg.js";
+import { WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS, WORKSPACE_SNAPSHOT_KEEP_DEFAULT, WORKSPACE_SNAPSHOT_KEEP_RANGE } from "./workspace-space.js";
 import { REMOTE_EXEC_PROVIDER_WORDS, executionLaneOf, executionLaneRequiredRefusal, isSingleMachineDefaultLane, laneRequiredEnv } from "./execution-lane-caps.js";
 import { MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS } from "@sema-agent/settings-schema/execution-lanes";
 import { AUTONOMY_MODES } from "./runtime-governance.js";
@@ -1853,19 +1855,7 @@ function parseOrchestrationDomain(ctx) {
                         ...((n) => (n !== undefined ? { timeoutMs: n } : {}))(optNumEnvStrict("K8S_TIMEOUT_MS")),
                         ...(process.env.K8S_MEMORY ? { memory: process.env.K8S_MEMORY } : {}),
                         ...(process.env.K8S_CPU ? { cpu: process.env.K8S_CPU } : {}),
-                        ...(process.env.MINIO_ENDPOINT && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
-                            ? {
-                                s3Snapshot: {
-                                    endpoint: process.env.MINIO_ENDPOINT,
-                                    bucket: process.env.WORKSPACE_SNAPSHOT_BUCKET ?? "workspaces",
-                                    accessKey: process.env.MINIO_ACCESS_KEY,
-                                    secretKey: process.env.MINIO_SECRET_KEY,
-                                    ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
-                                    ...(process.env.WORKSPACE_SNAPSHOT_PREFIX ? { keyPrefix: process.env.WORKSPACE_SNAPSHOT_PREFIX } : {}),
-                                    ...((n) => (n !== undefined ? { presignTtlSec: n } : {}))(optNumEnvStrict("WORKSPACE_SNAPSHOT_TTL_SEC")),
-                                },
-                            }
-                            : {}),
+                        ...k8sWorkspaceStore(),
                     }
                     :
                         process.env.REMOTE_EXEC === "ssh" && process.env.SSH_HOST && process.env.SSH_USER && process.env.SSH_PRIVATE_KEY
@@ -2039,7 +2029,14 @@ function parseLimitsHttpDomain() {
         maxTaskCostUsd: numEnv("MAX_TASK_COST_USD", "0"),
         maxTaskTokens: numEnv("MAX_TASK_TOKENS", "0"),
         maxPrincipalCostUsd: numEnv("MAX_PRINCIPAL_COST_USD", "0"),
-        costQuotaWindowSec: numEnv("COST_QUOTA_WINDOW_SEC", "86400"),
+        costQuotaWindowSec: (() => {
+            const sec = numEnv("COST_QUOTA_WINDOW_SEC", "86400");
+            if (!costQuotaWindowSecInRange(sec)) {
+                const { min, max } = COST_QUOTA_WINDOW_SEC_RANGE;
+                throw new Error(`env COST_QUOTA_WINDOW_SEC=${sec} must be in [${min}, ${max}] seconds — it is the length of the clock-aligned per-principal cost-quota window, and its end must be a representable instant; there is no "off" here: MAX_PRINCIPAL_COST_USD=0 (or unset) turns the quota off (the web-admin refuses the same value)`);
+            }
+            return sec;
+        })(),
         reapIntervalSec: numEnv("REAP_INTERVAL_SEC", "60"),
         runStaleSec: numEnv("REAP_RUN_STALE_SEC", "120"),
         toolResultTtlSec: (() => {
@@ -2385,6 +2382,39 @@ export function attachConfigGroups(flat) {
     }
     return flat;
 }
+function k8sWorkspaceStore() {
+    const workspacePersist = enumEnv("WORKSPACE_PERSIST", WORKSPACE_PERSIST_DEFAULT, WORKSPACE_PERSIST_WORDS);
+    const workspaceSnapshotKeep = numEnvBounded("WORKSPACE_SNAPSHOT_KEEP", String(WORKSPACE_SNAPSHOT_KEEP_DEFAULT), WORKSPACE_SNAPSHOT_KEEP_RANGE.min, WORKSPACE_SNAPSHOT_KEEP_RANGE.max);
+    if (!Number.isInteger(workspaceSnapshotKeep))
+        throw new Error(`env WORKSPACE_SNAPSHOT_KEEP=${workspaceSnapshotKeep} must be an integer (a count of snapshots kept per space key)`);
+    const endpoint = process.env.MINIO_ENDPOINT;
+    const accessKey = process.env.MINIO_ACCESS_KEY;
+    const secretKey = process.env.MINIO_SECRET_KEY;
+    if (!endpoint || !accessKey || !secretKey) {
+        if (workspacePersist === "space") {
+            const missing = [...(endpoint ? [] : ["MINIO_ENDPOINT"]), ...(accessKey ? [] : ["MINIO_ACCESS_KEY"]), ...(secretKey ? [] : ["MINIO_SECRET_KEY"])];
+            CONFIG_NOTICES.push({
+                level: "warn",
+                event: "workspace_persist_unavailable",
+                fields: { missing: missing.join(","), effect: "k8s workspace starts empty every run (no snapshot store); set the missing keys, or drop WORKSPACE_PERSIST=space (the default is off) to silence this line" },
+            });
+        }
+        return { workspacePersist, workspaceSnapshotKeep };
+    }
+    return {
+        workspacePersist,
+        workspaceSnapshotKeep,
+        s3Snapshot: {
+            endpoint,
+            bucket: process.env.WORKSPACE_SNAPSHOT_BUCKET ?? "workspaces",
+            accessKey,
+            secretKey,
+            ...(process.env.MINIO_REGION ? { region: process.env.MINIO_REGION } : {}),
+            ...(process.env.WORKSPACE_SNAPSHOT_PREFIX ? { keyPrefix: process.env.WORKSPACE_SNAPSHOT_PREFIX } : {}),
+            ...((n) => (n !== undefined ? { presignTtlSec: n } : {}))(optNumEnvStrict("WORKSPACE_SNAPSHOT_TTL_SEC")),
+        },
+    };
+}
 export function loadConfig() {
     EXEC_LANE_NOTICE = undefined;
     rejectRetiredEnvs();

package/dist/env-facts.d.ts

@@ -101,8 +101,8 @@ warn: (msg: string, meta?: object) => void): Promise<string | undefined>;
  *  这条豁免目录算不算绝对」——引擎自本版起按**树的家族**判(`isAbsoluteForFamily`,家族从树的 root/cwd 拼法
  *  读,不看宿主 OS),本函数用的是 Node 宿主口径。**posix 家族两者逐字同判**(2026-09-12 实测六形全同),
  *  而本闸又只在 `hostSemanticsLane` 上场(路径就是这台 worker 自己的盘)⇒ 今天零分歧,不改。**分歧只在 win
- *  家族的 `/`-开头无盘符那一类**(Node 说绝对、引擎说未完全限定)。判据与坐标属主见 `task-cwd.ts` 的
- *  {@link import("./task-cwd.js").isValidCwd} 顶注(同一条接缝,那里是唯一成文点,这里不复述第二份)。 */
+ *  家族的 `/`-开头无盘符那一类**(Node 说绝对、引擎说未完全限定)。同一条接缝的读数钉在 `test/task-cwd.test.ts`「[ref] 路径家族接缝」格
+ *  (cwd 那一侧的判官是契约包的 `isAbsoluteHostPath`,posix 口径;那里是唯一成文点,这里不复述第二份)。 */
 export declare function acceptShellScratchpadDir(raw: unknown, opts: {
     requirePrincipal: boolean;
     hostSemanticsLane: boolean;

package/dist/env-facts.js

@@ -1,7 +1,8 @@
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { dirCoversPath, isValidCwd, normalizeAbsolutePathLexically } from "./task-cwd.js";
+import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
+import { dirCoversPath, normalizeAbsolutePathLexically } from "./task-cwd.js";
 const MAX_STR = 64;
 const MAX_CAPS = 16;
 const MAX_PATH = 160;
@@ -118,7 +119,7 @@ export function screenShellScratchpadDir(raw, opts) {
     return canonical;
 }
 export function scratchpadCoveringTaskRoot(args) {
-    if (!args.cwdHonored || !isValidCwd(args.cwd))
+    if (!args.cwdHonored || !isAbsoluteHostPath(args.cwd))
         return undefined;
     const candidates = [];
     const shell = screenShellScratchpadDir(args.shellScratchpadDir, { requirePrincipal: args.requirePrincipal, hostSemanticsLane: true, warn: () => { } });

package/dist/fleet/fleet-bus.d.ts

@@ -62,7 +62,9 @@ export interface FleetTaskRow {
     /** Owning principal (= the run's scope). The `/v1/fleet/stream` route filters to the caller's scope (owner-gated)
      *  unless the caller is fleet-wide (operator / trace-token). NOT rendered — a tenant-isolation field. */
     scope?: string;
-    /** Fleet per-session scope: the run's rootTaskId (= sessionId). The
+    /** Fleet per-session scope: the **originating session id** — the id the caller submitted under, which is what a
+     *  shell sends as `?session=`. It is NOT the run's tree root (`rootTaskId`, the canonical taskId that forwarded
+     *  subagents nest under — a different quantity, see {@link fleetRunPublisher}'s `run` param). The
      *  `/v1/fleet/stream` route ALSO filters to the caller's `?session=` when present, so a TUI footer shows only the
      *  CURRENT session's rows, not OTHER sessions of the same principal (the "他会话 token" leak). NOT rendered — a
      *  scoping field like `scope`. Absent ⇒ the row is visible to any same-principal caller (back-compat, unscoped). */
@@ -128,6 +130,11 @@ export interface FleetTaskRow {
         turns?: number;
         costMicroUsd?: number;
     };
+    /** 顶层 run 的终局残局键(同上「只在终态帧出现」):k8s 车道工作区跨轮保留开着时,这条 run 结束的工作区快照
+     *  **没存上**(上传或 `latest` 指针写失败)⇒ `"failed"`;下一条 run 恢复的是上一份。成功 / 没开保留 / 不是 k8s
+     *  车道 / 这条 run 没碰过沙箱 / 结局晚于终态帧(只留运维行)⇒ 缺席。只承载本 run 在终态帧之前落定的结局。
+     *  单成员闭集;源 = `workspace-snapshot-residual.ts`。ADDITIVE / tolerate-absent。 */
+    workspaceSnapshot?: "failed";
     resumable?: boolean;
     editedFiles?: Array<{
         path: string;
@@ -179,7 +186,8 @@ export interface FleetWorkflowRow {
     description?: string;
     /** Owning principal (= the workflow run's scope). Same owner-gate as FleetTaskRow. NOT rendered. */
     scope?: string;
-    /** #3 fleet per-session scope (rootTaskId = sessionId): the `/v1/fleet/stream` `?session=` filter. NOT rendered. */
+    /** #3 fleet per-session scope (the originating session id, same quantity as {@link FleetTaskRow.sessionId}): the
+     *  `/v1/fleet/stream` `?session=` filter. NOT rendered. */
     sessionId?: string;
     status: string;
     doneCount?: number;
@@ -556,7 +564,13 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
     scope: string;
     name: string;
     description?: string;
+    /** 嵌子代树的根:这条腿的 canonical core taskId(`spec.taskId ?? sessionId`)。转发子代的 `parentTaskId` 与它相等
+     *  ⇒ 挂在 run 行下,否则挂在那个子代的行下。**只管嵌套**,不是行的会话键。 */
     rootTaskId?: string;
+    /** 发起会话 id —— 行上 `sessionId`(`GET /v1/fleet/stream?session=` 的过滤键)的**唯一来源**。
+     *  与 `rootTaskId` 是两个量(交互 / bg / 续跑三条腿的树根都是 taskId,不是会话 id)。
+     *  缺席 = 没有会话的 run:行不打键(既有 UNTAGGED 语义:同 principal 全会话可见,内容降权)。 */
+    sessionId?: string;
 }): {
     onStart: () => void;
     onEvent: (ev: {
@@ -592,11 +606,7 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
     /** [ref]①/(a) 案:`residuals` = 顶层 run 的终局残局键(有源才传,见 FleetTaskRow 上的键注)。
      *  只有**真终态**(completed/failed/killed)帧带残局——parked(suspended/needs_review)的行还活着,
      *  没有「终局」可言,误传也不上帧。 */
-    onTerminal: (status: RunStatusForFleet, residuals?: {
-        usage?: FleetTaskRow["usage"];
-        stoppedBy?: string;
-        transcriptId?: string;
-    }) => void;
+    onTerminal: (status: RunStatusForFleet, residuals?: FleetRunResiduals) => void;
 };
 /** The run-scoped publisher handle (returned by `fleetRunPublisher`). Threaded into `runInBackground` so a
  *  background run TRANSITIONS its fleet row exactly like the sync POST /v1/runs leg does. */
@@ -610,6 +620,12 @@ export type FleetRunPublisher = ReturnType<typeof fleetRunPublisher>;
  *  留着旧形不会红 —— 那正是危险所在:`TaskResult` 上已经没有 `errorCode` 这个键了,可结构性可选参数照样
  *  编译通过,于是 `stoppedBy:"user"` 会**静默地永远不再铸**(取消的 run 在舰队行上从此看不出是被人杀的)。
  *  终局事实一律走因由,`failureCodeOf` 是本仓读「这次失败带的是哪个码」的唯一形。 */
+export type FleetRunResiduals = {
+    usage?: FleetTaskRow["usage"];
+    stoppedBy?: string;
+    transcriptId?: string;
+    workspaceSnapshot?: "failed";
+};
 export declare function fleetRunResiduals(result: {
     sessionId?: string;
     terminal?: TerminalCause;
@@ -619,11 +635,7 @@ export declare function fleetRunResiduals(result: {
         toolCalls?: number;
         costMicroUsd?: number;
     };
-} | null | undefined): {
-    usage?: FleetTaskRow["usage"];
-    stoppedBy?: string;
-    transcriptId?: string;
-};
+} | null | undefined): FleetRunResiduals;
 /**
  * [ref]-B (core 1.240.0) — the PROCESS-LEVEL background-child fleet publisher, wired once
  * onto `RunnerDeps.onBackgroundChildEvent`. Unlike {@link fleetRunPublisher} (per-leg: dies at leg settle —

package/dist/fleet/fleet-bus.js

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import { DURABLE_AGENT_HANDLE_RE, deriveAgentDisplayStatus, isDelegatedAgentTerminal } from "@sema-agent/core";
 import { persistedPlaneOf } from "../terminal.js";
+import { takeWorkspaceSnapshotFailure } from "./workspace-snapshot-residual.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets } from "../trace/redact.js";
 import { buildRunObjectivePreview } from "../user-authored-text.js";
@@ -200,7 +201,7 @@ export function fleetRunPublisher(bus, run) {
         return { onStart: () => undefined, onEvent: () => undefined, onForwardEvent: () => undefined, onChildTerminal: () => false, onTerminal: () => undefined };
     let tokens = 0;
     const startedAt = Date.now();
-    const sessionField = run.rootTaskId ? { sessionId: run.rootTaskId } : {};
+    const sessionField = run.sessionId ? { sessionId: run.sessionId } : {};
     const children = new Set();
     const childStartedAt = new Map();
     const childByToolCall = new Map();
@@ -332,6 +333,7 @@ export function fleetRunPublisher(bus, run) {
                     ...(residuals.usage ? { usage: residuals.usage } : {}),
                     ...(residuals.stoppedBy ? { stoppedBy: residuals.stoppedBy } : {}),
                     ...(residuals.transcriptId ? { transcriptId: residuals.transcriptId } : {}),
+                    ...(residuals.workspaceSnapshot ? { workspaceSnapshot: residuals.workspaceSnapshot } : {}),
                 }
                 : {};
             bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt, ...res });
@@ -362,6 +364,7 @@ export function fleetRunResiduals(result) {
         ...(Object.keys(usage).length > 0 ? { usage } : {}),
         ...(persistedPlaneOf(result).errorCode === "cancelled" ? { stoppedBy: "user" } : {}),
         ...(result.sessionId ? { transcriptId: result.sessionId } : {}),
+        ...(takeWorkspaceSnapshotFailure(result.sessionId) ? { workspaceSnapshot: "failed" } : {}),
     };
 }
 export function fleetBackgroundChildPublisher(bus, log) {

package/dist/fleet/workspace-snapshot-residual.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Open the outcome seat of the env being built for a run of `sessionId` (call it when the env is built, before its
+ * connect). Closes the session's earlier seats and drops what they left pending. The returned function is the env's
+ * `onWorkspaceSnapshot` seat — a closure ⇒ `create*`.
+ */
+export declare function createRunWorkspaceSnapshotSeat(sessionId: string): (outcome: "saved" | "failed") => void;
+/** Take-once, at settle: `true` when this session's run reported a failed run-end snapshot that no settle has carried yet.
+ *  Closes the session's seat (see the header: the frame ends "before the frame"). */
+export declare function takeWorkspaceSnapshotFailure(sessionId: string | undefined): boolean;
+//# sourceMappingURL=workspace-snapshot-residual.d.ts.map

package/dist/fleet/workspace-snapshot-residual.js

@@ -0,0 +1,35 @@
+const pending = new Map();
+const seats = new Map();
+const CAP = 1024;
+let generation = 0;
+function bounded(map) {
+    while (map.size > CAP) {
+        const oldest = map.keys().next().value;
+        if (oldest === undefined)
+            return;
+        map.delete(oldest);
+    }
+}
+export function createRunWorkspaceSnapshotSeat(sessionId) {
+    const mine = ++generation;
+    seats.delete(sessionId);
+    seats.set(sessionId, mine);
+    bounded(seats);
+    pending.delete(sessionId);
+    return (outcome) => {
+        if (seats.get(sessionId) !== mine)
+            return;
+        pending.delete(sessionId);
+        if (outcome === "saved")
+            return;
+        pending.set(sessionId, true);
+        bounded(pending);
+    };
+}
+export function takeWorkspaceSnapshotFailure(sessionId) {
+    if (sessionId === undefined)
+        return false;
+    seats.delete(sessionId);
+    return pending.delete(sessionId);
+}
+//# sourceMappingURL=workspace-snapshot-residual.js.map