@sema-agent/server 7.138.0 → 7.139.0

package/dist/plugins/remote-shell.js

@@ -1,5 +1,6 @@
-import { ExecutionError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
-import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
+import { ExecutionError, FileError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
+import { NAME_MAX_BYTES, classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { randomBytes } from "node:crypto";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
 export function armPipeDestroyGrace(child) {
@@ -153,4 +154,167 @@ export async function runSymlinkChain(absPath, run) {
         return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
     return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout, absPath) } };
 }
+const STAGED_FILE = "data";
+const STAGE_DIR_REFUSED_EXIT = 3;
+const STAGE_DIR_UNSEALED_EXIT = 4;
+const STAGE_DIR_UNSEALED_MESSAGE = "sema: the private staging directory could not be made private (chmod 700 failed or did not take effect, or the mode or owner read back differently — the filesystem ignores permission bits or the parent directory carries a default ACL); nothing was staged";
+export const STAGE_DIR_LEFT_MARK = "sema: staging directory left behind:";
+export function buildStagingPaths(abs, nonce = randomBytes(6).toString("hex")) {
+    const cut = abs.lastIndexOf("/");
+    const parent = abs.slice(0, cut + 1);
+    const suffix = `.stage-${nonce}`;
+    const name = Array.from(abs.slice(cut + 1));
+    while (name.length > 0 && Buffer.byteLength(`.${name.join("")}${suffix}`, "utf8") > NAME_MAX_BYTES)
+        name.pop();
+    const dir = `${parent}.${name.join("")}${suffix}`;
+    return { dir, file: `${dir}/${STAGED_FILE}` };
+}
+function privateMkdir(dir) {
+    return `(umask 077 && mkdir -- ${dir})`;
+}
+function hardenPrivate(dir) {
+    const statOf = (gnu, bsd) => `$(stat -c ${gnu} -- ${dir} 2>/dev/null || stat -f ${bsd} -- ${dir} 2>/dev/null)`;
+    return `( chmod -- 700 ${dir} 2>/dev/null && m=${statOf("%a", "%Lp")} && u=${statOf("%u", "%u")} && case "$m" in 700|[1-7]700) [ "$u" = "$(id -u)" ];; *) false;; esac )`;
+}
+function emptyPrivate(dir) {
+    return `[ ! -e ${dir}/${STAGED_FILE} ] && [ ! -L ${dir}/${STAGED_FILE} ]`;
+}
+function sealPrivate(dir) {
+    return `${hardenPrivate(dir)} && ${emptyPrivate(dir)}`;
+}
+function removalOf(dir) {
+    return `{ [ ! -L ${dir} ] && rm -f -- ${dir}/${STAGED_FILE} && { rmdir -- ${dir} 2>/dev/null || [ ! -e ${dir} ]; }; }`;
+}
+function leftMark(dir) {
+    return `printf '%s %s\\0' ${shellQuote(STAGE_DIR_LEFT_MARK)} ${dir}`;
+}
+function removePrivate(dir) {
+    return `{ ${removalOf(dir)} || ${leftMark(dir)}; }`;
+}
+function abandonPrivate(dir) {
+    return `{ rmdir -- ${dir} 2>/dev/null || ${leftMark(dir)}; }`;
+}
+export function buildStagingPrepareCommand(stage) {
+    const parent = stage.dir.slice(0, stage.dir.lastIndexOf("/")) || "/";
+    const dir = shellQuote(stage.dir);
+    return (`{ mkdir -p -- ${shellQuote(parent)} || exit 1; ${privateMkdir(dir)} || exit ${STAGE_DIR_REFUSED_EXIT}; ` +
+        `${hardenPrivate(dir)} || { ${abandonPrivate(dir)}; printf '%s\\n' ${shellQuote(STAGE_DIR_UNSEALED_MESSAGE)} >&2; exit ${STAGE_DIR_UNSEALED_EXIT}; }; ` +
+        `${emptyPrivate(dir)} || { ${abandonPrivate(dir)}; printf '%s\\n' ${shellQuote("sema: the private staging directory gained an entry before it was made private; not used")} >&2; exit 1; }; }`);
+}
+function takeAndWrite(redirect) {
+    return (`[ -r "$s" ] || chmod -- u+r "$s" 2>/dev/null; exec 3< "$s" || exit 1; { [ ! -L "$d" ] && rm -f -- "$s"; } || { ${leftMark(`"$d"`)}; exit 1; }; ` +
+        `cat <&3 ${redirect} "$t"; w=$?; exec 3<&-; ${removePrivate(`"$d"`)}; exit $w; `);
+}
+export function buildStagedCommitCommand(stage, target) {
+    return (`{ d=${shellQuote(stage.dir)}; s="$d/${STAGED_FILE}"; t=${shellQuote(target)}; ` +
+        `if [ -L "$t" ]; then h=$(readlink -n -- "$t" && printf .) || h=; h=\${h%.}; ` +
+        `case "$h" in "") ;; /*) ;; *) l="\${t%/*}"; case "$l" in "") h="/$h" ;; */) h="$l$h" ;; *) h="$l/$h" ;; esac ;; esac; ` +
+        `if [ -n "$h" ] && [ ! -L "$h" ] && { [ ! -e "$h" ] || [ -f "$h" ]; }; then t="$h"; fi; fi; ` +
+        `if [ ! -L "$t" ] && { [ ! -e "$t" ] || [ -f "$t" ]; }; then ` +
+        `if [ "\${t%/*}" != "\${d%/*}" ]; then e="\${t%/*}/\${d##*/}"; ` +
+        `if { ${privateMkdir(`"$e"`)}; } 2>/dev/null; then ` +
+        `if { ${sealPrivate(`"$e"`)}; } 2>/dev/null; then ` +
+        `if cat -- "$s" > "$e/${STAGED_FILE}" 2>/dev/null; then o="$d"; d="$e"; s="$e/${STAGED_FILE}"; ${removePrivate(`"$o"`)}; else ${removePrivate(`"$e"`)}; fi; ` +
+        `else ${abandonPrivate(`"$e"`)}; fi; fi; fi; ` +
+        `if [ -f "$t" ]; then m=$(stat -c %a -- "$t" 2>/dev/null || stat -f %Lp -- "$t" 2>/dev/null) && chmod "$m" "$s" 2>/dev/null; fi; ` +
+        `if mv -f -- "$s" "$t" 2>/dev/null; then ${removePrivate(`"$d"`)}; exit 0; fi; fi; ` +
+        `${takeAndWrite(">")}}`);
+}
+export function buildStagedAppendCommand(stage, target) {
+    return `{ d=${shellQuote(stage.dir)}; s="$d/${STAGED_FILE}"; t=${shellQuote(target)}; ${takeAndWrite(">>")}}`;
+}
+export function buildStagingDiscardCommand(stage) {
+    return removalOf(shellQuote(stage.dir));
+}
+async function discardStaged(lane, stage) {
+    const r = await lane.run(buildStagingDiscardCommand(stage));
+    if (!r.ok)
+        return r.error.message;
+    return r.value.exitCode === 0 ? undefined : r.value.stderr.trim() || "it holds something this write did not put there, or it was replaced by a link";
+}
+function withResidue(e, stage, why) {
+    return why === undefined ? e : new FileError(e.code, `${e.message} (the staging directory ${stage.dir} could not be removed: ${why})`, e.path, e);
+}
+async function landStaged(lane, abs, abortSignal, commitOf, direct) {
+    if (abortSignal?.aborted)
+        return { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) };
+    const stage = buildStagingPaths(abs);
+    const prep = await lane.run(buildStagingPrepareCommand(stage), abortSignal);
+    if (!prep.ok) {
+        const left = await discardStaged(lane, stage);
+        return { ok: false, error: withResidue(fileErrorFromExec(prep.error, abs), stage, left) };
+    }
+    if (prep.value.exitCode !== 0) {
+        noteLeftDirs(prep.value.stdout);
+        if (abortSignal?.aborted)
+            return { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) };
+        const e = classifyFsStderr(prep.value.stderr, abs, "unknown");
+        if (prep.value.exitCode === STAGE_DIR_REFUSED_EXIT && e.code === "permission_denied")
+            return direct(createDirectContext(abs, abortSignal, "the directory does not accept new names"));
+        if (prep.value.exitCode === STAGE_DIR_UNSEALED_EXIT) {
+            recordFailOpen("server.remote-write.stage-seal-fallback", `${abs}: ${prep.value.stderr.trim()}`);
+            return direct(createDirectContext(abs, abortSignal, "the private staging directory could not be made private"));
+        }
+        return { ok: false, error: e };
+    }
+    if (abortSignal?.aborted) {
+        const left = await discardStaged(lane, stage);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), stage, left) };
+    }
+    const up = await lane.upload(stage.file, abortSignal);
+    if (!up.ok) {
+        const left = await discardStaged(lane, stage);
+        return { ok: false, error: withResidue(up.error, stage, left) };
+    }
+    if (abortSignal?.aborted) {
+        const left = await discardStaged(lane, stage);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the commit; the target was not touched", abs), stage, left) };
+    }
+    const c = await lane.run(commitOf(stage));
+    if (!c.ok) {
+        const left = await discardStaged(lane, stage);
+        const e = fileErrorFromExec(c.error, abs);
+        return { ok: false, error: withResidue(new FileError("unknown", `${e.message} (the commit's round trip failed, so whether it ran is unknown — re-read the target before retrying)`, abs, e), stage, left) };
+    }
+    noteLeftDirs(c.value.stdout);
+    if (c.value.exitCode !== 0) {
+        const left = await discardStaged(lane, stage);
+        return { ok: false, error: withResidue(classifyFsStderr(c.value.stderr, abs, "unknown"), stage, left) };
+    }
+    return { ok: true, value: undefined };
+}
+function noteLeftDirs(stdout) {
+    const head = `${STAGE_DIR_LEFT_MARK} `;
+    for (const rec of stdout.split("\0")) {
+        const at = rec.indexOf(head);
+        if (at >= 0)
+            recordFailOpen("server.remote-write.staging-dir-left", rec.slice(at + head.length));
+    }
+}
+function createDirectContext(abs, abortSignal, why) {
+    return {
+        signal: abortSignal,
+        inPlace: async (step) => {
+            if (abortSignal?.aborted)
+                return { ok: false, error: new FileError("aborted", `aborted before the in-place write started (${why}); the target was not touched`, abs) };
+            const r = await step(abortSignal);
+            if (r.ok || r.error.code !== "aborted")
+                return r;
+            return { ok: false, error: new FileError("unknown", `cancelled during an in-place write (${why}, so the bytes went straight to the target); the target may be partially written — re-read it before retrying`, abs, r.error) };
+        },
+    };
+}
+export async function rewriteAppend(read, write, add, ctx) {
+    const existing = await read(ctx.signal);
+    if (!existing.ok && existing.error.code !== "not_found")
+        return existing;
+    const merged = Buffer.concat([existing.ok ? existing.value : new Uint8Array(0), typeof add === "string" ? Buffer.from(add, "utf8") : add]);
+    return ctx.inPlace((signal) => write(merged, signal));
+}
+export function writeFileStaged(lane, abs, abortSignal) {
+    return landStaged(lane, abs, abortSignal, (stage) => buildStagedCommitCommand(stage, abs), (ctx) => ctx.inPlace((signal) => lane.upload(abs, signal)));
+}
+export function appendFileStaged(lane, abs, abortSignal, direct) {
+    return landStaged(lane, abs, abortSignal, (stage) => buildStagedAppendCommand(stage, abs), direct);
+}
 //# sourceMappingURL=remote-shell.js.map

