@sema-agent/server 7.147.0 → 7.148.0

package/dist/plugins/retention-deployment.d.ts

@@ -1,14 +1,14 @@
 /**
  * 托管留存的**部署那一半** —— 本仓的表经执行器(`stores-sql/retention-store-sql.ts`)的事务内钩表(K4)参与同一个破坏性事务。
- * 执行器是事务属主(开 / 提交 / 回滚),只认 core 的 `{domain, cutoffMs}`;部署的事实(hold、审计行的判定时点三格、认领、十一张部署表、
- * 结束了的空间)全在这里,经钩出场:
+ * 执行器是事务属主(开 / 提交 / 回滚),只认 core 的 `{domain, cutoffMs}`;部署的事实(hold、审计行的判定时点三格、认领、十三张部署表、
+ * 被删附件行的字节哈希)全在这里,经钩出场:
  *   · `holdLock`(首句)  —— hold 哨兵行锁读(`retention-lane-store-sql.ts` 的 {@link lockHoldSentinel});
- *   · `beforeDelete`(终集)—— 删十一张部署表里这批会话的行(下面 {@link deleteDeploymentSessionRows}),并按收到的
- *     `{sessionId, incarnation}` 自算结束了的空间(一份来源:执行器交来的那批行,不再读第二份);
+ *   · `beforeDelete`(终集)—— 删十三张部署表里这批会话的行(下面 {@link deleteDeploymentSessionRows}),并收集被删附件行的字节哈希(提交之后交收尾);
  *   · `audit`(提交前末句)—— 破坏性审计行({@link appendDestructiveAuditRow}),判定时点三格是这一次调用的。
  * 认领判(每只候选根的 `session.beforeCommit`)不在这里:它是会话座的钩(`plugins/session-store-sql.ts` 的 `createSqlSessionWriteHooks`,
  * `retention-delete` 臂),组合座把同一只交给执行器 —— 一处实现。
- * 钩只拿语句面(`query`),从不碰事务本身;库外副作用(回收空间)不在钩里做 —— 执行器提交成功返回之后,组合座把结束了的空间交给 lane。
+ * 钩只拿语句面(`query`),从不碰事务本身;库外副作用(附件字节、完成信箱围栏、会话信箱盒、空间)不在钩里做 —— 执行器提交成功返回之后,
+ * 组合座把删掉的会话树交给收尾(`session-erase.ts`,与在线删除同一只)。
  *
  * 钩表为什么**每次破坏性调用**铸一份(组合座 `plugins/store-backend.ts` 的 `createSqlRetentionExecutor`):审计行的 `{mode, policyDays,
  * fencingToken}` 与 `checkpoint_ctx` 属主门要的域是**这一次调用**的事实,而 core 的钩签名不带它们(`audit` 收 `{domain, op}` 与回执,
@@ -20,7 +20,7 @@
 import type { ManagedRetentionCapability, RetentionReceipt } from "@sema-agent/core";
 import type { SqlDialect, SqlExec } from "./sql-driver.js";
 import { type RetentionAuditContext } from "./retention-lane-store-sql.js";
-import type { EndedSpace } from "../workspace-space.js";
+import type { SessionTreesErased } from "../session-erase.js";
 /**
  * lane 消费的**执行器**面 —— core `ManagedRetentionCapability` 的三方法 + 非契约窄读口 `previewRetention`
  * (audit-only 档的读数源;core 契约无 count 面)+ 声明位。真身 = 组合座 `createSqlRetentionExecutor`。
@@ -50,11 +50,11 @@ export interface RetentionDestructiveInput {
     audit: RetentionAuditContext;
 }
 /**
- * 会话树 sweep 的回执 = core 契约的 `RetentionReceipt` + 本仓一位:`endedSpaces` = 本次删掉的会话树里**结束了的空间**(会话 id + 住客空间键 = 会话化身;
- * 读不出住客的空化身不算),present-iff 非空。lane 把它交给空间的回收座(与会话删除协调器同一只),缓存卷与快照随空间的终结回收。
+ * 会话树 sweep 的回执 = core 契约的 `RetentionReceipt` + 本仓一位:`erased` = 本次删掉的会话树交收尾的那一份(会话 + 删前属主 + 住客、附件字节哈希、
+ * 无出处卸载结果数),present-iff 删掉了至少一棵树。lane 把它交给收尾(`session-erase.ts` 的 `createSessionEraseSettler`,与会话删除协调器同一只)。
  */
 export type RetentionSessionsReceipt = RetentionReceipt & {
-    readonly endedSpaces?: readonly EndedSpace[];
+    readonly erased?: SessionTreesErased;
 };
 /** 装配面必须如实告知的**可选部署表在场性**(+ 执行器的诊断日志座)。 */
 export interface RetentionExecutorOptions {
@@ -72,6 +72,18 @@ export interface RetentionExecutorOptions {
      * 纯内存/local 车道压根没有 SQL 留存腿。
      */
     taskListTables: boolean;
+    /**
+     * 收件箱四表(`mailbox` / `mailbox_message` / `mailbox_consumed` / `mailbox_tombstone`)是否在场。**必填,没有默认值**(同上一条理由)。
+     * 生产上 `boot/stores.ts` 在**任何 SQL 后端**都无条件 ensure 这四张表并接上 SQL 信箱店 ⇒ 装配层照实传 true;为真时执行体在同一个事务里、
+     * 会话行删除之前的最后一腿丢掉被删会话的会话盒(店的 `drop` 同一组语句,`dropMailboxBoxOn`)。
+     */
+    mailboxTables: boolean;
+    /**
+     * workflow 完成信箱在不在用(本部署接了完成信箱 = 有 enqueue 方)。**必填,没有默认值**。为真时执行体在事务里给被删会话立清除围栏
+     * (信箱 `purge` 的同一句 `writeInboxPurgeFenceOn`),提交之后再清一次事务里落下的迟到行({@link sweepLateCompletionRows});为假时没有 enqueue 方、
+     * 也就没有围栏要立(围栏行只由信箱自己的写动词顺手扫,没有信箱就没人扫 ⇒ 不写)。
+     */
+    completionInbox: boolean;
     /** 诊断日志座(可选;交给执行器)。 */
     logger?: {
         info?(msg: string, meta?: unknown): void;
@@ -81,7 +93,27 @@ export interface RetentionExecutorOptions {
 /** 执行器会删东西的那几只成员(钩被告知的 `op`;与执行器钩表的同名型同读 core 的键集)。 */
 type RetentionOp = Exclude<keyof ManagedRetentionCapability, "listRetentionDomains">;
 /**
- * 一次破坏性调用的钩表 + 它收集到的结束了的空间。`call` = 这一次调用(域与判定时点三格)。
+ * 删净之后清一次**迟到的完成信箱行**:执行体事务里立的清除围栏提交之前别的连接看不见,事务进行中入队的完成会落行。按「这只会话 ∧ **删前属主** ∧ 入队时刻不晚于 `atMs`」删
+ * —— 与清除围栏同一把键(会话 × 属主):别的属主的行(同 id 重登记的别人)一行不碰;同一属主同 id 的下一位住客在围栏的窗内入队即被拒(`workflow_inbox_fence`),
+ * 它的行落不下 ⇒ 这一句只可能删到事务进行中漏进来的那几行。发在池上(提交之后);属主一组一句(`owner` 列可空,无主 = `IS NULL`)。
+ */
+export declare function sweepLateCompletionRows(db: SqlExec, dialect: SqlDialect, sessions: readonly {
+    readonly sessionId: string;
+    readonly owner: string | null;
+}[], atMs: number): Promise<void>;
+/**
+ * 部署行那一半的钩(`beforeDelete`:删这批会话在部署十三张表里的行)+ 它收集到的附件字节哈希(提交之后交收尾释放)。两种破坏性调用同一只:
+ * 留存清扫({@link createRetentionDeploymentHooks})与删一只会话(组合座 `createSqlSessionEraser`)。`domain` = 这批会话的域键(`checkpoint_ctx` 属主门读它)。
+ */
+export declare function createSessionRowsHook(dialect: SqlDialect, opts: RetentionExecutorOptions, domain: string): {
+    beforeDelete: (txn: SqlExec, rows: readonly {
+        readonly sessionId: string;
+        readonly incarnation: string | undefined;
+    }[]) => Promise<void>;
+    attachmentShas: () => readonly string[];
+};
+/**
+ * 一次留存破坏性调用的钩表 + 它收集到的附件字节哈希。`call` = 这一次调用(域与判定时点三格)。
  * 钩的形对齐执行器的 `SqlTransactionHooks`(组合座把 `hooks` 交给执行器时由类型系统对表,形一分叉就编译红)。
  */
 export declare function createRetentionDeploymentHooks(dialect: SqlDialect, opts: RetentionExecutorOptions, call: RetentionDestructiveInput): {
@@ -101,26 +133,26 @@ export declare function createRetentionDeploymentHooks(dialect: SqlDialect, opts
             }, receipt: RetentionReceipt) => Promise<void>;
         };
     };
-    endedSpaces: () => readonly EndedSpace[];
+    attachmentShas: () => readonly string[];
 };
 /**
- * 会话树里**部署表**这一半的删除(`beforeDelete` 钩的身体):十一张部署表,发在执行器事务的连接上,先于执行器删自己的表(K4 次序)。
- * 表与相对次序与在线协调器(`boot/session-faces.ts` 的 `purgeSession`)同一条顺序契约;等价性由
- * `retention-e21-equivalence-db-integration.test.ts` 的同种子剩余行集断言钉住(逐表比剩余行,与发语句的先后无关)。
+ * 会话树里**部署表**这一半的删除(`beforeDelete` 钩的身体):十三张部署表,发在执行器事务的连接上,先于执行器删自己的表(K4 次序)。
+ * 两个决定者同调(留存清扫 / 删一只会话的 `eraseSession`)—— 删净会话的行面只有执行器那一段事务体(`session-erase.ts` 头注);表与腿序对
+ * `SESSION_TREE_LEGS`(local 执行体按它迭代各店动词)。
  * 次序的承重理由:
  *   · `task_event` / `task_active` 经 `task_run` 连删 ⇒ 必须排在 `task_run` 删除**之前**;
  *   · `checkpoint_ctx` 的属主门是 `session_meta.owner` 的 EXISTS 子查询 ⇒ 必须在 meta 删除之前(执行器的 meta 删除在本钩之后,天然满足);
  *   · 任务清单:meta 行锁 → item → meta(与 `mutate` 同向的锁序,见该腿注)。
  *
  * 🔴 运行账本(task_event / task_active / task_run)**没有**属主门,按 `session_id` 单键删(F-A,2026-08-17
- * 合并码扫描;与在线协调器同刀改):`task_run.owner` 是**每次提交的 principal**,与会话主会分叉(无主存量
+ * 合并码扫描):`task_run.owner` 是**每次提交的 principal**,与会话主会分叉(无主存量
  * 会话被带 principal 的壳续聊 ⇒ 新行 owner="default")。行级属主门于是只删得掉半棵树,而 `session_meta`
  * 在同一事务里随后就删掉 ⇒ 执行器的候选读从此**永远枚举不到**这些行:它们不是
  * "下一轮再清",是**没有任何清理路径**的孤儿。域隔离不靠这道门承担 —— `ids` 已经是**本域** session_meta
  * 里选出来并 `FOR UPDATE` 锁住的终集,行级门去掉之后越域仍然结构上不可能。
  *
- * `checkpoint_ctx` 的属主门用**域键**(`domain`,`""` = 无主桶)而不是会话的 owner 值 —— 理由逐字见执行器 `purgeSessionTrees` 头注「有意改写」段。
+ * `checkpoint_ctx` 的属主门用**域键**(`domain`,`""` = 无主桶)而不是会话的 owner 值 —— 理由逐字见执行器 `purgeSessionTrees` 头注「属主门读域键」段。
  */
-export declare function deleteDeploymentSessionRows(txn: SqlExec, dialect: SqlDialect, domain: string, ids: readonly string[], opts: RetentionExecutorOptions): Promise<void>;
+export declare function deleteDeploymentSessionRows(txn: SqlExec, dialect: SqlDialect, domain: string, ids: readonly string[], opts: RetentionExecutorOptions): Promise<readonly string[]>;
 export {};
 //# sourceMappingURL=retention-deployment.d.ts.map

package/dist/plugins/retention-deployment.js

@@ -1,7 +1,9 @@
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
 import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
+import { deleteSessionApprovalRows } from "./approval-ask-store-sql.js";
 import { retentionDomainWhere, retentionIdSet } from "./retention-sql.js";
 import { appendDestructiveAuditRow, lockHoldSentinel } from "./retention-lane-store-sql.js";
+import { writeInboxPurgeFenceOn } from "./workflow-run-store-sql.js";
 function auditActionOf(op) {
     switch (op) {
         case "expireCheckpoints":
@@ -12,22 +14,37 @@ function auditActionOf(op) {
             return "deleted_tool_results";
     }
 }
-function endedSpacesOf(rows) {
-    return rows.flatMap((r) => (r.incarnation === undefined ? [] : [{ sessionId: r.sessionId, spaceKey: r.incarnation }]));
+export async function sweepLateCompletionRows(db, dialect, sessions, atMs) {
+    const byOwner = new Map();
+    for (const { sessionId, owner } of sessions)
+        byOwner.set(owner, [...(byOwner.get(owner) ?? []), sessionId]);
+    for (const [owner, ids] of [...byOwner].sort(([a], [b]) => String(a).localeCompare(String(b)))) {
+        const s = retentionIdSet(dialect, "session_id", [...ids].sort(), 1);
+        const next = (k) => (dialect === "mysql" ? "?" : `$${s.params.length + k}`);
+        const ownerSql = owner === null ? "owner IS NULL" : `owner = ${next(1)}`;
+        const at = next(owner === null ? 1 : 2);
+        await db.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql} AND ${ownerSql} AND enqueued_at_ms <= ${at}`, [...s.params, ...(owner === null ? [] : [owner]), atMs]);
+    }
+}
+export function createSessionRowsHook(dialect, opts, domain) {
+    const shas = [];
+    return {
+        beforeDelete: async (txn, rows) => {
+            shas.push(...(await deleteDeploymentSessionRows(txn, dialect, domain, rows.map((r) => r.sessionId), opts)));
+        },
+        attachmentShas: () => shas,
+    };
 }
 export function createRetentionDeploymentHooks(dialect, opts, call) {
     if (!call.audit) {
         throw new Error(`retention: refusing a destructive call in domain ${JSON.stringify(call.domain)} with no audit context — every destructive retention ` +
             `transaction must persist its {mode, policyDays, fencingToken} alongside the deletion. Pass \`audit\` from the sweep lane's current round.`);
     }
-    const ended = [];
+    const rowsHook = createSessionRowsHook(dialect, opts, call.domain);
     const hooks = {
         retention: {
             holdLock: async (txn, at) => (await lockHoldSentinel(txn, dialect, at.domain)) ? "held" : "proceed",
-            beforeDelete: async (txn, rows) => {
-                await deleteDeploymentSessionRows(txn, dialect, call.domain, rows.map((r) => r.sessionId), opts);
-                ended.push(...endedSpacesOf(rows));
-            },
+            beforeDelete: rowsHook.beforeDelete,
             audit: async (txn, at, receipt) => appendDestructiveAuditRow(txn, dialect, {
                 domain: at.domain,
                 action: auditActionOf(at.op),
@@ -38,7 +55,7 @@ export function createRetentionDeploymentHooks(dialect, opts, call) {
             }),
         },
     };
-    return { hooks, endedSpaces: () => ended };
+    return { hooks, attachmentShas: rowsHook.attachmentShas };
 }
 export async function deleteDeploymentSessionRows(txn, dialect, domain, ids, opts) {
     const q = (mysql, pg) => (dialect === "mysql" ? mysql : pg);
@@ -55,11 +72,18 @@ export async function deleteDeploymentSessionRows(txn, dialect, domain, ids, opt
         const s = set("session_id", 1);
         await txn.query(`DELETE FROM task_run WHERE ${s.sql}`, [...s.params]);
     }
+    await deleteSessionApprovalRows(txn, dialect, ids);
     {
         const s = set("checkpoint_ctx.session_id", 1);
         const w = retentionDomainWhere(dialect, "sm.owner", domain, 2);
         await txn.query(`DELETE FROM checkpoint_ctx WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint_ctx.session_id AND ${w.sql})`, [...s.params, ...w.params]);
     }
+    let attachmentShas = [];
+    if (opts.taskAttachmentTable) {
+        const s = set("session_id", 1);
+        const { rows } = await txn.query(`SELECT sha256 FROM task_attachment WHERE ${s.sql} FOR UPDATE`, s.params);
+        attachmentShas = rows.map((r) => String(r.sha256));
+    }
     for (const [table, col] of [
         ["resume_anchor", "session_id"],
         ["approval_exemption", "session_id"],
@@ -81,8 +105,15 @@ export async function deleteDeploymentSessionRows(txn, dialect, domain, ids, opt
         }
     }
     {
+        if (opts.completionInbox) {
+            const owner = domain === "" ? null : domain;
+            const now = Date.now();
+            for (const id of [...ids].sort())
+                await writeInboxPurgeFenceOn(txn, dialect, id, owner, now);
+        }
         const s = set("session_id", 1);
         await txn.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql}`, s.params);
     }
+    return attachmentShas;
 }
 //# sourceMappingURL=retention-deployment.js.map

package/dist/plugins/run-preview-m45.d.ts

@@ -0,0 +1,11 @@
+/** SQL 腿的粗筛:闭集标签各一个 `LIKE` 前缀(`<tag%`;标签名里没有 `%` / `_` / 转义字符)。粗筛中、精判不中的行(`<system-reminderish …`)不动。 */
+export declare const RUN_PREVIEW_COARSE_PREFIXES_M45: readonly string[];
+/** M45 选不选这一列值:以闭集开标签起头。 */
+export declare function startsWithInjectedOpenTagM45(value: string): boolean;
+/**
+ * M45 对这一列值的新值:不选 ⇒ `undefined`(不动);选中 ⇒ 剥到不动点,仍以开标签起头 ⇒ `""`。
+ * 终止:第一遍之后的值不长于 120;此后每一遍要么逐字节不变(不动点)要么严格变短(剥块 / trim / 截都只删,脱敏对自己的产出不再命中),
+ * 所以遍数不超过「首遍结果的长度 + 1」—— 循环上界就写这个数,走出循环的那一臂不可达。
+ */
+export declare function normalizedRunPreviewM45(value: string): string | undefined;
+//# sourceMappingURL=run-preview-m45.d.ts.map

package/dist/plugins/run-preview-m45.js

@@ -0,0 +1,19 @@
+import { INJECTED_BLOCK_TAGS, buildRunObjectivePreview } from "../user-authored-text.js";
+const INJECTED_OPEN_TAG_HEAD_M45 = new RegExp(`^<(?:${INJECTED_BLOCK_TAGS.join("|")})(?=[\\s>/]|$)`);
+export const RUN_PREVIEW_COARSE_PREFIXES_M45 = INJECTED_BLOCK_TAGS.map((tag) => `<${tag}%`);
+export function startsWithInjectedOpenTagM45(value) {
+    return INJECTED_OPEN_TAG_HEAD_M45.test(value);
+}
+export function normalizedRunPreviewM45(value) {
+    if (!startsWithInjectedOpenTagM45(value))
+        return undefined;
+    let cur = buildRunObjectivePreview(value);
+    for (let pass = 0, bound = cur.length + 1; pass <= bound; pass += 1) {
+        const next = buildRunObjectivePreview(cur);
+        if (next === cur)
+            return startsWithInjectedOpenTagM45(cur) ? "" : cur;
+        cur = next;
+    }
+    return "";
+}
+//# sourceMappingURL=run-preview-m45.js.map

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

@@ -2,15 +2,22 @@ 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 ClaimFenced, type CreateRunOutcome, type FencedRun, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
+import { type RunStallWiring, type ClaimFenced, type CreateRunOutcome, type FencedRun, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } 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 type { RunRecord, RunEvent, LatestRunRef } from "./store-contracts.js";
+/**
+ * 一次性迁移 **M44 改写半场**读 `task_run.result` 的那一口(窗口见 `plugins/one-time-migrations.ts` 登记表;随 M44 一起删):与店的读腿同一只解码
+ * ({@link decodeResultColumn},投影须经 `jsonColumnText`);读不出 ⇒ `"unreadable"`(迁移跳过那一行、码列不动 —— 店的读腿对它照旧响亮拒)。
+ */
+export declare function decodeRunResultCellM44(v: unknown, taskId: string): PersistedTaskResult | null | "unreadable";
 export declare class SqlRunStore {
     readonly db: SqlDriver;
-    /** `db` 公开只读:会话认领住在这只池背后的库里,写在认领栅栏里的店(workflow 子代决定行)读写都走它 —— 那只店的池只有这一处来源。 */
-    constructor(db: SqlDriver);
+    private readonly stall;
+    /** `db` 公开只读:会话认领住在这只池背后的库里,写在认领栅栏里的店(workflow 子代决定行)读写都走它 —— 那只店的池只有这一处来源。
+     *  `stall` = 落死亡判决的窗与计数(构造时拿到;生产装配 = `store-backend.ts` 递活配置的 getter,见 {@link RunStallWiring})。 */
+    constructor(db: SqlDriver, stall?: RunStallWiring);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** Dup-key classification — single owner in `sql-errors.ts` ([ref] P1-①; the old local form read
@@ -19,8 +26,10 @@ export declare class SqlRunStore {
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
      *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */
     private json;
-    /** Run statements atomically; rolls back on failure. */
+    /** Run statements atomically on a pooled connection; rolls back on failure. */
     private tx;
+    /** Run statements atomically on a connection the caller already holds (`createRun`'s claim-conflict arm: never borrow a second one); rolls back on failure. */
+    private txOn;
     /**
      * Create a run, but only if the session has no other active run (double-text guard) and no submission key
      * of this request already names a row (submission idempotency) — **atomic win or observe**.
@@ -52,6 +61,28 @@ export declare class SqlRunStore {
      * 续跑与 wake 复用 checkpoint 的会话 —— 所以零行只在「受理之后被删」这一种竞争里出现。
      */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
+    /** {@link createRun} 的一次建行事务(在调用方借来的那只连接上;结局四形之一,失败回滚后原样抛)。 */
+    private createRunOn;
+    /**
+     * 认领冲突的持有者落判决(`createRun` 唯一调用;同一只连接,自动提交读 → 单行落判决事务):持有者行 `due` ⇒ 落(命中 ⇒ `true`,调用方再认领一次);
+     * `live` / 停驻 / 终局 / 表外词 / 行不在 ⇒ `false`(照答冲突)。只读判决要的两列(不过结果列的解码:一条坏结果行不许把 409 变成 500)。
+     * 落判决写失败 ⇒ F 类留痕、`false`(照答冲突,收割器下一拍补)。
+     */
+    private settleDueHolderOn;
+    /**
+     * 🔴 **死亡判决的那一句**(收割器与两处单行落判决共用一只语句构造):`running ∧ updated_at < cutoff` ⇒ `failed` / `result = NULL` / {@link RUN_STALLED_ERROR} /
+     * `error_code = run.stalled`,同一事务放认领。两种作用域:
+     *  · **全表**(`taskId` 缺席,收割器):放掉每条非活非停驻行的认领 + 孤儿认领(语义同修前);
+     *  · **单行**(`AND task_id = ?`,观察口 / 认领冲突):只有命中 1 行才 `DELETE FROM task_active WHERE task_id = ?` —— 心跳或停驻抢先赢了 CAS ⇒ 0 行 ⇒ 认领不动。
+     * 取锁序 `task_run` → `task_active`(与栅栏 / 终局写 / 收割同序)。调用方持事务(`conn` 已 `begin`)。交回命中行数。
+     */
+    private landStallVerdicts;
+    /**
+     * 🔴 **观察口**(落判决的三处之一):调用方**已经读到、已经过了属主门**的那条行(授权在判决之前:外人拿着别人的 run id 得 404 且什么都不变)。
+     * 判决不是 `due` ⇒ 原样交回、零 I/O;`due` ⇒ 单行落判决(一个事务)⇒ 事务提交之后**当前读**一次(自动提交 SELECT,不在可能拿着旧快照的事务里读)⇒ 交回。
+     * 落判决写失败 ⇒ F 类留痕({@link RUN_STALL_VERDICT_UNLANDED_TAG})+ 行原样交回(收割器下一拍补)。谁调它 = 路由闭集表 `RUN_STATE_FACES`(`http/owner-access.ts`)。
+     */
+    observeRun(row: RunRecord): Promise<RunRecord>;
     /** run 行预览的**写一次补写**(腿上装着 prompt 屏时建行不写预览,引擎交付可写的那一份之后补;律的属主 = `run-acceptance.ts`):
      *  列仍是 NULL(没建过预览)才写 —— 建行写过的、已经补过的一律不动,所以补写永远盖不掉任何一份既有预览。不碰 `updated_at`(预览不是状态变化,
      *  收割与列表的时序都不该因它移动)。行不在 ⇒ 0 行,无事。PG 臂过 `pgSanitizeText`(与建行写同一条:预览是模型可控标量)。 */
@@ -81,8 +112,10 @@ export declare class SqlRunStore {
      *  running instance calls this on a timer so a long-but-alive turn (e.g. a subagent that emits no
      *  parent events for minutes) is not mistaken for a dead instance.
      *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}); the heartbeat is
-     *  always issued by the owning instance with the run's own owner, so this only narrows, never blocks. */
-    heartbeat(taskId: string, owner: string | null): Promise<void>;
+     *  always issued by the owning instance with the run's own owner, so this only narrows, never blocks.
+     *  🔴 **交回「行还在 running 吗」**:持有者拿它决定停不停自己的腿 —— 行已被判死(观察口 / 认领冲突 / 收割器)⇒ `false` ⇒ 持有者中止(判死一条行拦不住它的执行者,
+     *  这一答补上那一半)。刷新命中 ⇒ `true`;没命中 ⇒ 再读一次状态(属主不符的心跳今天就刷不上,它的行由收割器按窗判;只在行真的不在跑时才答 `false`)。 */
+    heartbeat(taskId: string, owner: string | null): Promise<boolean>;
     /** Append one event. A single INSERT — `updated_at` (liveness) is owned by `heartbeat`, so there
      *  is no second statement to keep atomic here. */
     appendEvent(taskId: string, seq: number, type: LedgerEventType, data: unknown): Promise<void>;
@@ -224,12 +257,12 @@ export declare class SqlRunStore {
     /**
      * [ref] —— 这个会话**最近一条腿**的窄指针(`/mcp` 面板的 `lastLegMcp` 与任何「上一条 run 是谁」的读面共用)。
      *
-     * 排序口径与 {@link listSessions} 的 `rn=1` 窗函数**逐字同一句**(`created_at DESC, task_id DESC`)——
+     * 排序口径与会话店列表投影的 `rn=1` 窗函数**逐字同一句**(`created_at DESC, task_id DESC`,`session-store-sql.ts` 的 `selectListRows`)——
      * 两处答的是同一个问题「哪一条是最新的」,口径分叉会让列表面的 `lastRunId` 与本读口指向不同的 run。
      * 走的也是同一条索引路径(`idx_task_run_session_status` 的 `session_id` 前缀),所以**不新加索引**:
      * 会话内行数有界,前缀定位之后的排序只在这一小撮行上。
      *
-     * 两方言只差占位符(动态子句为零,不像 listRuns/listSessions 那样需要各自的构造器臂)。
+     * 两方言只差占位符(动态子句为零,不像 listRuns 那样需要各自的构造器臂)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
     /**
@@ -240,24 +273,6 @@ export declare class SqlRunStore {
      * 结果列走 {@link rowToRun} 同一只解码口与同一个失败方向(读不出 ⇒ 拒,不把一条结了的腿读成「没有观测」)。
      */
     latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
-    /** GET /v1/sessions (CC /resume picker): DISTINCT sessions newest-first by last activity, keyset-paginated on
-     *  (last_activity, session_id). Aggregates task_run by session_id — one window pass picks the latest run per
-     *  session (rn=1) for the preview/status and rolls up first/last/count. Owner-scoped when set (the per-user view).
-     *  Bounded by per-tenant data today; a denormalized session table is the optimization if it ever goes hot.
-     *
-     *  🔴 Same builder divergence as {@link listRuns} — see its header note. */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
-    /** Shared row→summary mapper for listSessions (byte-identical between dialects). */
-    private rowToSession;
     /**
      * E21 (§0.5 session delete) — purge the service-owned RUNS LEDGER for one session: task_event (the replayable
      * event log), task_active (the single-active-run claim), and task_run (the run rows). Idempotent — returns
@@ -266,46 +281,18 @@ export declare class SqlRunStore {
      * their stores — this method owns only the runs-ledger tables. Done in one TX so a partial purge can't leak a
      * task_active claim with no run row (a permanent session lock).
      *
-     * 🔴 Scoped by `session_id` ALONE — deliberately NO per-row owner guard (F-A, 2026-08-17 合并码扫描;同一条
-     * 判断 `boot/session-faces.ts` 的 anchors 腿早就写过,run 账本这条腿当时没跟上):`task_run.owner` 是**每次
-     * 提交的 principal**,它与会话的 canonical owner 会分叉 —— 一条 `session_meta.owner = NULL` 的存量会话被
-     * 带 principal 的壳续聊后(REQUIRE_PRINCIPAL=false),新 run 行的 owner 是 `"default"`,而 DELETE 路由递进来
-     * 的是**会话行**的 owner(NULL)。行级 null-safe 属主门(`<=>` / `IS NOT DISTINCT FROM`)于是只删得掉 NULL
-     * 那批,具名那批连同它们的 task_event 全部存活 —— 而 `session_meta` 已经删了,留存腿的 sessionCandidates
-     * 再也枚举不到这棵树 ⇒ 孤儿行**没有任何清理路径**,路由却回 `{deleted:true}`。那就是一次**报成成功的
-     * 右删失效**(anchors 腿的注逐字写着这句)。删除决策的属主门在**路由层**(DELETE /v1/sessions/:id 先
-     * 经会话店唯一的按 id 读 `headOf` 取属主再比对 scope,fleet-wide 臂同门),本方法的唯一生产调用点是那条路由后面的 purge 协调器。
+     * 🔴 Scoped by `session_id` ALONE — deliberately NO per-row owner guard (F-A, 2026-08-17 合并码扫描):`task_run.owner` 是**每次提交的 principal**,与会话的
+     * canonical owner 会分叉(无主存量会话被带 principal 的壳续聊 ⇒ 新 run 行 owner `"default"`),行级属主门只删得掉一半、把具名行留成孤儿而路由答 `{deleted:true}`。
      *
-     * 🔴 **化身围栏**(`expectedSessionOwner`;codex 交叉复审 R1-[high],验真后修)—— 属主门下来了,但会话
-     * **身份**必须在同一个事务里重新确认。会话 id 由调用方自选、且删除之后**可被别人重新登记**
-     * (`register` 是 INSERT … ON DUPLICATE KEY / ON CONFLICT,老行没了就是一条新行,新 owner):于是
-     * 「路由已按 `headOf` 读到的属主验权」这句话在两只并发 purge 交错时会过期 —— A 与 A' 同时通过属主门,A' 跑完整条
-     * purge 把 meta 删掉,租户 B 用同一个 uuid 重新登记并跑完一次 run,慢半拍的 A 才走到这里 ⇒ 按 session_id
-     * 单键删就把 **B 的**行删了(修前的行级属主门恰好挡住这一形,因为 B 的行 owner≠A 的会话主)。
-     * ⇒ 事务头部 `SELECT owner FROM session_meta WHERE session_id = ? FOR UPDATE`,行不在或 owner 与路由验过的
-     * 那一位不符 ⇒ **一行不删**回 `{removed:0}`(诚实:属于调用方的那个化身已经不在了;协调器据此回
-     * `{deleted:false}`,不会拿别人的行数冒充成功)。锁序与留存腿逐字一致(先 session_meta 后 task_*),
-     * 不引入新的死锁环;锁在本事务提交时释放,其后的 checkpoint / history 两腿各自带属主门。
-     * ⚠️ 本围栏只有 SQL 双生做得到 —— File/Memory 孪生的账本里没有 session_meta(local 车道的会话表在另一只
-     * 店里),它们的同名参数因此只作**契约对齐**用,真围栏由协调器那条 pre-delete 复读 + local 数据根的
-     * 独占 BootLock(一个数据根恒一个进程)承担;逐字见 memory-run-store 的同名方法注。
-     *
-     * 🔴 Active-run re-assert INSIDE the TX (adversarial-review LOW — TOCTOU): the route's pre-purge `getActiveTaskId`
-     * 409 check is a non-transactional SELECT — a concurrent createRun can claim `task_active(session_id)` in the
-     * window between that check and this purge, then have its LIVE rows deleted here. So we re-take the no-active-run
-     * invariant transactionally: `SELECT task_id FROM task_active WHERE session_id=? FOR UPDATE` at the TOP of the TX.
-     * `FOR UPDATE` serializes against createRun's unique-key INSERT on the SAME session_id (createRun either already
-     * holds the row — we see it and abort — or blocks on our lock until commit, then fails its own unique-key claim
-     * against the now-absent row). If a claim exists we return `{ active }` (the route maps it to 409) and delete
-     * NOTHING. Returns `{ removed }` on a clean purge.
+     * **不判属主、不判认领**(会话三态,`src/session-deletion.ts`):本方法唯一的生产调用点是删除协调器,它在**围栏**之后才调 —— 围栏在根行锁里判过属主与「没有认领」、
+     * 写下了在删令牌;在删期间规则 L(认领事务锁根行读令牌)不让认领落下,于是这里没有可判的东西。协调器在调之前问过令牌仍是它的(被接管 ⇒ 不调)。
+     * 此前这里在同一事务里锁根行复核属主、锁定读 `task_active` 判认领 —— 删除路四处判活中的两处;判过之后到删行之前不挡认领,正是会话行被重建成无主行那一窗的根。
      *
      * 🔴 The multi-table DELETEs are dialect-divergent SQL FORMS (not just placeholders): TiDB's
      * `DELETE te FROM te JOIN tr ON …` vs PG's `DELETE FROM te USING tr WHERE …`.
      */
-    deleteBySession(sessionId: string, expectedSessionOwner: string | null): Promise<{
+    deleteBySession(sessionId: string): Promise<{
         removed: number;
-    } | {
-        active: string;
     }>;
     /** Per-door usage rollup (center systems-UI input): COUNT by (source,status) since a cutoff. Reads the
      *  denormalized columns only — no JSON parsing; served by full scan bounded by created_at (small windows). */
@@ -331,12 +318,10 @@ export declare class SqlRunStore {
     /** Events with seq strictly greater than `afterSeq` (use 0 for the whole stream). */
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
     /**
-     * Mark stale `running` rows as failed (best-effort recovery for runs whose instance died), then
-     * free any active-run claim whose run is no longer running (reaped here, or a terminal whose
-     * DELETE was lost). `olderThanMs` must exceed the longest expected gap between a run's events
-     * (each event refreshes `updated_at`), else a healthy slow run is wrongly reaped.
+     * 收割器(落判决的三处之一,全表形):心跳过期的 `running` 行翻 `failed`(`run.stalled`)、放掉终局行与孤儿的认领 —— 语句与观察口 / 认领冲突同一只
+     * ({@link landStallVerdicts})。窗读构造时拿到的那只 getter(`REAP_RUN_STALE_SEC`,判活窗只有这一个来源)。
      */
-    reapStale(olderThanMs: number): Promise<number>;
+    reapStale(): Promise<number>;
     /**
      * Durable F4 expiry: an approval parked beyond `olderThanMs` (the approval TTL) was never answered → fail
      * the run + RELEASE its task_active (unlock the session). Mirrors the checkpoint reaper's CAS-expire (≈ deny);
@@ -352,6 +337,9 @@ export declare class SqlRunStore {
      * opening a two-runs-one-session window. The NOT-EXISTS-pending guard (same shape as
      * failSuspendedWithExpiredCheckpoint) means this only ever reaps a row whose checkpoint is already gone/expired.
      *
+     * 卡与 run 按**归属列** `checkpoint.host_session_id` 连(兑现这张卡的那条 run 的会话;cascade 的级上卡归调用方的会话 —— 卡自己的 `session_id`
+     * 是级的对话,连不上这条 run)。两条收割腿与本地孪生的探针同一读法(`plugins/checkpoint-index-columns.ts` 的 `hostSessionOf`)。
+     *
      * 🔴 Alias-qualification divergence (kept EXPLICIT, never "fixed" to match): TiDB's SET clause QUALIFIES with
      * `tr.` (`SET tr.status = …`); PG's SET clause must NOT be alias-qualified (`SET status = …` — PG rejects
      * `SET a.col`). Both WHERE clauses use the `tr.` alias.
@@ -378,10 +366,10 @@ export declare class SqlRunStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBRunStore extends SqlRunStore {
-    constructor(pool: MySqlPool);
+    constructor(pool: MySqlPool, stall?: RunStallWiring);
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgRunStore extends SqlRunStore {
-    constructor(pool: PgPool);
+    constructor(pool: PgPool, stall?: RunStallWiring);
 }
 //# sourceMappingURL=run-store-sql.d.ts.map