@sema-agent/server 7.137.0 → 7.139.0

package/dist/plugins/session-fork.js

@@ -1,29 +1,46 @@
-import { SessionError, 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));
 }
-export function forkCopyOf(rows, sourceLeafId, point) {
-    if (point.entryId === undefined)
-        return { rows: [...rows], leafId: sourceLeafId };
-    if (point.position !== "at") {
-        throw new SessionError("invalid_fork_target", `fork point ${point.entryId} comes with a position this store does not copy (${String(point.position)}) — only the engine's "at" point is read here`);
+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";
     }
-    const byId = new Map();
-    for (const r of rows)
-        byId.set(r.entry_id, r);
-    const onPath = new Set();
-    let cursor = point.entryId;
-    while (cursor !== null) {
-        if (onPath.has(cursor)) {
-            throw new SessionError("invalid_session", `Entry ${cursor} is its own ancestor (parent chain cycles at ${cursor}) — start a new session, or fork from an entry above the loop`);
-        }
-        const row = byId.get(cursor);
-        if (row === undefined) {
-            throw new SessionError(cursor === point.entryId ? "invalid_fork_target" : "invalid_session", `Entry ${cursor} not found`);
+}
+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)}`);
         }
-        onPath.add(cursor);
-        cursor = row.parent_id;
     }
-    return { rows: rows.filter((r) => onPath.has(r.entry_id)), leafId: point.entryId };
 }
 //# sourceMappingURL=session-fork.js.map

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

@@ -22,4 +22,11 @@ export declare function forkOwnerOf(requested: string | null | undefined, source
  * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。判官 = {@link isSessionOwnerValue}(core 7.56.0 [ref] `principalNameOf`)。
  */
 export declare function assertFirstOwnerWritable(sessionId: string, owner: unknown): asserts owner is string | null;
+/**
+ * 导入者的属主 —— 换装的写腿(公开 `importEntries` / `replaceEntries` 与暂存提交)把调用方给的属主重戳进会话行之前的唯一读法:
+ * 主体名或 `null`(匿名)⇒ 原样交回;别的一切(空串、空白串、带控制 / 分隔 / 非连接符格式字符的串、非串)⇒ `TypeError` 响亮拒 ——
+ * 与引擎导入口拒同一类值时同一类错、同一句开头(引擎那一判只作用于交给它的属主,而换装交给引擎的是存档自己的戳,所以这一判在本仓)。
+ * 调用方在读写任何东西之前判,拒了就一个字节没写。判官 = {@link isSessionOwnerValue}(core `principalNameOf`),不在本仓另写规则。
+ */
+export declare function importerOwnerOf(owner: unknown): string | null;
 //# sourceMappingURL=session-ownership.d.ts.map

package/dist/plugins/session-ownership.js

@@ -22,4 +22,9 @@ export function assertFirstOwnerWritable(sessionId, owner) {
     throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal name or null (anonymous), got ${ownerValueFault(owner)} — ` +
         "a value that names nobody would leave the session claimable by anyone or ownable by no one; refusing, nothing written");
 }
+export function importerOwnerOf(owner) {
+    if (isSessionOwnerValue(owner))
+        return owner;
+    throw new TypeError(`session owner must be a principal name or null (anonymous), got ${ownerValueFault(owner)} — an import stamps it as the session's owner; refusing, nothing written`);
+}
 //# sourceMappingURL=session-ownership.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

package/dist/plugins/session-row-sql.js