package/dist/plugins/retention-store-sql.d.ts

@@ -404,6 +404,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *   ① `retention_hold` 哨兵行的**锁读** —— `held=1` ⇒ 零删、全 skip 返回;锁持有到 COMMIT;
      *   ② **一条**加锁读同时完成「候选 + 活引用重查」(谓词下推 + `FOR UPDATE`,见
      *      {@link SqlRetentionStore.sessionCandidates});
+     *   ②′ 读写序律的写者半:锁住候选行之后,逐只用**本事务的连接、新语句**锁定读一次认领(`lockRootAndReadClaim`);有认领的树整棵跳过;
      *   ③ 按 E21 顺序逐表删 → 墓碑 → 审计行(同事务)→ COMMIT。
      *
      * 🔴 活引用重查为什么是**候选查询本身**而不是第二条查询(codex 交叉复审 R1 的两条 high 合并采纳):
@@ -411,12 +412,14 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *  · `FOR UPDATE` 让这些会话行在本事务期间不可被 `touch()` 拉回视界、也不可被 session-sync 改写属主 ——
      *    旧形(不加锁 + 尾部无条件删 `session_event`)可以在属主被并发改写后,把**别的租户**的历史删掉;
      *  · 旧形还在删完 `task_active` **之后**才去复核它,那道复核因此恒真(自己刚把证据删了)—— 一段恒真的
