@sema-agent/server 7.137.0 → 7.139.0

package/dist/plugins/approval-ask-store-file.js

@@ -1,4 +1,5 @@
 import { closeSync, copyFileSync, openSync, readSync, statSync, existsSync } from "node:fs";
+import { isExecutionLane } from "../execution-lane-caps.js";
 import { join } from "node:path";
 import { AppendLog, atomicWriteFile, ensureDir } from "@sema-agent/core";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
@@ -295,6 +296,16 @@ export class FileApprovalAskStore {
     replayStats() {
         return { rejected: this.replayRejectedCount, corruptLines: this.corruptLineCount, records: this.records };
     }
+    backfillExecutionLanes(lanes, refuse) {
+        const pending = this.core.exportRows().asks.filter((r) => !isExecutionLane(String(r.executionLane ?? ""))).length;
+        if (pending === 0)
+            return 0;
+        if (lanes.length !== 1)
+            refuse(pending);
+        const filled = this.core.fillMissingExecutionLanes(lanes[0]);
+        this.compact();
+        return filled;
+    }
     dispose() {
         this.log?.close();
         this.log = undefined;

package/dist/plugins/approval-ask-store-memory.d.ts

@@ -29,6 +29,7 @@
  *  - resolveProvisional 故意不经 canAskTransition(同 SQL twin 头注：这是版本化补偿的例外通道）。
  */
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
+import { type ExecutionLane } from "../execution-lane-caps.js";
 import type { AskCallCoordinate, AskDecision, AskRow, AskTerminalClaimIntent, AskTerminalClaimOpts, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, EnsureAskResult, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
 /**
  * [ref] 的 `updatedInput` **入店编码**——两 twin 共用的那一只(本函数是唯一真源)。
@@ -72,6 +73,11 @@ export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
      * 两种可变性)。
      */
     exportRows(): ApprovalAskRowsSnapshot;
+    /**
+     * 执行放置切换 ④b 的 local 腿(File 形的内核口;`FileApprovalAskStore.backfillExecutionLanes` 调):出处车道还没记下的行(升级前写下的日志 / 快照行
+     * 装回后这一格缺席)记成 `lane`(一元车道表的唯一项 —— 调用方判过)。返回改了的行数;只碰缺这一格的行。
+     */
+    fillMissingExecutionLanes(lane: ExecutionLane): number;
     /** [ref]:一行的**同步**点读(拷贝;纯读,零判定)—— File 形在写口的同步前缀里用它(见类顶注)。 */
     peekAsk(askId: string): AskRow | null;
     /** [ref]:把快照里的行**原样**装回两张 Map(同键覆盖)。零谓词、零状态机 —— 它不是一条转移,是重放

package/dist/plugins/approval-ask-store-memory.js

@@ -1,4 +1,5 @@
 import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
+import { isExecutionLane } from "../execution-lane-caps.js";
 import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
 import { askRowCarriesOwner, askRowOnCall, assertDecideSettledBy, assertIdempotencyKeyShape, assertIntegralEpochMs, assertReapBounds, ApprovalAskReadAbortedError, claimTargetState, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth, projectDecideReading } from "./approval-ask-store-sql.js";
 function applyPatch(row, patch) {
@@ -41,6 +42,16 @@ export class InMemoryApprovalAskStore {
     exportRows() {
         return { asks: [...this.asks.values()].map((r) => ({ ...r })), batches: [...this.batches.values()].map((b) => ({ ...b })) };
     }
+    fillMissingExecutionLanes(lane) {
+        let filled = 0;
+        for (const [askId, row] of this.asks) {
+            if (isExecutionLane(String(row.executionLane ?? "")))
+                continue;
+            this.asks.set(askId, { ...row, executionLane: lane });
+            filled += 1;
+        }
+        return filled;
+    }
     peekAsk(askId) {
         const row = this.asks.get(askId);
         return row ? { ...row } : null;
@@ -74,6 +85,7 @@ export class InMemoryApprovalAskStore {
             sourceTaskId: row.sourceTaskId,
             sessionId: row.sessionId,
             owner: row.owner ?? null,
+            executionLane: row.executionLane,
             batchId: row.batchId,
             toolCallId: row.toolCallId,
             legKey: row.legKey,

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -44,6 +44,7 @@ import { type AskState, type BatchState } from "../approval-ask-machine.js";
 import type { HostSettledBy } from "../host-decision.js";
 import { type AskRowCause, type SettleCause } from "../approval-deny-reasons.js";
 import { type IndexSpec } from "./ensure-index.js";
+import { type ExecutionLane } from "../execution-lane-caps.js";
 export type AskDecision = "approve" | "deny";
 export interface AskRow {
     askId: string;
@@ -52,6 +53,11 @@ export interface AskRow {
     sessionId: string;
     /** 租户 scope——哨兵归一在消费层(车2+),店里存原值(设计定稿 §3)。 */
     owner: string | null;
+    /**
+     * 造这只问的那条执行的车道(审批出处带车道:问行唯一铸点 `ensureAsk` 与 `taskId` / `sessionId` 同处写;既有行命中一个字节不改)。
+     * 读根授权只读问自己记下的车道。存量行随执行放置切换的一次性迁移回填(SQL `approval_ask.execution_lane`、local 问账日志压实)。
+     */
+    executionLane: ExecutionLane;
     batchId: string;
     toolCallId: string;
     /** 车3 §3.2′ 换轴:数值 `leg` → `legKey`(= `sha256(resume token)` 的 hex,首腿空串)。语义与派生
@@ -174,6 +180,8 @@ export interface NewAskRow {
     sourceTaskId: string;
     sessionId: string;
     owner?: string | null;
+    /** 出处的执行车道(必填;语义见 {@link AskRow.executionLane})。 */
+    executionLane: ExecutionLane;
     batchId: string;
     toolCallId: string;
     legKey: string;
@@ -562,6 +570,14 @@ export interface ApprovalAskStore {
     getBatch(batchId: string): Promise<BatchRow | null>;
 }
 export declare const APPROVAL_ASK_TABLE = "approval_ask";
+/**
+ * `approval_ask.execution_lane` 的列定义(两方言;唯一属主)—— 建表 DDL 内联它,存量库的加列只由执行放置切换的一次性迁移做(`one-time-migrations.ts` M32 步 ②),
+ * 那一步也读这里的定义。`DEFAULT ''` 只为存量库一句加列;回填(同迁移步 ④b)之后没有 '' 行,读口对 '' 与词表外的值一律响亮拒({@link executionLaneColumnOf})。
+ */
+export declare const APPROVAL_ASK_EXECUTION_LANE_COLUMN: {
+    readonly mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''";
+    readonly pg: "execution_lane VARCHAR(32) COLLATE \"C\" NOT NULL DEFAULT ''";
+};
 export declare const APPROVAL_BATCH_TABLE = "approval_batch";
 /**
  * TiDB/MySQL-protocol 侧的两条建表语句,**抽成导出数组**(车3 刀 3a):`tidb-pool.ts` 的
@@ -571,7 +587,8 @@ export declare const APPROVAL_BATCH_TABLE = "approval_batch";
  * 下面的 `ensureTiDBApprovalAskSchema` 保留为遍历这个数组的薄壳(集成测试直接调它建表,
  * 不必为了建两张表去拉起整套中央 schema)。
  *
- * SCHEMA POLICY 同 `tidb-pool.ts` 头注:纯 CREATE,禁 ALTER 增量 seam,改列直接改这里 + 重建库
+ * SCHEMA POLICY 同 `tidb-pool.ts` 头注:纯 CREATE,禁 ALTER 增量 seam,加列直接改这里(新建库随它到货;带数据的存量库由列集对账拒启并打印 `ALTER`,部署者自己执行;
+ * 改列类型 / 可空性列集对账看不见,另走一次性迁移;只有空库 / 开发机可以整库重建〔销毁全部数据〕)
  * (`docs/schema/baseline-mysql.sql` 是由这些文本机器录制出的**产物**,永不手改)。
  *
  * ── 列宽的**测量依据**([ref] A10;U2 逐列取证在档)──────────────────────────────────────────────────
@@ -619,18 +636,18 @@ export declare function ensurePgApprovalAskSchema(q: PgQueryFn): Promise<void>;
  * [ref] 升级前置断言 —— **拒启**,不是 warn(形照 [ref] 的 `assertPermissionRuleApprovalSchema` /
  * [ref] 的 `assertToolResultProvenanceSchema` 两条先例)。
  *
- * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升上来
+ * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。于是一台**没跟上**就升上来
  * 的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `approval_ask` 是空操作 —— 本车新加的
  * `rule_command` / `rule_scope_root` 两列不在,而 `ensureAsk` 的 INSERT 与 `askCols` 的每一条读
  * **无条件**引用它们。后果不是「少一个新功能」,是**整条流内审批协议**在那台机器上是坏的:
  *  · 每一只 ask 的 `ensureAsk` 撞 unknown column ⇒ 被 `noteStoreError` 吞掉 ⇒ 整只 ask 退回 park 路由
  *    (卡不落库、`GET /v1/approvals` 的重放面恒空、迟到决议腿恒 404);
  *  · 而 `/v1/capabilities` 的 `streamApproval` 仍然报 active ⇒「says yes ⟺ route works」整句为假。
- * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 正是 [ref]「禁静默降级」要挡的形。
+ * 没有这道断言,运维得不到**任何**「这次升级必须先给表加列」的信号 —— 正是 [ref]「禁静默降级」要挡的形。
  *
  * 判据 = **能力探测**(恒空的 `WHERE 1=0` 读)+ **方言的缺列错误码**(判据属主 `sql-errors.ts` 的
- * {@link isMissingColumnError});其余错误**原样 rethrow**,一个字都不加工 —— 一句破坏性的
- * 「去 DROP TABLE」指路比它要挡的缺陷更贵([ref] 那两轮收窄的结论逐字继承)。
+ * {@link isMissingColumnError});其余错误**原样 rethrow**,一个字都不加工 —— 把一次瞬时故障诊断成「缺列」的拒因
+ * 比它要挡的缺陷更贵([ref] 那两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
  *
  * 🔴 位置与两条先例同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
  * 放在 DDL 之后、任何路由装配之前;且**只在流内审批协议真会上场时**跑(判据 = 与协调器同一个符号

package/dist/plugins/approval-ask-store-sql.js

@@ -2,8 +2,10 @@ import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
 import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { isExecutionLane } from "../execution-lane-caps.js";
 export function assertIntegralEpochMs(field, value) {
     if (!Number.isSafeInteger(value)) {
         throw new TypeError(`approval-ask store: ${field} must be an integer epoch-ms (BIGINT column), got ${String(value)}`);
@@ -99,6 +101,17 @@ export function projectDecideReading(row, owner) {
     return askRowCarriesOwner(row, owner) ? row : null;
 }
 export const APPROVAL_ASK_TABLE = "approval_ask";
+export const APPROVAL_ASK_EXECUTION_LANE_COLUMN = {
+    mysql: "execution_lane VARCHAR(32) NOT NULL DEFAULT ''",
+    pg: `execution_lane VARCHAR(32) COLLATE "C" NOT NULL DEFAULT ''`,
+};
+function executionLaneColumnOf(raw, askId) {
+    const lane = typeof raw === "string" ? raw : "";
+    if (!isExecutionLane(lane)) {
+        throw new Error(`approval-ask-store: ask ${askId} carries execution_lane ${JSON.stringify(lane)}, which is not an execution lane — the execution placement switch migration backfills every row; refusing rather than guess the lane this ask was raised on`);
+    }
+    return lane;
+}
 export const APPROVAL_BATCH_TABLE = "approval_batch";
 export const TIDB_APPROVAL_ASK_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${APPROVAL_BATCH_TABLE} (
@@ -118,6 +131,9 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     source_task_id VARCHAR(255) NOT NULL,
     session_id VARCHAR(64) NOT NULL,
     owner VARCHAR(190) NULL,
+    -- execution_lane:造这只问的那条执行的车道(审批出处带车道;ensureAsk 铸行时写,既有行命中不改)。DEFAULT '' 只为存量库一句加列
+    -- (一次性迁移加列并按根会话放置回填,迁移后没有 '' 行)。
+    ${APPROVAL_ASK_EXECUTION_LANE_COLUMN.mysql},
     batch_id VARCHAR(64) NOT NULL,
     tool_call_id VARCHAR(255) NOT NULL,
     -- leg_key: 车3 §3.2′ 身份轴——sha256(resume checkpoint token) 的 hex(64 字符),首腿存空串。
@@ -172,7 +188,7 @@ export const TIDB_APPROVAL_ASK_STATEMENTS = [
     UNIQUE KEY uq_approval_ask_idem (task_id, idempotency_key),
     KEY idx_ask_task_state (task_id, state),
     -- idx_ask_session_state: 车3 §5.1 的 sync 腿开流重放读口(listPendingBySession)的支撑索引。
-    -- 表尚未进生产 + SCHEMA POLICY 是删库重建 ⇒ 此刻加索引零迁移成本,晚一车加就要动生产表。
+    -- 表尚未进生产 ⇒ 此刻加索引零迁移成本,晚一车加就要动生产表。
     KEY idx_ask_session_state (session_id, state),
     KEY idx_ask_batch (batch_id),
     KEY idx_ask_state (state)
@@ -206,6 +222,8 @@ export async function ensurePgApprovalAskSchema(q) {
     source_task_id VARCHAR(255) COLLATE "C" NOT NULL,
     session_id VARCHAR(64) COLLATE "C" NOT NULL,
     owner VARCHAR(190) COLLATE "C",
+    -- execution_lane —— MySQL twin 逐字同形(语义见那侧注)。
+    ${APPROVAL_ASK_EXECUTION_LANE_COLUMN.pg},
     batch_id VARCHAR(64) COLLATE "C" NOT NULL,
     tool_call_id VARCHAR(255) COLLATE "C" NOT NULL,
     -- leg_key: 车3 §3.2′ 身份轴——sha256(resume checkpoint token) 的 hex(64 字符),首腿存空串
@@ -258,18 +276,16 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
             `persisted on the row too, so a replica that does not hold the waiting leg replays the approved bytes; every ask-row ` +
             `write and read names these columns unconditionally, so on this table the whole in-stream approval protocol degrades silently (no card ` +
             `is persisted, the replay list stays empty, late decisions 404) while /v1/capabilities still reports it active. ` +
-            `This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
-            `\`DROP TABLE ${APPROVAL_ASK_TABLE}; DROP TABLE ${APPROVAL_BATCH_TABLE};\` on the ` +
-            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
-            `The cost is bounded: these two tables hold IN-FLIGHT approval asks (cards awaiting an answer) plus settled ` +
-            `bookkeeping; the durable park face (checkpoint rows) and the persisted rules themselves are untouched, so an ` +
-            `in-flight card falls back to the durable gate (\`POST /v1/approvals/:sessionId/decide\`). ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `The table holds IN-FLIGHT approval asks (cards awaiting an answer) plus settled bookkeeping; the durable park face ` +
+            `(checkpoint rows) and the persisted rules themselves are untouched, so an in-flight card falls back to the durable gate ` +
+            `(\`POST /v1/approvals/:sessionId/decide\`) until the columns exist.\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, [APPROVAL_ASK_TABLE])));
     }
 }
 function askCols(dialect) {
     return [
-        "ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state",
+        "ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state",
         "provisional, rev, decision",
         jsonColumnText(dialect, "decision_actor"),
         "decision_note, settled_by",
@@ -307,6 +323,7 @@ function mapAskRowBody(r, askId) {
         sourceTaskId: String(r.source_task_id),
         sessionId: String(r.session_id),
         owner: strOrNull(r.owner),
+        executionLane: executionLaneColumnOf(r.execution_lane, askId),
         batchId: String(r.batch_id),
         toolCallId: String(r.tool_call_id),
         legKey: String(r.leg_key),
@@ -410,14 +427,15 @@ export class SqlApprovalAskStore {
         try {
             await conn.begin();
             await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES (?, ?, 'OPEN', 0, ?, ?)`, `INSERT INTO ${APPROVAL_BATCH_TABLE} (batch_id, task_id, state, rev, created_at_ms, updated_at_ms) VALUES ($1, $2, 'OPEN', 0, $3, $4) ON CONFLICT (batch_id) DO NOTHING`), [row.batchId, row.taskId, now, now]);
-            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
-                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $11, $12, $13, $14, $15, $16, $17) ON CONFLICT (ask_id) DO NOTHING"), [
+            const askInsert = await conn.query(this.q(`INSERT IGNORE INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)", `INSERT INTO ${APPROVAL_ASK_TABLE} (ask_id, task_id, source_task_id, session_id, owner, execution_lane, batch_id, tool_call_id, leg_key, parent_tool_call_id, bound_input_hash, state, provisional, rev, decision, decision_actor, decision_note, settled_by, decided_at_ms, denied_reason, gate_token, gate_bound_call_id, gate_bound_input_hash, idempotency_key, card_json, rule_command, rule_scope_root, schema_version, expires_at_ms, created_at_ms, updated_at_ms) ` +
+                "VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, 'STREAM_PENDING', 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $12, $13, $14, $15, $16, $17, $18) ON CONFLICT (ask_id) DO NOTHING"), [
                 row.askId,
                 row.taskId,
                 row.sourceTaskId,
                 row.sessionId,
                 row.owner ?? null,
+                row.executionLane,
                 row.batchId,
                 row.toolCallId,
                 row.legKey,

package/dist/plugins/background-agent-store-sql.js

@@ -3,6 +3,7 @@ import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
+import { backgroundAgentNameOf } from "../background-agent-name.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 function summaryCols(dialect) {
     return ("handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, " +
@@ -11,12 +12,14 @@ function summaryCols(dialect) {
 const readAgentRecordBody = createObjectColumnReader();
 const readUsageBody = createObjectColumnReader();
 function readRecordColumn(v, handle) {
+    let record;
     try {
-        return decodeJsonColumn(v, readAgentRecordBody, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`);
+        record = decodeJsonColumn(v, readAgentRecordBody, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`);
     }
     catch (e) {
         throw foldJsonColumn(e, (m) => `BackgroundAgentStore: ${m} — refusing rather than serve a hollow agent record`);
     }
+    return { ...record, name: backgroundAgentNameOf(record) };
 }
 function readUsageColumn(v, handle) {
     try {
@@ -45,7 +48,7 @@ function projParams(stored, json, text) {
         stored.parentSessionId ?? null,
         stored.rootSessionId ?? null,
         (stored.sessionScoped ? stored.owner : stored.parentSessionId) ?? null,
-        stored.name !== undefined ? text(stored.name).slice(0, 255) : null,
+        text(backgroundAgentNameOf(stored)).slice(0, 255),
         stored.agentType !== undefined ? text(stored.agentType).slice(0, 190) : null,
         stored.status,
         stored.spawnedAt,
@@ -68,7 +71,7 @@ function rowToSummary(r) {
         ...(r.session_id !== null && r.session_id !== undefined ? { sessionId: String(r.session_id) } : {}),
         ...(r.parent_session_id !== null && r.parent_session_id !== undefined ? { parentSessionId: String(r.parent_session_id) } : {}),
         ...(r.root_session_id !== null && r.root_session_id !== undefined ? { rootSessionId: String(r.root_session_id) } : {}),
-        ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}),
+        name: backgroundAgentNameOf({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }),
         ...(r.agent_type !== null && r.agent_type !== undefined ? { agentType: String(r.agent_type) } : {}),
         status: String(r.status),
         spawnedAt: Number(r.spawned_at_ms),

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

@@ -3,6 +3,7 @@ import type { OwnerAwareSessionStore, SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import type { InstructionSourceStore } from "../instruction-source-notice.js";
+import type { SessionWorkspaceStore } from "../session-workspace.js";
 import type { OwnerlessClaim } from "../delegated-session-owner.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
@@ -53,7 +54,7 @@ export declare class CachingSessionStore implements SessionStore {
     private readonly onStaleHit?;
     /** core `SessionStore.headOf` —— 按 id 读一行(属主 / 住客 / 叶子)的唯一读口,**纯转发、不经暖缓存**(答的是行,绝不从暖缓存里那只会话的元数据答 ——
      *  缓存的会话活得比「另一只店删掉又重建了这一行」长)。内层店必有(本类的暖命中按它核新鲜)。🔴 必须转发:生产默认把真店包进本类,授权口 / 属主门 /
-     *  parked 两读 / k8s 工作区空间 / SSE 探针 / resume-at 读的都是本类。 */
+     *  k8s 工作区空间 / SSE 探针 / resume-at 读的都是本类。 */
     readonly headOf: SessionHeadReader["headOf"];
     readonly register?: (sessionId: string, owner: string | null) => Promise<void>;
     /** [ref] 委派继承律的认领口,纯转发(写的是行上的属主那一格 —— 只 CAS 子行自己,不碰暖缓存里的会话;停驻挂点在默认部署上读的就是本类 —— 与 `placementOf` 同转发同缺:内店记录委派树 ⇒ 两只都在)。 */
@@ -71,12 +72,16 @@ export declare class CachingSessionStore implements SessionStore {
         q?: string;
     }) => Promise<SessionListItem[]>;
     readonly fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
+    /** fork 续写的店契约(原样转发;与 fork 同理绕过暖缓存 —— 读写的是持久行,新 id 本来就不在缓存里)。 */
+    readonly forkTo?: OwnerAwareSessionStore["forkTo"];
+    /** 执行席(原样转发:放置是会话**行**上的一格,缓存只缓存会话日志的暖句柄,不缓存行格 —— 读与写都直达内层店)。 */
+    readonly executionPlacement?: OwnerAwareSessionStore["executionPlacement"];
     readonly deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
     /** The session row's list projection for one id + its writable bits (`title` / `pinned`) — DURABLE, pure pass-through
      *  (they read / write `session_meta` / the local sidecars, never the warm cache). 🔴 Must forward (the retention / placements
      *  lesson): the production default wraps the real store in this class, and the route's fact `sessionPatch` reads THIS object. */
     readonly sessionSummaryOf?: (sessionId: string) => Promise<SessionListItem | undefined>;
-    readonly patchSessionMeta?: OwnerAwareSessionStore["patchSessionMeta"];
+    readonly writeSessionRowCells?: OwnerAwareSessionStore["writeSessionRowCells"];
     /** The auto-titler's NULL-only title write (SQL twins + local sidecar carry it; pure pass-through). */
     readonly setTitleIfNull?: (sessionId: string, title: string) => Promise<boolean>;
     readonly probeTitle?: (sessionId: string) => Promise<"none" | "untitled" | "titled">;
@@ -85,6 +90,10 @@ export declare class CachingSessionStore implements SessionStore {
      *  而装配点按「店上两个方法都在」判席 —— 不转发 = 默认部署上换源通告**静默不发**,且没有任何一处报错。 */
     readonly readInstructionSource?: InstructionSourceStore["readInstructionSource"];
     readonly recordInstructionSource?: InstructionSourceStore["recordInstructionSource"];
+    /** 会话行的位置与项目那一格(`session_meta.workspace` / local sidecar;`session-workspace.ts`),纯转发、不经暖缓存。
+     *  🔴 必须转发(同上一条教训):装配点与 resolveSpec 按「店上两个方法都在」判这一面 —— 不转发 = 默认部署上不记行、续跑腿不续声明项目,且没有任何一处报错。 */
+    readonly readSessionWorkspace?: SessionWorkspaceStore["readSessionWorkspace"];
+    readonly recordSessionWorkspace?: SessionWorkspaceStore["recordSessionWorkspace"];
     /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
      *  list/fork: an export reads the full durable log, an import writes durable state). */
     readonly exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;

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

@@ -12,13 +12,17 @@ export class CachingSessionStore {
     claimOwnerless;
     listSessions;
     fork;
+    forkTo;
+    executionPlacement;
     deleteSession;
     sessionSummaryOf;
-    patchSessionMeta;
+    writeSessionRowCells;
     setTitleIfNull;
     probeTitle;
     readInstructionSource;
     recordInstructionSource;
+    readSessionWorkspace;
+    recordSessionWorkspace;
     exportEntries;
     listEntryIds;
     exportEntriesStream;
@@ -55,8 +59,8 @@ export class CachingSessionStore {
             this.listSessions = ownerAware.listSessions.bind(inner);
         if (ownerAware.sessionSummaryOf)
             this.sessionSummaryOf = ownerAware.sessionSummaryOf.bind(inner);
-        if (ownerAware.patchSessionMeta)
-            this.patchSessionMeta = ownerAware.patchSessionMeta.bind(inner);
+        if (ownerAware.writeSessionRowCells)
+            this.writeSessionRowCells = ownerAware.writeSessionRowCells.bind(inner);
         if (ownerAware.setTitleIfNull)
             this.setTitleIfNull = ownerAware.setTitleIfNull.bind(inner);
         if (ownerAware.probeTitle)
@@ -65,8 +69,16 @@ export class CachingSessionStore {
             this.readInstructionSource = ownerAware.readInstructionSource.bind(inner);
         if (ownerAware.recordInstructionSource)
             this.recordInstructionSource = ownerAware.recordInstructionSource.bind(inner);
+        if (ownerAware.readSessionWorkspace)
+            this.readSessionWorkspace = ownerAware.readSessionWorkspace.bind(inner);
+        if (ownerAware.recordSessionWorkspace)
+            this.recordSessionWorkspace = ownerAware.recordSessionWorkspace.bind(inner);
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
+        if (ownerAware.forkTo)
+            this.forkTo = ownerAware.forkTo.bind(inner);
+        if (ownerAware.executionPlacement)
+            this.executionPlacement = ownerAware.executionPlacement;
         if (ownerAware.exportEntries)
             this.exportEntries = ownerAware.exportEntries.bind(inner);
         if (ownerAware.listEntryIds)

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

@@ -3,6 +3,7 @@ import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolvedOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity, type ToolApprovalCard } from "@sema-agent/core";
 import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 /** ctx 行改写店腿的读数(两孪生同形):扫到的可读行 · 回写成的行 · 回写成的行里改写函数报的改动数 · 读不出的行 · 改写之后一行装不下的行。 */
 export interface CtxRowsRewrite {
@@ -239,8 +240,8 @@ export declare function pendingRowPrecedes(a: {
  *
  * 🔴 为什么是一张表而不是每列一个 `assert*ColumnSchema` 函数([ref] 归一):[ref]① 那次是一列一函数,
  * 本批 [ref] 又要加两列 —— 照抄就是第二、第三份三十行的同形代码,而它们**唯一的差别只有列名与那句话**。
- * 探测法(恒空 `WHERE 1=0` 读 + 方言缺列码)、失败方向(只在**可证**缺列时才给删表指路)、恢复动作
- * (DROP TABLE checkpoint 的代价交代)三者对整张表是同一条,所以规则只留一条,列变成数据:下一次加列
+ * 探测法(恒空 `WHERE 1=0` 读 + 方言缺列码)、失败方向(只在**可证**缺列时才拒)、恢复动作
+ * (部署者按拒因打印的 ALTER 在原表上加列;表里是在飞的停驻,不动它)三者对整张表是同一条,所以规则只留一条,列变成数据:下一次加列
  * 只加一行,不再多一条规则。
  */
 export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
@@ -253,14 +254,15 @@ export declare const CHECKPOINT_ADDED_COLUMNS: ReadonlyArray<{
  * 依据是本仓 assert*Schema 探针族的真先例与失败方向本身)。[ref] 起判据对 {@link CHECKPOINT_ADDED_COLUMNS}
  * **整张列册**跑(见那张表的头注:归一的理由)。
  *
- * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:改列就改 CREATE + 删库重建)。一台**没删表**就升上来的
+ * 病:本仓不发 `ALTER TABLE`(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。一台**没跟上**就升上来的
  * 部署,`CREATE TABLE IF NOT EXISTS` 对存量 `checkpoint` 是空操作 —— 后加的列不在,而写口与读口
  * **无条件**引用它们。没有这道断言,服务照常过启动与健康检查,直到运行期才响,且首撞点在用户的
  * 审批 / resume 路径上。
  *
  * 判据 = **能力探测**(恒空的 `WHERE 1=0` 读)+ **方言的缺列错误码**({@link isMissingColumnError},
- * 判据属主 `sql-errors.ts`);其余错误**原样 rethrow**,一个字都不加工 —— 一句破坏性的「去 DROP TABLE」
- * 指路比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。
+ * 判据属主 `sql-errors.ts`);其余错误**原样 rethrow**,一个字都不加工 —— 把一次瞬时故障诊断成「缺列」的拒因
+ * 比它要挡的缺陷更贵([ref] 两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift}),
+ * 没有销毁性的一条:这张表里是在飞的停驻,出路是原表上加列。
  *
  * 位置:与三条先例同款,不在 `ensureSchema` 里(那条通道的契约是「只发 CREATE」),放在 boot 的
  * store 装配段、路由装配之前;**无条件**跑(与 [ref] tool_result 探针同档)——checkpoint 表在两方言的
@@ -464,9 +466,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     protected readonly logger?: {
         info?(msg: string, meta?: unknown): void;
     } | undefined;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
-     *  逐字见 {@link MANAGED_RETENTION}(本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
+     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
+    readonly retention: RetentionDeclaration;
     /**
      * `CheckpointStore.durability` 声明([ref] 欠账,[ref] 件5)—— 行落在 MySQL-protocol / PostgreSQL 的
      * `checkpoint` 表里,进程重启、副本轮换、整机重建都不丢 ⇒ `"durable"`,如实。
@@ -500,25 +502,13 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * `wiring-governance-operator.test.ts` 的 [ref] 组;已上报上游求一个能表达该宽度的词。
      */
     readonly fidelity: StoreFidelity;
-    /**
-     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[ref] clay 裁放行)——**如实按能力判**:
-     * 本店的 {@link SqlCheckpointStore.reopen} 是真 CAS 实现(`resolved`→`pending` 原子翻回 + `reopen_reason`
-     * 权威列,[ref] D-1 的两条重开腿都走它),声明 `reopen: true` 是读数不是抬举。core 的沙箱准入
-     * 模式(pre-flight 要求 `redecision.reopen === true`,declaration never duck-typing——方法在场不算数)
-     * 由这一格武装:Kata 腿(`capabilities.isolation` 真声明)+ durable park 部署下,`sandbox_local` ask
-     * 自动放行并以 `permission.sandbox_admitted` durable 事件披露(缺席披露=core 侧变异恰红)。
-     * `validatingLease` **不声明**:本店没有 durable validating-lease 纪律,不承诺没有的东西。
-     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
-     */
-    readonly redecision: {
-        readonly reopen: true;
-    };
     /**
      * `CheckpointStore.execution` 声明(core 7.7.0 [ref];[ref])——**必填**,且必须恰是 `{ outcome: true }`:
      * 店在此承诺 {@link SqlCheckpointStore.recordExecutionOutcome} 是契约描述的那条真 CAS(谓词、四词、
-     * 冲突抛),且 {@link SqlCheckpointStore.reopen} 认这条记录。与 `durability`/`fidelity`/`redecision`
-     * 三格同一条「声明而非鸭子判」姿势,区别只在这一格**不可缺席**:缺席的店会被 core 在 store 席的
-     * 第一次读(`resolveCheckpointStore`)以 `config.invalid_checkpoint_store` 拒启 —— 那是契约的正确行为,
+     * 冲突抛),且 {@link SqlCheckpointStore.reopen} 认这条记录。与 `durability`/`fidelity` 两格同一条
+     * 「声明而非鸭子判」姿势,区别只在这一格**不可缺席**:缺席的店(以及缺 `reopen` 动词的店 —— core 7.57.0 起它是必备
+     * 动词,原先的 `redecision` 声明格随之退役)会被 core 在 store 席的第一次读(`resolveCheckpointStore`)以
+     * `config.invalid_checkpoint_store` 拒启、句子点名缺的每一个成员 —— 那是契约的正确行为,
      * 因为一台记不下「已决动作最后被怎么处置」的部署,它手里每一条 resolved 行在这条轴上都永远读不出来。
      */
     readonly execution: {
@@ -526,7 +516,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     };
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
-    } | undefined);
+    } | undefined, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** JSON column binding. TiDB: plain `JSON.stringify`, stored verbatim. PG: `pgProtocolJsonStringify` —
@@ -891,12 +883,16 @@ export declare class SqlCheckpointStore implements CheckpointStore {
 export declare class TiDBCheckpointStore extends SqlCheckpointStore {
     constructor(pool: MySqlPool, logger?: {
         info?(msg: string, meta?: unknown): void;
+    }, opts?: {
+        readonly retention?: RetentionDeclaration;
     });
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgCheckpointStore extends SqlCheckpointStore {
     constructor(pool: PgPool, logger?: {
         info?(msg: string, meta?: unknown): void;
+    }, opts?: {
+        readonly retention?: RetentionDeclaration;
     });
 }
 //# sourceMappingURL=checkpoint-store-sql.d.ts.map

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

@@ -9,7 +9,8 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
-import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const CTX_REWRITE_PAGE = 500;
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
@@ -61,13 +62,10 @@ export async function assertCheckpointColumnSchema(query, dialect) {
                 throw err;
             throw new Error(`checkpoint is missing the column ${column} — refusing to start. ` +
                 `On this table ${breaksAt} — at runtime, after a healthy-looking boot. ` +
-                "This repository ships no ALTER TABLE migrations, so the table must be recreated: run " +
-                "`DROP TABLE checkpoint;` on the " +
-                (dialect === "pg" ? "PostgreSQL" : "MySQL-protocol") +
-                " backend and restart — the schema is recreated at boot. The cost is bounded but real: the table holds IN-FLIGHT " +
-                "durable parks (suspended approvals/reviews awaiting a decision) — those cards are lost and their runs must be " +
-                "re-triggered; `checkpoint_ctx`, run rows and every other persistent face are untouched. " +
-                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+                "The table holds IN-FLIGHT durable parks (suspended approvals/reviews awaiting a decision), so the way forward is an in-place " +
+                "ALTER that keeps them; `checkpoint_ctx`, run rows and every other persistent face are untouched.\n" +
+                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                (await describeProbedTableDrift(query, dialect, ["checkpoint"])));
         }
     }
 }
@@ -336,14 +334,14 @@ const EXECUTION_RECORD_CAS_ATTEMPTS = 8;
 export class SqlCheckpointStore {
     db;
     logger;
-    retention = MANAGED_RETENTION;
+    retention;
     durability = "durable";
     fidelity = "json";
-    redecision = { reopen: true };
     execution = { outcome: true };
-    constructor(db, logger) {
+    constructor(db, logger, opts = {}) {
         this.db = db;
         this.logger = logger;
+        this.retention = opts.retention ?? UNMANAGED_RETENTION;
     }
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
@@ -798,13 +796,13 @@ export class SqlCheckpointStore {
     }
 }
 export class TiDBCheckpointStore extends SqlCheckpointStore {
-    constructor(pool, logger) {
-        super(mysqlDriver(pool), logger);
+    constructor(pool, logger, opts) {
+        super(mysqlDriver(pool), logger, opts);
     }
 }
 export class PgCheckpointStore extends SqlCheckpointStore {
-    constructor(pool, logger) {
-        super(pgDriver(pool), logger);
+    constructor(pool, logger, opts) {
+        super(pgDriver(pool), logger, opts);
     }
 }
 //# sourceMappingURL=checkpoint-store-sql.js.map