@sema-agent/server 7.137.0 → 7.138.0

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). */
@@ -85,6 +86,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

@@ -19,6 +19,8 @@ export class CachingSessionStore {
     probeTitle;
     readInstructionSource;
     recordInstructionSource;
+    readSessionWorkspace;
+    recordSessionWorkspace;
     exportEntries;
     listEntryIds;
     exportEntriesStream;
@@ -65,6 +67,10 @@ 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.exportEntries)

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 {
@@ -464,9 +465,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 +501,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 +515,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 +882,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,7 @@ 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 { 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";
@@ -336,14 +336,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 +798,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

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

@@ -721,12 +721,13 @@ export class SqlFileHistoryStore {
                 bytes = await srcGetBlob(hash);
             }
             catch (err) {
-                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${foldCaughtFailure(err).text}` } };
+                const f = foldCaughtFailure(err);
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${f.text}`, ...f.fault } };
             }
             if (bytes === undefined)
                 return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
             if (sha256hex(bytes) !== hash) {
-                return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} served bytes that do not hash to its address — the source cannot supply this blob, so nothing is published` } };
             }
             await onVerified?.(hash, bytes);
         }

package/dist/plugins/k8s-pod-reaper.d.ts

@@ -7,9 +7,9 @@
  * 法(只删两形;判决链的缺省臂是「不动作」,删必须被显式选中 —— 销毁不可逆,拿不准恒不删,与 E2B 孤儿回收同一方向纪律):
  *  ② `status.phase ∈ {Succeeded, Failed}` —— 容器已全部结束,删它不掐断任何东西;不看 run、不看标签;
  *  ① 带 run 标签(`sema.io/run`,只有顶层 run 的 Pod 带)、run 行在 server 店里**已是终态**,且自 run 行**转终态的时刻**(行上的 `updatedAt` ——
- *     三只 run 店的终态写当拍盖它)起超过**这只 Pod 自带的**上界:`max(租约上限 + 宽限 = 6 min, 工作区快照时限 + 引擎拆环境放行 15 s)`
+ *     三只 run 店的终态写当拍盖它)起超过**这只 Pod 自带的**上界:`max(租约上限 + 宽限 = 6 min, 工作区快照时限 + 引擎拆环境放行 `teardownLegBudget()`)`
  *     ({@link sandboxRunEndHoldMs};租约上限 = 凭据代理的租约律那一只 `LEASE_TTL_MAX_MS`,本模块不另立)。
- *     第二项是 run 收尾的 `destroy()` 在终态之后还可能在 Pod 上存快照的最长时间(引擎的拆环境腿 15 s 放行、run 随即落终态,快照按数据时限接着跑)——
+ *     第二项是 run 收尾的 `destroy()` 在终态之后还可能在 Pod 上存快照的最长时间(引擎的拆环境腿按 `teardownLegBudget()` 放行、run 随即落终态,快照按数据时限接着跑)——
  *     那个数据时限是**建这只 Pod 的副本**的配置,所以上界**随 Pod 走、写一次读一次**:适配器建 Pod 时按自己的快照时限算一次、写进注解
  *     `sema.io/run-end-hold-ms`(`k8s-exec-protocol.ts` `SANDBOX_RUN_END_HOLD_ANNOTATION`),回收器只读 Pod 自带的这一格,**从不**读回收器所在副本的配置
  *     (列举是整个命名空间的 Pod:滚动改 `WORKSPACE_SNAPSHOT_TIMEOUT_MS` 时,一个时限短的副本不得替时限长的副本判它的 Pod)。
@@ -31,12 +31,6 @@ import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
 /** ① 的宽限(在租约上限之外再等的一段)。常量。 */
 export declare const SANDBOX_POD_REAP_GRACE_MS = 60000;
-/**
- * 引擎在 run 收尾时给「拆执行环境」那条腿的放行时限:超过它 run 照样落终态,`destroy()` 脱离着继续跑。值 = core 的 `TEARDOWN_LEG_MAX_MS`
- * (`dist/core/runner/teardown-bounded.js`)—— core 不从包根导出它(包的 exports 只有 `.` / `./bench` / `./fixtures`),本仓只能照抄这一个数;
- * 收口 = 向 core 要一个包根读口后改读、删本常量。
- */
-export declare const ENGINE_TEARDOWN_RELEASE_MS = 15000;
 /** ① 的上界:`max(租约上限 + 宽限, 快照时限 + 引擎拆环境放行)`。唯一的调用方 = 适配器建 Pod 的那一拍(快照时限 = 建它的副本的 `dataTimeoutMs`),结果写进 Pod 的注解。 */
 export declare function sandboxRunEndHoldMs(snapshotTimeoutMs: number): number;
 /** 一个副本两轮回收之间的间隔。常量。 */

package/dist/plugins/k8s-pod-reaper.js

@@ -3,12 +3,12 @@ import { reportPodDeleteFailed } from "./k8s-pod-delete-failure.js";
 import { runStatusClassOf } from "./store-contracts.js";
 import { LEASE_TTL_MAX_MS } from "../broker/lease-file.js";
 import { WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE } from "../workspace-space.js";
+import { teardownLegBudget } from "@sema-agent/core";
 export const SANDBOX_POD_REAP_GRACE_MS = 60_000;
-export const ENGINE_TEARDOWN_RELEASE_MS = 15_000;
 export function sandboxRunEndHoldMs(snapshotTimeoutMs) {
-    return Math.max(LEASE_TTL_MAX_MS + SANDBOX_POD_REAP_GRACE_MS, snapshotTimeoutMs + ENGINE_TEARDOWN_RELEASE_MS);
+    return Math.max(LEASE_TTL_MAX_MS + SANDBOX_POD_REAP_GRACE_MS, snapshotTimeoutMs + teardownLegBudget());
 }
-const RUN_END_HOLD_READABLE = { min: LEASE_TTL_MAX_MS + SANDBOX_POD_REAP_GRACE_MS, max: WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE.max + ENGINE_TEARDOWN_RELEASE_MS };
+const RUN_END_HOLD_READABLE = { min: LEASE_TTL_MAX_MS + SANDBOX_POD_REAP_GRACE_MS, max: WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE.max + teardownLegBudget() };
 function runEndHoldOf(raw) {
     if (raw === undefined || !/^[0-9]{1,16}$/.test(raw))
         return undefined;

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

@@ -32,17 +32,7 @@ export declare class LocalCheckpointStore {
      */
     readonly fidelity: StoreFidelity;
     /**
-     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[ref] clay 裁放行)——**如实按内核判**,
-     * 与 durability/fidelity 同一条判据:内核 core `FileCheckpointStore` **自己**声明 `{ reopen: true }`,
-     * 本类的 {@link LocalCheckpointStore.reopen} 纯委派给它 ⇒ 抄内核的读数是诚实的。包装类**不继承**被
-     * 包装者的声明(委派不是子类),所以这一格必须自己写。`validatingLease` 不声明(内核也没声明)。
-     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
-     */
-    readonly redecision: {
-        readonly reopen: true;
-    };
-    /**
-     * `CheckpointStore.execution` 声明(core 7.7.0 [ref];[ref])——**必填**,与上面三格同一条判据:**如实
+     * `CheckpointStore.execution` 声明(core 7.7.0 [ref];[ref])——**必填**,与上面两格同一条判据:**如实
      * 按内核判**。内核 core `FileCheckpointStore` 自己声明 `{ outcome: true }`,并把执行记录落成 ledger 的
      * 一个新事件种类(`execution`,与 resolve 同款「先 append+fsync 再翻内存」的崩溃序),
      * {@link LocalCheckpointStore.recordExecutionOutcome} 与 {@link LocalCheckpointStore.reopen} 都是纯委派

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

@@ -49,7 +49,6 @@ export class LocalCheckpointStore {
     retention = UNMANAGED_RETENTION;
     durability = "durable";
     fidelity = "json";
-    redecision = { reopen: true };
     execution = { outcome: true };
     inner;
     scopesPath;

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

@@ -4,6 +4,7 @@ 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 { SessionWorkspace } from "../session-workspace.js";
 import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
@@ -64,6 +65,9 @@ export declare class LocalSessionStore implements SessionStore {
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
+    /** 会话行的位置与项目那一格(`session-workspaces.json`)—— SQL 孪生 `session_meta.workspace` 的 local 对位:`{ [sessionId]: 那一格的文本 }`,
+     *  文本与 SQL 列同一只编解码(`session-workspace-cell.ts`,一格读不出 ⇒ 读作没有记录并计一次)。缺键 = 没有记录。一事一档,理由同 titles。 */
+    private readonly workspaces;
     /**
      * 会话元数据(`session-incarnations.json`,一格的形与两种读法见 {@link SessionMetaCell}):**属主与化身的唯一真源**,SQL 孪生
      * `session_meta` 行上 `owner` / `incarnation` 两列在本店的对位。两样都**必须落盘**:
@@ -175,6 +179,13 @@ export declare class LocalSessionStore implements SessionStore {
      * 开始之前共享的那张表只含落过盘的值,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /** 会话行的位置与项目那一格(local 孪生;读法与 SQL 两孪生同一只 `decodeSessionWorkspaceCell`)。缺键 ⇒ `undefined`。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座)。与 SQL 孪生「`UPDATE … WHERE session_id = ? AND incarnation = ?`」同义:**会话不在、或同 id
+     * 已换了住客 ⇒ 不写**,判与写排在这只会话的写锁里(删除 / 换人同锁 —— 判过的住客在这一笔落盘之前换不掉)。落不了盘 ⇒ 内存不动、抛。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
      *  read/parse error degrades to an empty map (createdAt ordering) rather than failing the list — the picker still
      *  works, just without restart-persisted recency. Memoized so concurrent listSessions share one read. */
@@ -235,11 +246,6 @@ export declare class LocalSessionStore implements SessionStore {
      * `REQUIRE_PRINCIPAL=true`,授权口也只在那时才把 principal 递过来认领(`security.ts` `createAuthorizer`)。
      */
     register(sessionId: string, owner: string | null): Promise<void>;
-    /** 2c P1d-β — re-stamp the session's owner WITHOUT rewriting entries (the staged-commit `identical` path: the log is
-     *  already present & equal, so only the owner needs re-stamping to the importing principal, §9). Persisted like every
-     *  owner write; the incarnation is untouched (same occupant). No cell (no such session) ⇒ no-op. Only caller:
-     *  {@link commitStagedImport}, inside the session's write lock. */
-    private restampOwner;
     touch(sessionId: string): Promise<void>;
     /** Durable history is retained by the repo; just drop the in-flight cache entry (mirrors TiDBSessionStore.release). */
     release(sessionId: string): Promise<void>;
@@ -322,27 +328,60 @@ export declare class LocalSessionStore implements SessionStore {
         afterSeq?: number;
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
-    /** 2c session-sync — IMPORT a verbatim entry log into `sessionId` via core `SessionRepo.importEntries`
-     *  (which runs the `validateEntriesForImport` fail-closed gate before writing). `owner` is the authenticated
-     *  importing principal (re-stamped into the service-side owner map; core's local repo has no owner column, §9).
-     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`).
-     *  The owner is recorded in the session-meta cell (persisted), together with the incarnation. */
+    /**
+     * 2c session-sync — IMPORT a verbatim entry log into `sessionId`(引擎的 `validateEntriesForImport` 闸在引擎仓的导入里先跑:坏包一个字节不写)。`owner` = 鉴权过的导入者。
+     * 与引擎 `SessionRepo.importEntries` 的导入律同一句,只是**属主在本店的属主格上判**(会话元数据那一格是本店唯一的属主真源;本店建的存档在引擎仓里
+     * 不带属主戳 —— `register` 只 `repo.create({ id })` —— 引擎仓的属主比较替这一格答不了):落在既有行上 ⇒ 只落在导入者自己的行上(读不中 ⇒ `conflict`,
+     * 一个字节不写),存档原地换日志、行原样;落在不存在的 id 上 ⇒ 新行(属主 = 导入者,铸一只化身)。整段在这只会话的写锁里;日志 = {@link swapLogHeld},行收尾 = {@link finishSwap}。
+     */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。调用方持这只会话的写锁。 */
-    private importEntriesAs;
-    /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
-     *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer
-     *  with NO compaction floor / cross-instance race (a process-local in-memory map / a single-process file repo), so
-     *  deleteSession-then-importEntries is effectively atomic for the local case (no concurrent reader can observe the
-     *  gap, unlike the durable cross-instance backends which do it in ONE SQL txn). Both halves are best-effort feature-
-     *  gated: a repo lacking either seam throws the same clear error importEntries does (no silent half-write). */
+    /**
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE,按接口句(`SessionStorage.replaceEntries`:先清这只会话既有的对话日志,再导入 `entries`)。
+     * 与 {@link importEntries} 同一个入口、同一只属主判、同一个行收尾,只差日志那一半:先清内容存档再导入(`purge_first`,见 {@link LogSwap})——
+     * 所以一只会话头读不出的存档也换得掉;存档是重建的那一只,建档时刻 = 换装时刻(SQL 孪生 replace 重插行、`created_at` 重记,同义)。
+     */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** {@link replaceEntries} 的锁内一形(调用方持这只会话的写锁)。 */
-    private replaceEntriesHeld;
+    /**
+     * 换装三条写腿(公开 {@link importEntries} / {@link replaceEntries} 与暂存提交 {@link commitStagedImport})的**同一个入口**:调用方给的属主先过
+     * {@link importerOwnerOf}(主体名或 `null`;否则 `TypeError`,什么都没读、一个字节没写),再进这只会话的写锁 —— 锁里的写体只见判过的那一个值,
+     * 写进行的属主就是它。引擎导入口的属主判管不到这一格:换装交给引擎的是存档自己的戳(见 {@link swapLogHeld}),不是调用方的属主。
+     */
+    private withImportLock;
+    /**
+     * 公开导入口({@link importEntries} / {@link replaceEntries})的锁内一形(调用方持这只会话的写锁)。属主判 —— 这条路径上**唯一**一次读那一格:
+     * 行在而它的属主格不是导入者 ⇒ `conflict`,一个字节不写;判过才交给写体(写体不读那一格、不判属主)。
+     */
+    private importHeld;
+    /**
+     * 换装的**日志**一半(公开导入 / 换装与暂存提交三条腿共用;行那一半在 {@link finishSwap})。调用方持这只会话的写锁,并已在本店的属主格上判过 ——
+     * 这里不读那一格、不判属主。只换**内容**;会话元数据那一格、标题 / 置顶 / 指令来源 / 工作区四只行边档、新近,这里一个字节不碰。
+     * 一次引擎仓导入,落在 {@link archiveToSwap} 交回的那一份存档上(怎么对待既有存档由写腿的动词定,{@link LogSwap}):
+     * 落在既有存档上 = 整份日志换成 `entries`、存档的元数据整只留着(其中的建档时刻是列表行的 firstActivityAt,与 SQL 孪生留在行上的 `created_at` 同义);
+     * 校验(`validateEntriesForImport`)、存档判与写在它里面是一步,抛在哪一处都一个字节没写。
+     * 存档上的属主戳不是本店的事实(属主只在那一格;本店建的存档一律不带戳,存量存档可能带着此前导入者的戳),只是引擎仓原地换的条件:
+     * 按那一份存档自己的戳导入,并以它为 `expect`(戳 + 存档的令牌;没有存档 ⇒ `row: null`,导入新建一只不带戳的存档)——
+     * 换的就是这一份;读与写之间它换了一代 ⇒ 引擎仓拒 `conflict`,一个字节不写。
+     */
+    private swapLogHeld;
+    /**
+     * 换装落在哪一份存档上(`null` = 没有存档,导入新建一只)—— {@link LogSwap} 的唯一读法。
+     * `in_place`:锁里读到的那一份(读不出 ⇒ 引擎的故障原样上抛,一个字节没写)。
+     * `purge_first`:先清掉内容存档(不带 `expect` —— 带了就得先读它的头,读不出的存档就清不掉),再交回 `null`;清不可撤,所以引擎导入里的那一只闸
+     * (`validateEntriesForImport`)在清之前先跑一遍,坏包什么都不清。清过之后导入再抛(I/O 故障),内容就没了、行与四只边档还在 —— 已发版本的 replace 同形(删后导入)。
+     */
+    private archiveToSwap;
+    /**
+     * 推送的**行**收尾 —— 换了日志的与内容相同只重戳的,都经这**一处**(暂存提交两支之后、公开两口的写体之后;调用方持写锁,`owner` 的形已在入口
+     * {@link withImportLock} 判过、归属已在锁里判过):
+     * 会话元数据那一格属主重戳为导入者;化身经 {@link carriedIncarnation}(三只店同一句)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客),
+     * 刚建的行 ⇒ 铸一只;然后记新近 = 此刻:推送即活动,不因内容相同分叉。标题 / 置顶 / 指令来源 / 工作区四只行边档不碰。
+     * SQL 孪生暂存提交那一句 `UPDATE session_meta SET owner = ?, updated_at = now, leaf_id, leaf_seq` 的 local 对位(那一句两支同写)。
+     */
+    private finishSwap;
     /** 2c session-sync P1d-β (PUSH streaming) — begin a STAGED import. The LOCAL backend is single-writer with no
      *  cross-instance / cross-replica concurrency story (the durable twins carry that), so the staging handle simply
-     *  ACCUMULATES the streamed batches in memory then, on commit, runs the SAME validate-first → replaceEntries the
-     *  whole-bundle local import uses (effectively atomic locally — no concurrent reader can observe the gap). Keep it
+     *  ACCUMULATES the streamed batches in memory then, on commit, runs the SAME in-place log swap ({@link swapLogHeld}: one
+     *  engine-repo import onto the archive as it stands — validate, judge and write in one step) the whole-bundle local import uses. Keep it
      *  simple per §1: the durable twins are where the SHADOW-id swap + bounded-memory + concurrency matter. */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
     /** 2c P1d-β (staged-row inspection) — the in-memory staged entries for a local staging id. No longer the import gate
@@ -354,7 +393,7 @@ export declare class LocalSessionStore implements SessionStore {
     /**
      * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
      * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 提交时重新分类(目的端此刻的日志 vs staged)
-     * → 拒未经同意的 fork / stale / 载荷分叉 → 换装(validate-first → 删 → 导入,化身按换装律沿用)或 identical 且内容相同时只重戳属主 → **在同一次持锁里**
+     * → 拒未经同意的 fork / stale / 载荷分叉 → 换日志({@link swapLogHeld},原地换;属主只在 CAS 那一读上判)或 identical 且内容相同时日志不动 → 两支同一收尾 {@link finishSwap}(重戳属主 + 记新近)→ **在同一次持锁里**
      * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
      * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。
      */