-     *    "防护"比没有更坏。现在删除前的最后一次判据就是候选查询,删除后不再假装复核。
-     * ⚠️ **残余**(如实成文,不假装消灭):`createRun` 只写 `task_active`(亲读 run-store-sql 坐实,它不碰
-     *  `session_meta`),所以本事务的会话行锁**不**与它构成互斥。一次恰好在候选查询之后、本事务提交之前
-     *  提交的新 claim 仍会被这一轮删掉。窗口 = 级联本身的耗时,且与**在线** purge 协调器的同款窗口一模一样
-     *  (它那条 `SELECT … FOR UPDATE task_active` 同样锁不住缺席行)。真正的收口是让 `createRun` 也去锁
-     *  `session_meta` 那一行(共同锁序)—— 那是在线热路径的改动,归属另一次裁定,已进交接清单。
+     *    "防护"比没有更坏。删除之前的判据是候选查询 + ②′ 那一读,删除后不再假装复核。
+     * 与认领的互斥(共同锁序,读写序律两半):
+     *  · 认领半:`createRun` 在认领事务里**先锁根会话行**(`session_meta … FOR UPDATE`)再插 `task_active`(`run-store-sql.ts` 的 `createRun` 顶注)
+     *    ⇒ 候选查询锁住会话行之后才来的认领等在那一行上,本事务提交后它锁定读到零行 ⇒ `sessionAbsent`,不建行;
+     *  · 写者半(②′):候选查询开始时**已经持着**会话行锁、尚未提交的认领 —— 候选查询等它提交后才拿到行锁,而那条 `NOT EXISTS task_active`
+     *    读的是语句开始时的快照(PG 读已提交下非目标表按语句快照读),看不见刚提交的认领;②′ 是行锁之后的**新语句**锁定读(PG 新快照、TiDB 当前读),
+     *    认领已提交就读得到 ⇒ 这棵树跳过。被锁住的根行上不会再有新认领(认领先锁根行),所以 ②′ 之后到提交之间没有窗。
+     *    `skipped` 仍由 {@link SqlRetentionStore.countProtectedSessions} 独立测得(非锁定读:PG 新语句看得见这一只,TiDB 读事务快照可能少计它一只 —— 回执的计数口径,不是删除判据)。
      *
      * 活引用的四条腿(与设计稿 §2 的清单对表,并如实标注一条**结构上不存在**的边):
      *   · `task_active` —— 活跑 claim(在线协调器的第一道门,同一张表同一条判据);

