@sema-agent/server 7.145.0 → 7.146.0

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

@@ -0,0 +1,152 @@
+import { isGateKind, judgeCheckpointRow, MAX_RULE_TEXT_CHARS, } from "@sema-agent/core";
+import { redactDeep, redactSecrets } from "../trace/redact.js";
+import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, readRuleOfferList } from "../approval-card.js";
+import { StoreCorruptError } from "./sql-json-column.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+const MAX_TOOL_INPUT_CHARS = 8192;
+export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
+export const TERMINAL_GRACE_MS = 3_600_000;
+const GATE_KIND_IS_LIVE_RUN_PARK = {
+    human: true,
+    irreversible_ask: true,
+    resource_limit: true,
+    needs_review: true,
+    plan_review: true,
+    task_done: false,
+};
+export const LIVE_RUN_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => GATE_KIND_IS_LIVE_RUN_PARK[k]);
+export const TERMINAL_PARK_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => !GATE_KIND_IS_LIVE_RUN_PARK[k]);
+export function pendingRowPrecedes(a, b, pick) {
+    if (pick === "oldest")
+        return a.createdAt < b.createdAt || (a.createdAt === b.createdAt && a.token < b.token);
+    return a.createdAt > b.createdAt || (a.createdAt === b.createdAt && a.token > b.token);
+}
+const MAX_RULE_OFFER_SCAN = 32;
+function preboundBatchMembers(item) {
+    if (typeof item !== "object" || item === null)
+        return item;
+    const candidate = item;
+    if (candidate.kind !== "batch" || !Array.isArray(candidate.rules) || candidate.rules.length <= MAX_RULE_OFFER_BATCH_MEMBERS)
+        return item;
+    return { ...candidate, rules: candidate.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS) };
+}
+function boundedReaderInput(raw) {
+    return Array.isArray(raw) ? raw.slice(0, MAX_RULE_OFFER_SCAN).map(preboundBatchMembers) : raw;
+}
+export function boundedRuleOffers(raw, opts = {}) {
+    const observe = opts.countRedactions ?? true;
+    const scrub = (text) => redactSecrets(text, { observe }).slice(0, MAX_RULE_TEXT_CHARS);
+    const read = readRuleOfferList(boundedReaderInput(raw));
+    const out = [];
+    for (const { offer } of read) {
+        if (out.length >= MAX_RULE_OFFERS)
+            break;
+        switch (offer.kind) {
+            case "single":
+                out.push({ kind: "single", rule: scrub(offer.rule), match: offer.match, command: scrub(offer.command) });
+                break;
+            case "batch":
+                out.push({
+                    kind: "batch",
+                    rules: offer.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
+                        switch (r.kind) {
+                            case "command":
+                                return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
+                            case "directoryRead":
+                                return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
+                            default:
+                                throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
+                        }
+                    }),
+                    uncoveredSegments: offer.uncoveredSegments,
+                    ...(offer.uncoveredDetail !== undefined ? { uncoveredDetail: offer.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
+                });
+                break;
+            default:
+                throw new Error(`unknown rule-offer kind: ${JSON.stringify(offer)}`);
+        }
+    }
+    return out.length > 0 ? out : undefined;
+}
+export class UnreadableCheckpointRowError extends StoreCorruptError {
+    rowVerdict;
+    constructor(corrupt, rowVerdict) {
+        super(corrupt.cause, corrupt.message);
+        this.rowVerdict = rowVerdict;
+    }
+}
+export function queueRowGateKind(kind) {
+    if (isGateKind(kind))
+        return kind;
+    recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
+    return undefined;
+}
+export function boundedToolInput(args) {
+    if (args === undefined)
+        return null;
+    const redacted = redactDeep(args);
+    const json = JSON.stringify(redacted);
+    if (json === undefined)
+        return null;
+    if (json.length > MAX_TOOL_INPUT_CHARS)
+        return { truncated: true, bytes: json.length };
+    return redacted;
+}
+export const DECIDED_REPLAY_SCAN_CAP = 8;
+export function approvalDecisionOfWinner(winner, boundCallId) {
+    if (winner === undefined)
+        return null;
+    if (winner.boundCallId !== boundCallId)
+        return null;
+    switch (winner.decision) {
+        case "allow":
+            return "approve";
+        case "deny":
+            return "deny";
+        case "approve":
+        case "reject":
+        case "edit":
+            return null;
+        default: {
+            const unhandled = winner.decision;
+            void unhandled;
+            return null;
+        }
+    }
+}
+function pendingActionToolCallId(body) {
+    if (typeof body !== "object" || body === null)
+        return { readable: false };
+    if ("sourceTaskId" in body)
+        return { readable: false };
+    const rawSource = "sourceSessionId" in body ? body.sourceSessionId : null;
+    if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
+        return { readable: false };
+    const sourceSessionId = typeof rawSource === "string" ? rawSource : null;
+    if (!("pendingAction" in body))
+        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceSessionId };
+    const pa = body.pendingAction;
+    if (typeof pa !== "object" || pa === null)
+        return { readable: false };
+    const kind = "kind" in pa ? pa.kind : null;
+    if (kind !== null && typeof kind !== "string")
+        return { readable: false };
+    if (!("toolCallId" in pa))
+        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceSessionId };
+    const id = pa.toolCallId;
+    if (typeof id !== "string")
+        return { readable: false };
+    if (kind !== "tool_approval")
+        return { readable: false };
+    const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
+    if (bih !== null && typeof bih !== "string")
+        return { readable: false };
+    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceSessionId };
+}
+export function candidateIdentityOf(cp) {
+    if (judgeCheckpointRow(cp).kind === "lacking")
+        return { readable: false };
+    return pendingActionToolCallId(cp);
+}
+export const CTX_CLAIM_REWRITES = ["written", "claim_released", "context_absent"];
+//# sourceMappingURL=checkpoint-store-face.js.map

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

