@sema-agent/server 7.140.0 → 7.142.0

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

@@ -1,7 +1,7 @@
 import { type SessionStore } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { StoreBackend } from "./store-backend.js";
-import { type DelegationRootWitness, type DelegationTree, type OrphanOwnerLog } from "../delegated-session-owner.js";
+import { type DelegationRootWitness, type OrphanOwnerLog } from "../delegated-session-owner.js";
 import type { OwnerAwareSessionStore } from "../security.js";
 /**
  * Session-store plugin seam.
@@ -37,31 +37,29 @@ export declare function createSessionStore(config: Pick<ServiceConfig, "sessionB
  * (`evictPolicy="delete"`)。本函数自己**不做**、也无法通用地做"这个 store 实例的 release 是否安全"的
  * 判别(`SessionStore` 接口没有暴露这个信息,类型层面区分不了两种店形)——上文"误判方向永远偏保守"
  * 只覆盖 `getLeafId` 那道校验,不覆盖"传了一个 release=delete 的店进来"这个前提违反。**调用方必须
- * 保证只在真正 durable(release 非破坏性)的店上调用本函数**——server 侧的强制点在 main.ts 装配区:
- * `ensureChildSessionDurable` 闭包只在 `config.sessionBackend === "tidb"` 时构造。
+ * 保证只在真正 durable(release 非破坏性)的店上调用本函数**——server 侧的强制点在 stage-07 装配区:
+ * `ensureChildSessionDurable` 闭包只在部署的子代转录档位是 `full` 时构造(core `resolveSubagentTranscriptTier`:会话店声明了 durable 的委派分区 ——
+ * 三只持久会话店;无 repo 的内存店不声明,档位不是 `full`,挂点不装)。
  */
 export declare function ensureSessionDurable(hostStore: SessionStore, sessionId: string): Promise<void>;
 /**
- * [ref] 主动晋升版 ensureChildSessionDurable(cli TiDB 真机撞获:1.263 的只查不迁形在拆店生产形下
- * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
- * (14ms~2s)+ settle failed,赎回窗口不存在):
- *   0. 属主([ref],`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
+ * core `SubagentToolOptions.background.ensureChildSessionDurable` 的实现体 —— 停驻挂点的**见证**:这只后台子代的转录此刻是 host 店里一只有真内容、
+ * 属主按委派继承律定得下来的会话,才放行停驻;任何一步不成立 ⇒ 抛 = 否决(core 收 veto 即 expire checkpoint + settle failed,pre-153 行为,不放大)。
+ *
+ * 规则(`fork-routing-session-store.ts` 头注):一只后台子代的 durable 行在,它的转录就是 host 店委派分区里的一只 placed 行。挂点只装在声明了
+ * durable 委派分区的部署上(stage-07:core `resolveSubagentTranscriptTier(...) === "full"`),那里 core 给每只新起的后台子代铸 placement、
+ * 转录生来就在 host 店 —— 所以这里**只验、不搬**(此前的「晋升」把私店的转录整树拷进 host 店,随这条规则退役)。
+ *   0. 属主(`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
  *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与写口放行的那一位(认领之前解析器那一读);core 的挂点签名只给子代 id,
- *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`:不按新住客晋升 / 认领);
+ *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`);
  *      缺席(行上没有根)或根行此刻不在 ⇒ 孤行哨兵。
- *   1. 快路:已在 host 店且有真内容 → 通过,**前提是那一行的属主按律定得下来**(`settleDelegatedOwner`:记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次
- *      (与 M23 同读数),无主 ⇒ 认领(CAS 子行,写判断时的读数)、没落下 ⇒ 抛(只有记录委派树的 SQL 店;local 店的行不记委派树 ⇒ 不认领);此刻属主不是律给的那一只 ⇒ 那是别人的同 id 会话,
- *      不是这只子代的转录 ⇒ 抛 = 停驻否决;与晋升建行前那一道同一只函数)。
- *   2. 晋升:routing.promoteToHost 把子会话整树从私店拷进 host 店(拷贝→私店 forget→路由记 host,
- *      三步见 ForkRoutingSessionStore.promoteToHost),宿主行在建行那一笔里带第 0 步的属主;写的是哨兵 ⇒ 写落下之后一行 warn。
- *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)+ 同一只属主定夺 —— 晋升产物必须达到与快路完全相同的
- *      标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ *   1. 在不在、有没有真内容:{@link ensureSessionDurable}(`requireExisting` 打开 + 叶子非空 + forget 收尾)。任何失败(不在、空壳、读故障)⇒ 原样上抛 = 否决
+ *      (读故障也否决:说不准转录在不在,就不让一次审批押在它上面)。这里**不判它是不是 placed 行**:复活的是旧行时 id 取行上的会话(升级前停驻、当年晋升进来的普通行),
+ *      它照样是这只子代的转录;判据只问「host 店里有这份真内容」。
+ *   2. 属主定夺(`settleDelegatedOwner`):记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次(与 M23 同读数),无主 ⇒ 认领(CAS 子行,写判断时的读数)、没落下 ⇒ 抛;
+ *      此刻属主不是律给的那一只 ⇒ 那是别人的同 id 会话,不是这只子代的转录 ⇒ 抛 = 停驻否决。认领写下的是哨兵 ⇒ 写落下之后一行 warn(`site: "park"`)。
  * 宿主店必须读得出属主(`delegatedOwnerHostOf`:`headOf`;记录委派树的店另交 `placementOf` + `claimOwnerless`,两只同在或同缺;生产的 SQL / local 店与缓存包装层都满足),
  * 否则响亮拒。
- * 调用方纪律与 {@link ensureSessionDurable} 同款:hostStore 必须是 release 非破坏性的真 durable 店
- * (stage-07 的 `config.sessionBackend === "tidb"` 门不变 —— 该词在 local 后端上同样归一成 `tidb`,所以本腿在 local 宿主店上也跑)。
  */