package/dist/plugins/retention-store-sql.js

@@ -3,6 +3,7 @@ import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./ta
 import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { incarnationFromCell } from "../session-incarnation.js";
+import { lockRootAndReadClaim, rowsOnSqlExec } from "./execution-placement-sql.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
 export function retentionSweepRuns(sweep) {
@@ -336,7 +337,12 @@ export class SqlRetentionStore {
                     skippedOnAbort = (await this.sessionCandidates(conn, input)).length + (await this.countProtectedSessions(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
-                const doomed = await this.sessionCandidates(conn, input, true);
+                const candidates = await this.sessionCandidates(conn, input, true);
+                const rowsOn = rowsOnSqlExec(conn);
+                const doomed = [];
+                for (const c of candidates)
+                    if ((await lockRootAndReadClaim(rowsOn, this.db.dialect, c.id)).activeTaskId === null)
+                        doomed.push(c);
                 const skipped = await this.countProtectedSessions(conn, input);
                 skippedOnAbort = doomed.length + skipped;
                 let deleted = 0;

package/dist/plugins/run-store-sql.d.ts

@@ -42,6 +42,14 @@ export declare class SqlRunStore {
      * `task_id` ⇒ `{ ok:false, existing }` (no new row; the submission surface renders the receipt); otherwise the
      * session claim was the collision ⇒ `{ ok:false, activeTaskId }`. A dup on the ROW insert that names no
      * observable row is not attributable to either key ⇒ rethrown (loud), never reported as a busy session.
+     *
+     * 🔴 **根会话行锁(读写序律)**:认领之前,同一事务先锁根会话行(`session_meta … FOR UPDATE`,两方言同一句)。改根行住客 / 放置的写者
+     * (删除 / 换装 / 留存 …)也在自己的事务里先锁这一行 ⇒ 认领与它们在根行上按同一锁序串行:写者持锁期间认领等锁,写者提交后认领读到的是新行。
+     * **锁定读零行**(根行在受理之后被删)⇒ 不插认领、不建行,答 `{ ok:false, sessionAbsent:true }` —— 否则认领会挂在一只没有会话行的根上,
+     * 随后同 id 登记的新住客就带着别人的认领出生。全局锁序:根 `session_meta` → `task_active` / `task_run`(删除 / 留存同序;认领持有者的
+     * `whileHoldingClaim` 只取 `task_run` → `task_active`,从不碰 `session_meta` —— 它的回调**不许**写 `session_meta`:回调持 `task_active`
+     * 等根行、认领持根行等 `task_active`,即成环;初始放置写走自己的事务、按全局锁序取锁)。fresh 根行由 authorizer 在受理时登记(唯一铸点即登记点),
+     * 续跑与 wake 复用 checkpoint 的会话 —— 所以零行只在「受理之后被删」这一种竞争里出现。
      */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
     /** Request cancel of a RUNNING run (durable, cross-replica). Sets the flag the owning instance's heartbeat
@@ -165,10 +173,12 @@ export declare class SqlRunStore {
      *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
      *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑;提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
      * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
-     *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 只插认领行、`deleteBySession` 见认领行在就中止,
-     *    都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
+     *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 先锁根会话行再插认领行(本序从不碰 `session_meta`)、
+     *    `deleteBySession` 先锁根会话行、见认领行在就中止,都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
      *    锁读没命中时 InnoDB 可能取一把间隙锁;本事务此后不往这两张表插任何行(见 space-commit 那条锁形注)。
      * 担保止于提交:判出「持有」的是这只事务;提交确认在路上迟到、这一跑随后失去认领,不在本栅栏的射程里(调用方的已知边界)。
+     * 🔴 **`write` 不许写 `session_meta`**:本事务持着 `task_active`,而 `createRun` 与改根行的写者都先锁根会话行再碰 `task_*`(全局锁序见 {@link createRun})——
+     *    回调去锁根行就是反序,与等着本会话认领的 `createRun` 各攥一行成环。门:`test/submission-root-contract.test.ts` 扫每个调用点的回调体。
      */
     whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn) => Promise<T>): Promise<ClaimFenced<T>>;
     /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
@@ -187,7 +197,7 @@ export declare class SqlRunStore {
      *  `uq_task_run_idem` makes it at most one row. */
     getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
     /** Undo THIS submission's binding (`idem_key` + `idem_body_fingerprint` → NULL) — called only where the submit surface refuses
-     *  the submission before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement
+     *  the submission before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement
      *  reject): the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;

package/dist/plugins/run-store-sql.js

@@ -81,6 +81,11 @@ export class SqlRunStore {
         let stage = "claim";
         try {
             await conn.begin();
+            const { rows: root } = await conn.query(this.q("SELECT session_id FROM session_meta WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM session_meta WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+            if (root.length === 0) {
+                await conn.rollback();
+                return { ok: false, sessionAbsent: true };
+            }
             const now = new Date();
             try {
                 await conn.query(this.q("INSERT INTO task_active (session_id, task_id, since) VALUES (?,?,?)", "INSERT INTO task_active (session_id, task_id, since) VALUES ($1,$2,$3)"), [sessionId, taskId, now]);

package/dist/plugins/schema-consistency.d.ts

@@ -8,14 +8,14 @@
  * `errorCode` 直接是裸 `42703` / `ER_BAD_FIELD_ERROR`。
  *
  * ── 与 SCHEMA POLICY(`tidb-pool.ts` 顶注,clay 裁 2026-07-26)不冲突 ─────────────────────────────
- * 那条口径禁的是 **ALTER seam**:「代码是 schema 的唯一真源、存量库删库重建、`ensure*` 里不许再出现
- * `ALTER TABLE`」。本探针**一条 DDL 都不发**,它是只读的 information_schema 对账 —— 恰恰是那条口径的
+ * 那条口径禁的是 **ALTER seam**:「代码是 schema 的唯一真源、不做增量(缺列由部署者按拒启句打印的 ALTER 自己执行)、
+ * `ensure*` 里不许再出现 `ALTER TABLE`」。本探针**一条 DDL 都不发**,它是只读的 information_schema 对账 —— 恰恰是那条口径的
  * **执行面**:口径说「库必须等于代码」,在此之前没有任何东西检查过这句话是不是真的。两者一个是禁令
  * (不许代码偷改库)、一个是对账(库偏离了就别起),同向不同面。
  *
  * ── 为什么两个方向都拒(缺列 **和** 多列)──────────────────────────────────────────────────────
- * 缺列 = 库比代码旧(升级没重建库):读写会在用户路径上炸。多列 = 库比代码**新** —— 滚动升级窗里一个
- * **旧副本**连上了已被新副本重建过的库;它按旧列集读写,新列上的不变量(本例:`gen` 血统)在它眼里
+ * 缺列 = 库比代码旧(升级时库没跟上):读写会在用户路径上炸。多列 = 库比代码**新** —— 滚动升级窗里一个
+ * **旧副本**连上了已被新副本升过的库;它按旧列集读写,新列上的不变量(本例:`gen` 血统)在它眼里
  * 根本不存在,于是它会悄悄写出违反新契约的行。后者比前者更隐蔽,所以不做「幽灵列只警告」。
  * ⇒ 运维顺序因此是**先升库再升副本**(见 `docs/DEPLOY-PREREQS.md` 滚动升级窗那一节)。
  *
@@ -85,7 +85,17 @@ export interface TableMismatch {
 }
 /** 对账(纯函数:期望 × 实况 → 不符表清单)。 */
 export declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
-/** 拒启文案(表名 + 缺/多列 + 两条路;ADD COLUMN 句由解析结果**生成**)。 */
+/**
+ * 逐表段 + 闭集出路段(多行):整库对账的拒启句与单表探针的拒因共用这一份句形(`schema-drift-sentence.ts` 的 `describeProbedTableDrift` 读它)。
+ * ADD COLUMN 句由解析结果**生成**,不手写。
+ *
+ * 出路段 = {@link SCHEMA_MISMATCH_WAYS_OUT}(**闭集三条**,常量;句子的属主在 `schema-drift-sentence.ts`):
+ * ① 部署与这个库匹配的构建;② 库比构建旧(缺列)⇒ 部署者自己执行上面逐字打印的 `ALTER TABLE … ADD COLUMN …`(列集对账与拒启句永不改库);
+ * ③ 库比构建新(多列)⇒ 部署持有那些列的构建(先升库、再升副本)。
+ * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据 —— 这里不写,拒启句的钉也守着(`test/schema-consistency.test.ts` ⑤)。
+ */
+export declare function describeMismatchedTables(mismatches: readonly TableMismatch[]): string[];
+/** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
 export declare function describeSchemaMismatch(dialect: SchemaDialect, mismatches: readonly TableMismatch[]): string;
 /**
  * 启动期对账:**建表之后**跑,不符即抛(= 拒启)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。

package/dist/plugins/schema-consistency.js

@@ -1,5 +1,6 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_WAYS_OUT } from "./schema-drift-sentence.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripLineComments(sql) {
@@ -120,13 +121,8 @@ export function diffSchema(expected, live) {
     }
     return out;
 }
-export function describeSchemaMismatch(dialect, mismatches) {
-    const lines = [
-        `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
-        "This repo ships no ALTER seam (schema policy: the code is the single source of truth), so a drifted database is",
-        "a deployment-order problem, not something the process may quietly work around.",
-        "",
-    ];
+export function describeMismatchedTables(mismatches) {
+    const lines = [];
     for (const m of mismatches) {
         if (m.missing.length > 0) {
             lines.push(`  table ${m.table}: MISSING column(s) ${m.missing.map((c) => c.name).join(", ")} — the database is OLDER than this build.`);
@@ -138,7 +134,17 @@ export function describeSchemaMismatch(dialect, mismatches) {
             lines.push(`    No ALTER is suggested for this direction: deploy the build that owns those columns (upgrade the database FIRST, then the replicas).`);
         }
     }
-    lines.push("", "  Two ways out: (1) deploy the build whose code matches this database; (2) rebuild the database from this build", "  (DROP DATABASE <name>; CREATE DATABASE <name>; restart — every table is recreated by ensure*Schema at boot).");
+    lines.push("", ...SCHEMA_MISMATCH_WAYS_OUT);
+    return lines;
+}
+export function describeSchemaMismatch(dialect, mismatches) {
+    const lines = [
+        `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
+        "Schema policy: the code is the single source of truth, and the column check that produced this refusal never alters a database —",
+        "so a drifted database is a deployment-order problem, not something the process may quietly work around.",
+        "",
+        ...describeMismatchedTables(mismatches),
+    ];
     return lines.join("\n");
 }
 export async function assertSchemaMatchesCode(read, dialect) {

package/dist/plugins/schema-drift-sentence.d.ts

@@ -0,0 +1,27 @@
+import type { SqlDialect } from "./sql-driver.js";
+/** 「库比构建旧」那一条出路的两个可变件:旧在哪(括注)、部署者要自己做的那件事。其余字一个不变。 */
+export interface OlderWayOut {
+    /** 括注:库旧在哪(例:`missing columns`)。 */
+    readonly when: string;
+    /** 部署者自己执行的动作(接在冒号后;句尾的「列集对账不改库」声明由本函数补)。 */
+    readonly action: string;
+}
+/**
+ * 出路段:**闭集三条**,编号 (1)(2)(3) 与顺序固定,与不符的方向无关(每一条自带适用条件)。
+ * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据。
+ */
+export declare function schemaWaysOut(older: OlderWayOut): readonly string[];
+/** 缺列方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。 */
+export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
+/** 探针读口:一条 SQL → `{ rows }`(各 `assert*Schema` 的 `query` 形)。 */
+export type ProbeQuery = (sql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>;
+/**
+ * 单表探针抓到可证缺列后,拒因里「哪几列缺、该跑哪几条 ALTER」+ 闭集出路这一整段(多行文本,不含探针自己的首句与底层错误)。
+ *
+ * 读不出库的列册(权限 / 超时)或对账看不到探针点名的表有缺列(探针与建表语句互相矛盾)⇒ **响亮**地说「ALTER 没能打印」及原因,
+ * 出路仍是同一份闭集(旧一条改成「按建表语句自己加」)—— 绝不退回销毁性指路,也不悄悄吞掉这一段。
+ */
+export declare function describeProbedTableDrift(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[]): Promise<string>;
+//# sourceMappingURL=schema-drift-sentence.d.ts.map

package/dist/plugins/schema-drift-sentence.js

@@ -0,0 +1,38 @@
+import { readLiveColumns } from "./schema-live-columns.js";
+export function schemaWaysOut(older) {
+    return [
+        "  Ways out (these three and no others):",
+        "    (1) deploy the build whose code matches this database;",
+        `    (2) the database is OLDER than this build (${older.when}): ${older.action} — the column check and this refusal never alter a database (the only DDL this service runs by itself on a table that already exists is idempotent index creation and the registered one-time migrations, see MIGRATION.md);`,
+        "    (3) the database is NEWER than this build (unknown columns): deploy the build that owns those columns — upgrade the database first, then the replicas.",
+    ];
+}
+export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
+    when: "missing columns",
+    action: "run the ALTER TABLE … ADD COLUMN statements printed above yourself",
+});
+export async function describeProbedTableDrift(query, dialect, tables) {
+    const d = dialect === "pg" ? "pg" : "mysql";
+    const read = async (sql) => (await query(sql)).rows;
+    let why;
+    try {
+        const sc = await import("./schema-consistency.js");
+        const diff = sc.diffSchema(await sc.expectedTableShapes(d), await readLiveColumns(read, d));
+        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [] }));
+        if (missingOnly.length > 0)
+            return sc.describeMismatchedTables(missingOnly).join("\n");
+        why = "this build's table definitions list no column that the database lacks on that table, so the probe and the definitions disagree";
+    }
+    catch (err) {
+        why = `information_schema.columns could not be read (${err instanceof Error ? err.message : String(err)})`;
+    }
+    return [
+        `  table ${tables.join(", ")}: a column this build reads is MISSING — the database is OLDER than this build; the ALTER statements could not be printed: ${why}.`,
+        "",
+        ...schemaWaysOut({
+            when: "missing columns",
+            action: "add each missing column yourself with an ALTER TABLE … ADD COLUMN statement built from this build's definition of the table",
+        }),
+    ].join("\n");
+}
+//# sourceMappingURL=schema-drift-sentence.js.map