@@ -367,10 +406,10 @@ export declare class LocalSessionStore implements SessionStore {
      *  tool-result rows are purged separately by the route's purgeSession coordinator. 整段在这只会话的写锁里(换人)。 */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     /**
-     * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装 {@link replaceEntriesHeld} 也走它)。
-     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、三只行边档(标题 / 置顶 / [ref] 的指令来源基线)、属主 + 化身那一格。
-     * 三只边档的那一键**都经各自的写链删**(`commit`:草稿上删、落盘、再发布 —— 与写它们的那一笔同一条链、同一把会话锁),落不了盘 ⇒ 抛:
-     * 留在盘上的值会挂到同 id 的下一位住客身上(E21 的删除权残留)。元数据格**最后**删:三只边档任一只落不了而抛时,那一格还在 ⇒ 会话对属主门仍
+     * {@link deleteSession} 的锁内一形(调用方持这只会话的写锁;换装不走它 —— 换装只换内容存档,行原样,见 {@link swapLogHeld})。
+     * 删的是 SQL 孪生 `session_meta` 那一行在本店的全部对位:会话存档、四只行边档(标题 / 置顶 / 指令来源基线 / 工作区)、新近标记、属主 + 化身那一格。
+     * 四只边档的那一键**都经各自的写链删**(`commit`:草稿上删、落盘、再发布 —— 与写它们的那一笔同一条链、同一把会话锁),落不了盘 ⇒ 抛:
+     * 留在盘上的值会挂到同 id 的下一位住客身上(E21 的删除权残留)。元数据格**最后**删:四只边档任一只落不了而抛时,那一格还在 ⇒ 会话对属主门仍
      * 「在」,重发删除照样走得进来、收敛;反过来先删格,重发就成了 no-op,残留永远留下。
      * 🔴 hydrate FIRST (workflow audit 2026-07-13): after a restart the maps start empty — an un-hydrated delete would find nothing and
      * the sidecar would keep the value (an E21 right-to-delete residue that would RESURRECT onto a same-id re-import). ensureLoaded is

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

@@ -1,6 +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 { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf } from "./session-ownership.js";
 import { FileSessionRepo, SessionError, StoredSession, settledForkOptions, validateEntriesForImport } from "@sema-agent/core";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
@@ -11,6 +11,7 @@ import { createLogger } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { UnreadableLeaf, carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 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";
@@ -35,7 +36,7 @@ function userText(entry) {
     }
     return null;
 }
-const SIDECAR_DEGRADES = { lastActivity: "recency", title: "title", pinned: "pin state", "instruction-source": "instruction-source baseline", "session-meta": "session owner + incarnation (the write that needed it failed loudly)" };
+const SIDECAR_DEGRADES = { lastActivity: "recency", title: "title", pinned: "pin state", "instruction-source": "instruction-source baseline", workspace: "each session's last recorded place and project (the next frame records it again)", "session-meta": "session owner + incarnation (the write that needed it failed loudly)" };
 const readPinnedSidecar = createZodColumnReader(z.record(z.string(), z.literal(true)));
 function readSessionMetaCell(cell) {
     return typeof cell === "string" ? { incarnation: cell, owner: undefined } : cell;
@@ -180,6 +181,7 @@ export class LocalSessionStore {
     titles;
     pinned;
     instructionSources;
+    workspaces;
     meta;
     log;
     sessionWriteLocks;
@@ -192,6 +194,7 @@ export class LocalSessionStore {
         this.titles = sidecar("session-titles.json", "title", readStringRecordColumn);
         this.pinned = sidecar("session-pinned.json", "pinned", readPinnedSidecar);
         this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source", readStringRecordColumn);
+        this.workspaces = sidecar("session-workspaces.json", "workspace", readStringRecordColumn);
         this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
         const root = dataDir ? resolve(dataDir) : undefined;
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
@@ -352,6 +355,26 @@ export class LocalSessionStore {
         if (!committed)
             throw new Error("LocalSessionStore: instruction-source sidecar write failed — baseline not recorded");
     }
+    async readSessionWorkspace(sessionId) {
+        await this.workspaces.ensureLoaded();
+        return decodeSessionWorkspaceCell(this.workspaces.state.entries.get(sessionId) ?? null, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        const text = encodeSessionWorkspaceCell(workspace, JSON.stringify, sessionId);
+        await this.withSessionWriteLock(sessionId, async () => {
+            if ((await this.metaOf(sessionId))?.incarnation !== incarnation)
+                return;
+            await this.workspaces.ensureLoaded();
+            const committed = await this.workspaces.commit((draft) => {
+                if (draft.get(sessionId) === text)
+                    return false;
+                draft.set(sessionId, text);
+                return true;
+            });
+            if (!committed)
+                throw new SessionError("storage", `LocalSessionStore: workspace sidecar write failed for session ${sessionId} — its place was not recorded`);
+        });
+    }
     async ensureLoaded() {
         if (!this.sidecarPath)
             return;
@@ -480,9 +503,6 @@ export class LocalSessionStore {
                 this.log.info("session_owner_claimed", { sessionId });
         });
     }
-    async restampOwner(sessionId, owner) {
-        await this.writeMeta(sessionId, (before) => (before === undefined ? undefined : { incarnation: readSessionMetaCell(before).incarnation, owner }));
-    }
     async touch(sessionId) {
         this.lastActivity.set(sessionId, new Date().toISOString());
         this.scheduleFlush();
@@ -607,28 +627,42 @@ export class LocalSessionStore {
         return gen();
     }
     async importEntries(sessionId, owner, entries) {
-        await this.withSessionWriteLock(sessionId, () => this.importEntriesAs(sessionId, owner, entries, mintSessionIncarnation()));
-    }
-    async importEntriesAs(sessionId, owner, entries, incarnation) {
-        if (!this.repo.importEntries)
-            throw new SessionError("storage", "session import is not supported by this local backend");
-        await this.meta.ensureLoaded();
-        await this.repo.importEntries(sessionId, owner ?? undefined, entries);
-        await this.writeMeta(sessionId, () => ({ incarnation, owner }));
+        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "in_place"));
     }
     async replaceEntries(sessionId, owner, entries) {
-        await this.withSessionWriteLock(sessionId, () => this.replaceEntriesHeld(sessionId, owner, entries));
+        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "purge_first"));
+    }
+    async withImportLock(sessionId, owner, body) {
+        const importer = importerOwnerOf(owner);
+        return this.withSessionWriteLock(sessionId, () => body(importer));
     }
-    async replaceEntriesHeld(sessionId, owner, entries) {
+    async importHeld(sessionId, owner, entries, swap) {
+        const row = await this.metaOf(sessionId);
+        if (row !== undefined && !ownerEq(row.owner ?? null, owner)) {
+            throw new SessionError("conflict", `session ${sessionId} is not the importer's row (its owner cell differs) — nothing was written`);
+        }
+        await this.swapLogHeld(sessionId, entries, swap);
+        await this.finishSwap(sessionId, owner);
+    }
+    async swapLogHeld(sessionId, entries, swap) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
-        if (!this.repo.delete)
-            throw new SessionError("storage", "session replace is not supported by this local backend (no delete seam)");
-        validateEntriesForImport(entries);
-        const current = await this.metaOf(sessionId);
-        const prior = current === undefined ? undefined : { owner: current.owner ?? null, incarnation: current.incarnation };
-        await this.deleteSessionHeld(sessionId, owner);
-        await this.importEntriesAs(sessionId, owner, entries, carriedIncarnation(sessionId, prior, owner));
+        const archive = await this.archiveToSwap(sessionId, entries, swap);
+        await this.repo.importEntries(sessionId, archive?.owner ?? undefined, entries, { expect: { row: archive } });
+    }
+    async archiveToSwap(sessionId, entries, swap) {
+        switch (swap) {
+            case "in_place":
+                return (await this.repo.headOf(sessionId)) ?? null;
+            case "purge_first":
+                validateEntriesForImport(entries);
+                await this.repo.delete({ id: sessionId, createdAt: "" });
+                return null;
+        }
+    }
+    async finishSwap(sessionId, owner) {
+        await this.writeMeta(sessionId, (before) => ({ incarnation: carriedIncarnation(sessionId, before === undefined ? undefined : readSessionMetaCell(before)), owner }));
+        await this.touch(sessionId);
     }
     beginImportStaging(realSessionId, token) {
         const h = new LocalStagingHandle(this, realSessionId, stagingIdFor(realSessionId, token));
@@ -642,7 +676,7 @@ export class LocalSessionStore {
         this.stagings.delete(stagingId);
     }
     async commitStagedImport(sessionId, owner, staged, opts) {
-        return this.withSessionWriteLock(sessionId, async () => {
+        return this.withImportLock(sessionId, owner, async (importer) => {
             const current = await this.metaOf(sessionId);
             if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
                 throw new StagedCommitOwnerChangedError(sessionId);
@@ -659,11 +693,9 @@ export class LocalSessionStore {
             }
             const contentEqual = rel.relation === "identical" && identicalIdsAlsoIdenticalContent(staged, dstEntries);
             if (rel.relation !== "identical" || !contentEqual) {
-                await this.replaceEntriesHeld(sessionId, owner, staged);
-            }
-            else {
-                await this.restampOwner(sessionId, owner);
+                await this.swapLogHeld(sessionId, staged, "in_place");
             }
+            await this.finishSwap(sessionId, importer);
             const meta = await this.metaOf(sessionId);
             if (meta === undefined)
                 throw new SessionError("storage", `LocalSessionStore: staged commit for session ${sessionId} left no session face — nothing was settled`);
@@ -685,7 +717,7 @@ export class LocalSessionStore {
             if (!isNotFound(e))
                 throw e;
         }
-        for (const [map, which] of [[this.titles, "title"], [this.pinned, "pinned"], [this.instructionSources, "instruction-source"]]) {
+        for (const [map, which] of [[this.titles, "title"], [this.pinned, "pinned"], [this.instructionSources, "instruction-source"], [this.workspaces, "workspace"]]) {
             await map.ensureLoaded();
             if (!(await map.deleteKey(sessionId)))
                 throw new SessionError("storage", `LocalSessionStore: ${which} sidecar write failed while deleting session ${sessionId} — its ${which} is still on disk; retry the delete`);