-export declare function ensureChildSessionDurableWithPromotion(hostStore: OwnerAwareSessionStore, routing: {
-    promoteToHost(sessionId: string, owner: string | null, tree: DelegationTree): Promise<void>;
-}, sessionId: string, root: DelegationRootWitness | undefined, log: OrphanOwnerLog): Promise<void>;
+export declare function attestChildSessionDurable(hostStore: OwnerAwareSessionStore, sessionId: string, root: DelegationRootWitness | undefined, log: OrphanOwnerLog): Promise<void>;
 //# sourceMappingURL=session-store.d.ts.map

package/dist/plugins/session-store.js

@@ -23,24 +23,16 @@ export async function ensureSessionDurable(hostStore, sessionId) {
         await hostStore.forget?.(acquired.sessionId);
     }
 }
-export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId, root, log) {
+export async function attestChildSessionDurable(hostStore, sessionId, root, log) {
     const host = delegatedOwnerHostOf(hostStore);
     if (host === undefined) {
         throw new Error(`session "${sessionId}" cannot be parked: the host session store cannot read a session's owner (headOf), or records delegation trees without being able to claim under them (placementOf / claimOwnerless), so the delegated transcript's owner cannot be derived or checked`);
     }
     const judged = await readDelegatedOwner(sessionId, root === undefined ? {} : { rootSessionId: root.sessionId }, sourceFacesVia(host.headOf));
     assertRootStillWitnessed(sessionId, root, judged);
-    let promoted = false;
-    try {
-        await ensureSessionDurable(hostStore, sessionId);
-    }
-    catch {
-        await routing.promoteToHost(sessionId, judged.inherited.owner, judged.tree);
-        await ensureSessionDurable(hostStore, sessionId);
-        promoted = true;
-    }
+    await ensureSessionDurable(hostStore, sessionId);
     const settled = await settleDelegatedOwner(host, sessionId, judged.inherited.owner, judged.tree);
-    if (promoted || settled.claimed)
-        reportWrittenOwner(log, "promotion", sessionId, settled.judged ?? judged);
+    if (settled.claimed)
+        reportWrittenOwner(log, "park", sessionId, settled.judged ?? judged);
 }
 //# sourceMappingURL=session-store.js.map

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

@@ -5,6 +5,7 @@ import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
 import { type OneTimeMigrationReport } from "./one-time-migrations.js";
+import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
@@ -325,16 +326,19 @@ export interface StoreBackend {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
     /**
-     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」就走这一口,不走 {@link checkpoint}。
+     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 「前世 / 别的副本留下的停驻」的读法,不走 {@link checkpoint}。两个读者:
+     *  · 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」(`listPendingSessionIds`);
+     *  · local 车道起服收敛(`approval-crash-convergence.ts`)对审计判为孤儿的前世 `PARKING` 问跑对账器判据 ① 的候选读口(`findCheckpointCandidatesForAsk`:
+     *    停车行其实已提交 ⇒ `PARKED`,不收 `VOID`)。
      * 区别只有一条:这一口**不牵动任何别的店**。local 车道的 `checkpoint()` 是 durable 停驻面的装配点 —— 它给 run 店接上 [ref] 的收割探针(停驻行的收割从 no-op 变生效),
-     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;留存腿在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失,看不见就会把还能被决的停驻的问删掉),
-     * 所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
+     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;两个读者在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失:留存腿看不见就会把还能被决的停驻的问删掉,
+     * 起服收敛看不见就会把前世已提交的停驻的问收成 `VOID`),所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
      *
-     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:留存腿读不到这一口的后果在**删除方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删),
-     * 「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端(`checkpoint` 缺席)交一只恒空的读口
-     * (`{ listPendingSessionIds: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
+     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:读不到这一口的后果都在**不可逆方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删;判据 ① 恒不命中 ⇒
+     * 已提交的停驻的问被收成终态),「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端
+     * (`checkpoint` 缺席)交一只恒空的读口(`{ listPendingSessionIds: async () => [], findCheckpointCandidatesForAsk: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
      */
-    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds">;
+    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds" | "findCheckpointCandidatesForAsk">;
     toolResult?(): ToolResultStoreFull;
     imageIndex?(): ImageIndex;
     imageBake?(): ImageBake;
@@ -408,6 +412,36 @@ export interface StoreBackend {
  *  编辑被拒)。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
  *  显式接受 SQL 店 + per-blob 帽(单机/测试台形)。local 后端不经此门(file 店,无 SQL 包墙)。 */
 export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "local", config: Pick<ServiceConfig, "snapshotBlobStore" | "snapshotBlobAllowSql">): void;
+/**
+ * LOCAL backend (clay 2026-06-25 seamless local↔cloud; P0.5 variant-2 + variant-1 file-backed 2026-06-26): a DB-less StoreBackend
+ * so a locally-run HTTP service serves the SAME contract a cloud worker does (runs + trace + sessions + resume;
+ * long-term memory rides the [ref] memory ENGINE, not this backend). Sessions / per-session policy / file snapshots are
+ * FILE-BACKED via core's `FileStorageBackend` over `root`, so a session SURVIVES a process restart and the resume
+ * picker (GET /v1/sessions → LocalSessionStore.listSessions) is restart-visible — the 2c "first local, then sync"
+ * hard prerequisite.
+ *
+ * The session store stays the §0.5 owner-aware {@link LocalSessionStore} wrapper, but over a fresh `FileSessionRepo`
+ * (NOT `fileBackend.sessionStore`, which is core's bare `TtlSessionStore` lacking the §0.5 owner/list/fork/delete
+ * ops); policy/snapshot delegate to the fileBackend's own file stores. The fileBackend takes a coarse boot
+ * single-instance lock on `root/LOCK` (an `O_EXCL`+`linkSync` PIDFILE, not flock — [ref] F4; same-host only:
+ * liveness = `process.kill(pid,0)`, so a foreign PID namespace or NFS defeats it, see DEPLOY-PREREQS) —
+ * `close()` MUST `dispose()` it so a graceful restart can
+ * re-acquire (a stale lock from a dead PID is pruned by core, but graceful restart relies on the release).
+ *
+ * P0.5 variant-1 (clay 2026-06-26): `run()`/`resumeAnchor()` are now FILE-backed too (FileRunStore /
+ * FileResumeAnchorStore over core 1.138.0's crash-safe fs primitives — atomicWriteFile/writeThenLink/AppendLog), so the
+ * runs ledger + trace event log + E18 anchors SURVIVE a process restart, completing variant-2's promised follow-on. The
+ * picker still lists from the session abstraction (variant-2), but a restart now also re-reads run history + resume
+ * anchors. Session owners are persisted too (7.119.0: in the session-meta sidecar, next to the incarnation — see
+ * LocalSessionStore), so an owner survives a restart like the SQL twins' column does. The cloud-only stores
+ * (checkpoint/approval/toolResult/imageIndex/imageBake/breaker/costQuota/rateLimiter) are OMITTED → the consumers'
+ * `backend?.X?.()` gates degrade them exactly like a no-DB env.
+ */
+/**
+ * The local session store's rows for the session view's window (`local-session-window.ts`): the local backend's own session store — its row
+ * projection and its log export — and `undefined` on any other backend. The one place that answers "is there a local store to read rows from".
+ */
+export declare function localSessionRowsOf(backend: StoreBackend | undefined): LocalSessionRows | undefined;
 /**
  * 启动日志里「跨副本 or 进程内」那一格的标签。
  *

package/dist/plugins/store-backend.js

@@ -17,6 +17,7 @@ import { NO_SQL_MIGRATIONS, assertExecutionPlacementSwitchAdmissibleOnPool, back
 import { deployedExecutionLanes } from "../execution-lane-caps.js";
 import { assertRetiredSchemaAbsentOnPool } from "./schema-consistency.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
+import { SESSION_DURABILITY, SESSION_PLACEMENTS } from "./session-placement.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
@@ -150,7 +151,7 @@ class TiDBBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep), claims: this.run() }); }
     checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new TiDBToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
@@ -204,7 +205,7 @@ class PgBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep), claims: this.run() }); }
     checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new PgToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new PgImageIndex(this.pool); }
@@ -222,6 +223,9 @@ class PgBackend {
     pgPool() { return this.pool; }
     async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); }
 }
+export function localSessionRowsOf(backend) {
+    return backend instanceof LocalBackend ? backend.session() : undefined;
+}
 class LocalBackend {
     kind = "local";
     fileBackend;
@@ -265,7 +269,11 @@ class LocalBackend {
             error: (msg, fields) => void (this.onError ?? this.onWarn)?.(msg, fields),
             strictHydrate: config.runStoreStrictHydrate,
         });
-        this.sessionStore = new LocalSessionStore(createLocalSessionRepo(this.fileBackend.root), this.runStore, this.fileBackend.root, { log: createLogger(config.logLevel) });
+        this.sessionStore = new LocalSessionStore(createLocalSessionRepo(this.fileBackend.root), this.runStore, this.fileBackend.root, {
+            log: createLogger(config.logLevel),
+            durability: SESSION_DURABILITY,
+            placements: SESSION_PLACEMENTS,
+        });
         this.parkDecisionLedgerRoot = config.workflowRunStoreBackend === "memory" ? undefined : join(this.fileBackend.root, "workflows");
         this.resumeAnchorStore = new FileResumeAnchorStore(this.fileBackend.root);
         this.approvalExemptionStore = new FileApprovalExemptionStore(this.fileBackend.root, { warn: corruptReadWarn });
@@ -283,9 +291,12 @@ class LocalBackend {
             ? undefined
             : (plane) => fileSessionCaptureRecordStore(plane?.controlDir ?? ownControlDir);
     }
-    async ensureSchema() { }
+    async ensureSchema() {
+        await this.sessionStore.settleArchiveSnapshots();
+    }
     async runOneTimeMigrations() {
         const holderDeathCodeRowsBackfilled = this.runStore.migrateLegacyHolderDeathCodes();
+        const archives = await this.sessionStore.migrateLocalArchives();
         const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
         return {
             ...NO_SQL_MIGRATIONS,
@@ -293,6 +304,12 @@ class LocalBackend {
             executionPlacementsBackfilled: placements.backfilled,
             executionPlacementSessionsUnreadable: placements.unreadable,
             askExecutionLanesBackfilled: backfillLocalAskExecutionLanes(this.approvalAskStore, { lanes: this.executionLanes }),
+            askJournalRecordsUpgraded: this.approvalAskStore.upgradeJournalEnvelope(),
+            localArchiveRowFactsBackfilled: archives.rowFactsBackfilled,
+            localArchivesAnonymized: archives.anonymized,
+            localArchivesKeptStamped: archives.keptStamped,
+            localArchivesUnreadable: archives.unreadable,
+            localArchiveSnapshotsRecovered: archives.snapshotsRecovered,
         };
     }
     async close() {
@@ -336,6 +353,7 @@ class LocalBackend {
         return (this.checkpointStoreInst ??= new LocalCheckpointStore(this.fileBackend.root, {
             getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
             readSessionOwner: async (sessionId) => (await this.sessionStore.headOf(sessionId))?.owner,
+            claims: this.runStore,
         }));
     }
     checkpoint() {

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

@@ -20,6 +20,7 @@
  */
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunIdentity } from "../identity-source.js";
+import type { SessionUnreadable } from "../session-error-wire.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -307,6 +308,13 @@ export type CreateRunOutcome = {
     activeTaskId?: undefined;
     sessionAbsent: true;
 };