package/dist/plugins/session-fork.d.ts

@@ -11,6 +11,10 @@
  * ## 为什么拷贝仍读整份日志、判官却读唤醒出来的会话
  * 拷贝要的是**整份**持久日志(压缩地板绕过 —— 唤醒只装 `[地板..叶]`,从唤醒里拷会丢地板之前的全部历史);判官要的只是叶链上最近几条(它是引擎的一份纯函数,
  * 吃一只 `Session`):唤醒出来的会话 `getEntry` 在地板之下会回读持久日志,所以判官在压缩过的会话上也看得见整条叶链。
+ *
+ * ## fork 续写的店契约(本文件下半)
+ * 三店同一只私有体 `forkTo(sourceId, owner, { id, key? })`:目标行原子新建(唯一创建点)· 撞已在按属主与 fork 键分类({@link classifyForkTarget})·
+ * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装经 `carriedRowCells`)。core 契约 `fork(sourceId, owner?)` = {@link forkByFreshId}。
  */
 import { type ForkPoint, type ForkRowShape, type SessionStorage } from "@sema-agent/core";
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
@@ -28,4 +32,54 @@ export interface ForkLogRow {
  * 引擎的原词原句)。本仓不再自写父链走法 —— 那曾是与引擎 `getPathToRoot` 同义的第二份。
  */
 export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
