@sema-agent/server 7.132.0 → 7.134.0

package/dist/plugins/remote-env-local-docker.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
-import { LANE_HOME_PROBE_COMMAND, judgeLaneHome } from "../lane-home-probe.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { randomBytes } from "node:crypto";
 import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
@@ -23,7 +23,9 @@ const unsupported = (op) => ({
 export class RemoteLocalDockerExecutionEnv {
     capabilities = { isolation: true, suspendable: false, canonicalPathAuthoritative: true };
     cwd;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
     cdPath = "unknown";
     cfg;
     spawnFn;
@@ -33,6 +35,7 @@ export class RemoteLocalDockerExecutionEnv {
     destroyed = false;
     connecting;
     homeRefusal;
+    homeSeat;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
             config = { ...config, image: config.image ?? "" };
@@ -46,7 +49,7 @@ export class RemoteLocalDockerExecutionEnv {
             controlTimeoutMs: config.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
         this.spawnFn = deps.spawn ?? spawn;
         const id = config.id ?? randomBytes(6).toString("hex");
         const suffix = randomBytes(4).toString("hex");
@@ -117,7 +120,7 @@ export class RemoteLocalDockerExecutionEnv {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         }
-        if (this.homeDir !== undefined && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
+        if (this.homeSeat.asks && !(await this.untilOrAborted(this.probeContainerShell(), config?.abortSignal))) {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while detecting the container's shell") };
         }
@@ -137,14 +140,14 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(this.handle);
     }
     async homeVerdict(signal) {
-        if (this.homeDir === undefined)
+        if (!this.homeSeat.asks)
             return undefined;
         const probe = await this.docker(this.execRaw(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.controlTimeoutMs });
-        const verdict = judgeLaneHome(PROVIDER, this.homeDir, probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
-        if (verdict === undefined)
-            return undefined;
         if (!probe.ok && probe.error.code === "aborted")
             return new RemoteExecutionError("aborted", "connect aborted while reading the environment's home");
+        const verdict = this.homeSeat.settle(probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
+        if (verdict === undefined)
+            return undefined;
         const error = new RemoteExecutionError("connect_failed", verdict.refusal);
         if (verdict.answered)
             this.homeRefusal = error;
@@ -174,7 +177,7 @@ export class RemoteLocalDockerExecutionEnv {
         }
         const insp = await this.docker(["inspect", "-f", "{{.State.Running}}", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs });
         if (insp.ok && insp.value.exitCode === 0 && insp.value.stdout.trim() === "true") {
-            if (this.containerId === undefined && this.homeDir !== undefined)
+            if (this.containerId === undefined && this.homeSeat.asks)
                 await this.probeContainerShell();
             const home = this.containerId === undefined ? await this.homeVerdict() : undefined;
             if (home !== undefined)

package/dist/plugins/remote-env-ssh.d.ts

@@ -1,22 +1,14 @@
 import { type SshHostKeyPolicy } from "../ssh-host-key.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
-export interface SshEnvConfig {
+export interface SshEnvConfig extends LaneHomeConfig {
     host: string;
     port?: number;
     username: string;
     /** PEM private key — from the adapter-held secret env (NEVER the workspace). [ref] §5 #2. */
     privateKey: string;
     passphrase?: string;
-    /**
-     * S-213④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root; relative paths resolve against it. Default "." (the login dir). */
     mountPath?: string;
     /** Connect handshake bound (ms). */
@@ -92,9 +84,11 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
      *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     private inFlight?;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
-    /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明胜,否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(声明胜 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    private readonly homeSeat;
+    /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返;没声明且已量到绝对路径之后不再问)。 */
     private homeChecked?;
     /** 目标机答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每个面原样回它(同一目标机同一登录用户同一答案:不再问、不再发命令)。 */
     private homeRefusal?;
@@ -126,9 +120,9 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     /** 家目录判定的 per-caller 可中止等待(共享的判定承诺不动,只退本 caller)。 */
     private raceVerdictAbort;
     /**
-     * 家目录:声明在场(`homeDir`,只来自 `REMOTE_EXEC_HOME_DIR` —— 本车道没有自己的缺省)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,
-     * 与命令同一个用户、同一份登录 env),交唯一判官 `judgeLaneHome`。答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;
-     * 没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 量到绝对路径为止)⇒ 在这条连接上问一次 `$HOME`(登录用户的 shell 答的,与命令同一个用户、同一份登录 env),读数交座。
+     * 声明在场:答了而不一致 / 不是绝对路径 ⇒ 拒记在环境上(每个面原样回它),命令一条都不发;没答上(通道开不出 / 非零退出 / 超时)⇒ 这一次同样不开、不记,下一次调用重问。
+     * 没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,命令照跑(没声明就没有声明可拒)—— 判定对这条连接记下,换了连接再问。
      * 问的是裸命令(不经工作目录守卫:工作目录进不去不影响家目录的答案)。上界 = 握手的 `readyTimeoutMs`(问一个环境变量,不是跑用户命令)。
      */
     private homeVerdict;

package/dist/plugins/remote-env-ssh.js

@@ -7,7 +7,7 @@ import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
-import { LANE_HOME_PROBE_COMMAND, judgeLaneHome } from "../lane-home-probe.js";
+import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -25,7 +25,10 @@ export class RemoteSshExecutionEnv {
     destroyed = false;
     connEpoch = 0;
     inFlight;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
     homeChecked;
     homeRefusal;
     cdPath = "unknown";
@@ -47,7 +50,7 @@ export class RemoteSshExecutionEnv {
             hostKey: config.hostKey,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -110,13 +113,13 @@ export class RemoteSshExecutionEnv {
             if (this.homeRefusal)
                 return { ok: false, error: this.homeRefusal };
             const transport = await this.ensureTransport(signal);
-            if (!transport.ok || this.homeDir === undefined)
+            if (!transport.ok || !this.homeSeat.asks)
                 return transport;
             const conn = this.conn;
             if (!conn)
                 return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection dropped right after connect") };
             if (this.homeChecked?.conn !== conn) {
-                const checked = { conn, verdict: this.homeVerdict(conn, this.homeDir) };
+                const checked = { conn, verdict: this.homeVerdict(conn) };
                 this.homeChecked = checked;
                 void checked.verdict.then((r) => {
                     if (!r.ok && this.homeRefusal === undefined && this.homeChecked === checked)
@@ -148,9 +151,10 @@ export class RemoteSshExecutionEnv {
             signal.removeEventListener("abort", onAbort);
         return raced;
     }
-    homeVerdict(conn, declared) {
+    homeVerdict(conn) {
         return new Promise((resolve) => {
-            let out = "";
+            const chunks = [];
+            let outBytes = 0;
             let settled = false;
             let channel;
             let channelClosed = false;
@@ -173,7 +177,7 @@ export class RemoteSshExecutionEnv {
                 const closeTrouble = closeChannel(channel);
                 if (closeTrouble !== undefined && !probe.ok)
                     probe = { ok: false, reason: `${probe.reason}; ${closeTrouble}` };
-                const verdict = judgeLaneHome(PROVIDER, declared, probe);
+                const verdict = this.homeSeat.settle(probe);
                 if (verdict === undefined)
                     return resolve(ok(undefined));
                 const error = new ExecutionError("shell_unavailable", verdict.refusal);
@@ -191,12 +195,14 @@ export class RemoteSshExecutionEnv {
                     channel = stream;
                     stream
                         .on("data", (d) => {
-                        if (out.length < 4096)
-                            out += d.toString("utf8");
+                        if (outBytes < 4096) {
+                            chunks.push(d);
+                            outBytes += d.length;
+                        }
                     })
                         .on("close", (code) => {
                         channelClosed = true;
-                        settle(code === 0 ? { ok: true, stdout: out } : { ok: false, reason: code == null ? "the channel closed without an exit status" : `exit ${code}` });
+                        settle(code === 0 ? { ok: true, stdout: Buffer.concat(chunks).toString("utf8") } : { ok: false, reason: code == null ? "the channel closed without an exit status" : `exit ${code}` });
                     });
                     stream.stderr.on("data", () => { });
                 });

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

@@ -2,13 +2,14 @@ import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import { type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
-import { type SqlDriver } from "./sql-driver.js";
+import { type ClaimFenced, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 export type { RunRecord, SessionSummary, RunEvent, LatestRunRef } from "./store-contracts.js";
 export declare class SqlRunStore {
-    protected readonly db: SqlDriver;
+    readonly db: SqlDriver;
+    /** `db` 公开只读:会话认领住在这只池背后的库里,写在认领栅栏里的店(workflow 子代决定行)读写都走它 —— 那只店的池只有这一处来源。 */
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
@@ -159,6 +160,17 @@ export declare class SqlRunStore {
      * (一个输掉的认领不许覆盖赢家的持有记录——同一条条件 UPDATE 天然保证)。
      */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
+    /**
+     * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
+     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
+     *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑;提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
+     * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
+     *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 只插认领行、`deleteBySession` 见认领行在就中止,
+     *    都不与本序成环。锁住之后:收割的改行 / 终局与收割的删认领 / 别人的建行都排在本事务之后,收割器提交后重判 `updated_at` 看到的是刚刷的。
+     *    锁读没命中时 InnoDB 可能取一把间隙锁;本事务此后不往这两张表插任何行(见 space-commit 那条锁形注)。
+     * 担保止于提交:判出「持有」的是这只事务;提交确认在路上迟到、这一跑随后失去认领,不在本栅栏的射程里(调用方的已知边界)。
+     */
+    whileHoldingClaim<T>(sessionId: string, taskId: string, write: (tx: SqlTxConn) => Promise<T>): Promise<ClaimFenced<T>>;
     /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
@@ -194,17 +206,7 @@ export declare class SqlRunStore {
      *  built with plain string pushes in call order. PG's `$n` needs a NUMBERED placeholder per param, so that arm
      *  keeps its own positional-counter closure (`p()`) — collapsing the two into one shared counter would hide
      *  the very placeholder-numbering divergence this file exists to keep visible. */
-    listRuns(opts: {
-        status?: string;
-        jobId?: string;
-        source?: string;
-        owner?: string;
-        cursor?: {
-            createdAt: string;
-            taskId: string;
-        };
-        limit: number;
-    }): Promise<RunRecord[]>;
+    listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * S-297 —— 这个会话**最近一条腿**的窄指针(`/mcp` 面板的 `lastLegMcp` 与任何「上一条 run 是谁」的读面共用)。
      *

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

@@ -269,6 +269,21 @@ export class SqlRunStore {
         const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, instance_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, instance_id = $1, updated_at = $2 WHERE task_id = $3 AND status IN ('suspended','needs_review')"), [instanceId, new Date(), taskId]);
         return affected === 1;
     }
+    async whileHoldingClaim(sessionId, taskId, write) {
+        let fenced = { held: false };
+        await this.tx(async (conn) => {
+            const run = await conn.query(this.q("SELECT task_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            if (run.rows.length === 0)
+                return;
+            const claim = await conn.query(this.q("SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE", "SELECT task_id FROM task_active WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+            const holder = claim.rows[0];
+            if (holder === undefined || String(holder.task_id) !== taskId)
+                return;
+            await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
+            fenced = { held: true, value: await write(conn) };
+        });
+        return fenced;
+    }
     async getActiveTaskId(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT task_id FROM task_active WHERE session_id = ?", "SELECT task_id FROM task_active WHERE session_id = $1"), [sessionId]);
         return rows[0] ? String(rows[0].task_id) : undefined;
@@ -335,7 +350,10 @@ export class SqlRunStore {
                 where.push("source = ?");
                 params.push(opts.source);
             }
-            if (opts.owner !== undefined) {
+            if (opts.owner === null) {
+                where.push("owner IS NULL");
+            }
+            else if (opts.owner !== undefined) {
                 where.push("owner = ?");
                 params.push(opts.owner);
             }
@@ -362,7 +380,9 @@ export class SqlRunStore {
             where.push(`job_id = ${p(opts.jobId)}`);
         if (opts.source !== undefined)
             where.push(`source = ${p(opts.source)}`);
-        if (opts.owner !== undefined)
+        if (opts.owner === null)
+            where.push("owner IS NULL");
+        else if (opts.owner !== undefined)
             where.push(`owner = ${p(opts.owner)}`);
         if (opts.cursor) {
             const a = p(new Date(opts.cursor.createdAt));

package/dist/plugins/schema-indexes.js

@@ -21,6 +21,8 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
     { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
     { table: "workflow_agent_session", name: "idx_wfagentsess_run", columns: ["run_id"] },
+    { table: "workflow_park_decision", name: "idx_wfparkdec_host", columns: ["host_session_id"] },
+    { table: "workflow_park_decision", name: "idx_wfparkdec_run", columns: ["run_id"] },
     { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
     { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
     { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },

package/dist/plugins/send-user-file.js

@@ -1,6 +1,6 @@
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
-import { CONTROL_AND_BIDI_STRIP_RE } from "../text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
 export const PRESIGN_MAX_TTL_SEC = 604_800;
@@ -11,7 +11,7 @@ export function scopeSegment(secretKey, scope) {
 }
 export function sanitizeSendFileName(name) {
     const base = (name ?? "").split(/[/\\]/).pop() ?? "";
-    let clean = base.replace(CONTROL_AND_BIDI_STRIP_RE, "").replace(/^\.+/, "").trim();
+    let clean = stripControlAndBidi(base).replace(/^\.+/, "").trim();
     if (clean.length > 128) {
         const dot = clean.lastIndexOf(".");
         const ext = dot > 0 && clean.length - dot <= 16 ? clean.slice(dot) : "";

package/dist/plugins/session-epoch-anchor.d.ts

@@ -1,13 +1,39 @@
-/** One row of the scan: its `seq` and the `payload` column projected as text (`jsonColumnText`). */
+/**
+ * The prompt-epoch anchor below a bounded window's floor — `SessionStorage.getEpochAnchor()` for every session storage that
+ * loads a window instead of the whole tree: the two SQL session backends (`tidb-session-storage.ts` / `pg-session-storage.ts`,
+ * the run's wake and the session view alike) and the local leg's session view (`local-session-window.ts`). One reading, three
+ * dialects: each storage hands in only its own page and reads its own rows.
+ *
+ * ## The rule: the store carries the record, the engine reads it
+ * A bounded wake loads `[floor .. leaf]`; when the loaded branch holds no epoch carrier (a rewind cut inside the kept
+ * tail, or compactions written before the engine restated the epoch), the engine's `Session.getPromptEpoch()` asks the
+ * storage for the nearest carrier BELOW the floor and reads it itself. The storage returns that record **as stored**:
+ *  · a `prompt_epoch` entry ⇒ the whole entry (the engine's branch walk reads the whole entry too);
+ *  · a compaction whose `details.promptEpoch` is present ⇒ that restatement;
+ *  · a compaction without a restatement carries nothing ⇒ the scan pages past it, to exhaustion (a session that lived
+ *    across the release that introduced epochs can hold any number of them between the floor and its pin).
+ * The storage never judges the record's shape. The engine answers a current-shape record as a pin and a retired-shape
+ * record by name (`legacy`, with whether it pinned a center artifact) — a storage that normalized the record first would
+ * turn a session pinned under a retired shape into one with no pin, and the engine would then skip the center source's
+ * handling of that pin. A record that is neither is the engine's to read as well (it reads as no record).
+ *
+ * `floorSeq <= 0` (a full load: the walk already reaches the root) or no carrier below the floor ⇒ `undefined`
+ * (a session that predates epochs).
+ *
+ * What "below the floor, newest first" walks is the storage's: the SQL twins page their `session_event` rows by `seq` (their
+ * window is cut by `seq` too); the local window pages the branch path it was cut from.
+ */
+import type { SessionTreeEntry } from "@sema-agent/core";
+/** One row of a scan: its position (`seq`, the keyset cursor). What else the row holds is the storage's — it reads the entry
+ *  out of the row itself ({@link scanEpochAnchor}'s `entryOf`), so a row is read only when the scan reaches it. */
 export interface EpochAnchorRow {
     readonly seq: string | number;
-    readonly payload: unknown;
 }
 /**
- * Page the rows `seq < beforeSeq` whose type is `prompt_epoch` or `compaction`, newest first (the backend's own SQL;
- * an empty page = no older row).
+ * Page the rows `seq < beforeSeq` that may carry an epoch record, newest first (an empty page = no older row). A page may hold
+ * other rows too — they carry nothing and the scan passes them.
  */
-export type EpochAnchorPage = (beforeSeq: number) => Promise<readonly EpochAnchorRow[]>;
+export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
 /** The nearest epoch carrier below `floorSeq`, as stored; see the file header. */
-export declare function scanEpochAnchor(sessionId: string, floorSeq: number, page: EpochAnchorPage): Promise<unknown>;
+export declare function scanEpochAnchor<R extends EpochAnchorRow>(floorSeq: number, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
 //# sourceMappingURL=session-epoch-anchor.d.ts.map

package/dist/plugins/session-epoch-anchor.js

@@ -1,5 +1,4 @@
-import { decodeSessionEventPayload } from "./session-event-payload.js";
-export async function scanEpochAnchor(sessionId, floorSeq, page) {
+export async function scanEpochAnchor(floorSeq, page, entryOf) {
     if (floorSeq <= 0)
         return undefined;
     let cursor = floorSeq;
@@ -8,7 +7,7 @@ export async function scanEpochAnchor(sessionId, floorSeq, page) {
         if (rows.length === 0)
             return undefined;
         for (const row of rows) {
-            const entry = decodeSessionEventPayload(row.payload, sessionId, row.seq);
+            const entry = entryOf(row);
             if (entry.type === "prompt_epoch")
                 return entry;
             if (entry.type === "compaction") {

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

@@ -0,0 +1,11 @@
+/**
+ * fork 拷贝的属主 —— core `SessionStore.fork` 契约的唯一读法:
+ * 显式串 ⇒ 该串;无参 / 显式 `null` ⇒ 源会话记下的属主(`undefined` = 源会话没记,拷贝也不记)。
+ */
+export declare function forkOwnerOf(requested: string | null | undefined, sourceOwner: string | null | undefined): string | null | undefined;
+/**
+ * `register` 首写的 owner 守卫 —— core `SessionStore.register` 契约的唯一读法(三只店同调):首写的 owner 既不是串也不是 `null` ⇒ 响亮拒(不留行);
+ * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。
+ */
+export declare function assertFirstOwnerWritable(sessionId: string, owner: unknown): asserts owner is string | null;
+//# sourceMappingURL=session-ownership.d.ts.map

package/dist/plugins/session-ownership.js

@@ -0,0 +1,11 @@
+import { SessionError } from "@sema-agent/core";
+export function forkOwnerOf(requested, sourceOwner) {
+    return typeof requested === "string" ? requested : sourceOwner;
+}
+export function assertFirstOwnerWritable(sessionId, owner) {
+    if (typeof owner === "string" || owner === null)
+        return;
+    throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal (string) or null (anonymous), got ${owner === undefined ? "undefined" : typeof owner} — ` +
+        "a stored value that ownerOf reads back as 'no row' would leave the session claimable forever and ownable never; refusing, nothing written");
+}
+//# sourceMappingURL=session-ownership.js.map

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

@@ -33,7 +33,7 @@
  *    宿主可枚举、release 不真删的普通会话 ——「声明了 full tier 却在静默说谎」。⇒ 在**声明了分区**的
  *    店上,带 placement 的 acquire 必须回读到**已持久化**且同一元组身份的行,回读缺失/异组=响亮拒。
  */
-import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord } from "@sema-agent/core";
+import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore } from "@sema-agent/core";
 /**
  * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
  *
@@ -88,20 +88,18 @@ export interface PlacementAcquireOpts {
     placement?: SessionPlacement;
 }
 /**
- * 准入判据 —— **两个方向**(顶注 ①②;core `TtlSessionStore.assertPlacementAdmission` 的 SQL 镜像,
- * 逐条同义,文案自铸)。
- *
- * @param persisted 该 id 在库里**已持久化**的元组(缺席 = 普通会话 / 无此行)。
- *
- * · 方向①(claim 关门):`persisted` 在场 + 非 `requireExisting` + 调用方没带创建 placement ⇒ 拒。
- *   `requireExisting`(读/复活形,义务 5)与「创建调用及其幂等重取」(带 placement 的可信内部链)
- *   是仅有的两个合法形。placement 不可变意味着带 placement 的参数**永远重写不了**任何东西——持久化
- *   的那一份恒赢,所以放行它不开任何口子。
- * · 方向②(镜像/squat):带 placement 的创建形回读到**缺席**或**异组**元组 ⇒ 拒。缺席 = 并发的
- *   claim 形抢先建出了普通会话(或带外写把元组抹了);异组 = 同 id 上坐着另一条委派链的转录。
- *   两者都不许让「声明了 durable 分区」这句话在静默中变成谎。
+ * 准入判据 —— 只有引擎那一只:core 包根导出 `admitSessionPlacement(sessionId, persisted, request, capability)`(core 7.54.0 #1468 K2;
+ * `TtlSessionStore` 自己调的同一只函数,两个方向:claim 关门 / 镜像·squat,`placement_refused`)。`capability.subagentPlacement` 读的是**店自己的声明**
+ * (`placements.subagent` 在场 —— 与 core `TtlSessionStore` 同一只读法,{@link placementCapabilityOf}),不是另写一个「这只店声明了」的常量:声明只有一处。
+ * 修前本模块持一份 SQL 镜像(`assertPlacementAdmission`,逐条同义、文案自铸)—— 与引擎是两份判据;随 7.54.0 退役、零别名。
+ * 拒句随之换成引擎的句子(缺元组那一形的结尾词:「or the repo dropped the tuple」,此前本仓写「written away out of band」)——
+ * 按原句匹配告警的运维规则要跟着改(MIGRATION 7.134.0 节记了这一句)。
  */
-export declare function assertPlacementAdmission(sessionId: string, persisted: SessionPlacementRecord | undefined, opts?: PlacementAcquireOpts): void;
+export declare function placementCapabilityOf(store: {
+    readonly placements?: SessionStore["placements"];
+}): {
+    readonly subagentPlacement: boolean;
+};
 /**
  * 一次 `listPlaced` 最多带回的行数。
  *

package/dist/plugins/session-placement.js

@@ -45,21 +45,8 @@ export function placementInsertValues(placement, placedAt) {
         placedAt,
     ];
 }
-export function assertPlacementAdmission(sessionId, persisted, opts) {
-    if (opts?.requireExisting === true)
-        return;
-    if (persisted !== undefined && opts?.placement === undefined) {
-        throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${persisted.kind} placement partition — a claim-form acquire cannot attach to it (read it with requireExisting, or address the agent through its a* handle)`);
-    }
-    if (opts?.placement === undefined)
-        return;
-    const want = opts.placement;
-    if (persisted === undefined) {
-        throw new SessionError("placement_refused", `session ${sessionId} exists OUTSIDE the ${want.kind} placement partition it was declared into — refusing to run a subagent transcript on it (a concurrent claim-form create won this id, or the tuple was written away out of band)`);
-    }
-    if (persisted.kind !== want.kind || persisted.scope !== want.scope || persisted.handle !== want.handle) {
-        throw new SessionError("placement_refused", `session ${sessionId}'s persisted placement does not match the declared one (persisted ${persisted.kind}/${persisted.scope ?? "-"}/${persisted.handle ?? "-"} vs declared ${want.kind}/${want.scope ?? "-"}/${want.handle ?? "-"}) — refusing a cross-tuple attach`);
-    }
+export function placementCapabilityOf(store) {
+    return { subagentPlacement: store.placements?.subagent !== undefined };
 }
 export const LIST_PLACED_BATCH = 1000;
 //# sourceMappingURL=session-placement.js.map

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

@@ -1,6 +1,8 @@
 import { type SessionStore } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { StoreBackend } from "./store-backend.js";
+import { type DelegationRootWitness, type DelegationTree, type OrphanOwnerLog } from "../delegated-session-owner.js";
+import type { OwnerAwareSessionStore } from "../security.js";
 /**
  * Session-store plugin seam.
  *
@@ -43,15 +45,23 @@ export declare function ensureSessionDurable(hostStore: SessionStore, sessionId:
  * [ref] 主动晋升版 ensureChildSessionDurable(cli TiDB 真机撞获:1.263 的只查不迁形在拆店生产形下
  * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
  * (14ms~2s)+ settle failed,赎回窗口不存在):
- *   1. 快路:已在 host 店且有真内容 → 直接通过(幂等/重入)。
+ *   0. 属主(S-1770,`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
+ *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与 claim 前后两读的那一位;core 的挂点签名只给子代 id,
+ *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`:不按新住客晋升 / 认领);
+ *      缺席(行上没有根)或根行此刻不在 ⇒ 孤行哨兵。
+ *   1. 快路:已在 host 店且有真内容 → 通过,**前提是那一行的属主按律定得下来**(`settleDelegatedOwner`:记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次
+ *      (与 M23 同读数),无主 ⇒ 认领(CAS 子行,写判断时的读数)、没落下 ⇒ 抛(只有记录委派树的 SQL 店;local 店的行不记委派树 ⇒ 不认领);此刻属主不是律给的那一只 ⇒ 那是别人的同 id 会话,
+ *      不是这只子代的转录 ⇒ 抛 = 停驻否决;与晋升建行前那一道同一只函数)。
  *   2. 晋升:routing.promoteToHost 把子会话整树从私店拷进 host 店(拷贝→私店 forget→路由记 host,
- *      三步见 ForkRoutingSessionStore.promoteToHost)。
- *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)——晋升产物必须达到与既有校验完全相同的
- *      durable 标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ *      三步见 ForkRoutingSessionStore.promoteToHost),宿主行在建行那一笔里带第 0 步的属主;写的是哨兵 ⇒ 写落下之后一行 warn。
+ *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)+ 同一只属主定夺 —— 晋升产物必须达到与快路完全相同的
+ *      标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ * 宿主店必须读得出属主(`delegatedOwnerHostOf`:`ownerOf` + `sessionFaceOf`;记录委派树的店另交 `placementOf` + `claimOwnerless`,两只同在或同缺;生产的 SQL / local 店与缓存包装层都满足),
+ * 否则响亮拒。
  * 调用方纪律与 {@link ensureSessionDurable} 同款:hostStore 必须是 release 非破坏性的真 durable 店
- * (main.ts 的 `config.sessionBackend === "tidb"` 门不变)。
+ * (stage-07 的 `config.sessionBackend === "tidb"` 门不变 —— 该词在 local 后端上同样归一成 `tidb`,所以本腿在 local 宿主店上也跑)。
  */
-export declare function ensureChildSessionDurableWithPromotion(hostStore: SessionStore, routing: {
-    promoteToHost(sessionId: string): Promise<void>;
-}, sessionId: string): Promise<void>;
+export declare function ensureChildSessionDurableWithPromotion(hostStore: OwnerAwareSessionStore, routing: {
+    promoteToHost(sessionId: string, owner: string | null, tree: DelegationTree): Promise<void>;
+}, sessionId: string, root: DelegationRootWitness | undefined, log: OrphanOwnerLog): Promise<void>;
 //# sourceMappingURL=session-store.d.ts.map

package/dist/plugins/session-store.js

@@ -1,5 +1,6 @@
 import { TtlSessionStore } from "@sema-agent/core";
 import { CachingSessionStore } from "./caching-session-store.js";
+import { assertRootStillWitnessed, delegatedOwnerHostOf, readDelegatedOwner, reportWrittenOwner, settleDelegatedOwner, sourceFacesVia, } from "../delegated-session-owner.js";
 export function createSessionStore(config, backend, metrics) {
     if (config.sessionBackend === "tidb") {
         if (!backend)
@@ -22,14 +23,24 @@ export async function ensureSessionDurable(hostStore, sessionId) {
         await hostStore.forget?.(acquired.sessionId);
     }
 }
-export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId) {
+export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId, root, log) {
+    const host = delegatedOwnerHostOf(hostStore);
+    if (host === undefined) {
+        throw new Error(`session "${sessionId}" cannot be parked: the host session store cannot read a session's owner (ownerOf / sessionFaceOf), or records delegation trees without being able to claim under them (placementOf / claimOwnerless), so the delegated transcript's owner cannot be derived or checked`);
+    }
+    const judged = await readDelegatedOwner(sessionId, root === undefined ? {} : { rootSessionId: root.sessionId }, sourceFacesVia(host.sessionFaceOf));
+    assertRootStillWitnessed(sessionId, root, judged);
+    let promoted = false;
     try {
         await ensureSessionDurable(hostStore, sessionId);
-        return;
     }
     catch {
+        await routing.promoteToHost(sessionId, judged.inherited.owner, judged.tree);
+        await ensureSessionDurable(hostStore, sessionId);
+        promoted = true;
     }
-    await routing.promoteToHost(sessionId);
-    await ensureSessionDurable(hostStore, sessionId);
+    const settled = await settleDelegatedOwner(host, sessionId, judged.inherited.owner, judged.tree);
+    if (promoted || settled.claimed)
+        reportWrittenOwner(log, "promotion", sessionId, settled.judged ?? judged);
 }
 //# sourceMappingURL=session-store.js.map