@@ -372,12 +372,6 @@ export declare class FileRunStore implements InProcessClaimFence {
     private releaseClaim;
     /** Drop a run entirely (registry + event log + open fd + on-disk dir) — used by deleteBySession. */
     private dropRun;
-    /**
-     * 一次性迁移 **M6 的 local 腿**(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):把 ≤7.115.x 写下的死亡判决行
-     * (`failed` ∧ 码列空 ∧ 句子是那两句,判据 = `readLegacyHolderDeathCode`)补上机读码,盘上(`run.json` 整份原子替换,同 `persist`)与内存同改。
-     * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 本车道没有滚动升级窗,不需要读侧半场。幂等:第二跑零命中零写盘。
-     */
-    migrateLegacyHolderDeathCodes(): number;
     /**
      * 一次性迁移 **M32 的 local 腿**(执行放置回填;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):有 run 行的会话 id(去重)。
      * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);读内存索引(构造时已从盘上 hydrate),零写。

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

@@ -8,7 +8,7 @@ import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprin
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { joinFromStore, splitForStore } from "./wiring-section-codec.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode, isTerminalRunStatus, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, isTerminalRunStatus, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
@@ -1107,17 +1107,6 @@ export class FileRunStore {
             }
         }
     }
-    migrateLegacyHolderDeathCodes() {
-        let migrated = 0;
-        for (const r of this.runs.values()) {
-            const code = readLegacyHolderDeathCode(r);
-            if (code === null || r.errorCode === code)
-                continue;
-            this.persist({ ...r, errorCode: code });
-            migrated += 1;
-        }
-        return migrated;
-    }
     sessionIdsWithRuns() {
         return new Set([...this.runs.values()].map((r) => r.sessionId));
     }

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

@@ -34,7 +34,7 @@
  */
 import { type SessionStore, type AcquiredSession, type SessionHead, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
 import type { ExecutionPlacementSeat } from "../execution-placement.js";
-import type { ForkToFn } from "./session-fork.js";
+import type { ForkPlacement, ForkToFn } from "./session-fork.js";
 /** acquire 选项形(core 5.48 SessionStore 契约):[ref] placement=受信 spawner 的分区建会话声明。 */
 type AcquireOpts = {
     requireExisting?: boolean;
@@ -86,7 +86,11 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     unpin(sessionId: string): void | Promise<void>;
     noteTaskRun(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     list(): Promise<SessionStoreSummary[]>;
-    fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** `opts.placement`(后台 fork 子代的转录进委派分区)原样交给做这次 fork 的那只店 —— 落不落由那只店的声明判(host 声明了分区就落;瞬态店不声明 ⇒ 忽略),
+     *  本类不判第二次(声明面从 host 逐字转发,引擎据它决定交不交元组)。 */
+    fork(sourceId: string, owner?: string | null, opts?: {
+        placement?: ForkPlacement;
+    }): Promise<string | null>;
     get size(): number;
     dispose(): void | Promise<void>;
 }

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

@@ -191,10 +191,10 @@ export class ForkRoutingSessionStore {
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);
     }
-    async fork(sourceId, owner) {
+    async fork(sourceId, owner, opts) {
         const routed = this.route.get(sourceId);
         const tryFork = async (store, where) => {
-            const forked = (await store.fork?.(sourceId, owner)) ?? null;
+            const forked = (await store.fork?.(sourceId, owner, opts)) ?? null;
             if (forked !== null) {
                 this.remember(sourceId, where);
                 this.remember(forked, where);

package/dist/plugins/imported-layer-root-retirement.d.ts

@@ -16,9 +16,10 @@
  * 一律问**店**:它能叫出名字的每一只桶,判据在桶里判(不在桶外按「谁可能有」预筛)。
  *  · SQL:规则表里的每一只桶(`listRuleBucketOwners`,按 `owner_key` 分页)。不从审批记录推 —— 收编把规则桶整桶改键到新身份、审批史留在旧身份名下,
  *    从记录推出的属主集在收编之后漏掉新桶。
- *  · File:引擎的 File 分区后端**没有**列桶口(桶文件按属主名的单向摘要命名),本步能叫出名字的只有本店导入记录点名过的属主
- *    (`FileRuleApprovalRecordStore.importRecordOwners`;`imported-cc` 只由导入记录派生,记录是只增日志)。**已知缺口(如实)**:引擎的本地数据根收编
- *    把一只桶改名到一个没有任何导入记录点名的身份之后,那只桶本步叫不出、不读 —— 等引擎给 File 分区后端一个列桶口再收。
+ *  · File:本店导入记录点名过的属主(`FileRuleApprovalRecordStore.importRecordOwners`;`imported-cc` 只由导入记录派生,记录是只增日志)∪ 引擎 File 分区后端
+ *    自己列得出名字的属主(`FileDurableRulePartitionProvider.listBucketOwners().owners`:本机属主那只桶,与收编标记点名的身份 —— 收编把桶改名到一个没有任何
+ *    导入记录点名的身份之后,那只桶照样被叫出来、被读)。**已知缺口(如实)**:桶文件按属主名的单向摘要命名,记录与收编标记都叫不出属主的桶本步不读;
+ *    引擎给的「叫不出名字的桶数」(`unnamedBuckets`)只认本机属主那只桶与收编标记、把导入记录点名过的桶也算进去,不是本步的缺数 —— 不报它(报了会把读过的桶说成没读)。
  *
  * ## 写在哪里(一处)
  * 墓碑经**这只桶自己的写面**落(`writerOf(partition).apply({ kind: "tighten-delete" })`,引擎的写面契约)—— SQL 两孪生走 `SqlDurableRulePartition` 的那只
@@ -30,10 +31,11 @@
  * 列桶 / 解析桶 / 读桶 / 取点 / 写面**抛** ⇒ 原样抛:起服拒,收据账里已提交的墓碑随拒因交出(与本段其余各步同一条路)。例外两条,都由店的判官按抛出物的**类**判(不按文案):
  * 取点时店说这只桶**在写它的那一步里没了**(`source.isVanishedBucket`:另一只副本删桶恰落在这一窗)⇒ 无可退役、点名跳过 `vanished`(桶都没了,它什么都不放行);
  * 另一条是解析桶(属主 → 分区)或读桶时**店的唯一判官整桶拒**了
- * 这只桶(解析与读同一条律、同一只判官;`source.isWholeBucketRefusal`:确定性判决,引擎读侧对它同样整桶拒、它什么都不放行;SQL = 读腿真往外交的那两类 —— 判官四道的拒与某只 JSON 列的体读不出)
- * ⇒ 点名跳过 `bucket_unreadable`,接着读下一只桶(一只读不出的桶不挡别的桶,也不挡起服);一次读失败(连接 / 超时)
- * 证明不了以后也读不出,所以它**不**归这一类 —— 跳过它就是让那几行在读恢复之后照旧放行。File 店没有这种判决证据(引擎的 File 分区对损坏与 I/O 失败抛同一种错,
- * 解析时读收编标记也是:一次 EIO 与一份坏标记同一种错)⇒ 那一侧解析 / 读桶抛一律起服拒。另两种店**答了**却做不了的(没有写面或写面拒 / 并发争不过)⇒ 点名跳过,下一次起服再试,其间那几行照旧放行,每次起服都点名。
+ * 这只桶(解析与读同一条律、同一只判官;`source.isWholeBucketRefusal`:确定性判决,引擎读侧对它同样整桶拒、它什么都不放行;SQL = 读腿真往外交的那两类 —— 判官四道的拒与某只 JSON 列的体读不出;
+ * File = 引擎 File 分区的拒码 `permission_rules.bucket_damaged`〔同一份字节每次读都同样拒〕)
+ * ⇒ 点名跳过 `bucket_unreadable`,接着读下一只桶(一只读不出的桶不挡别的桶,也不挡起服);一次读失败(连接 / 超时;File 的拒码 `permission_rules.bucket_unreadable`,
+ * 带系统错名 `errno`)证明不了以后也读不出,所以它**不**归这一类 —— 跳过它就是让那几行在读恢复之后照旧放行。File 解析时读收编标记的拒(标记自己的拒,不带桶拒码)同样不归这一类 ⇒ 起服拒。
+ * 另两种店**答了**却做不了的(没有写面或写面拒 / 并发争不过)⇒ 点名跳过,下一次起服再试,其间那几行照旧放行,每次起服都点名。
  */
 import { type DurableRulePartitionProvider, type PersistedRule, type RuleAdd, type RuleOwner } from "@sema-agent/core";
 /** 一只被退役的导入 add 所在的行(一行一条读数)。**不带规则正文**(与 M11 同一条纪律:规则正文不出店)—— 桶键 + 工具名足够让运维去列举面对上它。 */
@@ -77,6 +79,6 @@ export interface ImportedLayerRootRetirementSource {
 }
 /** 判据(引擎 §5.14 那一句,逐字):这一行里该退役的 add;不选 ⇒ 空。 */
 export declare function importedLayerRootAddsOf(row: PersistedRule): readonly RuleAdd[];
-/** 跑一遍:读记录点名的每只桶(按桶键去重),退役判据选中的 add。读数随每次提交记进 `into`。 */
+/** 跑一遍:读店叫得出名字的每只桶(`candidateOwners()`,见头注「读哪些桶」;两源有重 ⇒ 按桶键去重),退役判据选中的 add。读数随每次提交记进 `into`。 */
 export declare function retireImportedLayerRootAllows(source: ImportedLayerRootRetirementSource, into: ImportedLayerRootReadings): Promise<void>;
 //# sourceMappingURL=imported-layer-root-retirement.d.ts.map

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

@@ -1,5 +1,5 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ExecutionOutcomeRecordWord, type GateOutcome, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
-import { type CheckpointAskCandidate, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-sql.js";
+import { type CheckpointAskCandidate, type CtxClaimRewrite, type CtxRowRewrite, type CtxRowsRewrite, type DecidedApprovalRecord, type PendingCheckpoint, type PendingRowBinding } from "./checkpoint-store-face.js";
 import { type FencedRun, type InProcessClaimFence } from "./store-contracts.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
 export interface LocalCheckpointStoreOptions {
@@ -221,7 +221,7 @@ export declare class LocalCheckpointStore {
      */
     rewriteCtxWhileClaimed(sessionId: string, taskId: string, ctx: SealedCheckpointCtx, legHolds: (run: FencedRun) => boolean): Promise<CtxClaimRewrite>;
     /**
-     * 🔴 **一次性迁移的 ctx 行改写店腿**(local 孪生;`checkpoint-store-sql.ts` `CheckpointCtxRowsRewriter`,判词与 SQL 孪生 `rewriteCtxRows` 逐条同):
+     * 🔴 **一次性迁移的 ctx 行改写店腿**(local 孪生;`checkpoint-store-face.ts` `CheckpointCtxRowsRewriter`,判词与 SQL 孪生 `rewriteCtxRows` 逐条同):
      * 逐档读(信封经读腿**同一只**判形 —— 读不出 ⇒ 计数、跳过、**不删**),`rewrite` 交回新体 ⇒ 信封原样(`sessionId` / `updatedAt` 不动:收割按 `updatedAt` 判)
      * 只换 `ctx`,经写腿同一只形闸、同一只原子写落回原档。封签绑的是信封里的 `sessionId`(与 `getCtx` 认行的那一格同一个)。
      * 数据根独占 + 起服在任何读写者之前跑 ⇒ 本车道没有并发写者,不需要 CAS;没有一行装不下这回事(`tooLarge` 恒 0)。

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

@@ -6,7 +6,8 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { CHECKPOINT_LIST_LIMITS, FileCheckpointStore, atomicWriteFile, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
-import { approvalDecisionOfWinner, approvalPayloadFingerprint, boundedRuleOffers, boundedToolInput, candidateIdentityOf, pendingRowPrecedes, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
+import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
+import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, pendingRowPrecedes, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-face.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
 import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, readStringArrayColumn } from "./sql-json-column.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";

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

@@ -2,13 +2,13 @@ import { FileSessionRepo, type AcquiredSession, type PlacedSessionRow, type Sess
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { z } from "zod";
 import { StoreBootRefusalError, type SessionRunClaimSource, type SessionRunRollupSource, type SessionSummary } from "./store-contracts.js";
-import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
 import { type LocalArchiveKeptStamped, type LocalArchiveUnreadable } from "./one-time-migrations.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type ExecutionLane } from "../execution-lane-caps.js";
 import { type ExecutionPlacementSeat, type LocalPlacementBackfillSeat } from "../execution-placement.js";
-import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.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";
@@ -584,6 +584,17 @@ export declare class LocalSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** {@link listSessions} 带每行的住客(属主 + 化身那一格,与行同一刻读)—— `OwnerAwareSessionStore.listSessionRows`;化身不进行本身。 */
+    listSessionRows(opts: {
+        owner?: string;
+        includeUnowned?: boolean;
+        cursor?: {
+            lastActivityAt: string;
+            sessionId: string;
+        };
+        limit: number;
+        q?: string;
+    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
     /** 列表行要读的边档一次装齐(lastActivity / 标题 / 置顶 / 会话元数据);各自记忆化,只有第一次真读盘。 */
     private loadRowSidecars;
     /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `headOf(id)?.owner` 同答;列表不补铸缺的格,`headOf` 在第一次读时补)。 */
@@ -611,8 +622,11 @@ export declare class LocalSessionStore implements SessionStore {
      *  修前把参数原样写进新格:`fork(owned, null)` 铸出一份匿名的有主历史。
      *  拷**已提交**的叶(契约):在飞的 assistant 轮不进孩子 —— 分叉点只有引擎那一只判官(core 7.55.0 起包根导出的 `settledForkOptions`),本店把唤醒出来的源会话交给它、
      *  把它的答案原样交给引擎自己的 `repo.fork`(与 core 内存店 `TtlSessionStore.fork` 同一条调用链);两只 SQL 孪生同读它(`session-fork.ts`)。钉:
-     *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。 */
-    fork(sourceId: string, owner?: string | null): Promise<string | null>;
+     *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。
+     *  `opts.placement`(后台 fork 子代的转录)= fork 进委派分区:见 {@link forkToHeld} 的建行点。 */
+    fork(sourceId: string, owner?: string | null, opts?: {
+        placement?: ForkPlacement;
+    }): Promise<string | null>;
     /**
      * **fork 续写的店契约**(local 一形;规则与结果闭集在 `session-fork.ts`,SQL 孪生同义):
      *  · **两把写锁**:按 id 字典序依次取源与目标的写锁(锁不可重入;同 id 只取一把)—— 同 id 的每个写者(删除 / 登记 / 导入 / 按 id 首建 / 别的 fork)都在目标那把锁里,
@@ -622,11 +636,20 @@ export declare class LocalSessionStore implements SessionStore {
      *    (不交属主 —— 引擎仓匿名;子存档的属主格抄自源存档,源匿名 ⇒ 子匿名)。
      *    崩在两步之间 = fork 创建的格而存档不在 = `forking`:普通取用一律 {@link SessionForkInProgressError};同键重试在两把锁内补拷存档、答 `replayed`。
      *    拷贝抛错(不是崩溃)⇒ 撤掉刚写的目标格再上抛(撤不掉 ⇒ 留下的就是 `forking`,与崩在中间同形);
-     *  · **撞已在** ⇒ 按目标格的属主与 fork 键分类({@link classifyForkTarget})。
+     *  · **fork 进委派分区**(`target.placement`,只在声明了分区的店落;没声明 ⇒ 忽略、照常 fork):元组随引擎 `repo.fork` 落进子存档行头 —— 与带 placement 的建行
+     *    ({@link createPlacedHeld})同一处、同一形(存档行头,first-write 不可变,`placedAt` 由 repo 铸);行的属主仍是上面那一读(元组不带属主)。建后读回准入同
+     *    `createPlacedHeld`(镜像方向:repo 交回的行没带这一组元组 ⇒ `placement_refused`):拒了就删掉刚拷的存档、再撤目标格(**存档先删、格后撤** —— 崩在中间留下的是
+     *    「格在而存档不在」的惰性残格;反过来会留下一份没有属主格的有主历史拷贝),删不掉 ⇒ 两只故障同句点名、出路随句;
+     *  · **撞已在** ⇒ 按目标格的属主与 fork 键分类({@link classifyForkTarget});placed 目标永不带键(型面互斥)⇒ 永不 `replayed`。
      */
     forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
     /** {@link forkTo} 的锁内一形(调用方持源与目标两把写锁)。 */
     private forkToHeld;
+    /**
+     * fork 进委派分区的建后读回准入(锁内,调用方持目标的写锁、刚拷完存档):判据 = 引擎那一只 `admitSessionPlacement`(镜像方向,读 repo 交回的那一份行头元组,零额外读),
+     * 与 {@link createPlacedHeld} 的读回同一判。拒 ⇒ 存档先删、目标格后撤(见 {@link forkToHeld} 注),再原样上抛那只 `placement_refused`;删不掉 ⇒ 同码、两只故障同句点名。
+     */
+    private admitForkedPlacement;
     /** 2c session-sync — EXPORT a session's full durable entry log (core `SessionRepo.exportEntries`; the
      *  in-memory/file repo holds the whole log so there is no floor to bypass). null if the source is unknown / the
      *  underlying repo lacks the optional seam. The owner is NOT exported — import re-stamps it. */

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

@@ -1106,6 +1106,9 @@ export class LocalSessionStore {
         });
     }
     async listSessions(opts) {
+        return (await this.listSessionRows(opts)).map((a) => a.row);
+    }
+    async listSessionRows(opts) {
         await this.loadRowSidecars();
         const rows = [];
         for (const header of await this.rowHeaders())
@@ -1116,16 +1119,18 @@ export class LocalSessionStore {
             const owner = this.ownerCellOf(row.sessionId);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
-            all.push(await this.summaryOf(row, rollups));
+            const meta = this.metaCellOf(row.sessionId);
+            const incarnation = meta === undefined ? undefined : incarnationFromCell(row.sessionId, meta.incarnation, "absent");
+            all.push({ row: await this.summaryOf(row, rollups), occupant: { owner, incarnation } });
         }
         const qlc = opts.q?.toLowerCase();
-        const filtered = qlc ? all.filter((r) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
-        filtered.sort((a, b) => a.lastActivityAt !== b.lastActivityAt
+        const filtered = qlc ? all.filter(({ row: r }) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
+        filtered.sort(({ row: a }, { row: b }) => a.lastActivityAt !== b.lastActivityAt
             ? (a.lastActivityAt < b.lastActivityAt ? 1 : -1)
             : (a.sessionId < b.sessionId ? 1 : -1));
         const c = opts.cursor;
         const after = c
-            ? filtered.filter((r) => r.lastActivityAt < c.lastActivityAt || (r.lastActivityAt === c.lastActivityAt && r.sessionId < c.sessionId))
+            ? filtered.filter(({ row: r }) => r.lastActivityAt < c.lastActivityAt || (r.lastActivityAt === c.lastActivityAt && r.sessionId < c.sessionId))
             : filtered;
         return after.slice(0, opts.limit);
     }
@@ -1189,8 +1194,8 @@ export class LocalSessionStore {
             return null;
         }
     }
-    async fork(sourceId, owner) {
-        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    async fork(sourceId, owner, opts) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
     async forkTo(sourceId, owner, target) {
         await this.meta.ensureLoaded();
@@ -1215,20 +1220,24 @@ export class LocalSessionStore {
         const forkOwner = forkOwnerOf(owner, this.metaCellOf(sourceId)?.owner);
         const existing = this.metaCellOf(target.id);
         const targetArchived = await this.existsInRepo(target.id);
-        const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id });
+        const placement = this.placements !== undefined ? target.placement : undefined;
+        const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id, ...(placement !== undefined ? { placement } : {}) });
         if (existing === undefined && !targetArchived) {
             const created = await this.writeMeta(target.id, (before) => before !== undefined
                 ? undefined
                 : { incarnation: mintSessionIncarnation(), ...(forkOwner !== undefined ? { owner: forkOwner } : {}), ...(target.key !== undefined ? { forkKey: target.key } : {}), createdAt: rowBornNow(), forkedFrom: sourceId });
             if (!created)
                 throw new SessionError("storage", `LocalSessionStore: fork target ${target.id} gained a session-meta cell under its own write lock — refusing to guess`);
+            let forked;
             try {
-                await copy();
+                forked = await copy();
             }
             catch (err) {
                 await this.withdrawCreatedCell(target.id, err, (cause, drop) => `LocalSessionStore: fork into ${target.id} failed while copying (${cause}) and its target cell could not be withdrawn (${drop}) — the target stays in the fork-in-progress state; retry the same fork or delete the session`);
                 throw err;
             }
+            if (placement !== undefined)
+                await this.admitForkedPlacement(target.id, forked, placement);
             return { outcome: "created", id: target.id };
         }
         const out = classifyForkTarget(target, { owner: existing?.owner, forkKey: existing?.forkKey }, forkOwner);
@@ -1236,6 +1245,21 @@ export class LocalSessionStore {
             await copy();
         return out;
     }
+    async admitForkedPlacement(sessionId, forked, placement) {
+        try {
+            admitSessionPlacement(sessionId, (await forked.getMetadata()).placement, { placement }, placementCapabilityOf(this));
+        }
+        catch (refusal) {
+            try {
+                await this.repo.delete({ id: sessionId, createdAt: "" });
+            }
+            catch (left) {
+                throw new SessionError("placement_refused", `${refusal instanceof Error ? refusal.message : String(refusal)} — and the copy ${sessionId} this fork created could not be removed (${left instanceof Error ? left.message : String(left)}); delete the session by id`, refusal instanceof Error ? refusal : undefined);
+            }
+            await this.withdrawCreatedCell(sessionId, refusal, (cause, drop) => `LocalSessionStore: a placed fork into ${sessionId} was refused (${cause}); its copy was removed but its session-meta cell could not be withdrawn (${drop}) — the cell stays on disk, inert; delete the session to clear it`);
+            throw refusal;
+        }
+    }
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
             return null;

package/dist/plugins/memory-engine-pg.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder, PgQueryFn } from "./pg-query.js";
+import { type SqlApplyOpts } from "./memory-engine-sql-apply.js";
 import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 /** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
@@ -54,6 +55,8 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
     private readonly history?;
     /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     private historyRowsLost;
+    /** 交给共享驱动器的读口 / 写口 / history 冲刷(构造末尾铸一次)。 */
+    private readonly leg;
     /** [ref] rung indicator — same semantics as PgMemoryStore.vectorMode. */
     get vectorMode(): "native" | "portable" | "lexical";
     constructor(query: PgQueryFn, opts?: PgMemoryEngineBackendOptions);
@@ -70,12 +73,32 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
         limit?: number;
         exposureBands?: boolean;
     }): Promise<ScoredMemoryEntry[]>;
-    applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
-    private applyOne;
-    /** When the conditional write returns zero rows (a write landed inside the
-     *  SELECT→write window), the report's `currentRev` must be the rev NOW — re-reporting the pre-race
-     *  SELECT value could claim `baseRev === currentRev` alongside a "rev mismatch" reason. */
-    private freshRev;
+    /** core 落点问询协议的能力位:`applyPatches` 兑现 `opts.admit` / `opts.confirm`(读法见 `memory-engine-sql-apply.ts` 头注)。 */
+    readonly admitsLandings: true;
+    /** 判与驱动器只在 `memory-engine-sql-apply.ts` 一处(两只 SQL 腿共用);本腿只供读口、PG 方言写口(写语句绑定计划的投影)与 history 冲刷。
+     *  `opts.anchoredRoot` 是带目录的后端的事,本腿没有目录 ⇒ 不读(core 契约原文:a backend without a directory ignores it)。 */
+    applyPatches(patches: readonly NotePatch[], opts?: SqlApplyOpts): Promise<PatchReport>;
+    private rowOf;
+    private idsAt;
+    /** 一个 patch 第一次要写之前算一次它的向量参数(撞名 / 被挪重试复用,不重调 embedder —— 改前 add 也只在后缀循环外算一次)。
+     *  haystack 用调用方给的原形(add 的原名,不是撞名后缀),与改前同。 */
+    private prepareWrite;
+    /** 写不落之后的现读:这个 id 的行此刻的 rev 与投影(没了 ⇒ undefined)。 */
+    private freshRow;
+    /**
+     * add:`INSERT … ON CONFLICT (id)`,冲突靶 = 仅主键。计划时这个 id 已有行 ⇒ `DO UPDATE … WHERE` 行仍在计划的投影上(同 scope re-add 的幂等
+     * 覆盖;行被挪走就不覆盖 —— 被挪去的那个拼写没问过);计划时没有 ⇒ `DO NOTHING`(同 id 的行在判与写之间被别的副本插入就不覆盖)。
+     * 两种「不覆盖」都让 `RETURNING` 交零行 ⇒ 现读确认后答 `moved`(驱动器按现状重判)。剩下能撞的唯一键只有 `(scope, slug)` ⇒ `slug-taken`。
+     */
+    private writeAdd;
+    /** update:条件 = 判过的 rev **且**判过的投影(rev 是内容哈希、不含 scope / slug)。零行 ⇒ 现读:内容未变而投影变了 = `moved`;其余 =
+     *  CAS 冲突,currentRev 报现值(行没了 ⇒ 判时的值)。 */
+    private writeUpdate;
+    /** delete:条件同 update。 */
+    private writeDelete;
+    /** BEST-EFFORT history append(见 PgMemoryEngineBackendOptions.history 的如实取舍):entry 写已提交,审计行追加失败不许让报告失败 ——
+     *  吞 + warn,永不抛;appendHistory 按 (id, rev) 幂等,调用方重试安全。 */
+    private appendHistory;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
 }