+/**
+ * `forkTo` 的目标:调用方给的新会话 id 与(可选)fork 键。`key` 是服务端拼的不透明串(路由按「源 + 调用方 nonce」派生),存进新行那一格
+ * `fork_key`(SQL)/ `forkKey`(local):一个事实 = 「建这一行的那次 fork 请求的键」。缺 = 非键控 fork(core 契约的现铸形)。
+ */
+export interface ForkTarget {
+    readonly id: string;
+    readonly key?: string;
+}
+/**
+ * fork 键的**唯一**拼法(路由带键 ⇒ `forkTo(…, { id: forkId, key: forkKeyOf(源, forkNonce) })`):服务端拼的不透明串 —— 源 id 与调用方 nonce 的摘要,
+ * 定长(远短于 `fork_key` 的 255),源进摘要 ⇒ 「异源同 nonce」拼出不同的键(撞同一只目标即 409,不当重放)。调用方不读它,只靠同键重试同答。
+ */
+export declare function forkKeyOf(sourceId: string, forkNonce: string): string;
+/**
+ * `forkTo` 的结果(`null` = 源不在,与 core `fork` 的 `null` 同义):
+ *  · `created` —— 目标行由这一次新建(唯一创建点:SQL 事务首句 INSERT 主键排他;local 两把写锁内「目标格不在 ∧ 目标存档不在」才写目标格);
+ *  · `replayed` —— 目标已在,属主 = 本次新属主 ∧ fork 键相等(同键重试同答;local `forking` 中间态在两把锁内补拷存档后也答它);
+ *  · `occupied` —— 目标已在而不是这次请求的那一行:`sameOwner: false` ⇒ 路由答与未知源同形的 404(不泄存在),`true` ⇒ 409 `conflict.fork_id_taken`(终局)。
+ */
+export type ForkToOutcome = {
+    readonly outcome: "created";
+    readonly id: string;
+} | {
+    readonly outcome: "replayed";
+    readonly id: string;
+} | {
+    readonly outcome: "occupied";
+    readonly sameOwner: boolean;
+};
+/** 撞上已在的目标时的唯一分类(三店同调):属主不同 ⇒ `occupied{sameOwner:false}`;属主同 ∧ 本次带键 ∧ 键相等 ⇒ `replayed`;其余(含无键的普通会话、无键请求)⇒ `occupied{sameOwner:true}`。 */
+export declare function classifyForkTarget(target: ForkTarget, existing: {
+    readonly owner: string | null | undefined;
+    readonly forkKey: string | null | undefined;
+}, forkOwner: string | null | undefined): ForkToOutcome;
+/**
+ * SQL 输方回滚后在新视图里读不到目标(赢方在分类之前回滚或被删),整笔重跑一次之后仍读不到 —— 不猜,响亮抛;路由答 503 `permanence: "transient"`。
+ * 具名类型:按类型认,不按文案。
+ */
+export declare class ForkTargetUnsettledError extends Error {
+    readonly targetId: string;
+    readonly code = "state.fork_target_unsettled";
+    constructor(targetId: string);
+}
+/** 三店的 `forkTo` 形(私有体,经店面 `forkTo` 交出)。 */
+export type ForkToFn = (sourceId: string, owner: string | null, target: ForkTarget) => Promise<ForkToOutcome | null>;
+/**
+ * core 契约 `fork(sourceId, owner?) → string | null` = `forkTo(…, { id: uuidv7() })` 的投影(三店同一只):`created` ⇒ 新 id;源不在 ⇒ `null`。
+ * 新铸的 uuidv7 撞上已在的行(`occupied` / `replayed`)不是一个答案,是不变量破 ⇒ 响亮抛 —— 无键请求永不答 `replayed`。
+ */
+export declare function forkByFreshId(forkTo: ForkToFn, sourceId: string, owner: string | null | undefined): Promise<string | null>;
 //# sourceMappingURL=session-fork.d.ts.map

