@sema-agent/server 7.118.0 → 7.119.0

package/dist/plugins/local-session-store.js

@@ -1,13 +1,17 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { SessionError, validateEntriesForImport } from "@sema-agent/core";
+import { FileSessionRepo, SessionError, validateEntriesForImport } from "@sema-agent/core";
+import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { createZodColumnReader, decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
+import { createLogger } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
-import { openSessionForItself } from "../session-records-skipped-notice.js";
+import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
+import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
@@ -30,18 +34,32 @@ function userText(entry) {
     }
     return null;
 }
-const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline", incarnation: "session-incarnation (the write that needed it failed loudly)" };
+const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline", "session-meta": "session owner + incarnation (the write that needed it failed loudly)" };
+function readSessionMetaCell(cell) {
+    return typeof cell === "string" ? { incarnation: cell, owner: undefined } : cell;
+}
+const ownerRecorded = (cell) => cell !== undefined && readSessionMetaCell(cell).owner !== undefined;
+const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), z.object({ incarnation: z.string(), owner: z.string().nullable() }).strict()]));
+const readSessionMetaSidecar = createZodColumnReader(SESSION_META_SIDECAR);
+function ownerClaimWindowOpen() {
+    const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M10");
+    if (window === undefined)
+        throw new Error("LocalSessionStore: the one-time migration registry has no M10 row (the local session-owner claim window) — the claim arm outlived its registry row; delete it with that row");
+    return migrationWindowOpen(window, new Date().toISOString().slice(0, 10));
+}
 const SIDECAR_MAP_STATE_BY_PATH = new Map();
