@sema-agent/server 7.142.0 → 7.143.0

package/dist/plugins/sandbox-read-floor.js

@@ -35,11 +35,6 @@ export function buildReadFloorUnavailableMessage(reason, detail, floor) {
         `This command carries a read-deny table${first !== undefined ? ` (first row "${first}")` : ""} this sandbox cannot keep, so it is refused rather than run with fewer rows. ` +
         `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off (the lane then declares keepsReadFloor=false: each run with read-deny rows is announced, or refused when READ_DENY_FLOOR_REQUIRED=true).`);
 }
-export function buildReadFloorMissingMessage(lane) {
-    return (`read floor: this ${lane} sandbox keeps the read-deny byte floor, and this command start carries no floor — it is refused rather than run a process the floor does not judge ` +
-        `(every start on a lane that keeps the floor must carry the run's read-deny table). ` +
-        `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off.`);
-}
 export const ADAPTER_START = Object.freeze({ kind: "adapter" });
 export const BOOTSTRAP_START = Object.freeze({ kind: "bootstrap" });
 export function engineStart(readFloor, hold = false) {
@@ -121,6 +116,8 @@ export function parseRelayFrame(line) {
 }
 export const UNJUDGED_VERDICT = "read floor: no verdict for this start";
 function judgeOne(floor, path) {
+    if (floor === undefined)
+        return null;
     let v;
     try {
         v = floor.denies(path);
@@ -433,8 +430,6 @@ export function createKeptSandboxReadFloor(opts) {
                 }
                 case "engine": {
                     const floor = start.readFloor;
-                    if (floor === undefined)
-                        return spawnError(buildReadFloorMissingMessage(lane));
                     if (phase.kind === "unavailable")
                         return spawnError(buildReadFloorUnavailableMessage(phase.reason, phase.detail, floor));
                     if (phase.kind !== "ready" || bin === undefined)

package/dist/plugins/sql-errors.d.ts

@@ -1,7 +1,8 @@
 /**
  * SQL 驱动错误的**方言判别**——「这是不是唯一键冲突」的单一属主([ref] P1-①,病族
  * single-semantic-multi-site-drift)。`sql-escape.ts` / `sql-row-helpers.ts` / `store-contracts.ts`
- * 的同级叶子:零 store 逻辑、零驱动依赖(不 import mysql2/pg),纯谓词。
+ * 的同级叶子:零 store 逻辑、零驱动依赖(不 import mysql2/pg),纯谓词 —— 外加死锁判据唯一的消费形 {@link retryOnDeadlock}
+ * (「撞死锁重来几次」与「什么算死锁」住在一处:上界只有一个数,不在各店各写一个)。
  *
  * ## 为什么必须只有一份
  * 收编前这条谓词在 src/ 手铸 ≥7 处,而且**识别集互相漂移**:一半站点只认 `code === "ER_DUP_ENTRY"`,
@@ -96,6 +97,14 @@ export declare const PG_DEADLOCK_DETECTED_SQLSTATE = "40P01";
  * **MySQL 协议腿**,两方言都认只是为了让店不必自己判引擎。
  */
 export declare function isDeadlockError(dialect: SqlDialect, err: unknown): boolean;
+/** 引擎仲裁之后整段重来的**唯一**上界(全仓每一条「撞死锁就重来」的腿共用这一个数)。8 = 锁形并发套的并发度:缺行首写的 N 路竞争每轮至多多走一轮([ref] 读数 1 成 7 死锁)。 */
+export declare const DEADLOCK_RETRY_LIMIT = 8;
+/**
+ * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError};用尽 / 其它错误原样抛。
+ * `attempt` 必须整段重做语义等价(读-判-写全在里面的一只事务,或一条幂等语句)。`alsoArbitrated`:店自己认的另一种仲裁产物(例:缺行首写撞主键 ——
+ * 并发的另一只首写赢了,重读即走更新腿),与死锁同族、同一个上界。锁等待超时不在任何一族里(延迟信号,见 {@link isDeadlockError} 的注):它照抛。
+ */
+export declare function retryOnDeadlock<T>(dialect: SqlDialect, attempt: () => Promise<T>, alsoArbitrated?: (err: unknown) => boolean): Promise<T>;
 /** TiDB `ErrEntryTooLarge` (one row's key + value over `txn-entry-size-limit`, 6 MiB by default) — TiDB's own
  *  errno, which mysql2 carries without a symbolic name. */
 export declare const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;

package/dist/plugins/sql-errors.js

@@ -45,6 +45,19 @@ export function isDeadlockError(dialect, err) {
         return keyOf(err, "code") === PG_DEADLOCK_DETECTED_SQLSTATE;
     return keyOf(err, "errno") === MYSQL_ER_LOCK_DEADLOCK_ERRNO || keyOf(err, "code") === MYSQL_ER_LOCK_DEADLOCK_CODE;
 }
+export const DEADLOCK_RETRY_LIMIT = 8;
+export async function retryOnDeadlock(dialect, attempt, alsoArbitrated) {
+    for (let tries = 0;; tries++) {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || alsoArbitrated?.(err) === true))
+                continue;
+            throw err;
+        }
+    }
+}
 export const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;
 export const MYSQL_ER_NET_PACKET_TOO_LARGE_ERRNO = 1153;
 export const MYSQL_ER_NET_PACKET_TOO_LARGE_CODE = "ER_NET_PACKET_TOO_LARGE";

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

@@ -1,6 +1,6 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { SessionStore, SessionPolicyStore, FileHistoryStore, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
+import type { SessionStore, SessionPolicyStore, FileHistoryStore, FileHistoryBlobExchange, FileHistoryError, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
 import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
@@ -60,37 +60,37 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  *  carry (optional so the local lane's core `FileFileHistoryStore` still fits). Replaces the retired E19
  *  whole-tree `ServiceFileSnapshotStore` ([ref]: the boundary covers the TRACKED set only — files this
  *  session edited; there is no whole-tree manifest anymore). Also the 2c history-transfer store
- *  (exportHistory/importHistory + the blob negotiation faces below). */
+ *  (exportHistory/importHistory + the blob exchange below). */
 /**
- * The 2c `putBlob` answer: core's `FileHistoryResult` plus ONE arm — the SQL blob judge refused the blob on the connection that
- * would have written it ({@link import("./blob-backend.js").BlobTooLargeError}, code `blob_too_large_for_sql`). `PUT /sync/blobs`
- * answers that arm 413 (the store's sentence, plus the machine-readable `wallSource` = where the cap came from) and every other failure 502 (retryable).
+ * The SQL twins' blob exchange — core's {@link FileHistoryBlobExchange} group (`put` / `get` / `has`, all three or none, read only
+ * through `blobExchangeOf` in `session-sync.ts`, which defers to core's judge) with ONE narrowing: a `put` refusal may carry
+ * `blobCap`, the SQL blob judge's refusal on the connection that would have written the blob
+ * ({@link import("./blob-backend.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
+ * `blob_too_large_for_sql` (the judge's sentence, plus the machine-readable `wallSource` = where the cap came from). The content-address
+ * refusal is core's own (`adopt_failed`, `permanence: "terminal"`, nothing stored); every other failure is a write fault the route answers 502.
  */
-export type SyncBlobPutResult = import("@sema-agent/core").FileHistoryResult | {
+export type SqlBlobPutResult = {
+    readonly ok: true;
+} | {
     readonly ok: false;
-    readonly error: {
-        readonly code: import("./blob-backend.js").BlobTooLargeError["code"];
-        readonly message: string;
-        readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+    readonly error: FileHistoryError & {
+        readonly blobCap?: {
+            readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+        };
     };
 };
+export interface ServiceBlobExchange extends FileHistoryBlobExchange {
+    put(hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+}
 export type ServiceFileHistoryStore = FileHistoryStore & {
-    /** 2c sync blob-face marker — see SqlFileHistoryStore.syncBlobFaces (codex R2-high: name-probing
-     *  `putBlob` on an arbitrary store collides with the local core store's PRIVATE void helper). */
-    syncBlobFaces?: true;
+    /** The blob exchange (SQL twins only; core's local File store carries none). Narrowed per {@link ServiceBlobExchange}. */
+    readonly blobExchange?: ServiceBlobExchange;
     /** E21 purge / overwrite-dst sync wipe: drop the WHOLE scope incl. v1 baselines + DV-14 markers
      *  (`reap(scope, [])` deliberately retains those while the scope lives — not a purge). SQL twins only. */
     deleteBySession?(scope: string): Promise<number>;
     /** Async byte-GC for the file_history_blob domain (orphans left by reap/purge/lost mint races; grace-window
      *  protected — never a synchronous external-store delete). Reaper-driven; SQL twins only. */
     sweepOrphanBlobs?(): Promise<number>;
-    /** 2c blob negotiation: upload one content-addressed blob ahead of importHistory. SQL twins only. */
-    putBlob?(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
-    /** 2c blob read face (scope-checked by the route against the session's history graph). SQL twins only. */
-    getBlob?(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` already present — a cheap SQL INDEX probe (the import presence pre-check,
-     *  never N full getBlob GETs). SQL twins only. */
-    hasBlobs?(hashes: string[]): Promise<Set<string>>;
 };
 /** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service `deleteByRun` (GC extra). tidb/pg =
  *  durable SQL twins (cross-replica resume journal); local = the service {@link FileWorkflowJournalStore}
@@ -128,15 +128,10 @@ export type CheckpointStoreFull = TiDBCheckpointStore | PgCheckpointStore | Loca
 /** The full tool-result store: core `ToolResultStore` + the service maintenance extras. The SQL twins carry
  *  both extras; the LOCAL lane returns core's `FileToolResultStore` (core 1.219 — durable across a
  *  process restart, the TOC "ReadToolResult(ref) 恒空" fix) which since core 5.28.0 carries `deleteBySession`
- *  (owner sidecar 判属主,无边车存量计 unattributable 不删)but still NOT `reapOlderThan` — consumers must
- *  optional-call (`store.reapOlderThan?.()`,local 上恒 no-op)。(R5 复扫纠:旧句「carries NEITHER」自
- *  core 5.28 起半假——本类型注是消费方第一落点,与 LocalBackend 内部注必须同真。)
+ *  (owner sidecar 判属主,无边车存量计 unattributable 不删)and since core 7.61.0 the age bound `reap(now, { maxAgeMs })`
+ *  — both are core `ToolResultStore`'s own optional members, so consumers optional-call them (`store.reap?.(…)`).
  *  Structural (not a nominal union) so all three backends flow through one seam. */
-export type ToolResultStoreFull = ToolResultStore & {
-    /** TTL sweep (SQL twins only): purge rows older than the cutoff. Local file store omits it (CC posture:
-     *  a single user's tool-result files persist like transcripts; bounded by being text previews). */
-    reapOlderThan?(cutoffMs: number): Promise<number>;
-};
+export type ToolResultStoreFull = ToolResultStore & {};
 /** Cross-replica counter twins expose the write-behind lifecycle (startRefresh/stop) main.ts drives. */
 export type BreakerStateStore = TiDBBreakerState | PgBreakerState;
 export type CostQuotaStore = TiDBCostQuota | PgCostQuota;

package/dist/plugins/store-backend.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { createCorruptReadSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
 import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
+import { existsSync } from "node:fs";
 import { AdoptionError, FileStorageBackend } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { fileSessionCaptureRecordStore } from "@sema-agent/core";
@@ -58,7 +59,8 @@ import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js"
 import { TiDBRetentionStore, PgRetentionStore, sqlStoreRetention } from "./retention-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
-import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
+import { FILE_PERMISSION_RULE_DIR, createFilePermissionRuleStores } from "./permission-rule-store-file.js";
+import { retireImportedLayerRootAllows } from "./imported-layer-root-retirement.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { storeDegradedReasonFor } from "../store-posture.js";
 import { openWithinWait } from "./store-open-wait.js";
@@ -298,6 +300,11 @@ class LocalBackend {
         const holderDeathCodeRowsBackfilled = this.runStore.migrateLegacyHolderDeathCodes();
         const archives = await this.sessionStore.migrateLocalArchives();
         const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
+        const importedLayerRoot = { importedLayerRootAllowsRetired: [], importedLayerRootBucketsSkipped: [] };
+        if (existsSync(join(this.fileBackend.root, FILE_PERMISSION_RULE_DIR))) {
+            const rules = this.permissionRule();
+            await retireImportedLayerRootAllows({ candidateOwners: () => rules.approvals.importRecordOwners(), durable: rules.durable, isWholeBucketRefusal: () => false, isVanishedBucket: () => false }, importedLayerRoot);
+        }
         return {
             ...NO_SQL_MIGRATIONS,
             holderDeathCodeRowsBackfilled,
@@ -310,6 +317,7 @@ class LocalBackend {
             localArchivesKeptStamped: archives.keptStamped,
             localArchivesUnreadable: archives.unreadable,
             localArchiveSnapshotsRecovered: archives.snapshotsRecovered,
+            ...importedLayerRoot,
         };
     }
     async close() {

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

@@ -578,6 +578,24 @@ export interface LatestRunRef {
 }
 /** 引擎对一条腿实际挂上的记忆读集的观测(core `TaskResult.effectiveMemoryScopes` 的值;core 包根不单独导出这只型,从结果型取)。 */
 export type EffectiveMemoryScopes = NonNullable<PersistedTaskResult["effectiveMemoryScopes"]>;
+/**
+ * [ref] —— **空观测**的因由(闭集;词表属主 = 本文件,唯一铸点 = {@link settledLegObservationOf})。两词都只说**那条已结腿的记录里有什么**,不猜它为什么停 ——
+ * 停因的真源是那一条 run 自己的终局(`GET /v1/runs/:id` 的 `status` / `errorCode`),这里不复述第二份:
+ *  · `run_result_missing`    —— 记录里**没有结果**:本服务结算它时手里没有引擎的结果(持有它的实例丢了被收割、腿在引擎答出之前抛),或收割时写空了它(停驻过期被收割 ——
+ *    [ref] 律:收割把停驻结果写空,停驻时那份结果里的观测随之不在;本读口不另存一份);
+ *  · `run_result_unobserved` —— 记录里**有结果、结果里没有观测**:引擎的律是「缺席 ⇔ prepare 没走完」(引擎在准备阶段拒了 / 失败了它),
+ *    另两形同答 —— 引擎答出之前就被取消、由本服务铸的取消终局,与比这一观测更早的引擎写下的结果。
+ * 自铸 wire 值登记 = `trace/self-minted-wire.ts` 的 `sessionMemoryUnobservedReason`(`satisfies Record<…>`:加 / 删一个词而登记没跟 ⇒ tsc 红)。
+ */
+export declare const MEMORY_OBSERVATION_ABSENT_REASONS: readonly ["run_result_missing", "run_result_unobserved"];
+export type MemoryObservationAbsentReason = (typeof MEMORY_OBSERVATION_ABSENT_REASONS)[number];
+/** [ref] —— 空观测记号:与引擎三态同一只字段、同一个判别位 `state`(闭集加一词 `absent`;引擎哪天自己长出同名一态 ⇒ `trace/core-keyset-guard.ts` 的跨界钉当场红)。 */
+export interface AbsentMemoryObservation {
+    readonly state: "absent";
+    readonly reason: MemoryObservationAbsentReason;
+}
+/** 一条已结腿的记忆观测 —— 四态闭集:引擎铸的三态原样(`mounted` / `memoryless` / `none`)∪ 空观测({@link AbsentMemoryObservation})。消费方按 `state` 穷举分支。 */
+export type LegMemoryObservation = EffectiveMemoryScopes | AbsentMemoryObservation;
 /**
  * 「这个会话**最近一条已结腿**与它的记忆观测」的窄读面(run 店的 `latestMemoryObservationForSession` 的回值)—— 会话记忆同步触发口
  * (`POST /v1/sessions/:id/memory/sync`)的**会话读集**只读这一只:读集 = 最近一条已结腿结果里引擎铸的观测(引擎一处铸、随 run 行持久;路由不重铸 spec)。
@@ -586,17 +604,23 @@ export type EffectiveMemoryScopes = NonNullable<PersistedTaskResult["effectiveMe
  *  · 已结 = {@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 没走完)⇒ 交回那一条、观测缺席,**不往更早的腿找**
- *    (读集是「最近一条已结腿」的,不是「最近一条有观测的腿」的)。
+ *  · `observation` = 那一条腿的观测,**恒在场**,四态之一({@link LegMemoryObservation}):结果里有引擎的观测 ⇒ 原样;没有 ⇒ 空观测记号,因由说记录里有什么
+ *    ({@link MemoryObservationAbsentReason})。**不往更早的腿找**:读集是「最近一条已结腿」的,不是「最近一条有观测的腿」的 —— 空观测是那一条的值,不是去找下一条的信号。
+ * 空观测**不落盘**:它是行上已有事实(结果列、结果里那一键的缺席)的一只纯函数,铸在读口({@link settledLegObservationOf},三店共用);落一份 = 第二真源
+ * (与引擎「缺席 ⇔ prepare 没走完」那条律并存、两份要对得上),且终局写口二十余处、收割器整行写空结果的 SQL 两方言语句与存量行都得各补一份。
  * 结果列读不出 ⇒ 抛(与 `getRun` 同一个失败方向:不把一条结了的腿当成没有结果)。
  */
 export interface SettledLegMemoryObservation {
     readonly taskId: string;
-    readonly effectiveMemoryScopes: EffectiveMemoryScopes | undefined;
+    readonly observation: LegMemoryObservation;
 }
-/** {@link SettledLegMemoryObservation} 的一只投影(三只实现共用):一条已结腿的结果 → 读口的回值。 */
+/** {@link SettledLegMemoryObservation} 的**唯一铸点**(三只实现共用):一条已结腿的结果 → 读口的回值(空观测记号只在这里铸)。 */
 export declare function settledLegObservationOf(taskId: string, result: PersistedTaskResult | null): SettledLegMemoryObservation;
+/**
+ * run 店账本的一条事件 —— 三只孪生的 `getEvents` 都交出写口收下的那一形(按 seq 升序、每读一份新拷贝)。存形是孪生的私事、读者看不见:
+ * File 孪生把 `wiring_manifest` 行的容器段按会话存成块(`<root>/run-blobs/<会话>.jsonl`,律与唯一编解码 = `wiring-section-codec.ts`),行里只留引用,
+ * 读口装回整帧;装不回的那一帧不交出(F 类留痕),绝不交出缺段的清单。SQL / Memory 孪生整帧存。
+ */
 export interface RunEvent {
     seq: number;
     type: string;

package/dist/plugins/store-contracts.js

@@ -56,7 +56,10 @@ export function sessionTempoOfRunStatus(lastStatus) {
 export function runProvenElsewhere(run, thisInstanceId) {
     return typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId;
 }
+export const MEMORY_OBSERVATION_ABSENT_REASONS = ["run_result_missing", "run_result_unobserved"];
 export function settledLegObservationOf(taskId, result) {
-    return { taskId, effectiveMemoryScopes: result?.effectiveMemoryScopes ?? undefined };
+    if (result === null)
+        return { taskId, observation: { state: "absent", reason: "run_result_missing" } };
+    return { taskId, observation: result.effectiveMemoryScopes ?? { state: "absent", reason: "run_result_unobserved" } };
 }
 //# sourceMappingURL=store-contracts.js.map

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

@@ -23,7 +23,7 @@
  *  - 布尔列:无(遵 1.287.0 归一约定,若未来加,PG 用 SMALLINT 0/1)。
  *  - 绑定:`bind` 把行钉到 sessionId,两条律都在店里、都不是先读后写(契约见 {@link TaskAttachmentStore.bind}):
  *    **一经绑定不再改绑**(UPDATE 谓词只放行未绑的行与已绑本会话的行,行级原子;同会话重绑 —— 首交重试、续跑腿重放存量体 —— 不改 `bound_at_ms`);
- *    **一只会话一只种子**(未绑的项目包只在这只会话还没有项目包时绑上:SQL 两方言是锚行加锁的一只事务,进程内的店是一段不被打断的判与改:内存店同一段同步,local 店的变更口同排一条串行段、bind 判在副本上、落成的行才合回)。
+ *    **一只会话一只种子**(未绑的项目包只在这只会话还没有项目包时绑上:SQL 两方言是表上的唯一键 —— 种子键 `seed_session_id`(项目包行的会话,由引擎从 `mime` 与 `session_id` 推导)上的 `uq_att_seed`,第二只项目包的绑定被引擎拒;进程内的店是一段不被打断的判与改:内存店同一段同步,local 店的变更口同排一条串行段、bind 判在副本上、落成的行才合回)。
  *    同 session 多 task 共享自然成立(listBySession 是物化输入)。
  *    未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
  */
@@ -259,7 +259,7 @@ export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
     private readonly bytes;
     private readonly db;
     private readonly q;
-    /** 收池(不是裸 `PgQueryFn`):绑定的种子腿要一只事务({@link bindOnSql}),事务要一条借出的连接。 */
+    /** 收池:绑定({@link bindOnSql})走与 TiDB 孪生同一只驱动形({@link pgDriver})。 */
     constructor(pool: PgPool, bytes: AttachmentBytesStore);
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;

package/dist/plugins/task-attachment-store.js

@@ -3,7 +3,7 @@ import { ensureIndexes } from "./ensure-index.js";
 import { createHash } from "node:crypto";
 import { attachmentKindOf, PROJECT_BUNDLE_MIME } from "../project-bundle.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isDeadlockError } from "./sql-errors.js";
+import { isDupKeyError, retryOnDeadlock } from "./sql-errors.js";
 export const TaskAttachmentRecordSchema = z.object({
     id: z.string(),
     owner: z.string(),
@@ -183,6 +183,8 @@ export async function materializeAttachmentsInto(env, store, sessionId) {
     }
     return placements.length;
 }
+const SEED_KEY = "uq_att_seed";
+const SEED_KEY_EXPR = `CASE WHEN mime = '${PROJECT_BUNDLE_MIME}' THEN session_id END`;
 export async function ensureTiDBTaskAttachmentSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
     id VARCHAR(64) NOT NULL,
@@ -196,15 +198,19 @@ export async function ensureTiDBTaskAttachmentSchema(pool) {
     session_id VARCHAR(190) NULL,
     created_at_ms BIGINT NOT NULL,
     bound_at_ms BIGINT NULL,
+    -- 种子键:项目包行的会话,其余行 NULL(引擎推导,没有写者);唯一 ⇒ 一只会话一只种子
+    seed_session_id VARCHAR(190) GENERATED ALWAYS AS (${SEED_KEY_EXPR}) VIRTUAL,
     PRIMARY KEY (id),
     KEY idx_att_session (session_id),
-    KEY idx_att_unbound (created_at_ms)
+    KEY idx_att_unbound (created_at_ms),
+    UNIQUE KEY ${SEED_KEY} (seed_session_id)
   ) COLLATE utf8mb4_bin`);
     await ensureIndexes((text, params) => pool.query(text, params), "mysql", TASK_ATTACHMENT_INDEXES);
 }
 export const TASK_ATTACHMENT_INDEXES = [
     { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_session", columns: ["session_id"] },
     { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_unbound", columns: ["created_at_ms"] },
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: SEED_KEY, columns: ["seed_session_id"], unique: true },
 ];
 export async function ensurePgTaskAttachmentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
@@ -218,66 +224,50 @@ export async function ensurePgTaskAttachmentSchema(q) {
     session_id VARCHAR(190) COLLATE "C",
     created_at_ms BIGINT NOT NULL,
     bound_at_ms BIGINT,
+    -- 种子键(同 MySQL 侧注)
+    seed_session_id VARCHAR(190) COLLATE "C" GENERATED ALWAYS AS (${SEED_KEY_EXPR}) STORED,
     PRIMARY KEY (id)
   )`);
     await ensureIndexes(q, "pg", TASK_ATTACHMENT_INDEXES);
 }
-const SEED_BIND_DEADLOCK_RETRIES = 4;
 async function bindOnSql(db, owner, ids, sessionId, boundAtMs) {
     const list = [...new Set(ids)];
     if (list.length === 0)
         return { bound: [], refused: [] };
     const mysql = db.dialect === "mysql";
     const q = (mysqlSql, pgSql) => (mysql ? mysqlSql : pgSql);
-    const kinds = await db.query(q(`SELECT id, mime FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = ? AND id IN (${list.map(() => "?").join(",")})`, `SELECT id, mime FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = $1 AND id = ANY($2::varchar[])`), mysql ? [owner, ...list] : [owner, list]);
-    const kindOf = new Map(kinds.rows.map((r) => [String(r.id), attachmentKindOf(String(r.mime))]));
-    const verdicts = new Map();
-    const plain = list.filter((id) => kindOf.get(id) === "attachment");
-    if (plain.length > 0) {
-        const inList = plain.map(() => "?").join(",");
-        const held = await retryingDeadlock(db.dialect, async () => {
-            await db.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN ? ELSE bound_at_ms END, session_id = ? WHERE owner = ? AND id IN (${inList}) AND (session_id IS NULL OR session_id = ?)`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN $2::bigint ELSE bound_at_ms END, session_id = $1::varchar WHERE owner = $3 AND id = ANY($4::varchar[]) AND (session_id IS NULL OR session_id = $1::varchar)`), mysql ? [boundAtMs, sessionId, owner, ...plain, sessionId] : [sessionId, boundAtMs, owner, plain]);
-            return db.query(q(`SELECT id, session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = ? AND id IN (${inList})`, `SELECT id, session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = $1 AND id = ANY($2::varchar[])`), mysql ? [owner, ...plain] : [owner, plain]);
-        });
-        for (const r of held.rows) {
-            if (r.session_id === null || r.session_id === undefined)
-                continue;
-            verdicts.set(String(r.id), String(r.session_id) === sessionId ? "bound" : "bound_elsewhere");
-        }
-    }
+    const ownRows = (columns, of) => db.query(q(`SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = ? AND id IN (${of.map(() => "?").join(",")})`, `SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = $1 AND id = ANY($2::varchar[])`), mysql ? [owner, ...of] : [owner, of]);
+    const kindOf = new Map((await ownRows("id, mime", list)).rows.map((r) => [String(r.id), attachmentKindOf(String(r.mime))]));
+    const claim = (of) => retryOnDeadlock(db.dialect, () => inTransaction(db, (conn) => conn.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN ? ELSE bound_at_ms END, session_id = ? WHERE owner = ? AND id IN (${of.map(() => "?").join(",")}) AND (session_id IS NULL OR session_id = ?)`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN $2::bigint ELSE bound_at_ms END, session_id = $1::varchar WHERE owner = $3 AND id = ANY($4::varchar[]) AND (session_id IS NULL OR session_id = $1::varchar)`), mysql ? [boundAtMs, sessionId, owner, ...of, sessionId] : [sessionId, boundAtMs, owner, of])));
+    const attachments = list.filter((id) => kindOf.get(id) === "attachment");
+    if (attachments.length > 0)
+        await claim(attachments);
+    const seedFixed = new Set();
     for (const id of list) {
         if (kindOf.get(id) !== "project_bundle")
             continue;
-        const verdict = await retryingDeadlock(db.dialect, () => inTransaction(db, (conn) => bindProjectBundleOnSql(conn, mysql, owner, id, sessionId, boundAtMs)));
-        if (verdict !== undefined)
-            verdicts.set(id, verdict);
+        try {
+            await claim([id]);
+        }
+        catch (err) {
+            if (!isSeedKeyConflict(db.dialect, err))
+                throw err;
+            seedFixed.add(id);
+        }
     }
+    const holderOf = new Map((await ownRows("id, session_id", list)).rows.map((r) => [String(r.id), r.session_id === null || r.session_id === undefined ? undefined : String(r.session_id)]));
     const bound = [];
     const refused = [];
     for (const id of list) {
-        const v = verdicts.get(id);
-        if (v === "bound")
+        if (seedFixed.has(id))
+            refused.push({ kind: "bundle_seed_fixed", id });
+        else if (holderOf.get(id) === sessionId)
             bound.push(id);
-        else if (v !== undefined)
-            refused.push({ kind: v, id });
+        else if (holderOf.get(id) !== undefined)
+            refused.push({ kind: "bound_elsewhere", id });
     }
     return { bound, refused };
 }
-async function bindProjectBundleOnSql(conn, mysql, owner, id, sessionId, boundAtMs) {
-    const q = (mysqlSql, pgSql) => (mysql ? mysqlSql : pgSql);
-    const anchor = await conn.query(q(`SELECT session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE mime = ? AND (session_id IS NULL OR session_id = ?) ORDER BY id FOR UPDATE`, `SELECT session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE mime = $1 AND (session_id IS NULL OR session_id = $2::varchar) ORDER BY id FOR UPDATE`), [PROJECT_BUNDLE_MIME, sessionId]);
-    const own = await conn.query(q(`SELECT session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE id = ? AND owner = ? FOR UPDATE`, `SELECT session_id FROM ${TASK_ATTACHMENT_TABLE} WHERE id = $1 AND owner = $2 FOR UPDATE`), [id, owner]);
-    const [row] = own.rows;
-    if (row === undefined)
-        return undefined;
-    const holder = row.session_id;
-    if (holder !== null && holder !== undefined)
-        return String(holder) === sessionId ? "bound" : "bound_elsewhere";
-    if (anchor.rows.some((r) => r.session_id !== null && r.session_id !== undefined))
-        return "bundle_seed_fixed";
-    await conn.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = ?, session_id = ? WHERE id = ? AND owner = ? AND session_id IS NULL`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = $1::bigint, session_id = $2::varchar WHERE id = $3 AND owner = $4 AND session_id IS NULL`), [boundAtMs, sessionId, id, owner]);
-    return "bound";
-}
 async function inTransaction(db, work) {
     const conn = await db.connect();
     try {
@@ -294,17 +284,12 @@ async function inTransaction(db, work) {
         conn.release();
     }
 }
-async function retryingDeadlock(dialect, attempt) {
-    for (let tries = 0;; tries++) {
-        try {
-            return await attempt();
-        }
-        catch (err) {
-            if (tries < SEED_BIND_DEADLOCK_RETRIES && isDeadlockError(dialect, err))
-                continue;
-            throw err;
-        }
-    }
+function isSeedKeyConflict(dialect, err) {
+    if (!isDupKeyError(dialect, err) || err === null || typeof err !== "object")
+        return false;
+    if (dialect === "pg")
+        return Reflect.get(err, "constraint") === SEED_KEY;
+    return new RegExp(`\\b${SEED_KEY}\\b`).test(String(Reflect.get(err, "sqlMessage") ?? Reflect.get(err, "message") ?? ""));
 }
 export class TiDBTaskAttachmentStore {
     pool;

package/dist/plugins/tool-result-store-sql.d.ts

@@ -28,7 +28,6 @@ export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>
 export declare function assertToolResultProvenanceSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: SqlDialect): Promise<void>;
-/** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
@@ -73,14 +72,16 @@ export declare class SqlToolResultStore implements ToolResultStore {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined>;
-    /** TTL reap: delete results older than `cutoffMs`. Returns rows removed.
+    /** core `ToolResultStore.reap` (core 7.61.0 — the one age bound every backend reads): remove the results stored more than
+     *  `opts.maxAgeMs` before `now`. No bound ⇒ nothing removed; a bound that cannot be evaluated (`maxAgeMs` not a finite
+     *  number ≥ 0, `now` not a finite number) ⇒ refused, coded `config.retention_policy_invalid`, before any row is touched;
+     *  age alone decides (ownership is not consulted — the row and its owner columns go together). Returns rows removed.
      *  C6: a real DB error must NOT collapse into the same `0` a legitimate "nothing was old enough" returns —
-     *  those are different facts (query failed vs. query succeeded on an empty set) and folding them together
-     *  makes a stuck/broken reaper indistinguishable from a healthy quiet one. Matches every sibling reaper's
-     *  form (roster-store-sql.ts `reapOlderThan`, checkpoint-store-sql.ts `reapExpired`,
-     *  workflow-journal-store-sql.ts `reapExpired`): let the error propagate — the periodic-sweep call site
-     *  (boot/reapers.ts) already wraps this call in `.catch(() => undefined)` so the reap loop itself never dies. */
-    reapOlderThan(cutoffMs: number): Promise<number>;
+     *  those are different facts (query failed vs. query succeeded on an empty set). Let the error propagate — the
+     *  periodic-sweep call site (boot/reapers.ts) wraps this call in its throttled catch so the reap loop never dies. */
+    reap(now: number, opts?: {
+        maxAgeMs?: number;
+    }): Promise<number>;
     /**
      * E21 (§0.5 session delete) — purge offloaded tool results for one session. Selection is by the row's
      * **recorded provenance** (`owner_session_id`, the [ref] column `put` writes in the same statement as the

package/dist/plugins/tool-result-store-sql.js

@@ -55,6 +55,24 @@ export async function assertToolResultProvenanceSchema(query, dialect) {
             (await describeProbedTableDrift(query, dialect, ["tool_result"])));
     }
 }
+function toolResultAgeCutoff(now, opts) {
+    const refuse = (what, v) => {
+        throw Object.assign(new Error(`ToolResultStore.reap: ${what} must be a finite number${what === "maxAgeMs" ? " of milliseconds of 0 or more" : ""} (got ${typeof v === "string" ? JSON.stringify(v) : String(v)}) — a retention bound that cannot be evaluated is refused, never read as "no bound"`), {
+            code: "config.retention_policy_invalid",
+        });
+    };
+    if (opts !== undefined) {
+        for (const key of Object.keys(opts))
+            if (key !== "maxAgeMs")
+                refuse(`the bound "${key}" (only maxAgeMs is taken)`, opts[key]);
+    }
+    const maxAgeMs = opts?.maxAgeMs;
+    if (maxAgeMs !== undefined && (typeof maxAgeMs !== "number" || !Number.isFinite(maxAgeMs) || maxAgeMs < 0))
+        refuse("maxAgeMs", maxAgeMs);
+    if (typeof now !== "number" || !Number.isFinite(now))
+        refuse("now", now);
+    return maxAgeMs === undefined ? undefined : now - maxAgeMs;
+}
 export class SqlToolResultStore {
     db;
     retention;
@@ -126,8 +144,11 @@ export class SqlToolResultStore {
             return undefined;
         return { content: String(rows[0].slice ?? ""), offset, totalChars: Number(rows[0].total) };
     }
-    async reapOlderThan(cutoffMs) {
-        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoffMs)]);
+    async reap(now, opts) {
+        const cutoff = toolResultAgeCutoff(now, opts);
+        if (cutoff === undefined)
+            return 0;
+        const { affected } = await this.db.query(this.q("DELETE FROM tool_result WHERE created_at < ?", "DELETE FROM tool_result WHERE created_at < $1"), [new Date(cutoff)]);
         return affected;
     }
     async deleteBySession(sessionId) {

package/dist/plugins/wiring-section-codec.d.ts

@@ -0,0 +1,32 @@
+/** 块引用的唯一键。 */
+export declare const WIRING_SECTION_REF_KEY = "$blob";
+/** 一只段体:摘要(`sha256:<64 hex>`)+ 段值本身(JSON 容器)。 */
+export interface WiringSectionBlob {
+    readonly digest: string;
+    readonly body: object;
+}
+/** {@link splitForStore} 的产物:要落账本的那一形 + 本帧引用到的段体(按摘要去重,首见为准)。 */
+export interface WiringSectionSplit {
+    readonly stored: unknown;
+    readonly blobs: readonly WiringSectionBlob[];
+}
+/** 装回失败的一段:段名 + 它的引用(引用值不是串时记 `<not-a-digest>`)。 */
+export interface UnresolvedWiringSection {
+    readonly section: string;
+    readonly digest: string;
+}
+/** {@link joinFromStore} 的结局:整帧,或至少一段装不回(永不交出缺段的帧)。 */
+export type WiringSectionJoin = {
+    readonly kind: "joined";
+    readonly data: unknown;
+} | {
+    readonly kind: "unresolved";
+    readonly missing: readonly UnresolvedWiringSection[];
+};
+/** 段体的店键:段体(一只 JSON 值)规范 JSON 的 sha256 全长。 */
+export declare function wiringSectionDigest(body: object): string;
+/** 写口:清单帧里 JSON 形是容器的段换成块引用(段体是那一段的 JSON 形,与原值不共享);别的型、或 `data` 不是对象 ⇒ 原样、零块。 */
+export declare function splitForStore(type: string, data: unknown): WiringSectionSplit;
+/** 读口:清单行里恰为单键 `$blob` 对象的顶层段换回段体;任一段在 `lookup` 里找不到 ⇒ `unresolved`(点名每一段)。 */
+export declare function joinFromStore(type: string, data: unknown, lookup: (digest: string) => object | undefined): WiringSectionJoin;
+//# sourceMappingURL=wiring-section-codec.d.ts.map

package/dist/plugins/wiring-section-codec.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonStringify } from "@sema-agent/core";
+export const WIRING_SECTION_REF_KEY = "$blob";
+const WIRING_MANIFEST = "wiring_manifest";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function wiringSectionDigest(body) {
+    return `sha256:${createHash("sha256").update(canonicalJsonStringify(body), "utf8").digest("hex")}`;
+}
+function jsonContainerOf(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const text = JSON.stringify(value);
+    if (text === undefined)
+        return undefined;
+    const body = JSON.parse(text);
+    return typeof body === "object" && body !== null ? body : undefined;
+}
+export function splitForStore(type, data) {
+    if (type !== WIRING_MANIFEST || !isRecord(data))
+        return { stored: data, blobs: [] };
+    const blobs = new Map();
+    const stored = Object.fromEntries(Object.entries(data).map(([section, value]) => {
+        const body = jsonContainerOf(value);
+        if (body === undefined)
+            return [section, value];
+        const digest = wiringSectionDigest(body);
+        if (!blobs.has(digest))
+            blobs.set(digest, body);
+        return [section, { [WIRING_SECTION_REF_KEY]: digest }];
+    }));
+    return { stored, blobs: [...blobs].map(([digest, body]) => ({ digest, body })) };
+}
+export function joinFromStore(type, data, lookup) {
+    if (type !== WIRING_MANIFEST || !isRecord(data))
+        return { kind: "joined", data };
+    let refs = 0;
+    const missing = [];
+    const entries = Object.entries(data).map(([section, value]) => {
+        if (!isRecord(value))
+            return [section, value];
+        const keys = Object.keys(value);
+        if (keys.length !== 1 || keys[0] !== WIRING_SECTION_REF_KEY)
+            return [section, value];
+        refs += 1;
+        const ref = value[WIRING_SECTION_REF_KEY];
+        const body = typeof ref === "string" ? lookup(ref) : undefined;
+        if (body === undefined)
+            missing.push({ section, digest: typeof ref === "string" ? ref : "<not-a-digest>" });
+        return [section, body ?? value];
+    });
+    if (missing.length > 0)
+        return { kind: "unresolved", missing };
+    return { kind: "joined", data: refs === 0 ? data : Object.fromEntries(entries) };
+}
+//# sourceMappingURL=wiring-section-codec.js.map

package/dist/plugins/workspace-fill.d.ts

@@ -27,7 +27,7 @@ export interface WorkspaceChannel {
     run(command: string): Promise<ChannelRun>;
     write(absPath: string, bytes: Uint8Array): Promise<ChannelWrite>;
 }
-/** 恢复点交出的工作区从哪来:`minted` = 车道刚铸出的新工作区(没有可恢复的树 —— 含恢复的归档不在:`latest` 悬空、停驻快照从未物化);`restored` = 恢复出来的(空间 `latest` / 停驻快照的树真回来了)。 */
+/** 恢复点交出的工作区从哪来:`minted` = 车道刚铸出的新工作区(没有可恢复的树 —— 含恢复点指的归档不在:`latest` 悬空、停驻快照的归档不在);`restored` = 恢复出来的(空间 `latest` / 停驻快照的树真回来了)。 */
 export type WorkspaceOrigin = "minted" | "restored";
 /** 一次填充的结局。`standing` = 这只执行环境此后每一次恢复点都会得到同一个答(适配器把它记成这只环境的拒,不再建机器)。 */
 export type FillOutcome = {