package/dist/plugins/session-fork.js

@@ -1,4 +1,5 @@
-import { StoredSession, settledForkOptions } from "@sema-agent/core";
+import { SessionError, StoredSession, settledForkOptions, uuidv7 } from "@sema-agent/core";
+import { createHash } from "node:crypto";
 export async function forkPointOf(storage) {
     return settledForkOptions(new StoredSession(storage));
 }
@@ -6,4 +7,40 @@ export const FORK_LOG_ROW_SHAPE = {
     idOf: (row) => row.entry_id,
     parentOf: (row) => row.parent_id,
 };
+export function forkKeyOf(sourceId, forkNonce) {
+    return `fork1:${createHash("sha256").update(sourceId).update("\u0000").update(forkNonce).digest("hex")}`;
+}
+export function classifyForkTarget(target, existing, forkOwner) {
+    if ((existing.owner ?? null) !== (forkOwner ?? null))
+        return { outcome: "occupied", sameOwner: false };
+    if (target.key !== undefined && existing.forkKey === target.key)
+        return { outcome: "replayed", id: target.id };
+    return { outcome: "occupied", sameOwner: true };
+}
+export class ForkTargetUnsettledError extends Error {
+    targetId;
+    code = "state.fork_target_unsettled";
+    constructor(targetId) {
+        super(`fork target ${targetId} collided with another writer twice and could not be read back either time — retry the fork`);
+        this.targetId = targetId;
+        this.name = "ForkTargetUnsettledError";
+    }
+}
+export async function forkByFreshId(forkTo, sourceId, owner) {
+    const id = uuidv7();
+    const out = await forkTo(sourceId, owner ?? null, { id });
+    if (out === null)
+        return null;
+    switch (out.outcome) {
+        case "created":
+            return out.id;
+        case "replayed":
+        case "occupied":
+            throw new SessionError("storage", `fork of session ${sourceId}: a freshly minted id ${id} collided with an existing session (${out.outcome}) — nothing was written`);
+        default: {
+            const unknownOutcome = out;
+            throw new Error(`forkByFreshId: no arm for ${JSON.stringify(unknownOutcome)}`);
+        }
+    }
+}
 //# sourceMappingURL=session-fork.js.map