-class SidecarStringMap {
+class SidecarMap {
     path;
     label;
+    read;
     onUnreadable;
     onWriteFailed;
     strict;
     own = { entries: new Map(), writeChain: Promise.resolve() };
-    constructor(path, label, onUnreadable, onWriteFailed, strict = false) {
+    constructor(path, label, read, onUnreadable, onWriteFailed, strict = false) {
         this.path = path;
         this.label = label;
+        this.read = read;
         this.onUnreadable = onUnreadable;
         this.onWriteFailed = onWriteFailed;
         this.strict = strict;
@@ -59,7 +77,7 @@ class SidecarStringMap {
         if (!st.loaded) {
             st.loaded = (async () => {
                 try {
-                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), readStringRecordColumn, this.label);
+                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), this.read, this.label);
                     for (const [id, v] of Object.entries(parsed)) {
                         if (!st.entries.has(id))
                             st.entries.set(id, v);
@@ -73,45 +91,60 @@ class SidecarStringMap {
                         return;
                     }
                     const kind = e instanceof SqlJsonColumnError ? e.problem : (e?.code ?? "unreadable");
-                    throw new Error(`${this.label} is unreadable (${kind}) — refusing to read or mint session incarnations until it is repaired: a replacement ` +
-                        `token for an existing session would make it a different occupant (its memory opt-out would stop binding it), and a write ` +
-                        `would overwrite the unreadable bytes. The file is left in place at ${path}.`);
+                    throw new Error(`${this.label} is unreadable (${kind}) — refusing to read or write session owners and incarnations until it is repaired: ` +
+                        `reading it as empty would turn every session ownerless, and a replacement incarnation token for an existing session would ` +
+                        `make it a different occupant (its memory opt-out would stop binding it); a write would overwrite the unreadable bytes. ` +
+                        `The file is left in place at ${path}.`);
                 }
             })();
         }
         return st.loaded;
     }
     persist() {
-        return this.commit(() => () => undefined);
+        return this.commit(() => true);
     }
     commit(change) {
         const path = this.path;
         const st = this.state;
         const link = st.writeChain.then(async () => {
-            const undo = change(st.entries);
-            if (undo === undefined || !path)
-                return true;
-            try {
-                const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-                await writeFile(tmp, JSON.stringify(Object.fromEntries(st.entries)), "utf8");
-                await rename(tmp, path);
+            const base = new Map(st.entries);
+            const draft = new Map(base);
+            if (!change(draft))
                 return true;
+            if (path) {
+                try {
+                    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+                    await writeFile(tmp, JSON.stringify(Object.fromEntries(draft)), "utf8");
+                    await rename(tmp, path);
+                }
+                catch (e) {
+                    this.onWriteFailed(e);
+                    return false;
+                }
             }
-            catch (e) {
-                undo();
-                this.onWriteFailed(e);
-                return false;
+            for (const key of new Set([...base.keys(), ...draft.keys()])) {
+                if (draft.has(key) === base.has(key) && draft.get(key) === base.get(key))
+                    continue;
+                if (draft.has(key))
+                    st.entries.set(key, draft.get(key));
+                else
+                    st.entries.delete(key);
             }
+            return true;
         });
         st.writeChain = link.then(() => undefined);
         return link;
     }
 }
+export function createLocalSessionRepo(root) {
+    return new FileSessionRepo(root, {
+        onCorruptRead: createCorruptReadFailOpenSeat("server.session-repo.corrupt-record-skipped", noteReplayInSessionOpenScope),
+    });
+}
 export class LocalSessionStore {
     repo;
     retention = UNMANAGED_RETENTION;
     pending = new Map();
-    owners = new Map();
     lastActivity = new Map();
     lastTaskRun = new Map();
     stagings = new Map();
@@ -124,48 +157,63 @@ export class LocalSessionStore {
     sidecarPath;
     titles;
     instructionSources;
-    incarnations;
-    constructor(repo, dataDir) {
+    meta;
+    log;
+    constructor(repo, dataDir, opts) {
         this.repo = repo;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
-        const sidecar = (file, which, strict = false) => new SidecarStringMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
-        this.titles = sidecar("session-titles.json", "title");
-        this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source");
-        this.incarnations = sidecar("session-incarnations.json", "incarnation", true);
-    }
-    async writeIncarnation(sessionId, next) {
-        await this.incarnations.ensureLoaded();
-        const committed = await this.incarnations.commit((entries) => {
-            const before = entries.get(sessionId);
-            const value = next(before);
-            if (value === undefined || value === before)
-                return undefined;
-            entries.set(sessionId, value);
-            return () => {
-                if (before === undefined)
-                    entries.delete(sessionId);
-                else
-                    entries.set(sessionId, before);
-            };
+        this.log = opts?.log ?? createLogger();
+        const sidecar = (file, which, read, strict = false) => new SidecarMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, read, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
+        this.titles = sidecar("session-titles.json", "title", readStringRecordColumn);
+        this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source", readStringRecordColumn);
+        this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
+    }
+    async writeMeta(sessionId, next) {
+        await this.meta.ensureLoaded();
+        let changed = false;
+        const committed = await this.meta.commit((draft) => {
+            const value = next(draft.get(sessionId));
+            if (value === undefined)
+                return false;
+            draft.set(sessionId, value);
+            changed = true;
+            return true;
         });
         if (!committed)
-            throw new SessionError("storage", `LocalSessionStore: session-incarnation sidecar write failed for session ${sessionId} — nothing was recorded`);
+            throw new SessionError("storage", `LocalSessionStore: session-meta sidecar write failed for session ${sessionId} — nothing was recorded`);
+        return changed;
     }
-    mintIncarnation(sessionId) {
-        return this.writeIncarnation(sessionId, () => mintSessionIncarnation());
+    async dropMeta(sessionId) {
+        await this.meta.ensureLoaded();
+        const committed = await this.meta.commit((draft) => draft.delete(sessionId));
+        if (!committed)
+            throw new SessionError("storage", `LocalSessionStore: session-meta sidecar write failed while deleting session ${sessionId} — its owner/incarnation cell is still on disk`);
     }
-    ensureIncarnation(sessionId) {
-        return this.writeIncarnation(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+    async existsInRepo(sessionId) {
+        try {
+            await this.repo.open({ id: sessionId, createdAt: "" });
+            return true;
+        }
+        catch (e) {
+            if (isNotFound(e))
+                return false;
+            throw e;
+        }
     }
-    async sessionFaceOf(sessionId) {
-        const owner = await this.ownerOf(sessionId);
-        if (owner === undefined)
-            return undefined;
-        await this.ensureIncarnation(sessionId);
-        const incarnation = this.incarnations.state.entries.get(sessionId);
-        if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
+    async metaOf(sessionId) {
+        await this.meta.ensureLoaded();
+        const cell = this.meta.state.entries.get(sessionId);
+        if (cell !== undefined)
+            return readSessionMetaCell(cell);
+        if (!(await this.existsInRepo(sessionId)))
             return undefined;
-        return sessionFaceFromRow(sessionId, owner, incarnation);
+        await this.writeMeta(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+        const minted = this.meta.state.entries.get(sessionId);
+        return minted === undefined ? undefined : readSessionMetaCell(minted);
+    }
+    async sessionFaceOf(sessionId) {
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation);
     }
     async probeTitle(sessionId) {
         await this.titles.ensureLoaded();
@@ -186,17 +234,11 @@ export class LocalSessionStore {
     }
     async recordInstructionSource(sessionId, expected, source) {
         await this.instructionSources.ensureLoaded();
-        const committed = await this.instructionSources.commit((entries) => {
-            const before = entries.get(sessionId);
-            if (!sameInstructionSourceBaseline(decodeInstructionSource(before), expected))
-                return undefined;
-            entries.set(sessionId, encodeInstructionSource(source));
-            return () => {
-                if (before === undefined)
-                    entries.delete(sessionId);
-                else
-                    entries.set(sessionId, before);
-            };
+        const committed = await this.instructionSources.commit((draft) => {
+            if (!sameInstructionSourceBaseline(decodeInstructionSource(draft.get(sessionId)), expected))
+                return false;
+            draft.set(sessionId, encodeInstructionSource(source));
+            return true;
         });
         if (!committed)
             throw new Error("LocalSessionStore: instruction-source sidecar write failed — baseline not recorded");
@@ -271,11 +313,10 @@ export class LocalSessionStore {
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
-            await this.incarnations.ensureLoaded();
+            await this.meta.ensureLoaded();
             const session = await this.repo.create({});
             const id = (await session.getMetadata()).id;
-            this.owners.set(id, null);
-            await this.mintIncarnation(id);
+            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner: null }));
             return { session: session, sessionId: id };
         }
         if (opts?.requireExisting)
@@ -290,8 +331,6 @@ export class LocalSessionStore {
     async load(sessionId, requireExisting = false) {
         try {
             const session = await openSessionForItself(sessionId, () => this.repo.open({ id: sessionId, createdAt: "" }));
-            if (!this.owners.has(sessionId))
-                this.owners.set(sessionId, null);
             return { session: session, sessionId };
         }
         catch (e) {
@@ -299,56 +338,47 @@ export class LocalSessionStore {
                 throw e;
             if (requireExisting)
                 throw e;
-            await this.incarnations.ensureLoaded();
+            await this.meta.ensureLoaded();
             const session = await this.repo.create({ id: sessionId });
-            await this.mintIncarnation(sessionId);
-            if (!this.owners.has(sessionId))
-                this.owners.set(sessionId, null);
+            await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null }));
             return { session: session, sessionId };
         }
     }
     async register(sessionId, owner) {
-        if (this.owners.has(sessionId))
+        await this.meta.ensureLoaded();
+        if (ownerRecorded(this.meta.state.entries.get(sessionId)))
             return;
-        await this.incarnations.ensureLoaded();
-        this.owners.set(sessionId, owner);
-        try {
-            await this.repo.open({ id: sessionId, createdAt: "" });
-            await this.ensureIncarnation(sessionId);
-        }
-        catch (e) {
-            if (!isNotFound(e))
-                throw e;
+        const existed = await this.existsInRepo(sessionId);
+        const claim = existed && owner !== null && ownerClaimWindowOpen();
+        const wrote = await this.writeMeta(sessionId, (before) => {
+            if (ownerRecorded(before))
+                return undefined;
+            if (!existed || claim)
+                return { incarnation: existed && before !== undefined ? readSessionMetaCell(before).incarnation : mintSessionIncarnation(), owner };
+            return before === undefined ? mintSessionIncarnation() : undefined;
+        });
+        if (!existed && wrote)
             await this.repo.create({ id: sessionId });
-            await this.mintIncarnation(sessionId);
-        }
+        if (claim && wrote)
+            this.log.info("session_owner_claimed", { sessionId });
     }
     async ownerOf(sessionId) {
-        if (this.owners.has(sessionId))
-            return this.owners.get(sessionId) ?? null;
-        try {
-            await this.repo.open({ id: sessionId, createdAt: "" });
-            this.owners.set(sessionId, null);
-            return null;
-        }
-        catch (e) {
-            if (isNotFound(e))
-                return undefined;
-            throw e;
-        }
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : (meta.owner ?? null);
     }
     async getHead(sessionId) {
-        if (!this.owners.has(sessionId) && (await this.ownerOf(sessionId)) === undefined)
+        const before = await this.metaOf(sessionId);
+        if (before === undefined)
             return undefined;
-        const owner = this.owners.get(sessionId) ?? null;
         const leafId = await this.getLeafId(sessionId);
-        if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
+        const cell = this.meta.state.entries.get(sessionId);
+        const after = cell === undefined ? undefined : readSessionMetaCell(cell);
+        if (after === undefined || after.incarnation !== before.incarnation || (after.owner ?? null) !== (before.owner ?? null))
             return undefined;
-        return { owner, leafId };
+        return { owner: before.owner ?? null, leafId };
     }
-    restampOwner(sessionId, owner) {
-        if (this.owners.has(sessionId))
-            this.owners.set(sessionId, owner);
+    async restampOwner(sessionId, owner) {
+        await this.writeMeta(sessionId, (before) => (before === undefined ? undefined : { incarnation: readSessionMetaCell(before).incarnation, owner }));
     }
     async touch(sessionId) {
         this.lastActivity.set(sessionId, new Date().toISOString());
@@ -371,10 +401,12 @@ export class LocalSessionStore {
     async listSessions(opts) {
         await this.ensureLoaded();
         await this.titles.ensureLoaded();
+        await this.meta.ensureLoaded();
         const metas = await this.repo.list();
         const all = [];
         for (const meta of metas) {
-            const owner = this.owners.has(meta.id) ? (this.owners.get(meta.id) ?? null) : null;
+            const cell = this.meta.state.entries.get(meta.id);
+            const owner = cell === undefined ? null : (readSessionMetaCell(cell).owner ?? null);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
             const firstActivityAt = meta.createdAt || new Date(0).toISOString();
@@ -423,12 +455,11 @@ export class LocalSessionStore {
         }
     }
     async fork(sourceId, owner) {
-        await this.incarnations.ensureLoaded();
+        await this.meta.ensureLoaded();
         try {
             const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
             const id = (await session.getMetadata()).id;
-            this.owners.set(id, owner);
-            await this.mintIncarnation(id);
+            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner }));
             return id;
         }
         catch (e) {
@@ -471,10 +502,9 @@ export class LocalSessionStore {
     async importEntriesAs(sessionId, owner, entries, incarnation) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
-        await this.incarnations.ensureLoaded();
+        await this.meta.ensureLoaded();
         await this.repo.importEntries(sessionId, owner ?? undefined, entries);
-        this.owners.set(sessionId, owner);
-        await this.writeIncarnation(sessionId, () => incarnation);
+        await this.writeMeta(sessionId, () => ({ incarnation, owner }));
     }
     async replaceEntries(sessionId, owner, entries) {
         if (!this.repo.importEntries)
@@ -482,8 +512,8 @@ export class LocalSessionStore {
         if (!this.repo.delete)
             throw new SessionError("storage", "session replace is not supported by this local backend (no delete seam)");
         validateEntriesForImport(entries);
-        await this.incarnations.ensureLoaded();
-        const prior = this.owners.has(sessionId) ? { owner: this.owners.get(sessionId) ?? null, incarnation: this.incarnations.state.entries.get(sessionId) } : undefined;
+        const current = await this.metaOf(sessionId);
+        const prior = current === undefined ? undefined : { owner: current.owner ?? null, incarnation: current.incarnation };
         await this.deleteSession(sessionId, owner);
         await this.importEntriesAs(sessionId, owner, entries, carriedIncarnation(prior, owner));
     }
@@ -499,8 +529,8 @@ export class LocalSessionStore {
         this.stagings.delete(stagingId);
     }
     async deleteSession(sessionId, owner) {
-        const known = this.owners.has(sessionId);
-        if (!known || !ownerEq(this.owners.get(sessionId) ?? null, owner))
+        const current = await this.ownerOf(sessionId);
+        if (current === undefined || !ownerEq(current, owner))
             return false;
         try {
             await this.repo.delete({ id: sessionId, createdAt: "" });
@@ -509,10 +539,10 @@ export class LocalSessionStore {
             if (!isNotFound(e))
                 throw e;
         }
-        this.owners.delete(sessionId);
+        await this.dropMeta(sessionId);
         this.lastActivity.delete(sessionId);
         this.lastTaskRun.delete(sessionId);
-        for (const map of [this.titles, this.instructionSources, this.incarnations]) {
+        for (const map of [this.titles, this.instructionSources]) {
             await map.ensureLoaded();
             if (map.state.entries.delete(sessionId))
                 await map.persist();
@@ -572,7 +602,7 @@ class LocalStagingHandle {
             await this.store.replaceEntries(this.realSessionId, owner, this.staged);
         }
         else {
-            this.store.restampOwner(this.realSessionId, owner);
+            await this.store.restampOwner(this.realSessionId, owner);
         }
         this.store.forgetStaging(this.stagingId);
         return { relation: rel.relation };

package/dist/plugins/one-time-migrations.d.ts

@@ -65,6 +65,12 @@ export interface OneTimeMigrationWindow {
  * 而留着 M3 会让 M3 永远判「跑过了」。三条同版引入、同一天到期,本来就同一次删。
  */
 export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
+/**
+ * 一条登记行的窗**此刻**开着没有(`today` = UTC 日历日 YYYY-MM-DD):未发布形(`removableAfter: null`)⇒ 开;否则今天不晚于 `removableAfter` ⇒ 开
+ * (窗关当天仍开,与到期门「今天严格晚于才红」同一条边界)。
+ * 只给**窗内才生效的行为臂**用(M10 的认领):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
+ */
+export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
 /** local 车道上 SQL 独有的四条(M1 / M2 / M4 / M5)的读数(M3 / M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated" | "holderDeathCodeRowsBackfilled">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */

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

@@ -119,7 +119,24 @@ export const ONE_TIME_MIGRATIONS = [
             "`decide.workflow_parks_unreadable`);出路不变(续跑发起它的那条 workflow run);随包排空判据没了,换钉前没有机器读数可数这些卡",
         reportKeys: ["workflowParkIndexKey", "workflowParkIndexRowsCarried"],
     },
+    {
+        id: "M10",
+        introducedIn: "7.119.0",
+        releasedOn: "2026-10-08",
+        removableAfter: "2026-11-07",
+        removal: "删 local 车道的认领臂:`LocalSessionStore.register` 里「属主从没被记下的存量会话 ⇒ 带 principal 的登记认领它」那一支、认领日志行 `session_owner_claimed`" +
+            "(连同店构造参数里只为它存在的 `log` 位)与读本表 M10 行的 `ownerClaimWindowOpen`;`security.ts` `createAuthorizer` 里对无主会话的那次认领 `register` 调用;" +
+            "`http/routes/sessions.ts` 409 `conflict.session_ownerless` 句里「Ways out: on the local backend, during the upgrade window …」那半句(连同冻结表 " +
+            "`test/api-error-text-freeze.test.ts` 那一行、契约码目录 `docs/ASSISTANT-WIRE-CONTRACT.md` 那一行);本文件的 `migrationWindowOpen`(若再无别的读者)",
+        afterRemoval: "没有响亮臂(删码本身零行为变化:窗关那一刻起认领臂已经不生效):属主从没被记下的存量会话(边档那一格只有化身 —— 跳过了带本条的版本直接升," +
+            "或窗内从没被带 principal 提交过)照旧答无主(`ownerOf` = null):它的会话规则这条路由读不了也改不了(409 `conflict.session_ownerless`)," +
+            "已存的规则对写下它们的 principal 的 run 照旧生效;出路 = 删会话(`DELETE /v1/sessions/:id`,规则随之删)",
+        reportKeys: [],
+    },
 ];
+export function migrationWindowOpen(window, today) {
+    return window.removableAfter === null || today <= window.removableAfter;
+}
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
@@ -533,7 +550,8 @@ export function logOneTimeMigrations(log, backend, report) {
             "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 " +
             "under its old key shadowedRule rewritten to allowRuleShadowed; M9: the workflow park pointer index rebuilt with the key (session, run), " +
-            "its rows carried over). Each step " +
+            "its rows carried over; M10 writes nothing at boot — on the local backend, while its window is open, the first task submitted with a principal " +
+            "on a session written by an earlier version (which recorded no owner) claims that session for the principal, one session_owner_claimed line per claim). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",

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

@@ -0,0 +1,36 @@
+/**
+ * 对象存储配了快照桶却**不存在** = 部署错 —— boot 期核**一次**,缺 ⇒ 响亮拒启(不是每一拍 sweep 一条静默的 404)。
+ *
+ * ## 病
+ * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
+ * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
+ * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ *
+ * ## 形(一条规则,不加特例)
+ *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
+ *    NoSuchBucket 的 404)⇒ **不拒**、照常起服,走登记过的 F 类兜底口 `recordFailOpen("server.snapshot-bucket.presence-unproven")`(计数 + 探针行 + 记录器的一次性 warn;
+ *    三问写在该 tag 的 note 里)—— 拒启要有证据,没有证据只留痕;
+ *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
+ *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
+ *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
+ *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ */
+import type { ServiceConfig } from "../config-types.js";
+import { type StoreOpenWaitClock } from "./store-open-wait.js";
+type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** 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;
+/** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
+export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+/**
+ * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ */
+export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}, clock?: StoreOpenWaitClock): Promise<void>;
+export {};
+//# sourceMappingURL=snapshot-bucket-presence.d.ts.map

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

@@ -0,0 +1,40 @@
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { MinioBlobBackend } from "./blob-backend.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
+class SnapshotBucketMissing extends Error {
+    constructor() {
+        super("snapshot bucket missing");
+    }
+}
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+    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.`);
+}
+export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+    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 {
+        verdict = await openWithinWait(async () => {
+            const r = await probe.probeBucket(SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS);
+            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);
+    }
+    catch (err) {
+        if (err instanceof SnapshotBucketMissing)
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+        if (!isStoreOpenWindowExpired(err))
+            throw err;
+        verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
+    }
+    if (verdict.state === "unknown") {
+        recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
+    }
+}
+//# sourceMappingURL=snapshot-bucket-presence.js.map

package/dist/plugins/store-backend.d.ts

@@ -398,8 +398,11 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
  *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
  *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
  *
- *  降级条件不变(两形同一姿势):`sessionBackend=auto`(配置的 DB 不可达,S5 原形)或**默认推导**的
- *  local(`dbBackend=local && !dbBackendExplicit`)。**显式** DB_BACKEND=local / tidb 仍 fail-loud——
+ *  **降级臂只有一条:缺省推导的 local**(`dbBackend=local && !dbBackendExplicit`)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
+ *  `SESSION_BACKEND=auto` 与显式 `DB_BACKEND=mysql|pg` 同一待遇,库当下打不开 ⇒ 在 `STORE_LOCK_WAIT_MS` 的窗内重试
+ *  ({@link openWithinWait}),到窗仍打不开 ⇒ 拒启(拒句 {@link buildSqlStoreOpenRefusal} 点名后端与库的显示安全形)。修前 `auto` 在这里
+ *  静默落内存(只留一行 warn):会话 / 停驻 / run 账本进进程内存、重启即丢,而 `/health` 照样 200 —— [ref] P 类 fail-open。
+ *  零 DSN 的内存是配置说的(`config.ts` 的 `auto` 在无坐标时就不探测),不经过本函数。**显式** DB_BACKEND=local 仍 fail-loud——
  *  operator 要了 durable,静默丢=丢数据。 */
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
@@ -409,9 +412,17 @@ export declare function openStoreBackendWithFallback(config: ServiceConfig, logg
     degradedReason: StoreDegradedReason | undefined;
 }>;
 /**
- * S-866 ⑤c / G4 —— SQL 族「显式要了持久而店打不开」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`,给三条出路:修坐标 / 连通性;
- * `SESSION_BACKEND=auto`(尽力而为:店不可达时以内存起服,什么都不持久);`DB_BACKEND=memory`(显式内存部署)。驱动原文只取 message
- * (与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ * 已配置的 SQL 库坐标 → 一条只含 `scheme://host:port` 的 URL 串,**交给**配置型 URL 的唯一显示铸点 {@link buildDisplaySafeUrl}
+ * (出口处写 `buildDisplaySafeUrl(sqlStoreCoordinatesAsUrl(config))`)。它**不是**一份显示投影:显示形只有铸点一只;这里只做「结构化坐标 → URL 串」的拼装
+ * (`config.tidb` / `config.pg` 本来就是结构化坐标,没有 DSN 字符串),user / password / database 一概不进产物。
+ * host 过不了闭字符集(拼进 URL 会把 `/` `@` `?` 之类带成别的成分)或无坐标 ⇒ 交出一个不是 URL 的串,铸点答它的占位 `«redacted:url»`。
+ * scheme 只是引擎名(`postgres` / `mysql`),不对应任何连接。
  */
-export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", err: unknown): string;
+export declare function sqlStoreCoordinatesAsUrl(config: Pick<ServiceConfig, "dbBackend" | "tidb" | "pg">): string;
+/**
+ * SQL 族「配了 DSN 而店打不开(窗内重试过了)」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`、库的显示安全形(`postgres://host:port` / `mysql://host:port`,经 {@link sqlStoreCoordinatesAsUrl} 拼出、再过 {@link buildDisplaySafeUrl},
+ * 不带口令)、等了多久,出路两条:修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`);或**显式**内存部署(`DB_BACKEND=memory`)。🔴 没有第三条
+ * 「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ */
+export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", endpoint: string, waitedMs: number, err: unknown): string;
 //# sourceMappingURL=store-backend.d.ts.map