@sema-agent/server 7.132.0 → 7.134.0

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

@@ -3,6 +3,15 @@ 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 } from "../approval-card.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
+import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
+/** M28 店腿的读数(两孪生同形;随 M28 删):扫到的可读行 · 回写成的行 · 回写成的行里被改写的值 · 读不出的行 · 封好之后一行装不下的行。 */
+export interface CtxRowsRewriteM28 {
+    readonly scanned: number;
+    readonly rewritten: number;
+    readonly valuesRewritten: number;
+    readonly unreadable: number;
+    readonly tooLarge: number;
+}
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 /**
  * [ref] D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
@@ -37,6 +46,14 @@ export declare function tokenFingerprint(token: string): string;
  *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。 */
 export interface PendingCheckpoint extends ParkRowFacts {
     sessionId: string;
+    /**
+     * 这道停驻门的**非秘密稳定身份**(core `Checkpoint.checkpointId`,引擎每次停驻铸)—— 三处 durable 读面(本行 = `GET /v1/approvals` 的 `pending[]`
+     * 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的 `inbox[]`)共用的 **join 键**,也是 409 载体 A
+     * `pendingGate.checkpointId` / `terminal.paused.checkpointId` 的同一个值。**在场就是可信的那一个值,缺席就是缺席**:读法唯一 = `checkpoint-identity.ts` 的
+     * `durableRowIdentity`(过信任边界 —— 不含 token、有界),没有它的行(core 5.42.0 之前停驻的老行 / 没过边界的值)**照列**、键缺席(这一行没有可 join 的身份)、
+     * 每行计一次 `server.approvals.durable-row-checkpoint-id-missing`。两只店各读自己手里的那一份(SQL 孪生读 `checkpoint` 列的成员,LOCAL 孪生读 blob)。
+     */
+    checkpointId?: string;
     scope: string;
     toolName: string | null;
     toolCallId: string | null;
@@ -705,6 +722,12 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * {@link SqlCheckpointStore.pendingRowQuery};语义与三态全文见 {@link PendingRowBinding} 顶注。
      * `scope` 传 `""`(空串)历史上与缺席同义(旧形 `scope ?` 真值判),这里逐字保留。
      */
+    /**
+     * 每一只**待决** checkpoint 的会话(去重)—— 审批账本留存律的挂靠源(`approval-ask-retention.ts`:待决 checkpoint = 一个还能动的停驻,
+     * 它的会话就是停驻那条腿上问行的 `source_task_id`)。**不按门型过滤**:运维队列 {@link listPending} 不列 `gate_kind` 读不出的行,
+     * 而决断口的令牌回落仍认它 —— 留存若跟着队列漏掉它,就会删掉一只还能被决的停驻的问。只读 `session_id`,不读 blob。
+     */
+    listPendingSessionIds(): Promise<string[]>;
     findPendingTokenBySession(sessionId: string, scope?: string, binding?: PendingRowBinding): Promise<CheckpointToken | null>;
     /**
      * 🔴 [ref] 车5 §9 C4 —— 流内审批对账收敛器判据 1 的**窄读口**(店面承载;收敛器本体不在本车)。
@@ -804,8 +827,20 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      *  SUCCEED and replace a readable durable row with an unreadable one (caller sees 2xx, the next resume
      *  409s forever). So the serialized value is judged by {@link assertJsonColumnWritable} — the SAME shape
      *  reader the read leg uses — BEFORE the statement runs: refuse loudly, leave the row on disk untouched. */
-    putCtx(sessionId: string, ctx: object): Promise<void>;
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
+    /**
+     * 🔴 **一次性迁移 M28 的店腿**(窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28;编排 = `checkpoint-ctx-seal-m28.ts`,行改写 =
+     * `http/checkpoint-ctx.ts` 的 `sealStoredCheckpointCtxM28`;本店不知道「封」是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
+     * (每页 {@link CTX_REWRITE_PAGE} 行,只取会话 id 与 ctx 文本),行体经读腿**同一只**判形({@link decodeCtxColumn})—— 读不出 ⇒ 计数、跳过、不动;
+     * `rewrite` 交回新体 ⇒ 经写腿同一只编码与形闸,**按原文 CAS** 回写(MySQL 协议两边 `CAST(… AS BINARY)`,与 M17 / M18 同一条理由:连接排序规则大小写
+     * 不敏感;PG `text` 等值)。`updated_at_ms` **不动**(收割按它判,迁移不许延长或缩短一行的寿命)。CAS 打空(扫描与回写之间这一行被续跑腿 / 别的副本写过)
+     * ⇒ 不计、不重试(新写者是本版就已封好;是旧版副本就由之后的起服再扫到)。一行装不下(封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
+     */
+    rewriteCtxRowsM28(rewrite: (sessionId: string, ctx: object) => {
+        readonly ctx: SealedCheckpointCtx;
+        readonly values: number;
+    } | undefined): Promise<CtxRowsRewriteM28>;
     /**
      * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
      * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.

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

@@ -6,11 +6,13 @@ import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { durableRowIdentity } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
-import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf } from "./sql-errors.js";
+import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const REAP_CLASSIFY_BATCH = 200;
+const CTX_REWRITE_PAGE = 500;
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
@@ -183,6 +185,18 @@ function readParkRowFactsCell(cell) {
     return parkRowFacts(pendingAction);
 }
 const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
+const PARK_ROW_CHECKPOINT_ID = { key: "checkpointId", as: "checkpoint_id" };
+const readCheckpointIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "checkpointId is not a JSON string" });
+function readCheckpointIdCell(cell) {
+    try {
+        return decodeNullableJsonColumn(cell, readCheckpointIdMemberBody, "checkpoint.checkpoint $.checkpointId (operator queue row)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return null;
+    }
+}
 const PARK_ROW_GATE = { key: "gate", as: "park_gate" };
 function readParkGateCell(cell) {
     try {
@@ -581,9 +595,9 @@ export class SqlCheckpointStore {
     }
     async listPending(scope) {
         const d = this.db.dialect;
-        const base = `SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
+        const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
             `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)} ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -599,6 +613,7 @@ export class SqlCheckpointStore {
             const approvalCard = parkedApprovalCard(parkedGateOfRow(r));
             return [{
                     sessionId: String(r.session_id),
+                    ...durableRowIdentity("approvals-queue", readCheckpointIdCell(r[PARK_ROW_CHECKPOINT_ID.as]), r.token),
                     scope: String(r.scope),
                     toolName,
                     toolCallId,
@@ -628,6 +643,10 @@ export class SqlCheckpointStore {
         }
         return out;
     }
+    async listPendingSessionIds() {
+        const { rows } = await this.db.query("SELECT DISTINCT session_id FROM checkpoint WHERE status='pending'", []);
+        return rows.map((r) => String(r.session_id));
+    }
     async findPendingTokenBySession(sessionId, scope, binding) {
         const { sql, params } = this.pendingRowQuery("token", sessionId, scope || undefined, binding);
         const { rows } = await this.db.query(sql, params);
@@ -737,6 +756,49 @@ export class SqlCheckpointStore {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
+    async rewriteCtxRowsM28(rewrite) {
+        const out = { scanned: 0, rewritten: 0, valuesRewritten: 0, unreadable: 0, tooLarge: 0 };
+        let after = "";
+        for (;;) {
+            const { rows } = await this.db.query(this.q(`SELECT session_id, ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id > ? ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`, `SELECT session_id, ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id > $1 ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`), [after]);
+            for (const row of rows) {
+                const sessionId = String(row.session_id);
+                after = sessionId;
+                let ctx;
+                try {
+                    ctx = decodeCtxColumn(row.ctx, `for session ${JSON.stringify(sessionId)} (M28 scan)`);
+                }
+                catch {
+                    out.unreadable += 1;
+                    continue;
+                }
+                out.scanned += 1;
+                const next = rewrite(sessionId, ctx);
+                if (next === undefined)
+                    continue;
+                const text = this.json(next.ctx, "checkpoint ctx");
+                assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                let affected;
+                try {
+                    ({ affected } = await this.db.query(this.q("UPDATE checkpoint_ctx SET ctx = ? WHERE session_id = ? AND CAST(CAST(ctx AS CHAR) AS BINARY) = CAST(? AS BINARY)", "UPDATE checkpoint_ctx SET ctx = $1::jsonb WHERE session_id = $2 AND ctx::text = $3"), [text, sessionId, String(row.ctx)]));
+                }
+                catch (e) {
+                    const folded = rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                    if (!(folded instanceof StoreRowTooLargeError))
+                        throw folded;
+                    out.tooLarge += 1;
+                    continue;
+                }
+                if (affected > 0) {
+                    out.rewritten += 1;
+                    out.valuesRewritten += next.values;
+                }
+            }
+            if (rows.length < CTX_REWRITE_PAGE)
+                break;
+        }
+        return out;
+    }
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at_ms < ? " +
             "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +

package/dist/plugins/file-history-store-sql.d.ts

@@ -2,6 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport } from "@sema-agent/core";
 import { type BlobBackend } from "./blob-backend.js";
+import type { SyncBlobPutResult } from "./store-backend.js";
 import { type SqlDriver } from "./sql-driver.js";
 /** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -147,8 +148,10 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
     /** Upload ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). Store-level
-     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw. */
-    putBlob(hash: string, bytes: Uint8Array): Promise<FileHistoryResult>;
+     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw.
+     *  The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
+     *  keeps its own code — the route answers it 413 (the sentence names that connection's walls), every other write failure 502 ("retry"). */
+    putBlob(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
     /** The subset of `hashes` already present — one SQL INDEX probe (the import presence pre-check). */
     hasBlobs(hashes: string[]): Promise<Set<string>>;

package/dist/plugins/file-history-store-sql.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
-import { SqlBlobBackend } from "./blob-backend.js";
+import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -594,6 +594,8 @@ export class SqlFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
+            if (err instanceof BlobTooLargeError)
+                return { ok: false, error: { code: err.code, message: err.message, wallSource: err.cap.source } };
             return { ok: false, error: { code: "snapshot_failed", message: `putBlob ${hash} write/upload failed: ${discloseCaughtFailure(err)}` } };
         }
     }

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

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { StoreBootRefusalError, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { StoreBootRefusalError, type FenceLanded, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -22,7 +22,7 @@ import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState }
 export declare class RunStoreStrictHydrateError extends StoreBootRefusalError {
     readonly name = "RunStoreStrictHydrateError";
 }
-export declare class FileRunStore {
+export declare class FileRunStore implements InProcessClaimFence {
     private readonly runsDir;
     private readonly activeDir;
     private readonly tmpDir;
@@ -148,6 +148,8 @@ export declare class FileRunStore {
      *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
+    /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性(同步落盘)与 `write` 是同一个同步段。 */
+    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Undo THIS submission's binding (key + 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 reject):
@@ -161,17 +163,7 @@ export declare class FileRunStore {
     /** The run a submission's scoped `Idempotency-Key` names (the file twin of `uq_task_run_idem`), if any. */
     getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
-    listRuns(opts: {
-        status?: string;
-        jobId?: string;
-        source?: string;
-        owner?: string;
-        cursor?: {
-            createdAt: string;
-            taskId: string;
-        };
-        limit: number;
-    }): Promise<RunRecord[]>;
+    listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * S-297 —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
      *  `createdAt DESC, taskId DESC`,与本店 {@link FileRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。

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

@@ -525,6 +525,15 @@ export class FileRunStore {
     async getActiveTaskId(sessionId) {
         return this.active.get(sessionId);
     }
+    whileHoldingClaim(sessionId, taskId, write) {
+        const r = this.runs.get(taskId);
+        if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
+            return false;
+        r.updatedAt = new Date();
+        this.persist(r);
+        write();
+        return true;
+    }
     async getRun(taskId) {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;

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

@@ -24,6 +24,7 @@
  * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
  */
 import { type SessionStore, type AcquiredSession, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
+import { type DelegationTree } from "../delegated-session-owner.js";
 /** acquire 选项形(core 5.48 SessionStore 契约):[ref] placement=受信 spawner 的分区建会话声明。 */
 type AcquireOpts = {
     requireExisting?: boolean;
@@ -85,8 +86,15 @@ export declare class ForkRoutingSessionStore implements SessionStore {
      *     unpin 不落错店)。
      *
      * 已在 host(路由或真行)⇒ 幂等直返。两店都无此会话 ⇒ 抛(调用方=park veto,诚实 fail-closed)。
+     *
+     * S-1770:宿主行**在建行那一笔里**带属主 `owner` —— 调用方按委派继承律算好(`delegated-session-owner.ts`:委派树根的属主,
+     * 推不出 ⇒ 孤行哨兵;`tree` = 判据读到的委派树,判断用:宿主行记着别的树 ⇒ 拒),这里经宿主店的首写登记写下、再按律定夺(core `register` 契约:登记不判授权,判在复读)。
+     * 宿主店里同 id 已有一行:记着这一棵委派树且无主 ⇒ 按同一条律认领(只有记录委派树的店);别的树的 / 属主不是它(别人先认领的空壳,或 local 店的无主空壳)⇒ 抛(停驻否决),
+     * 转录不拷进别人的行;宿主店记不了 / 读不回属主 ⇒ 同样抛 —— 晋升出一只无主的转录行就是把它交给任何拿到 id 的人。
      */
-    promoteToHost(sessionId: string): Promise<void>;
+    promoteToHost(sessionId: string, owner: string | null, tree: DelegationTree): Promise<void>;
+    /** 晋升的建行那一笔(S-1770,规则见 {@link promoteToHost} 头注):宿主店首写登记 `owner`,然后按律定下宿主行的属主(与停驻快路同一只 `settleDelegatedOwner`)。 */
+    private registerPromotedOwner;
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
     get size(): number;
     dispose(): void | Promise<void>;

package/dist/plugins/fork-routing-session-store.js

@@ -1,5 +1,6 @@
 import { SessionError } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { delegatedOwnerHostOf, settleDelegatedOwner } from "../delegated-session-owner.js";
 const ROUTE_MAX = 8192;
 export class ForkRoutingSessionStore {
     host;
@@ -170,7 +171,7 @@ export class ForkRoutingSessionStore {
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);
     }
-    async promoteToHost(sessionId) {
+    async promoteToHost(sessionId, owner, tree) {
         if (this.promoted.has(sessionId))
             return;
         if (this.route.get(sessionId) === "host") {
@@ -190,6 +191,7 @@ export class ForkRoutingSessionStore {
         }
         const entries = await src.session.getEntries();
         const leaf = await src.session.getLeafId();
+        await this.registerPromotedOwner(sessionId, owner, tree);
         const dst = await this.host.acquire(sessionId);
         try {
             const storage = dst.session.getStorage();
@@ -217,6 +219,15 @@ export class ForkRoutingSessionStore {
         this.promoted.add(sessionId);
         this.remember(sessionId, "host");
     }
+    async registerPromotedOwner(sessionId, owner, tree) {
+        const register = this.host.register;
+        const host = delegatedOwnerHostOf(this.host);
+        if (register === undefined || host === undefined) {
+            throw new Error(`session "${sessionId}" cannot be promoted: the host session store cannot record or read back a session owner (register / ownerOf / sessionFaceOf; placementOf and claimOwnerless together or neither), so the promoted transcript would land ownerless`);
+        }
+        await register.call(this.host, sessionId, owner);
+        await settleDelegatedOwner(host, sessionId, owner, tree);
+    }
     async fork(sourceId, owner) {
         const routed = this.route.get(sourceId);
         const tryFork = async (store, where) => {

package/dist/plugins/host-platform.d.ts

@@ -34,6 +34,8 @@
 import type { ChildProcess } from "node:child_process";
 import { killProcessTree, type BackgroundHardKillOutcome } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
+/** 平台读点全仓一处(`test/host-shell-settle-order.test.ts` 源码钉);别处要平台串从这里取,不直读 Node 的平台字段。 */
+export declare const HOST_PLATFORM: NodeJS.Platform;
 export declare const IS_WIN32: boolean;
 export interface HostShell {
     shell: string;

package/dist/plugins/host-platform.js

@@ -1,7 +1,8 @@
 import os from "node:os";
 import { getShellConfig, killProcessTree, signalProcessTree } from "@sema-agent/core";
 import { redactSecrets } from "../trace/redact.js";
-export const IS_WIN32 = process.platform === "win32";
+export const HOST_PLATFORM = process.platform;
+export const IS_WIN32 = HOST_PLATFORM === "win32";
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedPosixShell;
 let winShellState = { kind: "unsettled" };

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

@@ -1,5 +1,6 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
-import { type CheckpointAskCandidate, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-sql.js";
+import { type CheckpointAskCandidate, type CtxRowsRewriteM28, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-sql.js";
+import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
@@ -98,6 +99,8 @@ export declare class LocalCheckpointStore {
     /** All still-pending checkpoints across the registered scopes (summary + full row via get). */
     private pendings;
     /** Operator approval queue — the same NON-secret card as the SQL twins (never the token). */
+    /** 每一只待决 checkpoint 的会话(去重;不按门型过滤 —— 理由与 SQL 孪生 `listPendingSessionIds` 逐字同,见那里)。 */
+    listPendingSessionIds(): Promise<string[]>;
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
     /**
      * [ref]:与 SQL 孪生**同判**的 session 键读口 —— `binding.gateKinds` 过滤门型、序恒「最新优先,token 兜平局」
@@ -197,7 +200,7 @@ export declare class LocalCheckpointStore {
      * 一个 `toJSON(k){ return k === "ctx" ? null : {…} }` 的对象验的是 `{…}`、写的是 `{"ctx":null}`
      * (实测两串逐字不同)。有状态的序列化器同理。⇒ 整条记录**只序列化一次**,闸判那一串,写也写那一串。
      */
-    putCtx(sessionId: string, ctx: object): Promise<void>;
+    putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
     /**
      * 🔴 **坏体 ⇒ 拒,绝不读成缺席**(S-577,与 SQL 孪生同一条判据)。修前这里是
      * `catch { return null }` + `(rec.ctx as T) ?? null`,于是一个撕裂 / 手改 / 权限读不动的 ctx 文件与
@@ -209,6 +212,16 @@ export declare class LocalCheckpointStore {
      * 只收对象,读腿只认对象,两条腿一个类型。
      */
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
+    /**
+     * 🔴 **一次性迁移 M28 的店腿**(local 孪生;窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28,判词与 SQL 孪生 `rewriteCtxRowsM28` 逐条同):
+     * 逐档读(信封经读腿**同一只**判形 —— 读不出 ⇒ 计数、跳过、**不删**),`rewrite` 交回新体 ⇒ 信封原样(`sessionId` / `updatedAt` 不动:收割按 `updatedAt` 判)
+     * 只换 `ctx`,经写腿同一只形闸、同一只原子写落回原档。封签绑的是信封里的 `sessionId`(与 `getCtx` 认行的那一格同一个)。
+     * 数据根独占 + 起服在任何读写者之前跑 ⇒ 本车道没有并发写者,不需要 CAS;没有一行装不下这回事(`tooLarge` 恒 0)。
+     */
+    rewriteCtxRowsM28(rewrite: (sessionId: string, ctx: object) => {
+        readonly ctx: SealedCheckpointCtx;
+        readonly values: number;
+    } | undefined): Promise<CtxRowsRewriteM28>;
     /** GC ctx files whose lifecycle is over — same three guards as the SQL twins (stale ∧ no pending ∧ no active run). */
     reapCtx(cutoff: number): Promise<number>;
     /**

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { parkRowFacts } from "../approval-card.js";
+import { durableRowIdentity } from "../checkpoint-identity.js";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -160,9 +161,12 @@ export class LocalCheckpointStore {
         }
         return out;
     }
+    async listPendingSessionIds() {
+        return [...new Set((await this.pendings()).map(({ cp }) => cp.sessionId))];
+    }
     async listPending(scope) {
         const rows = [];
-        for (const { cp } of await this.pendings(scope)) {
+        for (const { token, cp } of await this.pendings(scope)) {
             const pa = cp.pendingAction;
             const gate = cp.gate;
             const gateKind = queueRowGateKind(gate?.kind);
@@ -171,6 +175,7 @@ export class LocalCheckpointStore {
             const toolCallId = pa?.toolCallId ?? null;
             rows.push({
                 sessionId: cp.sessionId,
+                ...durableRowIdentity("approvals-queue", cp.checkpointId, token),
                 scope: cp.scope,
                 toolName: pa?.toolName ?? null,
                 toolCallId,
@@ -322,6 +327,32 @@ export class LocalCheckpointStore {
         const rec = refusingCtx(sessionId, () => decodeJsonColumn(readFileSync(p, "utf8"), createCtxRecordReader(), `checkpoint-ctx ${ctxFileOf(sessionId)} for session ${JSON.stringify(sessionId)}`));
         return rec.sessionId === sessionId ? rec.ctx : null;
     }
+    async rewriteCtxRowsM28(rewrite) {
+        const out = { scanned: 0, rewritten: 0, valuesRewritten: 0, unreadable: 0, tooLarge: 0 };
+        for (const f of readdirSync(this.ctxDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const p = join(this.ctxDir, f);
+            let rec;
+            try {
+                rec = decodeJsonColumn(readFileSync(p, "utf8"), createCtxRecordReader(), `checkpoint-ctx ${f} (M28 scan)`);
+            }
+            catch {
+                out.unreadable += 1;
+                continue;
+            }
+            out.scanned += 1;
+            const next = rewrite(rec.sessionId, rec.ctx);
+            if (next === undefined)
+                continue;
+            const text = JSON.stringify({ sessionId: rec.sessionId, updatedAt: rec.updatedAt, ctx: next.ctx });
+            assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(rec.sessionId)} (local M28 write)`);
+            atomicWriteFile(this.tmpDir, p, text);
+            out.rewritten += 1;
+            out.valuesRewritten += next.values;
+        }
+        return out;
+    }
     async reapCtx(cutoff) {
         let n = 0;
         for (const f of readdirSync(this.ctxDir)) {

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

@@ -4,10 +4,10 @@ import type { SessionRowPatch } from "../session-row.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import { type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
+import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
- * `audit.ts#buildSessionAuditLocal` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
+ * 窗口 `local-session-window.ts#LocalSessionWindow.wake` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
  * 在视图口读到一个字都没有。座 = F 类 `server.session-repo.corrupt-record-skipped`(会话存档里读不出的记录丢的是可用性:历史少一截 / 列表少一行,不开任何门;
  * 计数单位 = 一条被跳过的记录,逐命中探针行,warn 每进程一次),外加会话打开作用域的计数腿(`noteReplayInSessionOpenScope`:只在 `openSessionForItself`
  * 的作用域里才记,作用域外 —— 列表 / 导出 / 视图口 —— 是空操作,那些读只进运维面)。
@@ -299,9 +299,13 @@ export declare class LocalSessionStore implements SessionStore {
     /** Synthesize a session's objective preview = the most-recent USER text message (the objective the run last saw).
      *  Reads the session's entries through the repo; any read error degrades to null (never fails the list). */
     private previewOf;
-    /** E17 — fork a session's WHOLE history to a NEW id owned by `owner` (core SessionRepo.fork). Returns the new id,
-     *  or null if the source does not exist (the route maps that to 404). */
-    fork(sourceId: string, owner: string | null): Promise<string | null>;
+    /** E17 — fork a session's WHOLE history to a NEW id (core SessionRepo.fork). Returns the new id, or null if the source does not exist.
+     *  属主按 core `SessionStore.fork` 契约(core 7.54.0 `sessionStoreContract` 的 [ownership] 格,唯一读法 {@link forkOwnerOf}):显式串 ⇒ 该串;
+     *  无参 / 显式 `null` ⇒ **源会话记下的属主**(一份有主历史的拷贝永不降成匿名 —— 匿名的拷贝谁都能认领);源会话没记属主 ⇒ 拷贝也不记(读作无主)。
+     *  修前把参数原样写进新格:`fork(owned, null)` 铸出一份匿名的有主历史。
+     *  🚧 已知分歧(不在本版收):拷的是整份日志,含在飞的 assistant 轮(契约:只拷**已提交**的叶)—— 剪在飞轮的判据只能是引擎的 `settledForkOptions`
+     *  (core 7.54.0 未导出,#2098 排在 7.55.0),本仓不写第二份;钉 `test/session-store-contract-kit.test.ts` 的 `it.fails` 格。 */
+    fork(sourceId: string, owner?: string | null): Promise<string | null>;
     /** 2c session-sync — EXPORT a session's full durable entry log (core `SessionRepo.exportEntries`; the
      *  in-memory/file repo holds the whole log so there is no floor to bypass). null if the source is unknown / the
      *  underlying repo lacks the optional seam. The owner is NOT exported — import re-stamps it. */
@@ -352,14 +356,13 @@ export declare class LocalSessionStore implements SessionStore {
     /** Drop a finished/aborted local staging handle from the registry (called by the handle on commit/abort). */
     forgetStaging(stagingId: string): void;
     /**
-     * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):提交时重新分类(目的端此刻的日志 vs staged)
+     * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
+     * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 提交时重新分类(目的端此刻的日志 vs staged)
      * → 拒未经同意的 fork / stale / 载荷分叉 → 换装(validate-first → 删 → 导入,化身按换装律沿用)或 identical 且内容相同时只重戳属主 → **在同一次持锁里**
      * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
-     * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。
+     * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。
      */
-    commitStagedImport(sessionId: string, owner: string | null, staged: SessionTreeEntry[], opts?: {
-        resolution?: "overwrite-dst";
-    }): Promise<{
+    commitStagedImport(sessionId: string, owner: string | null, staged: SessionTreeEntry[], opts: StagedCommitOptions): Promise<{
         relation: SyncRelation["relation"];
         face: SessionFace;
     }>;

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

@@ -1,5 +1,6 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
 import { FileSessionRepo, SessionError, StoredSession, validateEntriesForImport } from "@sema-agent/core";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
@@ -13,7 +14,7 @@ import { decodeInstructionSource, encodeInstructionSource, sameInstructionSource
 import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
 import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
 import { buildObjectivePreview, isAttachmentFrame } from "../user-authored-text.js";
-import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, ownerCellIs, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
 const SESSION_OBJECTIVE_PREVIEW_CHARS = 200;
@@ -459,6 +460,7 @@ export class LocalSessionStore {
             await this.meta.ensureLoaded();
             if (ownerRecorded(this.meta.state.entries.get(sessionId)))
                 return;
+            assertFirstOwnerWritable(sessionId, owner);
             const existed = await this.existsInRepo(sessionId);
             const claim = existed && owner !== null && ownerClaimWindowOpen();
             const wrote = await this.writeMeta(sessionId, (before) => {
@@ -580,17 +582,21 @@ export class LocalSessionStore {
     }
     async fork(sourceId, owner) {
         await this.meta.ensureLoaded();
-        try {
-            const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
-            const id = (await session.getMetadata()).id;
-            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner }));
-            return id;
-        }
-        catch (e) {
-            if (isNotFound(e))
-                return null;
-            throw e;
-        }
+        return this.withSessionWriteLock(sourceId, async () => {
+            const source = this.meta.state.entries.get(sourceId);
+            const forkOwner = forkOwnerOf(owner, source === undefined ? undefined : readSessionMetaCell(source).owner);
+            try {
+                const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
+                const id = (await session.getMetadata()).id;
+                await this.writeMeta(id, () => (forkOwner === undefined ? mintSessionIncarnation() : { incarnation: mintSessionIncarnation(), owner: forkOwner }));
+                return id;
+            }
+            catch (e) {
+                if (isNotFound(e))
+                    return null;
+                throw e;
+            }
+        });
     }
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
@@ -657,12 +663,15 @@ export class LocalSessionStore {
     }
     async commitStagedImport(sessionId, owner, staged, opts) {
         return this.withSessionWriteLock(sessionId, async () => {
+            const current = await this.metaOf(sessionId);
+            if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
+                throw new StagedCommitOwnerChangedError(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
-            if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
+            if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 throw new SyncConflictError(sessionId, rel);
             }
-            if (rel.relation === "fast_forward" && opts?.resolution !== "overwrite-dst" && dstEntries !== null && dstEntries.length > 0) {
+            if (rel.relation === "fast_forward" && opts.resolution !== "overwrite-dst" && dstEntries !== null && dstEntries.length > 0) {
                 const dstSet = new Set(dstEntries.map((e) => e.id));
                 const diverged = fastForwardSharedContentDiverged(staged.filter((e) => dstSet.has(e.id)), dstEntries);
                 if (diverged)