@@ -0,0 +1,81 @@
+import { incarnationFromCell } from "../session-incarnation.js";
+import { judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+function lockedRowFrom(dialect, sessionId, row) {
+    return {
+        owner: row.owner === null || row.owner === undefined ? null : String(row.owner),
+        incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"),
+        placed: row.placement_kind !== null && row.placement_kind !== undefined,
+        mirror: row.execution_role === "mirror",
+        cells: {
+            title: row.title === null || row.title === undefined ? null : String(row.title),
+            pinned: dialect === "pg" ? row.pinned === true : Number(row.pinned) === 1,
+        },
+    };
+}
+async function lockedLogMark(conn, dialect, sessionId, leafSeq) {
+    const b = binder(dialect);
+    const last = await conn.query(`SELECT entry_id FROM session_event WHERE session_id = ${b.p(sessionId)} ORDER BY seq DESC LIMIT 1 FOR UPDATE`, b.values);
+    const id = last.rows[0]?.entry_id;
+    return { length: Number(leafSeq), lastEntryId: id === undefined || id === null ? null : String(id) };
+}
+export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAnswer) {
+    const dialect = db.dialect;
+    let verdict;
+    const conn = await db.connect();
+    try {
+        await conn.begin();
+        const read = binder(dialect);
+        const locked = (await conn.query(`SELECT owner, incarnation, placement_kind, execution_role, title, pinned, leaf_seq FROM session_meta WHERE session_id = ${read.p(sessionId)} FOR UPDATE`, read.values)).rows[0];
+        const mark = how.row.log === undefined || locked === undefined ? undefined : await lockedLogMark(conn, dialect, sessionId, locked.leaf_seq);
+        verdict = judgeSessionRowWrite(sessionId, how, locked === undefined ? undefined : lockedRowFrom(dialect, sessionId, locked), () => {
+            if (mark === undefined)
+                throw new Error(`writeSessionRowCellsSql: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
+            return mark;
+        });
+        if (verdict !== "write") {
+            await conn.rollback();
+        }
+        else {
+            const w = binder(dialect);
+            const sets = [];
+            if (cells.title !== undefined)
+                sets.push(`title = ${w.p(cells.title)}`);
+            if (cells.pinned !== undefined)
+                sets.push(`pinned = ${w.p(cells.pinned)}`);
+            if (sets.length > 0)
+                await conn.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ${w.p(sessionId)}`, w.values);
+            await conn.commit();
+        }
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+    switch (verdict) {
+        case "absent":
+            return { kind: "absent" };
+        case "mirror":
+            return { kind: "mirror" };
+        case "write":
+        case "changed":
+            return settleSessionRowWrite(how, verdict, await readAnswer(sessionId));
+        default: {
+            const unknownVerdict = verdict;
+            throw new Error(`writeSessionRowCellsSql: no verdict ${JSON.stringify(unknownVerdict)}`);
+        }
+    }
+}
+//# sourceMappingURL=session-row-sql.js.map

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

@@ -46,7 +46,7 @@ export declare function ensureSessionDurable(hostStore: SessionStore, sessionId:
  * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
  * (14ms~2s)+ settle failed,赎回窗口不存在):
  *   0. 属主([ref],`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
- *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与 claim 前后两读的那一位;core 的挂点签名只给子代 id,
+ *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与写口放行的那一位(认领之前解析器那一读);core 的挂点签名只给子代 id,
  *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`:不按新住客晋升 / 认领);
  *      缺席(行上没有根)或根行此刻不在 ⇒ 孤行哨兵。
  *   1. 快路:已在 host 店且有真内容 → 通过,**前提是那一行的属主按律定得下来**(`settleDelegatedOwner`:记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次

package/dist/plugins/session-workspace-cell.d.ts

@@ -0,0 +1,17 @@
+import type { SessionWorkspace } from "../session-workspace.js";
+import { type JsonColumnReader } from "./sql-json-column.js";
+/** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
+export declare const SESSION_META_WORKSPACE_COLUMN: {
+    readonly name: "workspace";
+    readonly tidb: "workspace JSON NULL";
+    readonly pg: "workspace JSONB";
+};
+/** 这一格的形读者(三只店与帧投影同一只;写前也过它 —— 写得进的就是读得出的)。 */
+export declare const readSessionWorkspaceCell: JsonColumnReader<SessionWorkspace>;
+/** 这一格的失败留痕 tag(F 类;登记行在 `observability/fail-open.ts`)。记录座(写 / 帧)与本文件(读)同一只。 */
+export declare const SESSION_WORKSPACE_DEGRADED: "server.session-workspace.record-degraded";
+/** 值 → 这一格的文本。`encode` 是该承载的编码器(MySQL 协议与 local:`JSON.stringify`;PG:`pgSafeJsonStringify`)。写前过形读者,不合形响亮抛、什么都不写。 */
+export declare function encodeSessionWorkspaceCell(workspace: SessionWorkspace, encode: (value: unknown) => string, sessionId: string): string;
+/** 一格(已按文本投影;SQL NULL / local 缺键 ⇒ 调用方传 `null`)→ 值。坏体 ⇒ 读作没有记录并计一次(见文件头);读腿漏投影 ⇒ 抛。 */
+export declare function decodeSessionWorkspaceCell(cell: unknown, sessionId: string): SessionWorkspace | undefined;
+//# sourceMappingURL=session-workspace-cell.d.ts.map

package/dist/plugins/session-workspace-cell.js

@@ -0,0 +1,38 @@
+import { PROJECT_ID_REGEX } from "@sema-agent/core";
+import { z } from "zod";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { assertJsonColumnWritable, createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
+export const SESSION_META_WORKSPACE_COLUMN = {
+    name: "workspace",
+    tidb: "workspace JSON NULL",
+    pg: "workspace JSONB",
+};
+const SESSION_WORKSPACE_SHAPE = z.object({
+    cwd: z.string().min(1),
+    root: z.string().min(1),
+    entered: z.object({ dir: z.string().min(1), byPath: z.literal(true).optional() }).optional(),
+    project: z.object({ id: z.string().regex(PROJECT_ID_REGEX), source: z.enum(["marker", "declared"]) }).optional(),
+    remote: z.boolean(),
+});
+export const readSessionWorkspaceCell = createZodColumnReader(SESSION_WORKSPACE_SHAPE);
+export const SESSION_WORKSPACE_DEGRADED = "server.session-workspace.record-degraded";
+const where = (sessionId) => `session_meta.workspace for session ${sessionId}`;
+export function encodeSessionWorkspaceCell(workspace, encode, sessionId) {
+    const text = encode(workspace);
+    assertJsonColumnWritable(text, readSessionWorkspaceCell, where(sessionId));
+    return text;
+}
+export function decodeSessionWorkspaceCell(cell, sessionId) {
+    if (cell === null)
+        return undefined;
+    try {
+        return decodeJsonColumn(cell, readSessionWorkspaceCell, where(sessionId));
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        recordFailOpen(SESSION_WORKSPACE_DEGRADED, `op=read ${e.where} problem=${e.problem}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-workspace-cell.js.map

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

@@ -350,7 +350,7 @@ export interface StoreBackend {
      */
     leaderRun?(): LeaderRunStore;
     /**
-     * device lane 的四表店(device-executor-lane-v2 §6,车A-2 交店 / 车A-4 接线)。**SQL 后端专有**,
+     * device lane 的三表店(device-executor-lane-v2 §6,车A-2 交店 / 车A-4 接线;绑定写在根会话行的执行格上,与会话店同一只池)。**SQL 后端专有**,
      * `local` 刻意省略 —— 与 {@link leaderRun} 逐字同一条理由:config 层已经把「`REMOTE_EXEC=device` 且
      * 无外部 SQL 店」整个组合拒启了(`device-durable-store` 不变量),所以 local 车道上根本不存在一个需要
      * 这四张表的 device worker。消费点按 `backend?.device?.()` 取,缺席 ⇒ `boot/device-lane.ts` 的

package/dist/plugins/store-backend.js

@@ -13,7 +13,8 @@ import { LocalWorkflowParkDecisionStore } from "../orchestration/workflow-park-d
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, assertExecutionPlacementSwitchAdmissibleOnPool, backfillLocalAskExecutionLanes, backfillLocalExecutionPlacements, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { deployedExecutionLanes } from "../execution-lane-caps.js";
 import { assertRetiredSchemaAbsentOnPool } from "./schema-consistency.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -53,7 +54,7 @@ import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
-import { TiDBRetentionStore, PgRetentionStore } from "./retention-store-sql.js";
+import { TiDBRetentionStore, PgRetentionStore, sqlStoreRetention } from "./retention-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
 import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
@@ -139,7 +140,7 @@ class TiDBBackend {
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new TiDBSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "tidb", this.pool); }
-    runOneTimeMigrations() { return runSqlOneTimeMigrations("tidb", this.pool); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("tidb", this.pool, { lanes: deployedExecutionLanes(this.config) }); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
     outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); }
@@ -149,9 +150,9 @@ class TiDBBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
+    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     checkpointReadView() { return this.checkpoint(); }
-    toolResult() { return new TiDBToolResultStore(this.pool); }
+    toolResult() { return new TiDBToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
     imageBake() { return new TiDBImageBake(this.pool); }
     leaderRun() { return new TiDBLeaderRunStore(this.pool); }
@@ -161,7 +162,7 @@ class TiDBBackend {
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new TiDBSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
+    session() { return new TiDBSessionStore(this.pool, { log: createLogger(this.config.logLevel), retention: sqlStoreRetention(this.config.retentionSweep) }); }
     adoptionLog() { return new TiDBAdoptionLogStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
@@ -193,7 +194,7 @@ class PgBackend {
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new PgSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
     legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "pg", this.pool); }
-    runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool); }
+    runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool, { lanes: deployedExecutionLanes(this.config) }); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
     outcomeSink() { return new PgOutcomeLedger(this.pool); }
     workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); }
@@ -203,9 +204,9 @@ class PgBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
+    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     checkpointReadView() { return this.checkpoint(); }
-    toolResult() { return new PgToolResultStore(this.pool); }
+    toolResult() { return new PgToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new PgImageIndex(this.pool); }
     imageBake() { return new PgImageBake(this.pool); }
     leaderRun() { return new PgLeaderRunStore(this.pool); }
@@ -215,7 +216,7 @@ class PgBackend {
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new PgSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
+    session() { return new PgSessionStore(this.pool, { log: createLogger(this.config.logLevel), retention: sqlStoreRetention(this.config.retentionSweep) }); }
     adoptionLog() { return new PgAdoptionLogStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
@@ -239,7 +240,9 @@ class LocalBackend {
     onError;
     discloseWarn;
     parkDecisionLedgerRoot;
+    executionLanes;
     constructor(root, config, onWarn, onError) {
+        this.executionLanes = deployedExecutionLanes(config);
         this.onWarn = onWarn;
         this.discloseWarn = onWarn ?? ((msg, meta) => console.warn(msg, meta));
         this.onError = onError;
@@ -282,7 +285,15 @@ class LocalBackend {
     }
     async ensureSchema() { }
     async runOneTimeMigrations() {
-        return { ...NO_SQL_MIGRATIONS, holderDeathCodeRowsBackfilled: this.runStore.migrateLegacyHolderDeathCodes() };
+        const holderDeathCodeRowsBackfilled = this.runStore.migrateLegacyHolderDeathCodes();
+        const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
+        return {
+            ...NO_SQL_MIGRATIONS,
+            holderDeathCodeRowsBackfilled,
+            executionPlacementsBackfilled: placements.backfilled,
+            executionPlacementSessionsUnreadable: placements.unreadable,
+            askExecutionLanesBackfilled: backfillLocalAskExecutionLanes(this.approvalAskStore, { lanes: this.executionLanes }),
+        };
     }
     async close() {
         await this.sessionStore.dispose();
@@ -364,17 +375,18 @@ export function createStoreBackend(config, onWarn, onError) {
         if (!config.pg)
             return undefined;
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs), onWarn);
-        return withRetiredSchemaProbe(new PgBackend(pool, config), { dialect: "pg", pool });
+        return withRetiredSchemaProbe(new PgBackend(pool, config), { dialect: "pg", pool }, { lanes: deployedExecutionLanes(config) });
     }
     if (!config.tidb)
         return undefined;
     const pool = createTidbPool(config);
-    return withRetiredSchemaProbe(new TiDBBackend(pool, config), { dialect: "tidb", pool });
+    return withRetiredSchemaProbe(new TiDBBackend(pool, config), { dialect: "tidb", pool }, { lanes: deployedExecutionLanes(config) });
 }
-function withRetiredSchemaProbe(inner, target) {
+function withRetiredSchemaProbe(inner, target, executionPlacementSwitch) {
     const guarded = Object.create(inner);
     guarded.ensureSchema = async () => {
         await assertRetiredSchemaAbsentOnPool(target);
+        await assertExecutionPlacementSwitchAdmissibleOnPool(target.dialect, target.pool, executionPlacementSwitch);
         await inner.ensureSchema();
     };
     return guarded;

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

@@ -276,26 +276,36 @@ export interface NewRunMeta {
     idem?: RunIdemBinding | null;
 }
 /**
- * `RunStore.createRun` 的结局 —— 三形,一形一句话:
+ * `RunStore.createRun` 的结局 —— 四形,一形一句话:
  *  · `{ ok: true }` —— 新行已建、会话 claim 已拿;
  *  · `{ ok: false, existing }` —— 这次提交的一把**幂等钥匙**已经指向一条行:`idem_key`(`Idempotency-Key`)或
  *    `task_id`(调用方自铸的 `body.taskId`)—— 两把钥匙是**同一条律**(资源行上的唯一键),先认 `idem_key` 再认 `task_id`。
  *    这是「原子赢或观察」的**观察**臂:行原样交回,没建新行、没动会话;回执由提交面的唯一回执函数判。
- *  · `{ ok: false, activeTaskId }` —— 会话被**别的** run 占着(双发守卫),没建行。
- * 另两位在每一形上恒 `undefined`(读 `created.existing` / `created.activeTaskId` 不用先窄化,判别仍是穷举的)。
+ *  · `{ ok: false, activeTaskId }` —— 会话被**别的** run 占着(双发守卫),没建行;
+ *  · `{ ok: false, sessionAbsent: true }` —— 根会话行不在(SQL 孪生在认领事务里锁根行读到零行:受理之后会话被删),没建行、没认领。
+ *    进程内两孪生(File / Memory)的账本里没有会话行,不答这一形。
+ * 其余几位在每一形上恒 `undefined`(读 `created.existing` / `created.activeTaskId` / `created.sessionAbsent` 不用先窄化,判别仍是穷举的)。
  */
 export type CreateRunOutcome = {
     ok: true;
     existing?: undefined;
     activeTaskId?: undefined;
+    sessionAbsent?: undefined;
 } | {
     ok: false;
     existing: RunRecord;
     activeTaskId?: undefined;
+    sessionAbsent?: undefined;
 } | {
     ok: false;
     existing?: undefined;
     activeTaskId: string;
+    sessionAbsent?: undefined;
+} | {
+    ok: false;
+    existing?: undefined;
+    activeTaskId?: undefined;
+    sessionAbsent: true;
 };
 /** SQL 认领栅栏的结局:`held: false` = 认领此刻不是这条 run 的(或它已不在跑),`write` 一次都没调。 */
 export type ClaimFenced<T> = {
@@ -504,13 +514,16 @@ export interface SessionSummary {
      *  零迁移路线 —— result 在终局与 park 时写、认领续跑即清空([ref])⇒ 在跑 run 键诚实缺席);OMIT-when-absent,恒不铸 null。轴辨析与
      *  wire 半场见 `security.ts SessionListItem.lastTaskRunId`(同名同义)。 */
     lastTaskRunId?: string;
-    /** The session's title: the user's (`patchSessionMeta`, unconditional; `null` clears it back to automatic) or the auto-titler's
+    /** The session's title: the user's (`writeSessionRowCells`; `null` clears it back to automatic) or the auto-titler's
      *  (cheap-model one-liner, `setTitleIfNull` — fills NULL only). null = not (yet) titled OR the lister face has no session_meta (the legacy
      *  task_run aggregate / memory twins — honest degrade). Writer order: `src/session-row.ts`. */
     title: string | null;
-    /** Pinned by the user (`patchSessionMeta`). Always present, `false` by default; the legacy task_run aggregate / memory
+    /** Pinned by the user (`writeSessionRowCells`). Always present, `false` by default; the legacy task_run aggregate / memory
      *  twins answer `false` (no session_meta ⇒ nothing there can pin it). */
     pinned: boolean;
+    /** 行标签(`src/session-row.ts` 的 `sessionRowTagOf`):这一位住客「PATCH 能写的每一格」的单向摘要,present-iff 这一行可被条件写(店有行格写原语 ∧ 行上有化身);
+     *  只经店的列表行映射铸(`sessionRowTagKey`)。没有会话行的 lister(legacy task_run 聚合 / 内存孪生)缺席。wire 半场见 `security.ts SessionListItem.rowTag`(同名同义)。 */
+    rowTag?: string;
 }
 /**
  * [ref] —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
@@ -529,6 +542,13 @@ export interface SessionRunRollupSource {
         limit: number;
     }): Promise<ReadonlyArray<Pick<SessionSummary, "sessionId" | "runCount" | "lastStatus" | "lastRunId" | "lastTaskRunId">>>;
 }
+/**
+ * 会话**此刻的 run 认领**(单活槽)的窄读面 —— run 店的 `getActiveTaskId`,同一个问题在 SQL 孪生里是写事务内对 `task_active` 的锁定读。
+ * local 会话店的执行席在 `markMirror` 的写锁内读它,判序与 SQL 孪生同(行不在 / 住客不同 / writer / mirror 先判,认领只拦「absent → mirror」这一笔写)。
+ */
+export interface SessionRunClaimSource {
+    getActiveTaskId(sessionId: string): Promise<string | undefined>;
+}
 /**
  * [ref] —— 「这个会话**最近一条腿**是哪一条 run」的窄读面(`latestRunForSession` 的回值)。
  *

package/dist/plugins/tidb-pool.d.ts

@@ -38,11 +38,15 @@ export declare function createTidbPool(config: ServiceConfig): Pool;
  * ── SCHEMA POLICY (clay 裁,2026-07-26) ─────────────────────────────────────────────────────────────
  * 本仓 schema 的唯一真源 = **这份代码**(此数组 + `pg-pool.ts` 的 PG 孪生)。口径:
  *
- *  1. **删库重建,不做增量。** 尚未上生产、单人本地,存量库一律 DROP DATABASE 重建;因此这里**不再保留
- *     任何 `ALTER TABLE` 增量 seam**。历史上的 21 条 ADD COLUMN / 3 条 CREATE INDEX / 1 条 MODIFY COLUMN
- *     已于 2026-07-26 全部折进下面的 `CREATE TABLE`(它们承载的语义已逐条搬成列上的行内注释 —— 那些注释
- *     是 pre-migration 行为契约的**唯一书面记录**,删注释 = 丢语义)。
- *  2. **不许再新增 `ALTER TABLE` seam。** 要改列/加列/改可空性 ⇒ 直接改下面的 `CREATE TABLE`,然后重建库。
+ *  1. **代码是唯一真源,不做增量。** 存量库缺列由部署者按拒启句里逐字打印的 `ALTER TABLE … ADD COLUMN …`
+ *     自己执行:列集对账与拒启句永不改库。进程自己对**已存在的表**发的 DDL 只有两种 —— 幂等加索引(`ensureIndex`,
+ *     只动索引、不碰列)与登记在册的一次性迁移(每条有窗、有登记行 `one-time-migrations.ts`);加列 / 改列 / 改名 /
+ *     删表只有后者做。因此这里**不再保留任何 `ALTER TABLE` 增量 seam**。历史上的 21 条
+ *     ADD COLUMN / 3 条 CREATE INDEX / 1 条 MODIFY COLUMN 已于 2026-07-26 全部折进下面的 `CREATE TABLE`
+ *     (它们承载的语义已逐条搬成列上的行内注释 —— 那些注释是 pre-migration 行为契约的**唯一书面记录**,
+ *     删注释 = 丢语义)。
+ *  2. **不许再新增 `ALTER TABLE` seam。** 要加列 ⇒ 直接改下面的 `CREATE TABLE`:新建库随它到货;带数据的存量库由列集对账拒启并逐列打印 `ALTER`,部署者自己执行(**不重建带数据的库**)。
+ *     改列类型 / 改可空性 / 改写存量字节 —— 列集对账只比列名、看不见这类漂移 —— 另走一次性迁移(带窗)或在升级步里写明手工语句。只有空库 / 开发机可以整库重建(销毁全部数据)。
  *     (再开增量通道就等于把「代码是真源」变回「代码 + 一串按时间排的补丁才是真源」。)
  *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
  *     —— 冲突时以本文件为准并重新生成)。
@@ -83,8 +87,9 @@ export declare const SCHEMA_INDEXES: readonly IndexSpec[];
  *
  *  Per the SCHEMA POLICY on {@link SCHEMA_STATEMENTS} this is a pure CREATE run — there are NO additive
  *  ALTER/CREATE-INDEX seams and no information_schema probes any more (2026-07-26): the schema contract is
- *  drop-and-recreate, so every column / index / nullability lives in its `CREATE TABLE`. Do not reintroduce a
- *  migration loop here; change the CREATE and rebuild the database.
+ *  code-as-single-source, so every column / index / nullability lives in its `CREATE TABLE`; an existing database that lacks
+ *  a column is refused at boot with the ALTER statements printed and its deployer runs them. Do not reintroduce a
+ *  migration loop here; change the CREATE (only a throwaway dev database may be recreated, which destroys all of its data).
  *
  *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each
  *  beforeAll calls ensureSchema), and in production every replica calls it at boot (`--scale service=4`).

package/dist/plugins/tidb-pool.js

@@ -7,6 +7,8 @@ import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
+import { sessionMetaPlacementColumnsDdl } from "./execution-placement-sql.js";
+import { SESSION_META_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
@@ -62,17 +64,22 @@ export const SCHEMA_STATEMENTS = [
      leaf_id     VARCHAR(64)  NULL,
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
      -- title: ONE column, two writers, one law (src/session-row.ts): the user's write (PATCH /v1/sessions/:id →
-     -- patchSessionMeta, unconditional; null = cleared back to the automatic title) and the auto-titler (cheap-model
+     -- writeSessionRowCells, unconditional unless the PATCH carries expectedRowTag; null = cleared back to the automatic title) and the auto-titler (cheap-model
      -- one-liner on a submit that finds it NULL; setTitleIfNull, fills NULL only) — a user-set title is never overwritten,
      -- a cleared one is filled again. Width = SESSION_TITLE_MAX_CHARS (the wire bound).
      title       VARCHAR(${SESSION_TITLE_MAX_CHARS}) NULL,
-     -- pinned: the user's pin (PATCH /v1/sessions/:id → patchSessionMeta); every list row carries it, false by default.
+     -- pinned: the user's pin (PATCH /v1/sessions/:id → writeSessionRowCells); every list row carries it, false by default.
      pinned      BOOLEAN      NOT NULL DEFAULT FALSE,
      -- instruction_source(S-690):本会话**上一次 run** 选中的项目指令文件 = 换源通告(instructions.source_changed)
      -- 的基线。NULL = 还没有任何 run 记过(首 run 只写不发);'' = 记过、那一次没有项目指令文件;其余 = 链成员相对路径
      -- (CLAUDE.md / .claude/CLAUDE.md / AGENTS.md / .claude/AGENTS.md)。服务端元数据:不进模型上下文、不进 wire
      -- 会话面;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL(新会话首 run 同样只写不发)。
      instruction_source VARCHAR(64) NULL,
+     -- workspace:本会话上一条腿**自己的**最后一帧 workspace_changed(引擎 7.58.0 的整份快照:cwd / root / entered / project / remote)。
+     -- NULL = 还没有任何腿记过;唯一写者 = 腿的记录座(src/session-workspace.ts),列属主 = src/plugins/session-workspace-cell.ts
+     -- (列定义、形读者、编解码;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里给出 ALTER)。下一条腿的 TaskSpec.projectId 读它的 project.id。
+     -- 服务端元数据:不进 wire 会话面、不进模型上下文;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL。
+     ${SESSION_META_WORKSPACE_COLUMN.tidb},
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组,**创建时一次落行、
      -- first-write 不可变**(register 的 ON DUPLICATE 臂永不重写这六列)。判别位 = placement_kind:
      -- 在场 ⇒ 该会话住在 placement 分区里(不上宿主枚举、claim 形 acquire 恒拒、release=真删除、
@@ -90,6 +97,11 @@ export const SCHEMA_STATEMENTS = [
      -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.tidb},
+     -- 执行放置:根会话行上**这一位住客**的一格 —— execution_role('writer' | 'mirror' | NULL = absent)、execution_lane、device 车道的设备与绑定属主、
+     -- 放下时刻、换绑序号;写只按住客谓词 (session_id, incarnation, owner) ∧ placement_kind IS NULL(换了住客 = 这一格不在)。fork_key = 建这一行的那次
+     -- fork 请求的键(只由 fork 创建点写,此后每个写携带)。规则在 src/execution-placement.ts,列定义与语句的唯一属主 = src/plugins/execution-placement-sql.ts
+     -- (存量库缺这些列 ⇒ 起服列册对账拒启;加列只由一次性迁移做)。
+     ${sessionMetaPlacementColumnsDdl("tidb")},
      PRIMARY KEY (session_id),
      KEY idx_session_meta_owner (owner),
      -- listPlaced 的检索腿(kind + 租户 + 年龄升序);普通会话这三列全 NULL ⇒ 不占索引选择性。
@@ -296,7 +308,7 @@ export const SCHEMA_STATEMENTS = [
      -- approval_card(core 7.55.0 #1468 P1 阶段二):门上的卡词**照存**(core checkpointIndexFacts(cp).approvalCard:TOOL_APPROVAL_CARDS 的词,或本引擎不认的串 ——
      -- 留着,更晚的引擎读得对);非审批门 / 无卡 / 非串 = NULL。写口与一次性迁移 M29 的存量回填同一只派生(plugins/checkpoint-index-columns.ts)。
      -- 读者:到期 facet 的生成谓词(由 core CARD_FACET_OVERRIDES + PAUSE_REGISTRY 生成;**不存 facet 本身** —— 存一份会在 core 改表那天陈旧)、运维队列行的卡。
-     -- 本仓不发 ALTER:存量库缺这一列 ⇒ 起服列册对账拒启并给 ADD COLUMN 句(持久数据:表里是在飞的停驻,不删表重建)。
+     -- 本仓不发 ALTER:存量库缺这一列 ⇒ 起服列册对账拒启并给 ADD COLUMN 句(持久数据:表里是在飞的停驻,只加列)。
      -- 列型 TEXT 而不是定长 VARCHAR:引擎照存集外词,长度不由本仓定(191 字的集外词照存)。TEXT 自己的容量是 65,535 **字节**(plugins/checkpoint-index-columns.ts 的
      -- APPROVAL_CARD_COLUMN_MAX_BYTES):引擎铸的卡词是闭集短词,超出只会是手改 / 外来写者的存量行 —— M29 回填对这样的行计数 + 点名跳过,不写、不挡起服。
      approval_card TEXT         NULL,