@sema-agent/server 7.142.0 → 7.143.0

package/dist/plugins/org-delivery-quota-store.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteFile, ensureDir } from "@sema-agent/core";
 import { mysqlDriver, pgDriver, sqlDbNowMs } from "./sql-driver.js";
-import { isDeadlockError } from "./sql-errors.js";
+import { retryOnDeadlock } from "./sql-errors.js";
 import { alignedWindow } from "../observability/cost-quota.js";
 export const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
 export const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
@@ -122,7 +122,6 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
         atomicWriteFile(this.tmpDir, this.path, `${JSON.stringify(snapshot)}\n`);
     }
 }
-const DEADLOCK_RETRY_LIMIT = 3;
 export class SqlOrgDeliveryQuotaStore {
     db;
     constructor(db) {
@@ -138,16 +137,7 @@ export class SqlOrgDeliveryQuotaStore {
         return this.inTx(ORG_DELIVERY_RECIPIENT_QUOTA_TABLE, policy, (conn, at) => this.takeIn(conn, fromScope, toScope, at, policy));
     }
     async inTx(table, policy, body) {
-        for (let tries = 0;; tries++) {
-            try {
-                return await this.inTxOnce(table, policy, body);
-            }
-            catch (err) {
-                if (tries < DEADLOCK_RETRY_LIMIT && isDeadlockError(this.db.dialect, err))
-                    continue;
-                throw err;
-            }
-        }
+        return retryOnDeadlock(this.db.dialect, () => this.inTxOnce(table, policy, body));
     }
     async inTxOnce(table, policy, body) {
         const at = quotaWindowStart(await sqlDbNowMs(this.db, table), policy.windowMs);

package/dist/plugins/park-commit-watch.d.ts

@@ -28,7 +28,7 @@ import type { CheckpointStore } from "@sema-agent/core";
 /**
  * 一只**已提交**的审批停车行说它握着哪些调用(停车行自己的陈述,原样,不是推断):
  *  · `sessionId` —— 行停住的会话 `cp.sessionId`(执行这次调用的会话:委派 / 后台子代的行落在**子会话**上)。core 铸行用的是 prepare-task 的
- *    同一个 `sessionId`,它也是同一次调用的 ask 上的 `sourceTaskId`(`askSourceIdentity`)⇒ 订阅者按**相等**配,不做别名(车 SO:
+ *    同一个 `sessionId`,它也是同一次调用的 ask 上的 `sourceSessionId`(`askSourceIdentity`)⇒ 订阅者按**相等**配,不做别名(车 SO:
  *    调用 id 只在 run 内唯一,宿主会话若当子代的等价别名,宿主停车行会冒充子代的提交);
  *  · `toolCallIds` —— 停在门前的那只调用(`pendingAction.toolCallId`)∪ 同一条助手消息里**尚未执行**的调用
  *    (`batchToolCallIds − completedCallIds`,core d.ts「#k+1..N are still pending」):那些调用随这一行一起被持久挂起,

package/dist/plugins/permission-rule-store-file.d.ts

@@ -2,7 +2,7 @@ import { FileDurableRulePartitionProvider, type RuleApprovalRecord, type RuleApp
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import type { Logger } from "../observability/logger.js";
-import { type RuleCandidate } from "@sema-agent/core";
+import { type RuleCandidate, type RuleOwner } from "@sema-agent/core";
 /**
  * `RuleApprovalRecordStore` 的 File 形。
  *
@@ -26,6 +26,13 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
     get(id: string): Promise<RuleApprovalRecord | StaleRuleApprovalRecord | undefined>;
     create(record: RuleApprovalRecord): Promise<void>;
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
+    /**
+     * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)在 File 店能叫出名字的桶:本店**导入记录**点名过的每一个属主(去重)。
+     * 引擎 File 分区的桶文件按属主名的单向摘要命名、分区后端没有列桶口,记录是本店唯一叫得出桶属主的地方(SQL 店直接列规则表;File 侧的缺口见
+     * `imported-layer-root-retirement.ts` 头注)。上一形的记录(Stale 信封)读不出种类 ⇒ 属主读得出就算上(多读一只桶零写,少读一只会漏)。
+     * 损坏闸合着 ⇒ 抛(读不全记录就叫不全桶;与本面其余口同一条 fail-closed)。
+     */
+    importRecordOwners(): Promise<RuleOwner[]>;
     /** 与 SQL 侧同名方法同义(超帽拒绝时收掉 `prepareCcImport` 已落盘的那条 pending 记录)。
      *  `state === "pending"` 是硬的:已确认/已兑付的记录是一次真人同意的审计事实。 */
     discardPendingRecord(recordId: string): Promise<boolean>;
@@ -87,6 +94,8 @@ export declare class FileRuleImportTicketStore {
      *  那一条:过期只挡开始一次兑付,不挡做完一次已经开始的)。抢到之后**换一代认领**。 */
     reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
 }
+/** 三面束在数据根下的目录名(唯一一处;束在第一次装配时建它 —— 没开过规则店的数据根下没有它)。 */
+export declare const FILE_PERMISSION_RULE_DIR = "permission-rules";
 /** local 车道的三面束 + 生命周期。`dispose()` 释放 core File durable 分区 provider 的写锁(见 {@link createFilePermissionRuleStores})。 */
 export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
     durable: FileDurableRulePartitionProvider;

package/dist/plugins/permission-rule-store-file.js

@@ -4,7 +4,7 @@ import { readdirSync } from "node:fs";
 import { performance } from "node:perf_hooks";
 import { FileDurableRulePartitionProvider, AppendLog, ensureDir, } from "@sema-agent/core";
 import { z } from "zod";
-import { DurableRuleScopeSchema, RuleOfferColumn, buildRulePayloadHash, recordOwnerOf, refusedOwnerSentence } from "./permission-rule-store-sql.js";
+import { DurableRuleScopeSchema, IMPORT_RECORD_KIND, RuleOfferColumn, buildRulePayloadHash, recordOwnerOf, refusedOwnerSentence } from "./permission-rule-store-sql.js";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, readRuleOwner } from "@sema-agent/core";
 const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
@@ -173,6 +173,18 @@ export class FileRuleApprovalRecordStore {
         this.rows.set(id, structuredClone(next));
         return true;
     }
+    async importRecordOwners() {
+        this.gate.assertUsable();
+        const owners = [];
+        for (const r of this.rows.values()) {
+            if (!("staleSchema" in r) && r.kind !== IMPORT_RECORD_KIND)
+                continue;
+            const owner = recordOwnerOf(r);
+            if (owner !== undefined)
+                owners.push(owner);
+        }
+        return owners;
+    }
     async discardPendingRecord(recordId) {
         this.gate.assertUsable();
         const cur = this.rows.get(recordId);
@@ -319,8 +331,9 @@ export class FileRuleImportTicketStore {
         return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
     }
 }
+export const FILE_PERMISSION_RULE_DIR = "permission-rules";
 export function createFilePermissionRuleStores(root, opts) {
-    const dir = join(root, "permission-rules");
+    const dir = join(root, FILE_PERMISSION_RULE_DIR);
     ensureDir(dir);
     const durable = opts?.onError ? new FileDurableRulePartitionProvider(dir, opts.onError) : new FileDurableRulePartitionProvider(dir);
     const approvals = new FileRuleApprovalRecordStore(dir, opts?.warn);

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -158,6 +158,8 @@ export declare function buildRuleBucketChecksum(body: {
     /** 这只桶的行写在哪一版规则文法里(`SESSION_RULES_GRAMMAR` 的数);缺席 = 存量无戳行(列 NULL)。 */
     grammar?: number;
 }): string;
+/** 一只桶要的全部 SQL 能力:方言 + 一只执行口(池,或一次性迁移握着锁的那一条连接 —— M36 在那条连接上经同一只写面落墓碑)。 */
+type BucketSql = Pick<SqlDriver, "dialect" | "query">;
 /**
  * SQL 双方言的 {@link DurableRulePartitionProvider} —— [ref] 里的 **durable 分区后端**
  * (`user` + `project` 两源的 OR-Set CRDT),**不是**引擎接缝本身:
@@ -170,7 +172,7 @@ export declare function buildRuleBucketChecksum(body: {
 export declare class SqlDurableRulePartitionProvider implements DurableRulePartitionProvider {
     private readonly db;
     private readonly now;
-    constructor(db: SqlDriver, now?: () => number);
+    constructor(db: BucketSql, now?: () => number);
     forPrincipal(principal: string | undefined): DurableRulePartition;
     forLocalOwner(): DurableRulePartition;
 }
@@ -182,6 +184,33 @@ export declare function recordOwnerOf(record: {
     readonly owner?: unknown;
     readonly principal?: unknown;
 }): RuleOwner | undefined;
+/**
+ * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)要读的桶:**规则表里的每一只桶**(按 `owner_key` 分页,与 M11 同一只走法)。
+ * 不从审批记录推:收编腿把规则桶整桶改键到新身份、而审批史按 D2 留在旧身份名下(`src/adoption/plan.ts` 的 `permission_rule#owner_key` 腿与
+ * `permission-rule-approval-history` 一员)—— 从记录推出的属主集在收编之后漏掉新桶。属主读法只有引擎的 `readRuleOwner`(与本店读口同一只);
+ * 读不出属主的行不点名任何可解析的桶(读腿同样解析不到它),不返回。`db` 是池或迁移握锁的那一条连接。
+ */
+export declare function listRuleBucketOwners(db: Pick<SqlDriver, "dialect" | "query">): Promise<RuleOwner[]>;
+/**
+ * 取 dot 那一步「建行之后、读行之前」这只桶被并发删掉了(另一只副本删桶恰落在这一窗里)。具名类 ⇒ 调用方按类判(M36 退役读作「无可退役」),不按文案。
+ */
+export declare class RuleBucketVanishedError extends Error {
+    readonly ownerKey: string;
+    constructor(ownerKey: string);
+}
+/** 这只抛出物是不是本店的「桶在写它的那一步里没了」({@link RuleBucketVanishedError})。 */
+export declare function isSqlBucketVanished(e: unknown): boolean;
+/**
+ * 这只读桶抛出物是不是**本店读腿的整桶拒** —— 判的是读腿({@link SqlDurableRulePartition} 的 `list` / 写的读基)**真往外交的**那两类,不是判官内部的抛出形:
+ *  · {@link BucketRefusedError} —— 判官四道(文法戳 / 指纹 / 行的 behavior / 引擎校验器)的拒;
+ *  · {@link StoreCorruptError} —— 某只 JSON 列的体读不出(`not-json` / `malformed`),读腿在 {@link refusingUnreadableColumns} 把判官抛的列错误折成的店拒绝契约。
+ * 两类都是这一行的确定性判决:原样再读也读不出,读腿对它同样整桶拒(零规则),所以它什么都不放行。
+ * 别的抛出物**不是**这一类:连接 / 超时 / 权限(一次读失败证明不了以后也读不出);以及仍以 {@link SqlJsonColumnError} 穿出读腿的唯一一形 `not-text`
+ * (列没按文本投影:读腿与解码点漂了,是码缺陷不是坏数据 —— 按列错误类判它会把一次码漂读成「这只桶坏了」)。
+ */
+export declare function isSqlBucketRefusal(e: unknown): boolean;
+/** 导入记录的种类词(引擎闭集 `RULE_APPROVAL_KINDS` 的一员;`imported-cc` 出处由它派生)。 */
+export declare const IMPORT_RECORD_KIND = "import";
 /** 写口拒句(两只店同一句):属主引擎读不出,记录不落。 */
 export declare function refusedOwnerSentence(recordId: string): string;
 /**
@@ -542,4 +571,5 @@ export interface PermissionRuleStores {
     reapExpired(nowMs: number): Promise<number>;
 }
 export declare function createSqlPermissionRuleStores(db: SqlDriver, now?: () => number): PermissionRuleStores;
+export {};
 //# sourceMappingURL=permission-rule-store-sql.d.ts.map

package/dist/plugins/permission-rule-store-sql.js

@@ -6,7 +6,7 @@ import { isMissingColumnError } from "./sql-errors.js";
 import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError, StoreCorruptError } from "./sql-json-column.js";
 import { redactSecrets } from "../trace/redact.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
@@ -508,7 +508,7 @@ class SqlDurableRulePartition {
                 const { rows } = await this.db.query(this.q(`SELECT actor, counter, grammar FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, grammar FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
                 const row = rows[0];
                 if (row === undefined)
-                    throw new Error(`permission_rule bucket ${this.ownerKey} vanished while minting a dot`);
+                    throw new RuleBucketVanishedError(this.ownerKey);
                 readBucketStamp(this.ownerKey, row.grammar);
                 const cur = Number(row.counter);
                 const next = cur + 1;
@@ -593,6 +593,39 @@ export class SqlDurableRulePartitionProvider {
 export function recordOwnerOf(record) {
     return readRuleOwner(record.owner ?? { kind: "principal", principal: record.principal });
 }
+export async function listRuleBucketOwners(db) {
+    const owners = [];
+    let after = "";
+    for (;;) {
+        const { rows } = await db.query(db.dialect === "mysql"
+            ? `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
+            : `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
+        for (const row of rows) {
+            after = String(row["owner_key"]);
+            const principal = row["principal"] === null || row["principal"] === undefined ? undefined : String(row["principal"]);
+            const owner = readRuleOwner({ kind: row["owner_kind"], ...(principal !== undefined ? { principal } : {}) });
+            if (owner !== undefined)
+                owners.push(owner);
+        }
+        if (rows.length < UNDURABLE_PURGE_PAGE)
+            return owners;
+    }
+}
+export class RuleBucketVanishedError extends Error {
+    ownerKey;
+    constructor(ownerKey) {
+        super(`permission_rule bucket ${ownerKey} vanished while minting a dot`);
+        this.name = "RuleBucketVanishedError";
+        this.ownerKey = ownerKey;
+    }
+}
+export function isSqlBucketVanished(e) {
+    return e instanceof RuleBucketVanishedError;
+}
+export function isSqlBucketRefusal(e) {
+    return e instanceof BucketRefusedError || e instanceof StoreCorruptError;
+}
+export const IMPORT_RECORD_KIND = "import";
 export function refusedOwnerSentence(recordId) {
     return `refusing to create approval record ${recordId}: its owner is not one the engine reads as an owner (a principal name must be a non-blank string; the kind must be a member of the owner set) — nothing was written`;
 }

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

@@ -314,21 +314,18 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
  * 🔴 **工厂认设备不认住客**(读口一只 = 会话店执行席 `seat.read(root)`,与解析器 / 换绑门 / 执行放置读面 / 准入链同一只读):按 placement 根读**当前**格,
  * 与这条腿带来的设备句柄 `honor` 比,不同即 typed 拒。判序(一次行读):
  *   root  = ctx.placementRootSessionId                       // 空 ⇒ config.placement_root_invalid
- *   honor = ctx.resumeWorkspace?.deviceId
+ *   honor = ctx.placementTarget?.deviceId                    // 引擎交来的放置围栏(这条腿必须落在哪台设备上)
  *   cell  = seat.read(root).cell                             // 行不在 / 格缺 / mirror / writer(device, ∅) ⇒ device.not_bound(唯一读法 `boundDeviceOf`)
  *   honor ≠ undefined ∧ 格上设备 ≠ honor                    ⇒ device.identity_mismatch(句点名两台,零连接)
  *   readDeviceForAdmission(格上设备, 格上属主)
  * 工厂**不**读 `task_run`、不读子代分区行、不按 `ctx.taskId`、不比化身、不比属主(住客谓词只用于写与 judged 复核,不是工厂的读者)。
- * 续跑腿(core 7.54.0 [ref] r3 / [ref],`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备 ⇒ 本工厂**只**在那台设备上铸 —— 根此刻绑的不是它(换绑过)
- * ⇒ `device.identity_mismatch`(换绑后赎回的同一个词,零新码);不连另一台、不改道(新设备没有那个工作区)。「绑的就是它但现在不在线」与新跑同形:
- * 构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。行没记设备(早于该字段的行)⇒ 引擎已命名的「行未记设备 ⇒ 普通路由」臂,按根读当前格。
- * 句柄(`workspaceHandle()`)恒报连接真到达的设备,不抄 `resumeWorkspace`。
- *
- * 🔴 **过渡期(条件句)**:新派后代腿的放置句柄(引擎在 `ExecutionEnvFactoryContext` 上的放置工作区字段,`honor` 的第二来源)**只在本仓所基的引擎版本带它时**
- * 进判序;本仓今天所基的引擎上下文没有这个字段 ⇒ `honor` 只取续跑腿的 `resumeWorkspace`,新派后代腿按根读当前格。本仓**不**注入任何替代见证、不造任何行
- * (修在源头)。敞口(在那个字段到货之前成立):活过父 turn 的后台子代,在根换绑之后新派的腿会落到根当前设备 —— 换绑半边由换绑门的子代活性判关闭(归换绑门那一车),
- * 删除半边另有票。字段到货后的形:`honor = ctx.resumeWorkspace?.deviceId ?? <放置句柄>.deviceId`,放置句柄的 provider 不是本车道 ⇒ 装配拒(`config.placement_root_invalid` 同级)。
- * 本仓任何文本不得宣称工厂「一律按住客定址」。
+ * 围栏(`ExecutionEnvFactoryContext.placementTarget`,引擎每条腿一个答案):派生它的那条腿的环境报过的目标 —— 委派子代 / 工作流 agent / 被唤醒的
+ * 保留 agent 带唤醒腿的目标,级联后续阶 / 验证腿带第一条腿的目标,续跑腿带检查点行记下的目标。围栏点名了设备 ⇒ 本工厂**只**在那台设备上铸 ——
+ * 根此刻绑的不是它(换绑过)⇒ `device.identity_mismatch`(换绑后赎回的同一个词,零新码);不连另一台、不改道(新设备没有那个工作区)。
+ * 「绑的就是它但现在不在线」与新跑同形:构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。围栏缺席(顶层首腿,或派生它的腿
+ * 不是远端环境)或不点名设备 ⇒ 普通路由,按根读当前格。围栏的 `provider` 不进判序(引擎的回执也只比设备)。
+ * 句柄(`workspaceHandle()`)恒报连接真到达的设备,不抄围栏;引擎拿这份报告复核每条带围栏的腿(不符 ⇒ 续跑腿 `resume.env_failed`、
+ * 其余腿 `config.placement_not_honored`,都在腿跑之前)—— 本工厂在连接之前就拒,那两个词只在报告与围栏真不一致时出现。
  */
 export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
 /**

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

@@ -17,6 +17,7 @@ export const DEVICE_OUTCOME_TO_FILE_ERROR = {
     is_directory: "is_directory",
     liveness_no_output: "unknown",
     name_too_long: "name_too_long",
+    symlink_loop: "symlink_loop",
     not_directory: "not_directory",
     not_found: "not_found",
     not_supported: "not_supported",
@@ -40,6 +41,7 @@ export const DEVICE_OUTCOME_TO_EXEC_ERROR = {
     is_directory: "unknown",
     liveness_no_output: "liveness_no_output",
     name_too_long: "unknown",
+    symlink_loop: "unknown",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "shell_unavailable",
@@ -771,6 +773,7 @@ const OUTCOME_TO_REMOTE_ERROR = {
     is_directory: "unknown",
     liveness_no_output: "liveness_no_output",
     name_too_long: "unknown",
+    symlink_loop: "unknown",
     not_directory: "unknown",
     not_found: "unknown",
     not_supported: "unsupported",
@@ -806,10 +809,10 @@ export function deviceExecutionEnvFactory(deps) {
             throw deviceFactoryRefusal(DEVICE_ERROR_CODES.NOT_BOUND, `device lane: no device binding for placement root ${rootSessionId} [${DEVICE_ERROR_CODES.NOT_BOUND}] — ` +
                 "the submit-time admission chain must bind the root session to a device before a run reaches the factory (v2 §4.3.2)");
         }
-        const honor = ctx.resumeWorkspace?.deviceId;
+        const honor = ctx.placementTarget?.deviceId;
         if (honor !== undefined && honor !== binding.id) {
-            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, `device lane: this resume rebuilds the workspace on device ${honor}, but placement root ${rootSessionId} is now bound to ${binding.id} [${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] — ` +
-                "a parked call does not follow a rebind (the new device has no copy of that workspace); finish or cancel the parked task, then start it again on the device now bound");
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, `device lane: this leg is placed on device ${honor} (the device the work it continues ran on), but placement root ${rootSessionId} is now bound to ${binding.id} [${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] — ` +
+                "work already under way does not follow a rebind (the new device has no copy of that workspace); finish or cancel the running or parked task, then start it again on the device now bound");
         }
         const view = await deps.store.readDeviceForAdmission(binding.id, binding.owner);
         if (!view) {

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

@@ -386,6 +386,7 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * loud `workspace_latest_dangling`, the pointer deleted, an empty workspace); absent (404 — the key, with the bucket there) ⇒ a fresh pod; a read that
      * FAILS ⇒ a loud `connect_failed` — a 404 `NoSuchBucket` included ({@link refuseMissingBucket}) — never a silent fresh workspace (a run that believes it resumed while it did not is
      * the worst form). Once the pod holds the workspace, this env arms its fence seat (its destroy will commit).
+     * The same walk ({@link establish}) is the restore point of a parked run's resumed leg whose park packed nothing ({@link resumeVM}).
      * Persistence off / no store ⇒ a fresh pod, exactly as before. Persistence on but no such session (the occupant absent) ⇒ a
      * fresh pod and one `workspace_space_unavailable` line (no restore by any other key). The occupant read FAULTED ⇒ the same
      * loud `connect_failed` as a failed `latest` read, no pod ({@link provision} refuses it — every entry that would create one).
@@ -397,14 +398,16 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * as it stands to every later connect on every lane — the previous commit is not waited on again, `latest` is not read again, no pod is created.
      */
     connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
-    /** The one walk of a connect ({@link connect} runs it once at a time). */
+    /** The one walk of a connect ({@link connect} runs it once at a time) — also the resumed leg's walk when its park packed nothing ({@link restorePointOf},
+     *  under the resume's own hold of the same gate). */
     private establish;
     /**
      * The restore point's fill (`workspace-fill.ts`): a pod whose workspace this env just minted or restored is handed over only once the fill seat placed
      * its content — through {@link fillChannel} (this adapter's own exec, never the public face: inside a connect the public face waits on that very connect).
      * A fill that does not complete releases the pod (no tool and no run-end snapshot may see a half-filled workspace); a refusal that would answer the same
      * again (`standing`) is held for the env ({@link holdRefusal}). No seat ⇒ the pod as it came. `origin` tells the seat whether the workspace was minted
-     * (a new pod with nothing restored: the space off / unavailable / without `latest`, or `latest` dangling) or restored (the space's `latest`, or a park snapshot whose archive came back; a park snapshot with no archive — a plan-only park — is minted).
+     * (a new pod with nothing restored: the space off / unavailable / without `latest`, or a dangling restore point — `latest` or a park snapshot whose archive is gone)
+     * or restored (the space's `latest`, or a park snapshot whose archive came back). A park that packed nothing resumes through a new connect, so it reads as that connect does.
      */
     private settle;
     /** The restore point's channel: a fixed command through the one start seam (start form `adapter`, the engine's commands' identity) and a write in
@@ -447,9 +450,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      * never its text. Not a knob: there is no honest way to run a space we could not read — a retry of the run reads it again.
      */
     private refuseUnreadableOccupant;
-    /** Every space-lane operator line: the space is named by its incarnation's log prefix only, and free text (a curl
-     *  stderr, a fetch error) passes {@link redactIncarnations} — the full token never reaches a log body. */
+    /** Every space-lane operator line: the space is named by its incarnation's log prefix only ({@link snapshotLine} does the rest). */
     private spaceLine;
+    /** Every snapshot operator line, both lanes — the ONE redaction seat: each string field (a key, a curl stderr, a fetch error, an effect) passes
+     *  {@link redactIncarnations}, so a full incarnation-shaped token never reaches a log body, whatever text carried it there. */
+    private snapshotLine;
     /** A fresh pod (create → Running → workspace root), bounded retry — THE seat every pod of this env is created through
      *  ({@link connect} and, via {@link restoreSnapshot}, {@link resumeVM}). A lane keyed by an occupant read that faulted ⇒ refused
      *  here, before any request ({@link refuseUnreadableOccupant}): never retried (the reading is this env's, fixed at construction). */
@@ -651,11 +656,14 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
      */
     private uploadSnapshot;
     /**
-     * Resume a workspace snapshot onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM):
-     * provision a pod, then download + untar the snapshot into the workspace ({@link restoreSnapshot}, lane `park`). A
-     * missing object (a plan-only park: no pod was ever minted, so nothing was uploaded) resumes as a clean workspace whose origin is `minted` —
-     * no restorable tree — so the restore point seeds it; the resume walks the park lane and never reads the space's `latest` (which a fresh connect with the space on
-     * would restore); a snapshot that came back is `restored` and never seeded.
+     * Resume a parked run's workspace onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM). Where the leg's workspace comes from is
+     * read off the park's snapshot id — it says what the park packed ({@link snapshotIdHolds}), never guessed from what the store answers:
+     *  - an archive ⇒ provision a pod, then download + untar it into the workspace ({@link restoreSnapshot}, lane `park`): it came back ⇒ `restored`
+     *    (never seeded); it is not there ⇒ a dangling restore point, the same rule on both lanes ({@link dropDangling}: one line, an empty workspace);
+     *  - nothing (the env held no pod when it parked — the run parked before anything touched its hand) ⇒ there is no workspace of the park to
+     *    restore, so the leg's restore point is the one a new connect has ({@link establish}): space open ⇒ the previous commit waited out and
+     *    `latest` restored (none ⇒ a fresh workspace), space off ⇒ a fresh workspace — never a fresh workspace beside a `latest` that the leg's
+     *    run-end commit would then overwrite. No archive is asked for under such an id.
      *
      * [ref]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
      * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
@@ -666,15 +674,14 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<ConnectResult>;
     /** The one walk of a resume ({@link resumeVM} runs it under the connect gate). */
     private resumeWalk;
-    /**
-     * The ONE tar download (both lanes): provision a FRESH pod, download + untar the lane's archive into the workspace.
-     * A missing archive (404) starts from the clean workspace on both lanes, and on both it is the same fact — no restorable tree ⇒ origin
-     * `minted` (the restore point seeds it, exactly as on a fresh connect). What differs is only what it means:
-     *  - park: a plan-only suspend has no object (the park came before anything touched the hand) — nothing to say;
-     *  - space: `latest` dangles (its pointer is only written after a successful upload, so the archive was removed later —
-     *    by the bucket's lifecycle rule or a hand): the data is gone by an operator rule ⇒ loud and continuable —
-     *    {@link dropDanglingLatest} (one `workspace_latest_dangling` line, the pointer deleted); the run's own run-end
-     *    snapshot then becomes the new `latest`.
+    /** The resumed leg's restore point, chosen by what the park's id names ({@link resumeVM}) — a closed set, one arm each. */
+    private restorePointOf;
+    /**
+     * The ONE tar download (both lanes): provision a FRESH pod, download + untar the lane's archive into the workspace. Only an id that names an
+     * archive reaches it ({@link snapshotIdHolds}: a park that packed nothing resumes through {@link establish}; `latest` names only an object
+     * that was written). So a missing archive (404) is one fact on both lanes — the restore point names data that is gone (removed later, by the
+     * bucket's lifecycle rule or a hand) ⇒ loud and continuable, ONE rule: {@link dropDangling} (one `workspace_latest_dangling` line), and the
+     * run continues on the clean workspace, origin `minted` (no restorable tree ⇒ the restore point seeds it, exactly as on a fresh connect).
      * An attempt that does not complete releases the pod it provisioned: no tool and no run-end snapshot may ever see a torn
      * workspace. A transient class ({@link restoreFailureIsTransient}) is tried again on a fresh pod after the `retry.backoffMs`
      * pause, up to the lane's {@link RESTORE_MAX_ATTEMPTS}; a non-transient one ends the restore at once. The lane then says what
@@ -691,12 +698,18 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     /** The pause before a restore's next attempt (`retry.backoffMs`, the adapter's one retry pause). `false` ⇒ aborted (now or during it). */
     private restorePause;
     /**
-     * `latest` names an archive that is not there ([ref]): one `workspace_latest_dangling{space, key, deleted}` line and the
-     * pointer is deleted (the next run must not trip on it again); the run continues on the empty workspace. A pointer
-     * delete that fails rides on the same line (`deleted: false` + the error) — the next run then says it once more.
-     * This env is the space's only writer here (the commit fence admits one per space), so the delete is a plain one.
-     */
-    private dropDanglingLatest;
+     * A restore point names an archive that is not there — the data is gone by an operator rule (a bucket lifecycle rule, a hand): loud and
+     * continuable, ONE rule on both lanes — one `workspace_latest_dangling{lane, key, …}` line, and the run continues on the empty workspace
+     * {@link restoreSnapshot} hands over. `key` = the object the id names, spelled by {@link snapshotBase} (the one spelling of both partitions).
+     * What each lane adds is only what it holds:
+     *  - space: its `latest` pointer is deleted (the next run must not trip on it again); the line carries `space` and `deleted` — a delete that
+     *    fails rides on the same line (`deleted: false` + the error) and the next run says it once more. This env is the space's only writer here
+     *    (the commit fence admits one per space), so the delete is a plain one. The run's own run-end snapshot then becomes the new `latest`;
+     *  - park: there is no pointer to drop (the id lives in the engine's checkpoint); the line carries the session id. With the space open, the
+     *    resumed leg's run-end snapshot then becomes the space's new `latest`.
+     * Both lines pass the one redaction seat ({@link snapshotLine}).
+     */
+    private dropDangling;
     /**
      * Honest post-resume consistency ([ref] §5 council #8): the workspace FILES are restored byte-for-byte
      * from the snapshot, so read-before-edit hashing already lines up — there's nothing to re-fetch. In-VM

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

@@ -8,7 +8,7 @@ import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, shellQuote,
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
-import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
+import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
 import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
@@ -509,8 +509,10 @@ export class RemoteK8sExecutionEnv {
         return spaceReadFailed("occupant", ` (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
     }
     spaceLine(event, space, fields) {
-        const safe = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "string" ? redactIncarnations(v) : v]));
-        this.logger?.warn(event, { space: incarnationLogPrefix(space.incarnation), ...safe });
+        this.snapshotLine(event, { space: incarnationLogPrefix(space.incarnation), ...fields });
+    }
+    snapshotLine(event, fields) {
+        this.logger?.warn(event, Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "string" ? redactIncarnations(v) : v])));
     }
     provision(signal) {
         const space = this.spaceLane;
@@ -1224,12 +1226,12 @@ export class RemoteK8sExecutionEnv {
     async uploadSnapshot(target, boundMs = this.cfg.dataTimeoutMs) {
         if (target.lane === "park" && this.inFlight.size > 0)
             return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
-        const snapshotId = mintSnapshotId(this.occupantIncarnation);
         if (!this.podName) {
             return target.lane === "space"
                 ? { ok: false, error: new RemoteExecutionError("connect_failed", "the sandbox pod was gone when the run-end snapshot reached the upload — nothing was saved (the workspace could not be read), and `latest` keeps naming the previous snapshot") }
-                : ok(snapshotId);
+                : ok(mintSnapshotId(this.occupantIncarnation, "nothing"));
         }
+        const snapshotId = mintSnapshotId(this.occupantIncarnation, "archive");
         const presigned = this.presignSnapshot({ ...target, method: "PUT", snapshotId });
         if (!presigned.ok)
             return presigned;
@@ -1273,13 +1275,26 @@ export class RemoteK8sExecutionEnv {
             this.logger?.warn("sandbox_pod_released_before_restore", { pod: this.podName, ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}), effect: "this env held a pod minted before the park snapshot's restore — it is deleted; the restore provisions the leg's one pod" });
             await this.releasePod();
         }
-        const r = await this.settle(await this.restoreSnapshot({ lane: "park" }, snapshotId, options?.abortSignal));
+        const r = await this.restorePointOf(snapshotId, options?.abortSignal);
         if (!r.ok)
             return r;
         this.handleSnapshotId = snapshotId;
         this.armSpace();
         return ok(this.workspaceHandle());
     }
+    async restorePointOf(snapshotId, abortSignal) {
+        const holds = snapshotIdHolds(snapshotId);
+        switch (holds) {
+            case "archive":
+                return this.settle(await this.restoreSnapshot({ lane: "park" }, snapshotId, abortSignal));
+            case "nothing":
+                return this.establish(abortSignal ? { abortSignal } : undefined);
+            default: {
+                const unreachable = holds;
+                throw new Error(`unhandled snapshot id family: ${String(unreachable)}`);
+            }
+        }
+    }
     async restoreSnapshot(target, snapshotId, abortSignal) {
         const presigned = this.presignSnapshot({ ...target, method: "GET", snapshotId });
         if (!presigned.ok)
@@ -1303,8 +1318,7 @@ export class RemoteK8sExecutionEnv {
                     : undefined;
             if (!failure) {
                 if (r.ok && r.value.stdout.includes("EMPTY_SNAPSHOT")) {
-                    if (target.lane === "space")
-                        await this.dropDanglingLatest(target.space, snapshotId);
+                    await this.dropDangling(target, snapshotId);
                     return { ok: true, value: this.workspaceHandle(), origin: "minted" };
                 }
                 return { ok: true, value: this.workspaceHandle(), origin: "restored" };
@@ -1347,15 +1361,34 @@ export class RemoteK8sExecutionEnv {
             signal?.addEventListener("abort", onAbort, { once: true });
         });
     }
-    async dropDanglingLatest(space, snapshotId) {
-        const prefix = this.snapshotKeyPrefix();
-        const dropped = await this.writePointer(space, "latest", null);
-        this.spaceLine("workspace_latest_dangling", space, {
-            key: `${prefix}/${space.incarnation}/space/${snapshotId}.tar.gz`,
-            deleted: dropped.ok,
-            ...(dropped.ok ? {} : { error: dropped.error.message }),
-            effect: "the space's latest snapshot is gone (removed by a bucket lifecycle rule or by hand) — this run starts from an empty /workspace; its run-end snapshot becomes the new latest",
-        });
+    async dropDangling(target, snapshotId) {
+        const key = `${this.snapshotBase(target)}${snapshotId}.tar.gz`;
+        switch (target.lane) {
+            case "space": {
+                const dropped = await this.writePointer(target.space, "latest", null);
+                this.spaceLine("workspace_latest_dangling", target.space, {
+                    lane: "space",
+                    key,
+                    deleted: dropped.ok,
+                    ...(dropped.ok ? {} : { error: dropped.error.message }),
+                    effect: "the space's latest snapshot is gone (removed by a bucket lifecycle rule or by hand) — this run starts from an empty /workspace; its run-end snapshot becomes the new latest",
+                });
+                return;
+            }
+            case "park":
+                this.snapshotLine("workspace_latest_dangling", {
+                    lane: "park",
+                    key,
+                    ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}),
+                    effect: "the parked run's snapshot is gone (removed by a bucket lifecycle rule or by hand) — the resumed leg starts from an empty /workspace" +
+                        (this.spaceLane.state === "open" ? "; its run-end snapshot becomes the space's new latest" : ""),
+                });
+                return;
+            default: {
+                const unreachable = target;
+                throw new Error(`unhandled snapshot lane: ${String(unreachable.lane)}`);
+            }
+        }
     }
     async postResumeInit() {
         if (!this.cfg.s3Snapshot)

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

@@ -387,7 +387,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 它的域完全靠「属主 sessionId 的墓碑」推。而会话 id 是**调用方可自选**的 ⇒ 两个租户先后用过同一个 id
      * 完全合法;两边都删过之后,同一个 row_key 上会有**两个域**的墓碑,这时任何一边的 sweep 拿自己的墓碑
      * 去认领这些字节都只是猜。判据因此是:**存在第二个域的同名墓碑 ⇒ 这批行不可归属 ⇒ 一根不删**,
-     * 实体清理退回既有的 TTL 腿(`reapOlderThan`)。少删一次是可接受的;删掉另一个租户的字节、还跳过它的
+     * 实体清理退回既有的 TTL 腿(core `ToolResultStore.reap`)。少删一次是可接受的;删掉另一个租户的字节、还跳过它的
      * legal hold 与审计域,不可接受。
      */
     protected orphanToolResultCandidates(exec: {
@@ -475,7 +475,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *    也只计 `skipped` 不删。会话本体的清理归 {@link SqlRetentionStore.deleteExpiredSessions}(它会连着
      *    这行一起删),两条腿因此不重叠也不互相抢行。
      *  · **一根不碰的那一支**:`owner_session_id IS NULL` 的**无出处**行。没有出处就没有域,按任何域去删它
-     *    都是猜;实体清理归既有的 TTL 腿(`reapOlderThan`,`boot/reapers.ts` 驱动)。这与 core 的
+     *    都是猜;实体清理归既有的 TTL 腿(core `ToolResultStore.reap`,`boot/reapers.ts` 驱动)。这与 core 的
      *    「an UNOWNED entry is never deleted」是同一条纪律的两处执行点。
      *
      * 事务形与另外两只方法逐字同款(hold 哨兵行锁读 → 删除+墓碑 → 审计行,同 commit 同 rollback)。

package/dist/plugins/sandbox-read-floor.d.ts

@@ -5,11 +5,9 @@ export declare const READ_FLOOR_UNAVAILABLE_REASONS: readonly ["arch", "user_not
 export type ReadFloorUnavailableReason = (typeof READ_FLOOR_UNAVAILABLE_REASONS)[number];
 /** F2:附着不过的环境上,带地板起动的拒句(纯字符串 ⇒ `build*`)。首句点名原因词;点名表的首行与旋钮。 */
 export declare function buildReadFloorUnavailableMessage(reason: ReadFloorUnavailableReason, detail: string | undefined, floor: ReadFloor | undefined): string;
-/** F6:守地板的环境上,不带地板的引擎起动的拒句。 */
-export declare function buildReadFloorMissingMessage(lane: SandboxFloorLane): string;
 /**
  * 一次起动是什么(闭集,调用方必须表态 —— 没有缺省臂):
- *  · `engine` —— 经执行环境公共起动口要起的命令(引擎的,或替引擎干活的服务端调用方的);带不带地板是它交来的事实。`hold` = 适配器之后还会以
+ *  · `engine` —— 经执行环境公共起动口要起的命令(引擎的,或替引擎干活的服务端调用方的);它带的地板就是它的表,缺席 = 表无行。`hold` = 适配器之后还会以
  *    同一起动号再起 `run`(k8s 后台作业的轮询 / 停 / 收尾读的是这次起动的产物,按这次起动的地板跑),登记留到 {@link SandboxReadFloor.release};
  *  · `under` —— 以一次已登记(`hold`)起动的号再起一只 `run`(上面那类轮询);
  *  · `adapter` —— 适配器自己的固定命令(文件面助手、探针、数据搬运、全杀);附着成功之后经监督者的 `plain` 起;
@@ -29,7 +27,7 @@ export type FloorStart = {
 };
 export declare const ADAPTER_START: FloorStart;
 export declare const BOOTSTRAP_START: FloorStart;
-/** 引擎起动:`readFloor` 原样交(`undefined` = 这次起动不带地板)。 */
+/** 引擎起动:`readFloor` 原样交(`undefined` = 这次起动的表一行都没有)。 */
 export declare function engineStart(readFloor: ReadFloor | undefined, hold?: boolean): FloorStart;
 /** 起动身份:`root` = 车道以 root 起(e2b `user:"root"`、local-docker `-u 0`);`exec-user` = 车道自己的执行身份(改前的形)。 */
 export type FloorLaunchIdentity = "root" | "exec-user";
@@ -125,8 +123,8 @@ export interface RelayAnswer {
 export declare const UNJUDGED_VERDICT = "read floor: no verdict for this start";
 /** 判官:适配器进程里唯一回答「这条路径拒不拒」的东西。live object ⇒ `create*`。 */
 export interface FloorJudge {
-    /** 登记一次带地板的起动,回它的起动号(随机、不可猜)。`held` ⇒ 之后还会以这个号再起 `run`(`under`),直到 {@link release};否则这一次就是它唯一的起动。 */
-    register(floor: ReadFloor, held: boolean): string;
+    /** 登记一次引擎起动(带它的表;`undefined` = 表无行),回它的起动号(随机、不可猜)。`held` ⇒ 之后还会以这个号再起 `run`(`under`),直到 {@link release};否则这一次就是它唯一的起动。 */
+    register(floor: ReadFloor | undefined, held: boolean): string;
     /** 以这个号再起一次 `run`(`under`)之前问:在册且适配器没说过「不再起」⇒ `true`(记下又有一只监督者将连上);否则 `false`(起动拒)。 */
     launch(startId: string): boolean;
     /** 适配器不会再以这个号起 `run` 了。登记要两件都到才撤(协议 §5.5):这一句 ∧ 此后的 `gone` —— `gone` 已在 ⇒ 当即撤;否则等它(还连着的监督者照旧有判官答)。 */
@@ -202,7 +200,7 @@ export interface SandboxReadFloor {
     readonly state: SandboxReadFloorState;
     /** 这只模块钉住的监督者二进制(守地板 ⇒ 在;裸模块 ⇒ 缺席)。k8s 的 pod 座({@link buildFloorPodSeat})只读它 —— 放进 pod 的与自检核的是同一份钉。 */
     readonly binaries: FloorBinaries | undefined;
-    /** 唯一接缝:一次起动 → 答案,或 `spawn_error`(F2 / F6 / 时机不对的引导起动 / 已撤的号)。 */
+    /** 唯一接缝:一次起动 → 答案,或 `spawn_error`(F2 / 时机不对的引导起动 / 已撤的号)。 */
     wrap(start: FloorStart): Result<FloorLaunch, ExecutionError>;
     /** 适配器不会再以这个号起 `run`(`hold` 起动的收尾)。登记在其后的 `gone` 到时撤(还连着的监督者照旧有判官答)。 */
     release(startId: string | undefined): void;