+/**
+ * 认领栅栏交给 `write` 的那一行 run 此刻的事实(SQL = 锁住那一行读的;进程内 = 同步段里读的)。认领与 `running` 只认 taskId,而续跑腿让同一个 taskId
+ * 停驻之后回到 `running`、认领仍在 —— 「接下这笔写的那条腿还是不是这条 run 的腿」要按腿问的写者拿它问(今天:副本 `instanceId`,续跑的 CAS 赢点把它改成接手的副本)。
+ */
+export interface FencedRun {
+    readonly instanceId: string | null;
+}
 /** SQL 认领栅栏的结局:`held: false` = 认领此刻不是这条 run 的(或它已不在跑),`write` 一次都没调。 */
 export type ClaimFenced<T> = {
     readonly held: true;
@@ -325,13 +333,13 @@ export type FenceLanded = typeof FENCE_LANDED;
  * **宿主会话的认领当写栅栏用 —— 进程内那一形**(属主 = run 店;Memory / File 两孪生同律)。认领 = 会话 → 持有它的 taskId,
  * 由 {@link CreateRunOutcome} 的建行(或续跑腿的 markResuming)取得、终局 / 收割放掉 —— 「这次受理还持有会话吗」只问它,不另记身份。
  *
- * `whileHoldingClaim(sessionId, taskId, write)`:**只有** `taskId` 此刻持有 `sessionId` 的认领、且这条 run 是活的(`running`)时才调 `write`、答 `true`,
+ * `whileHoldingClaim(sessionId, taskId, write)`:**只有** `taskId` 此刻持有 `sessionId` 的认领、且这条 run 是活的(`running`)时才调 `write`(交给它那一行的 {@link FencedRun})、答 `true`,
  * 同一拍把这条 run 的活性戳刷新(一次栅栏写也是一次心跳);否则一次都不调、答 `false`。整只是**同步**的 —— `write` 也是:判、刷新、`write` 落定是同一个同步段,
  * 中间没有让出,所以认领在 `write` 落定之前挪不动(这一条由类型担保 —— `write` 必须同步交回 {@link FENCE_LANDED},不靠「这里恰好没有 await」)。
  * SQL 孪生的栅栏是一个事务(`run-store-sql.ts` `SqlRunStore.whileHoldingClaim`,`write` 收那只事务连接,结局 {@link ClaimFenced}),不是本型。
  */
 export interface InProcessClaimFence {
-    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
+    whileHoldingClaim(sessionId: string, taskId: string, write: (run: FencedRun) => FenceLanded): boolean;
 }
 /**
  * `RunRecord["status"]`(= `"running" | TaskStatus`)的**唯一分类表** —— 词表的属主 = 判据的属主,
@@ -436,7 +444,7 @@ export declare function isUnsuccessfulRunStatus(status: RunRecord["status"]): bo
  * 未知词的方向与 {@link isTerminalRunStatus} 同向保守:判**不是** park。理由是消费点会据此做**不可逆**
  * 动作(cancel 的恢复把手会 CAS-expire 一张 checkpoint);对一个本进程读不懂的状态,少动一次远好过错杀。
  */
-export declare function isParkedRunStatus(status: RunRecord["status"]): boolean;
+export declare function isParkedRunStatus(status: RunRecord["status"]): status is ParkedRunStatus;
 /**
  * 会话的**活动词**(core `PeerSessionTempo`)——「这条会话现在在忙还是闲」的**唯一**一张表([ref])。
  *
@@ -524,6 +532,9 @@ export interface SessionSummary {
     /** 行标签(`src/session-row.ts` 的 `sessionRowTagOf`):这一位住客「PATCH 能写的每一格」的单向摘要,present-iff 这一行可被条件写(店有行格写原语 ∧ 行上有化身);
      *  只经店的列表行映射铸(`sessionRowTagKey`)。没有会话行的 lister(legacy task_run 聚合 / 内存孪生)缺席。wire 半场见 `security.ts SessionListItem.rowTag`(同名同义)。 */
     rowTag?: string;
+    /** 这只会话的存档读不出:present-iff 头的叶子读不出(唯一铸点 `session-error-wire.ts` 的 `sessionUnreadableOf`;码与读口同表)。叶子是行上一列的店(SQL 孪生)
+     *  与没有会话行的 lister 恒缺席。wire 半场见 `security.ts SessionListItem.unreadable`(同名同义)。 */
+    unreadable?: SessionUnreadable;
 }
 /**
  * [ref] —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
@@ -565,6 +576,27 @@ export interface LatestRunRef {
     owner: string | null;
     createdAt: string;
 }
+/** 引擎对一条腿实际挂上的记忆读集的观测(core `TaskResult.effectiveMemoryScopes` 的值;core 包根不单独导出这只型,从结果型取)。 */
+export type EffectiveMemoryScopes = NonNullable<PersistedTaskResult["effectiveMemoryScopes"]>;
+/**
+ * 「这个会话**最近一条已结腿**与它的记忆观测」的窄读面(run 店的 `latestMemoryObservationForSession` 的回值)—— 会话记忆同步触发口
+ * (`POST /v1/sessions/:id/memory/sync`)的**会话读集**只读这一只:读集 = 最近一条已结腿结果里引擎铸的观测(引擎一处铸、随 run 行持久;路由不重铸 spec)。
+ *
+ * 一条规则,三只实现同答:
+ *  · 已结 = {@link isTerminalRunStatus}(成功 / 非成功终局;在飞与停在门上的腿还占着会话的认领,不算;读不懂的词同向保守判「未结」)。两孪生调这只谓词;
+ *    SQL 两方言按本文件的惯例写字面词集 `status IN ('completed','failed','blocked')`,与谓词的同源由 `test/source-hygiene-gate.test.ts` 的方言对 parity 门钉;
+ *    取最近一条(排序口径与 {@link LatestRunRef} 逐字同一句:`created_at DESC, task_id DESC`);
+ *  · `effectiveMemoryScopes` = 那一条腿结果里的观测**原样**(三态:`mounted` / `memoryless` / `none`,读法归调用方);
+ *  · 那一条腿结了而**没有观测**(结果为空 / 结果里没有这一键 —— prepare 没走完)⇒ 交回那一条、观测缺席,**不往更早的腿找**
+ *    (读集是「最近一条已结腿」的,不是「最近一条有观测的腿」的)。
+ * 结果列读不出 ⇒ 抛(与 `getRun` 同一个失败方向:不把一条结了的腿当成没有结果)。
+ */
+export interface SettledLegMemoryObservation {
+    readonly taskId: string;
+    readonly effectiveMemoryScopes: EffectiveMemoryScopes | undefined;
+}
+/** {@link SettledLegMemoryObservation} 的一只投影(三只实现共用):一条已结腿的结果 → 读口的回值。 */
+export declare function settledLegObservationOf(taskId: string, result: PersistedTaskResult | null): SettledLegMemoryObservation;
 export interface RunEvent {
     seq: number;
     type: string;

package/dist/plugins/store-contracts.js

@@ -56,4 +56,7 @@ export function sessionTempoOfRunStatus(lastStatus) {
 export function runProvenElsewhere(run, thisInstanceId) {
     return typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId;
 }
+export function settledLegObservationOf(taskId, result) {
+    return { taskId, effectiveMemoryScopes: result?.effectiveMemoryScopes ?? undefined };
+}
 //# sourceMappingURL=store-contracts.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -21,12 +21,16 @@
  *  - 隔离键排序规则:TiDB 表级 utf8mb4_bin / PG owner 列 COLLATE "C"(bga F2 同姿,'=' 字节等价)。
  *    owner 值恒为 server 端从凭据推导(非用户输入),PAD SPACE 近撞面不可达,VARBINARY 键列不必要。
  *  - 布尔列:无(遵 1.287.0 归一约定,若未来加,PG 用 SMALLINT 0/1)。
- *  - 绑定:`bind` 把行钉到 sessionId(重复绑定=改绑,同 owner 内 last-wins;同 session 多 task 共享
- *    自然成立——listBySession 是物化输入)。未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
+ *  - 绑定:`bind` 把行钉到 sessionId,两条律都在店里、都不是先读后写(契约见 {@link TaskAttachmentStore.bind}):
+ *    **一经绑定不再改绑**(UPDATE 谓词只放行未绑的行与已绑本会话的行,行级原子;同会话重绑 —— 首交重试、续跑腿重放存量体 —— 不改 `bound_at_ms`);
+ *    **一只会话一只种子**(未绑的项目包只在这只会话还没有项目包时绑上:SQL 两方言是锚行加锁的一只事务,进程内的店是一段不被打断的判与改:内存店同一段同步,local 店的变更口同排一条串行段、bind 判在副本上、落成的行才合回)。
+ *    同 session 多 task 共享自然成立(listBySession 是物化输入)。
+ *    未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
  */
 import { z } from "zod";
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
+import type { Pool as PgPool } from "pg";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
@@ -55,8 +59,14 @@ export interface TaskAttachmentStore {
     /** meta(不带 bytes);owner 不匹配/不存在 → null(无 oracle)。 */
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
-    /** 把 ids 钉到 sessionId(owner 门在 WHERE);返回真绑到的行数——调用方以 count===ids.length 判全成。 */
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    /**
+     * 把 ids(请求序)钉到 sessionId。绑定的两条律都在店里判,判与写对这只会话的其它绑定是原子的(不是先读后写):
+     *  · **一经绑定不再改绑** —— 已绑别的会话的行 ⇒ `bound_elsewhere`(行不动);已绑本会话的行命中、不改 `boundAtMs`;
+     *  · **一只会话一只种子** —— 一只**未绑的项目包**只在这只会话此刻没有项目包时绑上,否则 ⇒ `bundle_seed_fixed`(同一次调用里请求序靠前的那只先占);
+     *    两次并发绑定各带一只新项目包到同一会话 ⇒ 恰一只绑上。
+     * 属主门在店里(owner 不匹配 / 不存在的 id 两边都不出现,无 oracle)。`bound` 按请求序、不重复。
+     */
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     /** 物化输入(env 建立时)——按 session 单键查(绑定时已 owner 验过;session uuid 不可枚举)。 */
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
@@ -89,22 +99,108 @@ export interface AttachmentBytesStore {
  *  (created_at_ms, id)分配 `attachments/<name>`;同名撞车时后者前缀 id 头 8 位。名字在上传时已
  *  消毒为安全 basename([A-Za-z0-9._-]),拼接后仍是安全相对路径。 */
 export declare function materializedRelPaths(atts: TaskAttachmentRecord[]): Map<string, string>;
-/** 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → throw(mapTo400));
- *  resume 腿降级(warn+跳过——4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。
- *  notice 路径从**绑定后的全 session 集**推导(与物化共用 materializedRelPaths),只罗列本次引用的文件。 */
+/**
+ * 提交体 `attachmentIds` 绑定时的拒(闭集;码与状态的唯一映射 = {@link attachmentBindRefusalAnswer})。
+ *  · `bound_elsewhere` —— 这只附件已绑在别的会话上(一经绑定不再改绑;每个会话各上传一次);
+ *  · `bundle_lane_not_isolated` —— 项目包只交给 OS 隔离边界内的车道(`laneIsolated`),这条腿的车道不是;
+ *  · `bundle_seed_fixed` —— 本会话的种子已定(最早绑定的那只项目包),第二只项目包不收。
+ */
+export type AttachmentBindRefusal = {
+    readonly kind: "bound_elsewhere";
+    readonly id: string;
+} | {
+    readonly kind: "bundle_lane_not_isolated";
+    readonly id: string;
+    readonly lane: string;
+} | {
+    readonly kind: "bundle_seed_fixed";
+    readonly id: string;
+};
+/** 店在一次绑定里答的拒(闭集的子集:车道那一只是提交侧对这条腿的判,店不判)。 */
+export type AttachmentStoreBindRefusal = Extract<AttachmentBindRefusal, {
+    readonly kind: "bound_elsewhere" | "bundle_seed_fixed";
+}>;
+/** 一次 {@link TaskAttachmentStore.bind} 的答:此刻绑在这只会话上的 id(请求序)与店拒掉的 id;两边都不在的 id = 不在 / 他人的。 */
+export interface AttachmentStoreBindOutcome {
+    readonly bound: readonly string[];
+    readonly refused: readonly AttachmentStoreBindRefusal[];
+}
+/**
+ * 进程内的店(local 文件店、测试内存店)的绑定律 —— {@link TaskAttachmentStore.bind} 那一条律在进程内的**唯一**写法:判与改在**同一段同步**里
+ * (本函数不 await),于是调用方只要不在本函数前后放开(内存店:整条 `bind` 就是这一段;local 店:`bind` 与店的其它变更口同排一条串行段),
+ * 同一进程里两次并发绑定不可能都读到「这只会话还没有种子」(local 契约本就是单进程,`local-task-attachment-store.ts` 头注)。
+ * 改的是传进来的 `rows` 里的行对象本身 —— 内存店传自己的索引;需要落盘的店传**副本**,只把落盘落成的那些 `claimed` 行合回自己的索引
+ * (`claimed` = 这一次新绑上的行,即副本里被改的那些行对象;索引只反映盘上已有的)。
+ */
+export declare function bindRowsInProcess(rows: ReadonlyMap<string, TaskAttachmentRecord>, owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): {
+    readonly outcome: AttachmentStoreBindOutcome;
+    readonly claimed: readonly TaskAttachmentRecord[];
+};
+/** 绑定拒的码 → 状态:唯一属主表(一个码在本服务上只有一个状态;`<名>_HTTP_STATUS` 是本仓这类表的名形,码目录门按名形读它的键)。 */
+export declare const ATTACHMENT_BIND_HTTP_STATUS: {
+    readonly "attachment.bound_elsewhere": 409;
+    readonly "attachment.bundle_lane_not_isolated": 409;
+    readonly "attachment.bundle_seed_fixed": 409;
+};
+export type AttachmentBindCode = keyof typeof ATTACHMENT_BIND_HTTP_STATUS;
+/** 一只绑定拒在 wire 上的答(状态取自 {@link ATTACHMENT_BIND_HTTP_STATUS} + 码 + 句 + 体键);穷举 switch —— 闭集多一种而这里没跟 ⇒ 编译红。 */
+export declare function attachmentBindRefusalAnswer(r: AttachmentBindRefusal): {
+    readonly status: number;
+    readonly errorCode: AttachmentBindCode;
+    readonly message: string;
+    readonly extra: Record<string, string>;
+};
+/** 会话里**附件**那一类的行(项目包行不在其中)—— 告知的路径分配与物化读的唯一过滤读口:过滤在路径分配之前(种子行不挤动附件的撞名前缀)。 */
+export declare function listAttachmentsBySession(store: TaskAttachmentStore, sessionId: string): Promise<TaskAttachmentRecord[]>;
+/**
+ * 会话种子的读口:最早绑定的项目包行 + 它的字节,字节**必核**行上的 `sha256` 与 `sizeBytes`(种子身份 = 上传那一刻的摘要;local 店读侧不核,这里核)。
+ * 三种答:没有种子 ⇒ `undefined`;种子在、字节在、摘要对 ⇒ `{ record, bytes }`;店里的定局坏了(行在、字节没了 / 摘要不符)⇒ `{ record, broken }`。
+ * 店读本身抛(连接断、超时)⇒ 原样抛:那是一时的失败,不是这只会话的定答 —— 调用方据此分「换一次恢复点重读」与「这只环境此后同一个拒」。
+ */
+export declare function seedOfSession(store: TaskAttachmentStore, sessionId: string): Promise<{
+    readonly record: TaskAttachmentRecord;
+    readonly bytes: Uint8Array;
+} | {
+    readonly record: TaskAttachmentRecord;
+    readonly broken: string;
+} | undefined>;
+/**
+ * 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → `onMissing` throw;拒 → `onRefused` throw);
+ * resume 腿降级(warn+跳过 —— 4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。判序:
+ *  ① 行在不在(属主门);② 已绑别的会话 ⇒ `bound_elsewhere`;③ 项目包 × 车道不隔离 ⇒ `bundle_lane_not_isolated`;
+ *  ④ 本次提交体里第二只新项目包 ⇒ `bundle_seed_fixed`(只看提交体本身,不读店);
+ *  ⑤ 绑定 —— 「本会话已有种子」与「不改绑」两条律只在店里判({@link TaskAttachmentStore.bind},判与写原子:并发的两次提交在那里分胜负,这里不先读):
+ *    提交体那只新项目包先**单独**绑,店拒了它 ⇒ `onRefused` 在体里其余 id 绑上之前就到(新提交腿上,店拒了种子候选的提交,体里其余 id 一只都不绑;读与绑之间才被别的会话抢走的附件不在此列 —— 先绑上的不回滚,请求仍 409);其余 id 随后一次绑。
+ * notice 只罗列本次引用的**附件**(项目包是工作区本身,不进告知),路径从绑定后的全会话附件集推导(与物化共用 {@link materializedRelPaths})。
+ */
 export declare function bindAttachmentsForTask(opts: {
     store: TaskAttachmentStore;
     owner: string;
     ids: string[];
     sessionId: string;
+    /** 这条腿的执行车道(执行上下文那一读)与它是否在 OS 隔离边界内(`laneIsolated` 那一判,调用方判一次交进来)。 */
+    lane: {
+        readonly word: string;
+        readonly isolated: boolean;
+    };
     leg: "fresh" | "resume";
     nowMs: number;
     onMissing: (id: string) => void | never;
+    onRefused: (refusal: AttachmentBindRefusal) => void | never;
 }): Promise<{
     notice: string | undefined;
 }>;
-/** 半场③(env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
- *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建沙箱/resume 重写同路径同字节。 */
+/** 会话绑定的附件按工作区收它们的样子:行 + 物化相对路径(与 objective 告知同一份推导 {@link materializedRelPaths})。
+ *  两只物化座(没有恢复点的车道 = 执行环境建立时 {@link materializeAttachmentsInto};隔离车道 = 恢复点的填充 `workspace-fill.ts`)读的是这一份。 */
+export interface AttachmentPlacement {
+    readonly record: TaskAttachmentRecord;
+    readonly relPath: string;
+}
+export declare function attachmentPlacementsOf(store: TaskAttachmentStore, sessionId: string): Promise<AttachmentPlacement[]>;
+/** 一只要放进工作区的附件的字节;读不到 ⇒ 抛(fail-loud:objective 已宣告它在场)。 */
+export declare function attachmentBytesOf(store: TaskAttachmentStore, rec: TaskAttachmentRecord): Promise<Uint8Array>;
+/** 半场③(没有恢复点的车道:env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
+ *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建 env / resume 重写同路径同字节。 */
 export declare function materializeAttachmentsInto(env: {
     createDir(path: string, options?: {
         recursive?: boolean;
@@ -129,10 +225,10 @@ export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const TASK_ATTACHMENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
-/** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     private readonly pool;
     private readonly bytes;
+    private readonly db;
     constructor(pool: Pool, bytes: AttachmentBytesStore);
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
@@ -143,7 +239,7 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
      *  失败只吞不抛——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
      *  经 API 不可达,彻底清收敛记 follow-up。 */
     private deleteBytesIfUnreferenced;
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
@@ -160,16 +256,18 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     private filterStillOrphan;
 }
 export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
-    private readonly q;
     private readonly bytes;
-    constructor(q: PgQueryFn, bytes: AttachmentBytesStore);
+    private readonly db;
+    private readonly q;
+    /** 收池(不是裸 `PgQueryFn`):绑定的种子腿要一只事务({@link bindOnSql}),事务要一条借出的连接。 */
+    constructor(pool: PgPool, bytes: AttachmentBytesStore);
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
     }): Promise<void>;
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     private deleteBytesIfUnreferenced;
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;