package/dist/plugins/session-row-sql.d.ts

@@ -0,0 +1,22 @@
+/**
+ * **会话行格写原语的 SQL 半** —— 两孪生(`tidb-session-store.ts` / `pg-session-storage.ts`)同一只实现,方言只在语句文本里。规则在 `src/session-row.ts`
+ * 头注「写原语」;判序只在那里的判官 `judgeSessionRowWrite`,本模块只说事务与语句。
+ *
+ * ## 一只事务(经 `SqlDriver.connect()`)
+ *  ① `SELECT … FROM session_meta WHERE session_id = ? FOR UPDATE` —— 判定读 = 锁读(当前读;连接初始化钉住读语义:TiDB 悲观、设不上拒启,
+ *     `sql-driver.ts` 的 `@contract txn.read-semantics`);行期望带 `log` 时,同锁下读日志的 mark:长度 = 锁住的行上的 `leaf_seq`(每次追加与
+ *     `leaf_id` 同句 +1,导入 / 换装 / fork 写成条目数),末条 = `session_event` 按 `seq` 倒序第一行(锁读)。追加者先锁这一行再插事件,所以持锁期间 mark 不动。
+ *  ② 判官(行期望 → 写者身份 → 标签);不是 `write` ⇒ 回滚、一个字节不写。
+ *  ③ `write` ⇒ 按 `session_id` 写(行已被本事务锁住)→ 提交。`updated_at` 不动(改名不是活动 —— 列表的新近序不变)。
+ * 应答行在**提交 / 回滚之后**由调用方的列表行读另读(新语句、新快照 —— 不在事务内用普通 `SELECT` 读:TiDB 悲观事务的普通读钉 `start_ts`,
+ * 等锁之后会读回判定之前的旧值),再交 `settleSessionRowWrite` 复核住客。
+ * 全局锁序:只锁根 `session_meta` 一行(读日志 mark 时再锁它的末条事件),不碰 `task_*`,不进放置写者「根 meta → `task_*`」锁序的后段。
+ */
+import type { SqlDriver } from "./sql-driver.js";
+import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";
+/**
+ * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
+ * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。
+ */
+export declare function writeSessionRowCellsSql<Row>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, cells: SessionRowPatch, how: SessionRowWrite, readAnswer: (sessionId: string) => Promise<SessionRowAnswer<Row> | undefined>): Promise<SessionRowWriteOutcome<Row>>;
+//# sourceMappingURL=session-row-sql.d.ts.map