@sema-agent/server 7.135.0 → 7.136.0

package/dist/plugins/one-time-migrations.js

@@ -1,13 +1,13 @@
 import { SESSION_RULES_GRAMMAR, compileSessionRuleBucket, isGateKind, readSessionRulesShape, unreadableDenyEntries } from "@sema-agent/core";
 import { APPROVAL_GATE_KINDS, ASK_USER_QUESTION_TOOL_NAME, isApprovalGateKind } from "../approval-content-kind.js";
-import { APPROVAL_CARD_COLUMN_MAX_BYTES, buildCheckpointIndexCells } from "./checkpoint-index-columns.js";
+import { judgeCheckpointIndexCells } from "./checkpoint-index-columns.js";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { SCHEMA_STATEMENTS, acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
 import { PG_SCHEMA_STATEMENTS, acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn, readOpaqueJsonValueColumn, } from "./sql-json-column.js";
-import { SESSION_META_INCARNATION_COLUMN, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { incarnationFromCell, sessionFaceFromRow } from "../session-incarnation.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR } from "./store-contracts.js";
 import { PERMISSION_RULE_TABLE, purgeUndurableScopeRows } from "./permission-rule-store-sql.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
@@ -19,7 +19,6 @@ import { MAILBOX_KEYED_TABLES, mailboxKeyDeleteSql, storedMailboxKeyless } from
 const RETIRED_SESSION_RULE_BUCKETS = ["commandAllow", "commandDeny"];
 export function buildMigrationReceipts() {
     return {
-        sessionIncarnationsBackfilled: 0,
         holderDeathCodeRowsBackfilled: 0,
         allowRuleShadowRowsMigrated: 0,
         allowRuleShadowRowsUnreadable: 0,
@@ -49,16 +48,14 @@ export function buildMigrationReceipts() {
     };
 }
 function completedReport(r) {
-    const { sessionIncarnationColumn, workflowParkIndexKey, sessionRuleColumn, workflowJournalScopeColumn } = r;
-    if (sessionIncarnationColumn === undefined || workflowParkIndexKey === undefined || sessionRuleColumn === undefined || workflowJournalScopeColumn === undefined) {
-        throw new Error(`one-time migrations finished without settling a shape reading (M5 ${String(sessionIncarnationColumn)} / M9 ${String(workflowParkIndexKey)} / M17 ${String(sessionRuleColumn)} / M24 ${String(workflowJournalScopeColumn)}) — a step did not record it`);
+    const { workflowParkIndexKey, sessionRuleColumn, workflowJournalScopeColumn } = r;
+    if (workflowParkIndexKey === undefined || sessionRuleColumn === undefined || workflowJournalScopeColumn === undefined) {
+        throw new Error(`one-time migrations finished without settling a shape reading (M9 ${String(workflowParkIndexKey)} / M17 ${String(sessionRuleColumn)} / M24 ${String(workflowJournalScopeColumn)}) — a step did not record it`);
     }
-    return { ...r, sessionIncarnationColumn, workflowParkIndexKey, sessionRuleColumn, workflowJournalScopeColumn };
+    return { ...r, workflowParkIndexKey, sessionRuleColumn, workflowJournalScopeColumn };
 }
 function changedAnything(r) {
-    return (r.sessionIncarnationColumn === "added" ||
-        r.sessionIncarnationsBackfilled > 0 ||
-        r.holderDeathCodeRowsBackfilled > 0 ||
+    return (r.holderDeathCodeRowsBackfilled > 0 ||
         r.allowRuleShadowRowsMigrated > 0 ||
         r.allowRuleShadowRowsUnreadable > 0 ||
         r.workflowParkIndexKey === "reshaped" ||
@@ -122,18 +119,6 @@ export class OneTimeMigrationInterruptedError extends Error {
     }
 }
 export const ONE_TIME_MIGRATIONS = [
-    {
-        id: "M5",
-        introducedIn: "7.104.0",
-        releasedOn: "2026-09-28",
-        removableAfter: "2026-10-28",
-        removal: "删 migrateOn 的 M5 步(`session_meta` 在场探针、`incarnation` 列在场探针 + `ADD COLUMN`、空化身回填循环)与 `backfillSessionIncarnations`;" +
-            "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `sessionIncarnationColumn` / `sessionIncarnationsBackfilled`;**列本身留在中央 DDL 里**(它不是迁移的一部分)",
-        afterRemoval: "① 列不在的存量库:起服列册探针 `schema-consistency.ts`(S-547)的缺列臂拒启 `config.schema_mismatch`,拒句里的 `ALTER TABLE … ADD COLUMN` " +
-            "由同一份 DDL 生成(响亮);② 列在但行上仍是空化身(跳过了带 M5 的版本直接升):会话店头读投成活住客(`sessionFaceOfHead`)时对那一行响亮拒 " +
-            "`session.incarnation_missing`(parked 决定腿因此拒、记忆座退回按 id 绑定并 warn)—— 运维手工给那些行填一只随机令牌即可",
-        reportKeys: ["sessionIncarnationColumn", "sessionIncarnationsBackfilled"],
-    },
     {
         id: "M6",
         introducedIn: "7.116.0",
@@ -237,26 +222,13 @@ export const ONE_TIME_MIGRATIONS = [
         removableAfter: "2026-11-09",
         removal: "删 `config-lkg.ts` 的 formatVersion 2 读回迁移:`migrateV2Lkg` / `migrateDroppedIdentityRow` / `RETIRED_CATALOG_COORDINATE` 与其上的窗注;`loadLkg` 的 2 臂" +
             "(版本判据里的 `2` 与 `formatVersion === 2 ? migrateV2Lkg(…)` 那一支 —— 2 回到「unknown formatVersion」拒)、返回型的 `migrated` 位与 JSDoc 里说它的那一行、" +
-            "文件头注「2 读回时一次性迁移」那一句;`boot/web-admin.ts` 读 `read.migrated` 打 `config_lkg_migrated` 的那一行(formatVersion 1 迁移的同名事件那一行留);" +
-            "`migrateV1Lkg` 里不带 v1 的 etag 那一句旁注对 `migrateV2Lkg` 的引用(不带 etag 的规则本身留 —— v1 载荷同样没有完整的被丢条目记录);契约 §A.1d " +
+            "文件头注「2 读回时一次性迁移」那一句;`boot/web-admin.ts` 读 `read.migrated` 打 `config_lkg_migrated` 的那一行(这一行与 M15 / M22 的读回迁移共用 —— 三条都删完才整段删,先删 M13 时只去掉信封 2 → 3 那一路的 `migrated` 来源);契约 §A.1d " +
             "`droppedEntries` 一节「升级窗(如实)」那一条与 §A.1d `[config.model_refused_name_minted]` 那一条里「LKG 载体 `droppedIdentities` 读回时一次性迁移」那半句;手写 formatVersion 2 信封的测试夹具" +
             "(`test/config-lkg.test.ts`、`test/config-hot/batch1-version-ordinal.test.ts` 改写成 3;`test/models-dropped-entries-s1295.test.ts` 的旧 LKG 迁移格改钉 2 读回不可用)",
         afterRemoval: "既有响亮臂 `config_lkg_unusable`(`loadLkg` 对 2 答「unknown formatVersion 2」):2 读回 ⇒ 不可用,中心可达照拉(整拉,读腿铸出完整载体,新 LKG 按 3 覆盖)、" +
             "断着则 env 兜底,下一份干净候选重写 —— 与回滚到 7.122.0 读 3 同一种处置",
         reportKeys: [],
     },
-    {
-        id: "M14",
-        introducedIn: "7.99.0",
-        releasedOn: "2026-09-24",
-        removableAfter: "2026-10-24",
-        removal: "删 `config-lkg.ts` 的 formatVersion 1 迁移:`legacyV1LkgPath` / `migrateV1Lkg` 与其上的窗注(`loadLkg` 的 1 臂今天已是拒句,不动);" +
-            "`boot/web-admin.ts` `bootFromLkg` 里调用 `migrateV1Lkg` 的那一段(含它打 `config_lkg_migrated` / 推不出身份时响亮拒的那两行);" +
-            "`migrateV1Lkg` 的测试格(`test/config-lkg.test.ts` v1 迁移组)",
-        afterRemoval: "既有响亮臂 `config_lkg_unusable`(`loadLkg` 对 1 答「pre-identity LKG (formatVersion 1) — not read back …」):旧默认路径上的 v1 文件不再被迁进箱、" +
-            "原样留在盘上;中心可达照拉(整拉,新 LKG 按现行箱名落盘)、断着则 env 兜底",
-        reportKeys: [],
-    },
     {
         id: "M15",
         introducedIn: "7.124.0",
@@ -322,10 +294,15 @@ export const ONE_TIME_MIGRATIONS = [
         releasedOn: "2026-10-16",
         removableAfter: "2026-11-15",
         removal: "删 `src/stored-request-tool-axes-m19.ts` 整只文件(`storedToolAxesRereadM19` / `readToolAxesAsServer7129M19` / `readA2aToolAxesAsServer7131M19` / `StoredToolAxesRereadM19`);" +
-            "`boot/resolve-spec.ts` 里两条请求腿共用的那一行(`const storedToolAxes = opts?.leg === \"fresh\" ? undefined : storedToolAxesRereadM19(…)`)、递给 `resolveRequestMcp` / `resolveRequestA2a` 的两处实参与它的 import;" +
+            "`boot/resolve-spec.ts` 里两条请求腿共用的那一行(`const storedToolAxes = opts?.leg === \"fresh\" ? undefined : storedToolAxesRereadM19(…)`,在腿首、A2A 快照之前求值)、" +
+            "`snapshotRequestA2a(…, { reread: storedToolAxes !== undefined })` 的第二实参、`parts` 里的 `storedToolAxes`(类型与解构)、递给 `resolveRequestMcp` / `resolveRequestA2a` 的两处实参与它的 import;" +
             "`task-mcp.ts` 里 `resolveRequestMcp` / `classifyRequestMcp` / `classifyHonored` / `validateRequestMcpEntries` / `normalizeServer` 的 `storedToolAxes` 形参、" +
             "`toolAxesReread` 事实与运维行 `mcp_tool_axes_read_as_before_upgrade`,以及对本模块的型 import(升级前读法的词表与两只谓词住在本模块里,随它一起删);" +
-            "`task-a2a.ts` 里 `resolveRequestA2a` / `validateRequestA2aEntries` / `normalizeA2aPeer` 的 `storedToolAxes` 形参、`toolAxesReread` 事实与运维行 `a2a_tool_axes_read_as_before_upgrade`、对本模块的型 import;" +
+            "`task-a2a.ts` 里 `resolveRequestA2a` / `validateRequestA2aEntries` / `normalizeA2aPeer` 的 `storedToolAxes` 形参、`toolAxesReread` 事实与运维行 `a2a_tool_axes_read_as_before_upgrade`、对本模块的型 import," +
+            "以及只为重读座存在的克隆机器的全部名字:`cloneDeclaration` / `DeclarationClone` / `CloneFrame` / `openCloneNode` / `putCloneMember`、快照类型 `PeerSnapshot` 的字段 `toolAxesDeclared` 与 `mintPeerSnapshot` / `snapshotPeer` / `snapshotRequestA2a` 的 `reread` 形参、`toolAxesNotCloneableIssue`、读器里 `declared` 那一臂(`node:util` 的 `types` 与 `errorKindOf` 的 import 若再无别的读者一并删);" +
+            "随克隆一起退役的两句例外文字:`USAGE.md` 里 `a2a_injection_dropped` 条目 `reason` 那句「只有一臂例外 … `declaration not cloneable (<because>) — …`」与 `task-a2a.ts` 里 `A2aInjectionDrop.reason` 注的同一句例外(删后 `reason` 恒与 400 拒句同一句,回到「逐字同一句」不带例外);" +
+            "`test/task-a2a.test.ts` 里的克隆钉(标题去掉开头的 `🔴 ` 后以 `克隆钉:` 开头的各格,整格删;按这个精确前缀删,不按标题里的「M19 重读」之类泛词删 —— 那会误删同文件里的通用不变式钉),以及三格不带前缀、删码后要改写的钉:`需要「读」的两个键…` 那格的 `readRequestToolAxes` 调用方名单(`normalizeA2aPeer` 只在 M19 重读臂里调它,删后名单只剩 `mintPeerSnapshot`,标题里「与读器里 M19 重读产物的那一次」半句同删)、`读器与门的差别只有三格…` 改成两格(删 ③ 的注释行与标题里的 ③)、`请求入口快照的形…` 里 `snapshotRequestA2a(…, { reread: false })` 的第二实参(删 `reread` 形参后改成单参);" +
+            "`test/one-time-migration-window-gate.test.ts` 里 M19 一节中与克隆有关的三格(声明抽取器正负控 · 删法条与克隆名字两向对账 · 克隆钉标题前缀对账)与它们共用的帮手 `declaredNames`;" +
             "`test/mcp-tool-axes-m19.test.ts`(窗关那一格 —— 存量坏形整条不进、warn 与通告点名 `field: toolAxes` —— 改钉到 `test/task-mcp.test.ts`);" +
             "本文件的 `migrationWindowOpen`(若再无别的读者)",
         afterRemoval: "没有新的臂,接住它的是今天的读法(删码零行为变化:窗关那一刻起重读臂已经不生效):升级前存下的请求体里引擎判官判不过的 `toolAxes`,续跑重放时这一条 server 整条不进," +
@@ -463,7 +440,7 @@ export const ONE_TIME_MIGRATIONS = [
         introducedIn: "7.135.0",
         releasedOn: "2026-10-22",
         removableAfter: "2026-11-21",
-        removal: "删 migrateOn 的 M29 步(`backfillParkedApprovalCards`:列在场探针、pending 候选分页扫描、整只文档读 + 同一只派生 + CAS 写列)与 `PARKED_CARD_BACKFILL_PAGE` / `readM29Document` / `m29CardOf`;" +
+        removal: "删 migrateOn 的 M29 步(`backfillParkedApprovalCards`:列在场探针、pending 候选分页扫描、整只文档读 + 写口那一只判官 + CAS 写列)与 `PARKED_CARD_BACKFILL_PAGE` / `readM29Document` / `m29Judge`;" +
             "报告、日志行(含逐行的 `parked_approval_card_row_unreadable` / `parked_approval_card_row_too_long`)与 `NO_SQL_MIGRATIONS` 的 `parkedApprovalCardsBackfilled` / `parkedApprovalCardRowsUnreadable` / `parkedApprovalCardRowsTooLong`;`test/one-time-migrations.test.ts` 的 M29 组与 " +
             "`test/checkpoint-index-columns-db-integration.test.ts` 的 M29 格。**不随本条删**:`approval_card` 列、写口的派生、到期 facet 的生成谓词(常设)",
         afterRemoval: "没有新的臂(如实):跳过了带本条的版本直接升的库,升级前停驻、升级后仍挂着的行卡列是 NULL —— 生成谓词读门型的 facet(审批门 ⇒ SLA 拒扫腿),问答行到期被拒扫" +
@@ -475,8 +452,6 @@ export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;
 }
 export const NO_SQL_MIGRATIONS = {
-    sessionIncarnationColumn: "lazy-on-read",
-    sessionIncarnationsBackfilled: 0,
     allowRuleShadowRowsMigrated: 0,
     allowRuleShadowRowsUnreadable: 0,
     workflowParkIndexKey: "file-ledger",
@@ -592,7 +567,6 @@ async function migrateOn(db, dialect) {
     return completedReport(receipts);
 }
 async function migrateStepsOn(db, dialect, receipts) {
-    await migrateSessionIncarnations(db, dialect, receipts);
     receipts.holderDeathCodeRowsBackfilled += await db.exec(dialect === "tidb"
         ? "UPDATE task_run SET error_code = ? WHERE status = 'failed' AND error_code IS NULL AND error = ?"
         : "UPDATE task_run SET error_code = $1 WHERE status = 'failed' AND error_code IS NULL AND error = $2", [RUN_HOLDER_DEATH_CODES.stalled, RUN_STALLED_ERROR]);
@@ -1113,25 +1087,32 @@ export async function backfillParkedApprovalCards(db, dialect, receipts) {
             const [full] = await db.rows(`SELECT session_id, ${jsonColumnText(dialect, "checkpoint")} FROM checkpoint WHERE token = ${ph(1)} AND status = 'pending'`, [token]);
             if (full === undefined)
                 continue;
-            const reading = m29CardOf(full.checkpoint);
-            if (reading.kind === "unreadable") {
-                receipts.parkedApprovalCardRowsUnreadable.push({ sessionId: String(full.session_id) });
-                continue;
-            }
-            if (reading.card === null)
-                continue;
-            const bytes = Buffer.byteLength(reading.card, "utf8");
-            if (bytes > APPROVAL_CARD_COLUMN_MAX_BYTES[dialect]) {
-                receipts.parkedApprovalCardRowsTooLong.push({ sessionId: String(full.session_id), bytes });
-                continue;
+            const reading = m29Judge(full.checkpoint, dialect);
+            switch (reading.kind) {
+                case "unreadable":
+                    receipts.parkedApprovalCardRowsUnreadable.push({ sessionId: String(full.session_id) });
+                    continue;
+                case "card_too_long":
+                    receipts.parkedApprovalCardRowsTooLong.push({ sessionId: String(full.session_id), bytes: reading.bytes });
+                    continue;
+                case "cells": {
+                    const card = reading.cells.approval_card;
+                    if (card === null)
+                        continue;
+                    receipts.parkedApprovalCardsBackfilled += await db.exec(`UPDATE checkpoint SET approval_card = ${ph(1)} WHERE token = ${ph(2)} AND status = 'pending' AND approval_card IS NULL`, [card, token]);
+                    continue;
+                }
+                default: {
+                    const unhandled = reading;
+                    throw new Error(`M29: unhandled judgement ${JSON.stringify(unhandled)}`);
+                }
             }
-            receipts.parkedApprovalCardsBackfilled += await db.exec(`UPDATE checkpoint SET approval_card = ${ph(1)} WHERE token = ${ph(2)} AND status = 'pending' AND approval_card IS NULL`, [reading.card, token]);
         }
         if (page.length < PARKED_CARD_BACKFILL_PAGE)
             return;
     }
 }
-function m29CardOf(cell) {
+function m29Judge(cell, dialect) {
     let doc;
     try {
         doc = decodeJsonColumn(cell, readM29Document, "checkpoint.checkpoint (M29 approval-card backfill)");
@@ -1141,11 +1122,7 @@ function m29CardOf(cell) {
             throw e;
         return { kind: "unreadable" };
     }
-    const gate = doc.gate;
-    const pendingAction = doc.pendingAction;
-    if (typeof gate !== "object" || gate === null || typeof pendingAction !== "object" || pendingAction === null)
-        return { kind: "unreadable" };
-    return { kind: "card", card: buildCheckpointIndexCells(doc).approval_card };
+    return judgeCheckpointIndexCells(doc, dialect);
 }
 const PLACED_OWNER_SCAN_PAGE = 500;
 function placedOwnerScanSql(dialect) {
@@ -1207,68 +1184,8 @@ export async function inheritPlacedSessionOwners(db, dialect, receipts) {
             return;
     }
 }
-const INCARNATION_BACKFILL_BATCH = 500;
-async function migrateSessionIncarnations(db, dialect, receipts) {
-    if (!(await tableExists(db, dialect, "session_meta"))) {
-        receipts.sessionIncarnationColumn = "no-table";
-        return;
-    }
-    const col = SESSION_META_INCARNATION_COLUMN;
-    let column = "present";
-    if (!(await columnExists(db, dialect, "session_meta", col.name))) {
-        try {
-            await db.exec(`ALTER TABLE session_meta ADD COLUMN ${dialect === "tidb" ? col.tidb : col.pg}`);
-            column = "added";
-        }
-        catch (e) {
-            if (!(await columnExists(db, dialect, "session_meta", col.name)))
-                throw e;
-        }
-    }
-    receipts.sessionIncarnationColumn = column;
-    await backfillSessionIncarnations(db, dialect, receipts);
-}
-async function backfillSessionIncarnations(db, dialect, receipts) {
-    const remaining = async () => Number((await db.rows("SELECT COUNT(*) AS n FROM session_meta WHERE incarnation = ''"))[0]?.n ?? 0);
-    const initial = await remaining();
-    if (initial === 0)
-        return;
-    const ceiling = Math.ceil(initial / INCARNATION_BACKFILL_BATCH) * 2 + 2;
-    let written = 0;
-    let after;
-    for (let round = 0; round < ceiling; round++) {
-        const ids = (after === undefined
-            ? await db.rows(`SELECT session_id FROM session_meta WHERE incarnation = '' ORDER BY session_id LIMIT ${INCARNATION_BACKFILL_BATCH}`)
-            : await db.rows(`SELECT session_id FROM session_meta WHERE incarnation = '' AND session_id > ${dialect === "pg" ? "$1" : "?"} ORDER BY session_id LIMIT ${INCARNATION_BACKFILL_BATCH}`, [after])).map((r) => String(r.session_id));
-        if (ids.length === 0) {
-            if (after === undefined)
-                return;
-            after = undefined;
-            continue;
-        }
-        const params = [];
-        const bind = (v) => {
-            params.push(v);
-            return dialect === "pg" ? `$${params.length}` : "?";
-        };
-        const cases = ids.map((id) => `WHEN ${bind(id)} THEN ${bind(mintSessionIncarnation())}`).join(" ");
-        const inList = ids.map((id) => bind(id)).join(", ");
-        const landed = await db.exec(`UPDATE session_meta SET incarnation = CASE session_id ${cases} END WHERE incarnation = '' AND session_id IN (${inList})`, params);
-        written += landed;
-        receipts.sessionIncarnationsBackfilled += landed;
-        after = ids.length < INCARNATION_BACKFILL_BATCH ? undefined : ids[ids.length - 1];
-    }
-    const left = await remaining();
-    if (left > 0) {
-        throw new Error(`one-time migration M5: ${left} session_meta row(s) still carry an empty incarnation after ${ceiling} backfill round(s) ` +
-            `(${written} written) — refusing to start rather than serve sessions whose occupant cannot be told apart. Retry the boot; ` +
-            `if it repeats, something keeps writing rows without an incarnation (an older replica still inserting?).`);
-    }
-}
 function readingFields(r) {
     return {
-        ...(r.sessionIncarnationColumn !== undefined ? { sessionIncarnationColumn: r.sessionIncarnationColumn } : {}),
-        sessionIncarnationsBackfilled: r.sessionIncarnationsBackfilled,
         holderDeathCodeRowsBackfilled: r.holderDeathCodeRowsBackfilled,
         allowRuleShadowRowsMigrated: r.allowRuleShadowRowsMigrated,
         allowRuleShadowRowsUnreadable: r.allowRuleShadowRowsUnreadable,
@@ -1305,8 +1222,7 @@ export function logOneTimeMigrations(log, backend, report) {
         backend,
         ...readingFields(report),
         removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
-        note: "one-time persisted-data migrations (M5: the " +
-            "session incarnation column added and every session row without one minted its own token; M6: run rows failed by a " +
+        note: "one-time persisted-data migrations (M6: run rows failed by a " +
             "holder-death verdict written by an earlier version with only the sentence got the machine-readable code run.stalled / " +
             "run.orphaned; M7 writes nothing — it is the window of the refusal that keeps a suspended task whose stored allow list was written " +
             "under an earlier reading from resuming under the current one; M8: parked rows' allow-layer disclosure written by an earlier engine " +
@@ -1463,7 +1379,7 @@ function logOneTimeMigrationsInterrupted(log, backend, error) {
         ...readingFields(error.receipts),
         note: "the one-time migrations failed after committing changes: the readings on this line and the lines that follow are what this boot already committed — a retried " +
             "boot finds that work done and does not report it again, so these lines are the only record of them, written once by this boot — save them. The failure itself follows " +
-            "as this boot's refusal. A shape reading absent from this line (sessionIncarnationColumn / workflowParkIndexKey / sessionRuleColumn / workflowJournalScopeColumn) belongs to a step that did not " +
+            "as this boot's refusal. A shape reading absent from this line (workflowParkIndexKey / sessionRuleColumn / workflowJournalScopeColumn) belongs to a step that did not " +
             "finish; sessionRuleColumn absent after session_rule_row_old_grammar_entries lines means the column still carries its in-progress name — the next boot rewrites the " +
             "remaining rows (rows already rewritten are left alone) and publishes the final name",
     });

package/dist/plugins/remote-env-k8s.d.ts

@@ -110,7 +110,7 @@ export interface K8sEnvConfig extends LaneHomeConfig {
     cacheMisses?: CacheMissMemory;
     /** Operator log seat (the e2b adapter's shape): `workspace_snapshot_failed` / `workspace_snapshot_prune_failed` /
      *  `workspace_space_unavailable` / `workspace_space_unreadable_occupant` / `workspace_commit_abandoned` / `workspace_latest_dangling` /
-     *  `workspace_restore_failed` / `workspace_cache_fresh` / `workspace_cache_unavailable`. */
+     *  `workspace_restore_failed` / `workspace_snapshot_bucket_missing` / `workspace_cache_fresh` / `workspace_cache_unavailable`. */
     logger?: {
         warn(event: string, fields?: Record<string, unknown>): void;
     };
@@ -311,8 +311,8 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * Connect = the workspace SPACE's restore point. Space lane open ⇒ first wait out a commit still in flight
      * ({@link awaitSpaceCommit}: the run store's commit row), then read `<prefix>/<incarnation>/space/latest`: present ⇒
      * restore it through {@link restoreSnapshot} (the one tar download, shared with `resumeVM`; an archive that is gone ⇒
-     * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404) ⇒ a fresh pod; a read that
-     * FAILS ⇒ a loud `connect_failed` — never a silent fresh workspace (a run that believes it resumed while it did not is
+     * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404 — the key, with the bucket there) ⇒ a fresh pod; a read that
+     * FAILS ⇒ a loud `connect_failed` — a 404 `NoSuchBucket` included ({@link refuseMissingBucket}) — never a silent fresh workspace (a run that believes it resumed while it did not is
      * the worst form). Once the pod holds the workspace, this env arms its fence seat (its destroy will commit).
      * Persistence off / no store ⇒ a fresh pod, exactly as before. Persistence on but no such session (the occupant absent) ⇒ a
      * fresh pod and one `workspace_space_unavailable` line (no restore by any other key). The occupant read FAULTED ⇒ the same
@@ -425,10 +425,13 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * charset-validated upstream, so each path segment is allowlisted here (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) before it enters
      * the object key: a segment of `..` / `../x` / one containing `/` would otherwise let one tenant's snapshot key normalize into
      * another tenant's prefix (cross-tenant read on resume / clobber on suspend). The space partition (a minted v4 uuid) goes
-     * through the same one allowlist. Returns a typed error instead of signing a traversing key. Folds the old
+     * through the same one allowlist ({@link SNAPSHOT_KEY_SEGMENT}); the key prefix is a `/`-separated path of the same segments
+     * ({@link snapshotKeyPrefixProblem}, the rule the config loader refuses boot with). Returns a typed error instead of signing a traversing key. Folds the old
      * snapshotKey()+s3Presign() pair so the two call sites can't diverge.
      */
     private presignSnapshot;
+    /** The key prefix of every snapshot object this env signs — the ONE reading of `keyPrefix` (unset ⇒ the default); its form is judged in {@link presignSnapshot}. */
+    private snapshotKeyPrefix;
     /** A lane's partition prefix inside the bucket — the ONE place it is spelled (`presignSnapshot` signs under it; the reclaim reads the listing against it).
      *  The partition segment is validated by `presignSnapshot` before a URL is signed. */
     private snapshotBase;
@@ -456,9 +459,19 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** Worker-side object-store request, bounded by the control-plane RPC wall-clock — or a tighter caller deadline — and
      *  the caller's abort. */
     private storeFetch;
-    /** Read one space pointer object: its trimmed body, or `undefined` = absent (404); any other failure is a typed
+    /** Read one space pointer object: its trimmed body, or `undefined` = absent (404 — the bucket is there, the key is not); a 404 that says
+     *  `NoSuchBucket` is NOT absence — the bucket itself is missing, and the run is refused ({@link refuseMissingBucket}); any other failure is a typed
      *  `connect_failed` naming the pointer. */
     private readPointer;
+    /**
+     * The store answered the `latest` read with `404 NoSuchBucket`: the workspace snapshot bucket does not exist, so this space can be neither restored
+     * nor saved — a run started on it would work on an empty /workspace and lose everything it wrote. The env's refusal ({@link holdRefusal}), in the one
+     * space-read failure form ({@link spaceReadFailed}), naming the bucket and the knob that picks it; one `workspace_snapshot_bucket_missing{space, bucket, code, effect}`
+     * line per env (the refusal stands until destroy: later connects and operations answer it without another read or line; a retry of the run builds a fresh env, which
+     * asks the store afresh — a bucket created in between is found). The boot probe (`snapshot-bucket-presence.ts`) refuses a boot where the bucket is already missing;
+     * this is the same judgement ({@link isNoSuchBucketAnswer}) for a bucket that went missing afterwards or that the probe could not prove either way.
+     */
+    private refuseMissingBucket;
     /** Read the space's `latest` pointer. The body's shape is checked where it is used — restoreSnapshot → presignSnapshot
      *  (the one segment check). */
     private readLatest;

package/dist/plugins/remote-env-k8s.js

@@ -6,7 +6,9 @@ import { StringDecoder } from "node:string_decoder";
 import WebSocket from "ws";
 import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, kindFromMode, numEnvOr } from "./remote-shell.js";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
-import { K8S_WORKSPACE_MOUNT_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotNameOwnedBy } from "../workspace-space.js";
+import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
+import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
+import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
@@ -703,21 +705,20 @@ export class RemoteK8sExecutionEnv {
     }
     presignSnapshot(req) {
         const s3 = this.cfg.s3Snapshot;
-        const prefix = s3.keyPrefix ?? "kata";
         const [label, partition] = req.lane === "space" ? ["spaceIncarnation", req.space.incarnation] : ["sessionId", this.cfg.sessionId ?? "_"];
         const snapshotId = "snapshotId" in req ? req.snapshotId : undefined;
         const objectName = "object" in req ? req.object : undefined;
-        const safe = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
         const segments = [
             [label, partition],
             ...(snapshotId !== undefined ? [["snapshotId", snapshotId]] : []),
             ...(objectName !== undefined ? [["object", objectName]] : []),
-            ["keyPrefix", prefix],
         ];
         for (const [label, seg] of segments) {
-            if (!safe.test(seg))
+            if (!SNAPSHOT_KEY_SEGMENT.test(seg))
                 return { ok: false, error: new RemoteExecutionError("connect_failed", `unsafe snapshot key segment (${label}): refusing to build a traversing object key`) };
         }
+        if (snapshotKeyPrefixProblem(this.snapshotKeyPrefix()) !== undefined)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "unsafe snapshot key segment (keyPrefix): refusing to build a traversing object key") };
         const common = {
             endpoint: s3.endpoint,
             bucket: s3.bucket,
@@ -732,8 +733,11 @@ export class RemoteK8sExecutionEnv {
         const object = "pointer" in req ? req.pointer : "object" in req ? req.object : `${req.snapshotId}.tar.gz`;
         return { ok: true, value: presignS3Url({ ...common, key: `${base}${object}`, method: req.method }) };
     }
+    snapshotKeyPrefix() {
+        return this.cfg.s3Snapshot?.keyPrefix ?? WORKSPACE_SNAPSHOT_PREFIX_DEFAULT;
+    }
     snapshotBase(req) {
-        const prefix = this.cfg.s3Snapshot.keyPrefix ?? "kata";
+        const prefix = this.snapshotKeyPrefix();
         return req.lane === "space" ? `${prefix}/${req.space.incarnation}/space/` : `${prefix}/${this.cfg.sessionId ?? "_"}/`;
     }
     async reclaimSpaceSnapshots(spaceKey, deadline) {
@@ -825,12 +829,25 @@ export class RemoteK8sExecutionEnv {
         catch (e) {
             return spaceReadFailed(what, `: ${this.redactUrl(errorMessageOf(e), url.value)}`, e);
         }
+        if (isNoSuchBucketAnswer(res.status, body))
+            return this.refuseMissingBucket(space);
         if (res.status === 404)
             return ok(undefined);
         if (!res.ok)
             return spaceReadFailed(what, ` (HTTP ${res.status})`);
         return ok(body.trim());
     }
+    refuseMissingBucket(space) {
+        const bucket = this.cfg.s3Snapshot.bucket;
+        this.spaceLine("workspace_snapshot_bucket_missing", space, {
+            bucket,
+            code: SNAPSHOT_BUCKET_MISSING,
+            effect: "the workspace snapshot bucket does not exist in the object store (the server never creates buckets) — this run is refused rather than started on a workspace that could be neither restored nor saved",
+        });
+        return this.holdRefusal(spaceReadFailed("pointer", ` (${SNAPSHOT_BUCKET_MISSING}): the workspace snapshot bucket "${bucket}" (WORKSPACE_SNAPSHOT_BUCKET; default ${WORKSPACE_SNAPSHOT_BUCKET_DEFAULT}) does not exist in the object store — ` +
+            `refusing to start this run on a workspace that could be neither restored nor saved. Ways out: create the bucket, or set WORKSPACE_SNAPSHOT_BUCKET to one that exists, ` +
+            "or set WORKSPACE_PERSIST=off for a deployment that keeps no workspace between runs").error);
+    }
     async readLatest(space, signal) {
         const r = await this.readPointer(space, "latest", signal);
         return r.ok ? ok(r.value === undefined ? undefined : r.value) : r;
@@ -1045,7 +1062,7 @@ export class RemoteK8sExecutionEnv {
         });
     }
     async dropDanglingLatest(space, snapshotId) {
-        const prefix = this.cfg.s3Snapshot?.keyPrefix ?? "kata";
+        const prefix = this.snapshotKeyPrefix();
         const dropped = await this.writePointer(space, "latest", null);
         this.spaceLine("workspace_latest_dangling", space, {
             key: `${prefix}/${space.incarnation}/space/${snapshotId}.tar.gz`,

package/dist/plugins/s3-answer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How this server reads an S3-compatible store's ANSWER — the one place a "the bucket itself is not there" reading is spelled.
+ *
+ * A 404 from an object store means two different things: `NoSuchKey` (the bucket is there, this object is not — a space's first run,
+ * a pointer never written) and `NoSuchBucket` (the bucket was never created — a deployment error no run can fix by retrying). Reading
+ * the second as the first turns a missing bucket into a silently empty workspace on every run. The ONLY evidence of a missing bucket is
+ * a 404 whose body carries the S3 error code `NoSuchBucket`: a bare 404, a 404 from a proxy or a wrong path, a 403 (credentials that
+ * cannot list ≠ no bucket) and a 5xx prove nothing about the bucket. Every consumer asks this one predicate: the boot probe of a
+ * configured bucket (`MinioBlobBackend.probeBucket`) and the runtime read of the workspace `latest` pointer (`remote-env-k8s.ts`).
+ */
+/** The code a run's refusal / operator line carries when the store answered "no such bucket" (the `workspace_snapshot_bucket_missing` line's `code`). */
+export declare const SNAPSHOT_BUCKET_MISSING = "snapshot_bucket_missing";
+/** Does this answer prove the bucket is missing? `status` = the HTTP status, `body` = the answer's text (an S3 error document). */
+export declare function isNoSuchBucketAnswer(status: number, body: string): boolean;
+//# sourceMappingURL=s3-answer.d.ts.map

package/dist/plugins/s3-answer.js

@@ -0,0 +1,5 @@
+export const SNAPSHOT_BUCKET_MISSING = "snapshot_bucket_missing";
+export function isNoSuchBucketAnswer(status, body) {
+    return status === 404 && /<Code>NoSuchBucket<\/Code>/.test(body);
+}
+//# sourceMappingURL=s3-answer.js.map

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -5,6 +5,8 @@
  * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
  * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
  * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ * `WORKSPACE_SNAPSHOT_BUCKET`(缺省 `workspaces`,k8s 工作区快照桶)同病且更隐:起服不核它 ⇒ 缺桶 / 无权限时每条 run 读 `latest` 得 404,
+ * 被读成「这个空间头一回」,从空目录起;run 末的保存虽失败,报的却是一条不点名桶的 curl 404,没有一行说「桶没建」。
  *
  * ## 形(一条规则,不加特例)
  *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
@@ -13,24 +15,57 @@
  *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
  *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
  *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
- *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 核的桶是一张角色表({@link SNAPSHOT_BUCKET_ROLES},闭集两行)里的两只,**同一只探针、同一条规则、同一只兜底口**:
+ *    `session` = `config.snapshotBlobStore.bucket`(`SESSION_SNAPSHOT_BUCKET`;SendUserFile 的私桶缺省同一只);
+ *    `workspace` = k8s 车道的 `config.remoteExec.s3Snapshot.bucket`(`WORKSPACE_SNAPSHOT_BUCKET`,缺省 `workspaces`)—— 车道没开 / 没配对象存储 ⇒ 没有这只桶,不核。
+ *    拒句的旋钮名跟着桶走(缺的是哪只桶就只点哪只的旋钮)。公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 运行期的对应臂:工作区 `latest` 指针读答 404 `NoSuchBucket`(同一条「桶不在」判据 `isNoSuchBucketAnswer`)⇒ 那条 run 响亮拒绝,不再读成「空间头一回」
+ *    (`remote-env-k8s.ts` `readPointer`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
  */
 import type { ServiceConfig } from "../config-types.js";
 import { type StoreOpenWaitClock } from "./store-open-wait.js";
 type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** 被核的桶的角色(闭集):`session` = 快照 blob / SendUserFile 私桶;`workspace` = k8s 工作区快照桶。 */
+export type SnapshotBucketRole = "session" | "workspace";
+/** 两只被核的桶的角色表 —— 拒句、`snapshot_bucket_wait` 披露与 {@link ensureSnapshotBuckets} 都读这一张(缺一行 = 编译错)。 */
+export declare const SNAPSHOT_BUCKET_ROLES: {
+    readonly session: {
+        readonly noun: "snapshot bucket";
+        readonly knob: "SESSION_SNAPSHOT_BUCKET";
+        readonly defaultName: "session-snapshots";
+        readonly consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)";
+        readonly createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment";
+    };
+    readonly workspace: {
+        readonly noun: "workspace snapshot bucket";
+        readonly knob: "WORKSPACE_SNAPSHOT_BUCKET";
+        readonly defaultName: "workspaces";
+        readonly consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing";
+        readonly createHint: "";
+    };
+};
 /** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
 /** 缺桶的拒启句(唯一铸点)。 */
 /** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */
-export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number): string;
+export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number, role?: SnapshotBucketRole): string;
 /** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
 /**
- * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * boot 期核一次**一只**快照桶。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
  * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ * @param role 这只桶的角色({@link SNAPSHOT_BUCKET_ROLES}):决定拒句点名哪根旋钮;缺省 `session`。
  */
 export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
     warn(msg: string, meta?: Record<string, unknown>): void;
-}, clock?: StoreOpenWaitClock): Promise<void>;
+}, clock?: StoreOpenWaitClock, role?: SnapshotBucketRole): Promise<void>;
+/**
+ * boot 期核**这份配置要用的全部**快照桶(`boot/stores.ts`,排在打开任何店之前):角色表的每一行,配置里有这只桶才核 —— 会话快照桶 ⇐ 配了对象存储
+ * (`snapshotBlobStore`);工作区快照桶 ⇐ k8s 车道配了对象存储(`remoteExec.s3Snapshot`)。依角色表顺序逐只核,每只各有自己的 `STORE_LOCK_WAIT_MS` 窗
+ * (缺的桶才占窗;在场的桶一次探针就过),第一只缺的桶即拒启。
+ */
+export declare function ensureSnapshotBuckets(config: Pick<ServiceConfig, "snapshotBlobStore" | "remoteExec" | "storeLockWaitMs">, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}): Promise<void>;
 export {};
 //# sourceMappingURL=snapshot-bucket-presence.d.ts.map

package/dist/plugins/snapshot-bucket-presence.js

@@ -1,21 +1,39 @@
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { MinioBlobBackend } from "./blob-backend.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_ROLES = {
+    session: {
+        noun: "snapshot bucket",
+        knob: "SESSION_SNAPSHOT_BUCKET",
+        defaultName: SESSION_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)",
+        createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment",
+    },
+    workspace: {
+        noun: "workspace snapshot bucket",
+        knob: "WORKSPACE_SNAPSHOT_BUCKET",
+        defaultName: WORKSPACE_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing",
+        createHint: "",
+    },
+};
 export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
 class SnapshotBucketMissing extends Error {
     constructor() {
         super("snapshot bucket missing");
     }
 }
-export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs, role = "session") {
+    const r = SNAPSHOT_BUCKET_ROLES[role];
     const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first check (STORE_LOCK_WAIT_MS=0: no wait)";
-    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the snapshot bucket "${bucket}" (SESSION_SNAPSHOT_BUCKET; default session-snapshots) does not exist there ${waited} — refusing to boot: ` +
-        `the server never creates buckets, so every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever). ` +
-        `Next: create the bucket (mc mb <alias>/${bucket}; this version's sema-up scripts create it — re-run them on an existing sema-up deployment), or set SESSION_SNAPSHOT_BUCKET to a bucket that exists.`);
+    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the ${r.noun} "${bucket}" (${r.knob}; default ${r.defaultName}) does not exist there ${waited} — refusing to boot: ` +
+        `the server never creates buckets, so ${r.consequence}. ` +
+        `Next: create the bucket (mc mb <alias>/${bucket}${r.createHint}), or set ${r.knob} to a bucket that exists.`);
 }
 export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
-export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+export async function ensureSnapshotBucket(store, waitMs, logger, clock, role = "session") {
     const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
     let verdict;
     try {
@@ -24,11 +42,11 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
             if (r.state === "missing")
                 throw new SnapshotBucketMissing();
             return r;
-        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
+        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { role, bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
     }
     catch (err) {
         if (err instanceof SnapshotBucketMissing)
-            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs, role), { cause: err });
         if (!isStoreOpenWindowExpired(err))
             throw err;
         verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
@@ -37,4 +55,14 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
         recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
     }
 }
+export async function ensureSnapshotBuckets(config, logger) {
+    const wanted = [
+        ["session", config.snapshotBlobStore],
+        ["workspace", config.remoteExec?.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
+    ];
+    for (const [role, store] of wanted) {
+        if (store)
+            await ensureSnapshotBucket(store, config.storeLockWaitMs, logger, undefined, role);
+    }
+}
 //# sourceMappingURL=snapshot-bucket-presence.js.map