@sema-agent/server 7.117.0 → 7.119.0

package/dist/parked-decide.js

@@ -1,4 +1,4 @@
-import { readRunParks } from "./orchestration/workflow-agent-session-index.js";
+import { routeWorkflowPark } from "./orchestration/workflow-agent-session-index.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { backgroundScopesForCheckpointScope, decodeCheckpointScope } from "./security.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
@@ -20,19 +20,30 @@ export async function findParkOrigin(sources, cp) {
     if (index === undefined || runStore === undefined)
         return undefined;
     try {
-        const row = await index.findByAgentSession(cp.sessionId);
-        if (row === null)
+        const pointers = await index.listByAgentSession(cp.sessionId);
+        if (pointers.length === 0)
             return undefined;
-        const run = await runStore.get(row.runId);
-        if (run === null)
-            return undefined;
-        const parks = readRunParks(run);
-        if (parks === undefined)
-            return { kind: "workflow_parks_unreadable", runId: row.runId, run };
-        const park = parks.find((p) => p.sessionId === cp.sessionId && p.token === cp.token);
-        if (park === undefined)
-            return undefined;
-        return { kind: "workflow", runId: row.runId, run, park };
+        const runs = [];
+        for (const runId of new Set(pointers.map((p) => p.runId))) {
+            const run = await runStore.get(runId);
+            if (run !== null)
+                runs.push(run);
+        }
+        const route = routeWorkflowPark(cp.sessionId, runs);
+        switch (route.kind) {
+            case "held":
+                return route.park.token === cp.token ? { kind: "workflow", runId: route.runId, run: route.run, park: route.park } : undefined;
+            case "forked":
+                return { kind: "workflow_park_forked", runIds: route.runIds };
+            case "unproven":
+                return { kind: "workflow_parks_unreadable", runId: route.runId, run: route.run, cause: route.cause, ...(route.readableHolderRunId !== undefined ? { readableHolderRunId: route.readableHolderRunId } : {}) };
+            case "none":
+                return undefined;
+            default: {
+                const unhandled = route;
+                throw new Error(`unhandled workflow park route: ${JSON.stringify(unhandled)}`);
+            }
+        }
     }
     catch (e) {
         quiet(sources.warn, "workflow_park_probe_failed", { error: e instanceof Error ? e.message : String(e) });
@@ -90,12 +101,39 @@ export function buildParkedResumeOutcome(req) {
     };
 }
 export function denyWorkflowParksUnreadable(origin) {
+    switch (origin.cause) {
+        case "older_engine":
+            return {
+                status: 409,
+                body: {
+                    error: "this decision cannot be matched to the pending step it belongs to: the run's record was written by an earlier engine version, which did not record which run is waiting on each pending step — and that record is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resume the run itself instead — `Workflow({resumeFromRunId})` with the runId below — and once the resumed run is waiting on this step again it records itself as the one waiting, after which deciding here works normally. Only if the engine also refuses that resume is the run truly unrecoverable",
+                    errorCode: "decide.workflow_parks_unreadable",
+                    runId: origin.runId,
+                },
+            };
+        case "unreadable":
+            return {
+                status: 409,
+                body: {
+                    error: "this decision cannot be matched to the pending step it belongs to: this run's record cannot be read (the list of pending steps the run owns is damaged: one of its entries is malformed, or it is not a list at all) — and that list is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resuming does not clear this: the damaged record keeps naming this step whatever runs after it, so the decision stays undeliverable until whoever operates this deployment repairs that record (the runId below); after that, deciding here works normally. When the response also carries readableHolderRunId, that run's record is readable and is the latest one waiting on this step — it is where the work can be carried on, but the damaged record above still keeps this decision from being delivered until that record is fixed",
+                    errorCode: "decide.workflow_parks_unreadable",
+                    runId: origin.runId,
+                    ...(origin.readableHolderRunId !== undefined ? { readableHolderRunId: origin.readableHolderRunId } : {}),
+                },
+            };
+        default: {
+            const unhandled = origin.cause;
+            throw new Error(`unhandled workflow parks-unreadable cause: ${String(unhandled)}`);
+        }
+    }
+}
+export function denyWorkflowParkForked(origin) {
     return {
         status: 409,
         body: {
-            error: "this decision cannot be matched to the pending step it belongs to: this run's record was written by an older engine, or one of its entries is damaged, so it no longer says which pending steps the run owns — and that list is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resume the run itself instead — `Workflow({resumeFromRunId})` with the runId below — and the engine rebuilds that list from its own records as it admits the resume, after which deciding here works normally. Only if the engine also refuses that resume is the run truly unrecoverable",
-            errorCode: "decide.workflow_parks_unreadable",
-            runId: origin.runId,
+            error: "this decision cannot be delivered: the same run was resumed more than once and every resumed copy listed in runIds is waiting on this same step, so there is no single run to hand the decision to. Nothing was delivered and the approval card stays pending. Resume one of the runs listed in runIds; once that run is waiting on this step again, deciding here works normally",
+            errorCode: "decide.workflow_park_forked",
+            runIds: [...origin.runIds],
         },
     };
 }

package/dist/permission-rule-vocab.d.ts

@@ -10,12 +10,13 @@ import type { RuleApprovalRecord, RuleBehavior } from "@sema-agent/core";
  */
 export declare function isPersistedRuleTool(name: string): boolean;
 /**
- * `PersistedRuleMatch` 五员(core 顶注逐字):`exact` / `prefix`(历史 colon-star,永久兼容读、复合前缀形的
+ * `PersistedRuleMatch` 七员(core 顶注逐字):`exact` / `prefix`(历史 colon-star,永久兼容读、复合前缀形的
  * 唯一拼写)/ `wildcard`([ref] 尾 space-star,单命令体上与 prefix **同一谓词**,建议面自此铸它)/
  * `subpath`(Read 目录形,永不容纳任何命令)/ `path`(core 7.9.0 [ref]:路径族 deny/ask/allow 的模式文法
- * —— `//abs`、`~/`、`/root-relative`、cwd 相对,段内 `*`、跨段 `**`)。
+ * —— `//abs`、`~/`、`/root-relative`、cwd 相对,段内 `*`、跨段 `**`)/ `name` / `name_prefix`(core 7.43.0 #1318:`Skill` 的名字文法 ——
+ * `Skill(<名>)` 精确、`Skill(<前缀>:*)` 名字前缀、无词界;技能卡的建议行 `match: "name"`)。
  */
-export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path"];
+export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix"];
 /**
  * S-511 —— `RuleBehavior` 每一员在**无同意仪式的直接写口**(`POST /v1/rules`)上的逐员表态。
  *

package/dist/permission-rule-vocab.js

@@ -2,7 +2,7 @@ import { ruleToolGrammarOf } from "@sema-agent/core";
 export function isPersistedRuleTool(name) {
     return ruleToolGrammarOf(name) !== undefined;
 }
-export const PERSISTED_RULE_MATCHES = ["exact", "prefix", "wildcard", "subpath", "path"];
+export const PERSISTED_RULE_MATCHES = ["exact", "prefix", "wildcard", "subpath", "path", "name", "name_prefix"];
 const MATCHES_PIN = true;
 void MATCHES_PIN;
 export const DIRECT_RULE_WRITE_ADMITS = {

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -82,8 +82,8 @@ export interface AskRow {
     decisionNote: string | null;
     /**
      * 🔴 S-558(#1016 的持久半场)—— 这条决议的**结算来源**:`null` = 一个人答的(= 缺席律,core 对
-     * 不带这一格的 outcome 逐字按 `"human"` 读),非 null = 宿主自报的那个词(今天 wire 上只开
-     * `"policy"`,词表属主恒是 core —— 见 {@link HostSettledBy})。
+     * 不带这一格的 outcome 逐字按 `"human"` 读),非 null = 宿主自报的那个词(S-1154 起写进来的只有决定体出处位
+     * `decidedBy:"policy"` 经 `liveSettledBy` 映射来的 `"policy"`,allow 与 deny 两向都写;词表属主恒是 core —— 见 {@link HostSettledBy})。
      *
      * **为什么必须是行上的一格**(病灶,7.93.3 合并树 codex ① 验真):`settledBy` 此前只到达**当次**回决的
      * 即时回调,行上不留痕 ⇒ 重放 / 再入 / 同 askId 的兄弟等待者 / 歧义提交恢复读回的是裸 `false`,
@@ -230,8 +230,8 @@ export interface DecideAskInput {
      * 🔴 S-558:本次回决的**结算来源**,与决议同一条 UPDATE 落列 `settled_by`(语义/两态读法/为什么是
      * 自己一列,全在 {@link AskRow.settledBy})。缺席 ⇒ 列 NULL ⇒ 读回是「一个人答的」。
      *
-     * 店**不判词**(词表属主是 core):写什么存什么。店只判**形** —— `assertDecideSettledBy` 的两条
-     * (长度 ≤ 列宽、只与 `deny` 同行),理由见那只门的顶注;三 twin 同判。
+     * 店**不判词**(词表属主是 core):写什么存什么。店只判**形** —— `assertDecideSettledBy` 的那一条
+     * (长度 ≤ 列宽;S-1154 起 approve 行也可以带来源位),理由见那只门的顶注;三 twin 同判。
      */
     settledBy?: HostSettledBy;
     /** [ref]:ctrl+g 编辑实参,与决议同一条 UPDATE 落列(语义三态见 {@link AskRow.updatedInput})。
@@ -270,26 +270,23 @@ export declare function assertIntegralEpochMs(field: string, value: number): voi
 export declare function assertIdempotencyKeyShape(key: string): void;
 /** `settled_by` 列宽 = 这一格的唯一尺(两方言 DDL 与下面的形门读同一个常量,不手抄第二份)。 */
 export declare const MAX_SETTLED_BY_CHARS = 16;
-/** `settled_by` 这一列装得下这个词吗(1..{@link MAX_SETTLED_BY_CHARS})—— 形门 ① 的**谓词本身**,店门口
- *  ({@link assertDecideSettledBy})与耐久 ask 回决口的 CAS 前体门(S-843:确定的体形错误拒成 400,不落进提交歧义臂)
- *  读同一只,尺不抄第二份。 */
+/** `settled_by` 这一列装得下这个词吗(1..{@link MAX_SETTLED_BY_CHARS})—— 店门口形门({@link assertDecideSettledBy})的**谓词本身**。
+ *  S-1154 起决定口不再读它:wire 上的出处位是闭集(`host-decision.ts` 的 `APPROVAL_DECIDED_BY`),映射到这一列的词恒在尺内。 */
 export declare function settledByFitsColumn(v: string): boolean;
 /**
  * S-558 的**入店卫生门**(三 twin 同判,与 {@link assertIdempotencyKeyShape} / {@link assertIntegralEpochMs} 同族)。
- * 判的是**形**,不是**词** —— 词表属主恒是 core(`resolveAsk` 对自报词表外的值是响亮 fail-closed deny),
- * 本层一个词都不认识。两条:
+ * 判的是**形**,不是**词** —— 词表属主恒是 core,本层一个词都不认识。一条:
  *
- * ① **长度 ≤ 列宽**。`settled_by` 是 `VARCHAR(16)` 的闭集词列,而值来自 wire(两条回决腿只证得出「它是个串」)。
- *    不拦的话:MySQL 协议侧非严格模式**静默截断**、PG 侧直接报错 —— 同一份调用方代码在两个后端拿到两种
- *    答案(`assertIdempotencyKeyShape` 的 PAD SPACE 论证逐字同源),而**被截断过的词与原词是两个词**:
- *    一条决议的来源在库里变成了另一件事。空串同拒(core 那边它不是词,存进去只会读成一个假的「非人」)。
- * ② **只与 `deny` 同行**。core 的契约明写两个非人词只在 `allow:false` 上合法(`{allow:true,settledBy}` 是
- *    fail-closed 拒),两条回决腿也都在**裁决之前**照此响亮拒(`tool-approval.ts` 的
- *    `SETTLED_BY_DENY_ONLY`,两腿共用一份文案)。在店门口再执行一次不是「第二个判官」:判的不是词而是**这一对列能不能共存**。
- *    收益是结构性的 —— 「approve 行带来源位」从此在写面不可表示,读回铸点(`outcomeOfDecidedRow`)的 allow 臂
- *    因此**证得出**不会丢掉任何真事实,而不是靠记性。
+ * **长度 ≤ 列宽**。`settled_by` 是 `VARCHAR(16)` 的闭集词列。不拦的话:MySQL 协议侧非严格模式**静默截断**、PG 侧直接
+ * 报错 —— 同一份调用方代码在两个后端拿到两种答案(`assertIdempotencyKeyShape` 的 PAD SPACE 论证逐字同源),而**被截断过的
+ * 词与原词是两个词**:一条决议的来源在库里变成了另一件事。空串同拒(core 那边它不是词,存进去只会读成一个假的「非人」)。
+ *
+ * 🔴 S-1154:此前的第二条「只与 `deny` 同行」**删了** —— 它的前提(「只有人能批准一个要执行的动作,core 对 `{allow:true,settledBy}`
+ * 一律 fail-closed 拒」)自 core 7.39.0 起不成立:策略的放行铸 `policy_allowed`,决定体的出处位 `decidedBy:"policy"` 在 allow 与 deny
+ * 上都落这一列,approve 行带来源位是一条合法的行(读回铸点 `outcomeOfDecidedRow` 两向都读它)。今天写这一列的只有两条路:决定口经
+ * `liveSettledBy` 映射来的 `"policy"`,与 `claimTerminal(refuse)` 的 {@link POLICY_REFUSAL_DECISION} —— 都是 core 在两向上都收的词。
  */
-export declare function assertDecideSettledBy(decision: Pick<DecideAskInput, "decision" | "settledBy">): void;
+export declare function assertDecideSettledBy(decision: Pick<DecideAskInput, "settledBy">): void;
 /**
  * [ref] 车3 刀 3b(§14.2 遗留记账):两条**重放读口**被调用方的 deadline 掐断时抛的具名错误。
  *
@@ -324,7 +321,7 @@ export type AskTerminalClaimIntent = "expire" | "cancel" | "refuse";
  * `refuse` 意图落行的决议(NP-2)—— **部署政策拒**:deny + 结算来源 `policy`。来源词的型取 core 的 `HostSettledBy`
  * (core 改词 / 退词 ⇒ 这里 tsc 红);协调器交给 core 的那一只(`tool-approval.ts` 的 `UnattendedPolicyRefusal`)读的是
  * **同一个**常量,于是「行上记的来源」与「首判交出去的来源」在构造上是一个词。三 twin 落行前都过 {@link assertDecideSettledBy}
- * (settled_by 的唯一形门:长度 ≤ 列宽、只与 deny 同行)。
+ * (settled_by 的唯一形门:长度 ≤ 列宽)。
  */
 export declare const POLICY_REFUSAL_DECISION: {
     readonly decision: "deny";

package/dist/plugins/approval-ask-store-sql.js

@@ -24,9 +24,6 @@ export function assertDecideSettledBy(decision) {
     if (!settledByFitsColumn(v)) {
         throw new Error(`invalid settledBy: the settlement source is one word from the engine's closed set and lands in a VARCHAR(${MAX_SETTLED_BY_CHARS}) column — must be 1-${MAX_SETTLED_BY_CHARS} chars (got ${JSON.stringify(v.slice(0, 32))}${v.length > 32 ? "…" : ""}, length ${v.length})`);
     }
-    if (decision.decision !== "deny") {
-        throw new Error(`invalid settledBy: a settlement source is only representable on a deny row (got decision="${decision.decision}") — only a person approves an action that EXECUTES, so an approve row carrying a non-human settlement source is a row no replay could honestly hand back to the engine`);
-    }
 }
 export class ApprovalAskReadAbortedError extends Error {
     constructor(where) {

package/dist/plugins/approval-exemption-store.d.ts

@@ -1,6 +1,10 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { Logger } from "../observability/logger.js";
+/** The server's own audit event for a question a row answered without asking anyone — one name for both reading positions
+ *  (the list gate: field `seat: "deployment_list"`; the approval seat: `seat: "approval_seat"`). Not a settlement record: nobody
+ *  was asked, so it names no human / person / policy and carries no `remember`. */
+export declare const APPROVAL_EXEMPTED_EVENT = "approval_exempted";
 export interface ApprovalExemptionRow {
     toolName: string;
     grantedBy: string | null;

package/dist/plugins/approval-exemption-store.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { AppendLog, ensureDir, sanitizePathComponent } from "@sema-agent/core";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
+export const APPROVAL_EXEMPTED_EVENT = "approval_exempted";
 export class TiDBApprovalExemptionStore {
     pool;
     constructor(pool) {

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

@@ -108,6 +108,15 @@ export interface MinioBlobBackendConfig {
  *  同步路径,SendUserFile 工具调用永不返回。120s 对慢链路 ~64MiB 单 PUT/GET 仍宽裕(presignTtlSec
  *  注释同口径),远小于病形。send-user-file 与 leader/diffup 同 import 此常量。 */
 export declare const OBJECT_STORE_IO_TIMEOUT_MS = 120000;
+/** 桶存在性探针的结果(闭集):`present` = 列举 2xx;`missing` = 404 且体里是 `NoSuchBucket`(**唯一**能证明缺桶的形);其余一切 = `unknown`(带一句原因,不回显体)。 */
+export type BucketProbe = {
+    readonly state: "present";
+} | {
+    readonly state: "missing";
+} | {
+    readonly state: "unknown";
+    readonly detail: string;
+};
 export declare class MinioBlobBackend implements BlobBackend {
     private readonly cfg;
     private readonly keyPrefix;
@@ -160,6 +169,10 @@ export declare class MinioBlobBackend implements BlobBackend {
     headObject(hash: string): Promise<{
         lastModifiedMs: number;
     } | undefined>;
+    /** 桶存在性探针(boot 期核**一次**,`plugins/snapshot-bucket-presence.ts`):presigned ListObjectsV2 `max-keys=1`(与 sweep 的列举同一条签名路径,零新依赖)。
+     *  🔴 只有「404 且体里是 `NoSuchBucket`」才算缺桶;网络不通 / 403(凭据不能列举 ≠ 桶不在)/ 5xx / 没有 NoSuchBucket 的 404(代理 / 路径错)
+     *  都**证明不了**缺桶 ⇒ `unknown`,调用方不拒启、只报一次。总函数:不抛。`timeoutMs`:boot 期调用方给的单次上界(黑洞端点不许把起服拖到 120s)。 */
+    probeBucket(timeoutMs?: number): Promise<BucketProbe>;
     /** Byte-delete the given hashes — called ONLY from the async sweepOrphanBlobs reaper (NEVER the synchronous purge
      *  path). Honors the SAME created_at grace window as the SQL backend: with an index, DELETE the grace-passed index
      *  rows first (the index's created_at is the authoritative age — an S3 object carries no service-controlled timestamp

package/dist/plugins/blob-backend.js

@@ -253,6 +253,32 @@ export class MinioBlobBackend {
         const ms = lm ? Date.parse(lm) : NaN;
         return { lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
     }
+    async probeBucket(timeoutMs = OBJECT_STORE_IO_TIMEOUT_MS) {
+        const f = this.cfg.fetchImpl ?? fetch;
+        const url = presignS3ListUrl({
+            endpoint: this.cfg.endpoint,
+            bucket: this.cfg.bucket,
+            prefix: this.keyPrefix,
+            maxKeys: 1,
+            accessKey: this.cfg.accessKey,
+            secretKey: this.cfg.secretKey,
+            ...(this.cfg.region ? { region: this.cfg.region } : {}),
+            expiresSec: this.ttl,
+        });
+        let res;
+        try {
+            res = await f(url, { method: "GET", signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch (err) {
+            return { state: "unknown", detail: `request failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (res.ok)
+            return { state: "present" };
+        const body = await res.text().catch(() => "");
+        if (res.status === 404 && /<Code>NoSuchBucket<\/Code>/.test(body))
+            return { state: "missing" };
+        return { state: "unknown", detail: `HTTP ${res.status}` };
+    }
     async deleteBlobs(hashes) {
         if (hashes.length === 0)
             return 0;

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

@@ -1,8 +1,17 @@
-import { type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
+import { FileSessionRepo, type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionSummary } from "./store-contracts.js";
+import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+/**
+ * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座与会话视图口
+ * `audit.ts#buildSessionAuditLocal` 的读旁路),所以坏记录的披露座只有这一份接线 —— 修前视图口自建一只不带座的 repo,同一份坏档在这里读到有计数 / 探针,
+ * 在视图口读到一个字都没有。座 = F 类 `server.session-repo.corrupt-record-skipped`(会话存档里读不出的记录丢的是可用性:历史少一截 / 列表少一行,不开任何门;
+ * 计数单位 = 一条被跳过的记录,逐命中探针行,warn 每进程一次),外加会话打开作用域的计数腿(`noteReplayInSessionOpenScope`:只在 `openSessionForItself`
+ * 的作用域里才记,作用域外 —— 列表 / 导出 / 视图口 —— 是空操作,那些读只进运维面)。
+ */
+export declare function createLocalSessionRepo(root: string): FileSessionRepo;
 export declare class LocalSessionStore implements SessionStore {
     private readonly repo;
     /** [ref] 车1:托管留存声明 —— **诚实的 none**。本店的行没有任何按期删除的腿(留存 lane 的三方法只实现在
@@ -12,8 +21,6 @@ export declare class LocalSessionStore implements SessionStore {
     readonly retention: import("@sema-agent/core").RetentionDeclaration;
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one (mirrors TiDBSessionStore). */
     private readonly pending;
-    /** Service-side owner scope per session (core's repo has no owner column). Registered-ownerless ⇒ null; absent ⇒ undefined. */
-    private readonly owners;
     /** Last-activity marker (touch) for ordering — the keyset sort key for {@link listSessions}. PERSISTED to a JSON
      *  sidecar under {@link dataDir} (when given) so the /resume picker's newest-first order SURVIVES a service restart:
      *  without persistence the map starts EMPTY on boot and every session degrades to `createdAt` ordering (the picker
@@ -54,35 +61,52 @@ export declare class LocalSessionStore implements SessionStore {
     private readonly sidecarPath?;
     /** Auto-title map (`session-titles.json`). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
      *  #10 clobber area); titles are write-once + ultra-low-rate (one per session, ever). Cross-instance sharing: see
-     *  {@link SidecarStringMap}. */
+     *  {@link SidecarMap}. */
     private readonly titles;
     /** S-690 — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
      *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
-    /** S-790 / S-506([ref] §2):会话化身(`session-incarnations.json`,`{ [sessionId]: token }`)。SQL 孪生的
-     *  `session_meta.incarnation` 列在本店的对位。🔴 **必须落盘**(不能像 `owners` 那样只活在内存):化身的口径是「一位住客一生
-     *  稳定」,而记忆引擎按它绑定会话级记录(opt-out / 污染标记)—— 重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集。
-     *  设计稿原说「存进属主边车」,但本店**没有**落盘的属主边车(`owners` 是纯内存 Map,S3 裁定),所以落在同一族的第四只边档
-     *  (同一只 `SidecarStringMap`:同写链、失败回滚)。铸点只在新建会话;盘上旧会话没有这一格 ⇒ 第一次读补铸并落盘。 */
-    private readonly incarnations;
+    /**
+     * 会话元数据(`session-incarnations.json`,一格的形与两种读法见 {@link SessionMetaCell}):**属主与化身的唯一真源**,SQL 孪生
+     * `session_meta` 行上 `owner` / `incarnation` 两列在本店的对位。两样都**必须落盘**:
+     *  · 化身(S-790 / S-506,[ref] §2)的口径是「一位住客一生稳定」,记忆引擎按它绑定会话级记录(opt-out / 污染标记)——
+     *    重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集;
+     *  · 属主(7.119.0)是会话策略规则的存储键:规则按「会话 × 属主」存、按 run 的 principal 读 —— 重启后属主丢了,规则照样在跑,
+     *    属主自己却读不到也删不掉(`409 conflict.session_ownerless`)。7.118.x 及更早属主只活在一只进程内存 Map 里,就是这个病。
+     * 没有第二份:进程里的读视图就是这只边档按路径共享的那张表({@link SidecarMap},同写链;只发布已落盘的值 —— 写失败什么都不发布)。铸点只在新建会话;
+     * 盘上有会话而边档里没有它那一格 ⇒ 第一次读补铸一格只有化身的(属主没有事实可写)并落盘。严格读(读不出 ⇒ 整只拒,见 `SidecarMap.strict`)。
+     */
+    private readonly meta;
+    /** 认领行(`session_owner_claimed`)的出口 —— 一次性迁移 M10 的认领臂专用(窗口见 `plugins/one-time-migrations.ts` 登记表)。 */
+    private readonly log;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param dataDir  the SAME data dir the file-backed repo persists under (LocalBackend passes `fileBackend.root`).
      *                  When given, lastActivity is persisted to `<dataDir>/session-last-activity.json` so it survives a
-     *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives). */
-    constructor(repo: SessionRepo, dataDir?: string);
+     *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives).
+     *  @param opts.log the `session_owner_claimed` line's sink (LocalBackend passes a logger at the deployment's LOG_LEVEL;
+     *                  absent ⇒ an info-level JSON-line logger — a claim is never silent). */
+    constructor(repo: SessionRepo, dataDir?: string, opts?: {
+        log?: Pick<Logger, "info">;
+    });
+    /**
+     * 把 `sessionId` 那一格写成 `next(before)` 的结果并**落盘**(写链里在草稿上判、写、落盘后才发布给读者 —— 与 instruction-source 同一只 `commit`;
+     * 判据建立在每一节之前的盘上状态上,所以防 clobber 的「已记下就不动」写在 `next` 里,不写在链外)。`next` 返回 `undefined` = 不改。
+     * 落不了盘 ⇒ 抛(属主与化身都是正确性事实,不做「内存里先记着」的降级:一只没落盘的化身重启后会被换掉 —— 那是另一位住客;
+     * 一个没落盘的属主重启后就丢了 —— 那正是 7.119.0 修的病)。返回这一次是否真改了那一格。
+     */
+    private writeMeta;
+    /** 删一只会话的那一格(落盘;落不了 ⇒ 抛 —— 留下的格会让一只删掉的会话在重启后「还在」)。 */
+    private dropMeta;
+    /** 盘上有没有这只会话(repo 的唯一探针;`open` 读整只存档,所以只在边档里没有那一格时才走到这里)。 */
+    private existsInRepo;
     /**
-     * S-790:把 `sessionId` 的化身写成 `next(before)` 的结果并**落盘**(写链里判、写、失败回滚 —— 与 instruction-source 同一只
-     * `commit`)。`next` 返回 `undefined` = 不改。落不了盘 ⇒ 抛(化身是正确性事实,不做「内存里先记着」的降级:一只没落盘的化身
-     * 重启后会被换掉,那就是另一位住客)。
+     * 一只会话的元数据 —— 属主与化身的**唯一读口**(`ownerOf` / `sessionFaceOf` / `getHead` / 删除与换装的属主门都经它)。`undefined` = 无此会话。
+     * 边档里有那一格 ⇒ 读它(一次同步读,两样同出一格,不会拼出混世代组合);没有那一格而盘上有会话(7.104.0 之前的会话从没被铸过化身)
+     * ⇒ 补铸一格只有化身的(属主没有事实可写,不伪造)并落盘后再答 —— 之后的读都命中那一格,不再回 repo。
      */
-    private writeIncarnation;
-    /** S-790:新建会话 ⇒ 铸一只新的(覆盖同 id 上任何残留 —— 新建行就是新住客)。 */
-    private mintIncarnation;
-    /** S-790:已存在的会话缺一只化身(盘上 7.104.0 之前的会话)⇒ 补铸;已有的一个字节不动。 */
-    private ensureIncarnation;
-    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)。盘上有会话而边档里没有它的化身 ⇒ 补铸并落盘后再答;
-     *  读的过程中会话被删 / 换了主 ⇒ `undefined`(与 {@link getHead} 同一条「读间被删」判据)。 */
+    private metaOf;
+    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)—— 两样出自 {@link metaOf} 读到的同一格。 */
     sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
      *  no "none" (register-lag) dimension here — two states only. */
@@ -94,10 +118,10 @@ export declare class LocalSessionStore implements SessionStore {
     /** S-690 —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
-     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 回滚内存再抛**,与 SQL 孪生
+     * S-690 —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 内存不动、抛**,与 SQL 孪生
      * 「要么提交要么抛」同形 —— 修前写失败只 warn、内存照样前进,同来源的后续 run 在相等比较上短路、再也不重写,重启后
-     * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定、落盘、失败回滚**整段在写链的一节里**(`commit`):下一节
-     * 开始之前内存已回到盘上那份,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
+     * 比的是一份过期的盘,codex che-NM r1 [medium])。CAS 判定(在草稿上)、落盘、发布**整段在写链的一节里**(`commit`):下一节
+     * 开始之前共享的那张表只含落过盘的值,判定永远不会建立在一个没落过盘的值上(codex che-NM r2 [medium])。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
     /** Best-effort, one-shot hydrate of the persisted lastActivity map (no-op when not persisting / no sidecar yet). A
@@ -141,28 +165,35 @@ export declare class LocalSessionStore implements SessionStore {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
-    /** Idempotently record a session's owner — never overwrites an existing owner (mirrors TiDBSessionStore.register).
-     *  TiDB parity: register INSERTs a session_meta row so the session EXISTS (forkable) even before its
-     *  first acquire/run — so we also ensure an EMPTY repo session exists (open if present → never overwrite history;
-     *  create if not), else `ownerOf` would say a registered-but-never-acquired session exists while `fork` 404s it. */
-    register(sessionId: string, owner: string | null): Promise<void>;
-    /** Owner of a session: `null` if registered ownerless, `undefined` if no such session (mirrors TiDBSessionStore.ownerOf).
+    /**
+     * Idempotently record a session's owner — never overwrites a RECORDED owner (incl. a recorded `null`, "registered ownerless";
+     * mirrors TiDBSessionStore.register's first-write rule). TiDB parity: register INSERTs a session_meta row so the session EXISTS
+     * (forkable) even before its first acquire/run — so we also ensure an EMPTY repo session exists (open if present → never
+     * overwrite history; create if not), else `ownerOf` would say a registered-but-never-acquired session exists while `fork` 404s it.
      *
-     *  S3 修(clay 裁 2026-07-26:**local=单用户,多租户走云** ⇒ 跨重启不承诺 owner 隔离):`owners` 是纯内存
-     *  Map,重启后失忆——曾把「失忆」答成 `undefined`(=「无此会话」),让 DELETE /v1/sessions 的 route 门短路成
-     *  already-gone、checkpoint 的 EXISTS 镜像门 return 0 ⇒ **E21 对盘上老会话整体 no-op 且无人知道**。
-     *  现在 Map miss 时探 repo:盘上在 ⇒ 按 load() 两处懒回填早已写下的同一判据回填 `null`(registered
-     *  ownerless);repo 真没有才 `undefined`。SQL 孪生无此形(owner 在 session_meta 行,重启无损)。 */
+     * 首写判据在写链里判(两只并发登记:先落盘的那一只赢,后一只不改、也不建会话)。一只**盘上已有、属主从没被记下**的会话
+     * (边档那一格只有化身 —— 7.118.x 及更早写下的,或更早到连化身都没有)是一次性迁移 M10 的对象(窗口见 `plugins/one-time-migrations.ts`
+     * 登记表):窗开着、且这次登记带着 principal(`owner !== null`)⇒ **认领**(记下属主,化身一个字节不动 —— 同一位住客),一行 info
+     * `session_owner_claimed`;否则只补化身(缺就补),属主仍是「没被记下」,读作无主。认领的安全前提是单用户 —— local 后端起服门拒
+     * `REQUIRE_PRINCIPAL=true`,授权口也只在那时才把 principal 递过来认领(`security.ts` `createAuthorizer`)。
+     */
+    register(sessionId: string, owner: string | null): Promise<void>;
+    /** Owner of a session: `null` if ownerless (registered ownerless, or an owner that was never recorded — a session written by
+     *  an earlier version), `undefined` if no such session (mirrors TiDBSessionStore.ownerOf). Reads {@link metaOf}: the persisted
+     *  cell, so the answer survives a restart exactly like the SQL twins' `session_meta.owner` column does. (Before 7.119.0 the
+     *  owner lived in a process-local Map and this method answered `null` for every session after a restart — the S3 fallback
+     *  "on disk ⇒ ownerless" kept the E21 delete working, but froze every owner-keyed session-policy rule.) */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
-    /** [ref] 六轮复审:owner+leafId 原子快照——单线程 JS 内两同步/顺序读之间无 await 打断 owner 判定
-     *  (owner 先取快照,leaf 读后 owner 复核,变了=undefined 视作删除中,调用方按删处理)。 */
+    /** [ref] 六轮复审:owner+leafId 原子快照 —— 先读那一格,读 leaf,再同步复读那一格:格没了(读间被删)或换了主 / 换了住客 ⇒
+     *  undefined(调用方按删处理)。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
-    /** 2c P1d-β — re-stamp the service-side owner scope WITHOUT rewriting entries (the staged-commit `identical` path:
-     *  the log is already present & equal, so only the owner needs re-stamping to the importing principal, §9). */
-    restampOwner(sessionId: string, owner: string | null): void;
+    /** 2c P1d-β — re-stamp the session's owner WITHOUT rewriting entries (the staged-commit `identical` path: the log is
+     *  already present & equal, so only the owner needs re-stamping to the importing principal, §9). Persisted like every
+     *  owner write; the incarnation is untouched (same occupant). No cell (no such session) ⇒ no-op. */
+    restampOwner(sessionId: string, owner: string | null): Promise<void>;
     touch(sessionId: string): Promise<void>;
     /** E18 — the session's current leaf SessionTreeEntry.id (@see TiDBSessionStore.getLeafId). Reads the repo's storage
      *  leaf (no acquire-lock; InMemory/File repo reads don't lock). null when the session doesn't exist / has no leaf. */
@@ -174,10 +205,9 @@ export declare class LocalSessionStore implements SessionStore {
      * abstraction (`repo.list()`), keyset-paginated newest-first by last activity. Session IDENTITY comes from the
      * repo (one entry per persisted session); a {@link SessionSummary} is SYNTHESIZED per id so the wire shape is
      * byte-identical to {@link TiDBSessionStore.listSessions} (the run picker doesn't drift):
-     *   - `owner`           — the service-side owner map (process-local; null when unknown/ownerless). Owner FILTERING
-     *                          is best-effort here (the in-memory map IS the source of truth; a single-user local
-     *                          deployment runs REQUIRE_PRINCIPAL=off so the principal path passes owner=null and every
-     *                          null-owner session lists). The route already owner-gates at the HTTP layer.
+     *   - `owner`           — the session's persisted session-meta cell (null when ownerless / never recorded). A
+     *                          single-user local deployment runs REQUIRE_PRINCIPAL=off; the route already owner-gates
+     *                          at the HTTP layer.
      *   - `firstActivityAt` — the session's `createdAt` (repo metadata).
      *   - `lastActivityAt`  — the touch marker (falls back to `createdAt`); the keyset sort key.
      *   - `objectivePreview`— the last USER-text entry, synthesized from the session tree (no run ledger).
@@ -240,9 +270,10 @@ export declare class LocalSessionStore implements SessionStore {
     /** 2c session-sync — IMPORT a verbatim entry log into `sessionId` via core `SessionRepo.importEntries`
      *  (which runs the `validateEntriesForImport` fail-closed gate before writing). `owner` is the authenticated
      *  importing principal (re-stamped into the service-side owner map; core's local repo has no owner column, §9).
-     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`). */
+     *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`).
+     *  The owner is recorded in the session-meta cell (persisted), together with the incarnation. */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** importEntries / replaceEntries 的共用写半场:导日志 + 盖属主 + 落化身(新建铸的那只,或换装沿用的那只)。 */
+    /** importEntries / replaceEntries 的共用写半场:导日志 + 一格写全属主与化身(新建铸的那只,或换装沿用的那只)。 */
     private importEntriesAs;
     /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
      *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer