@sema-agent/server 7.50.0 → 7.52.0

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

@@ -1,6 +1,6 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 export function writerOfSqlRuleStore(store) {
@@ -14,7 +14,7 @@ export function writerOfSqlRuleStore(store) {
         return undefined;
     return { nextDot: nextDot, apply: apply, readRaw: readRaw };
 }
-const RuleScopeSchema = z.union([
+export const DurableRuleScopeSchema = z.union([
     z.object({ kind: z.literal("global") }).strict(),
     z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
 ]);
@@ -28,12 +28,12 @@ const PersistedAllowRuleSchema = z
     tool: z.literal("Bash"),
     match: z.enum(["exact", "prefix"]),
     command: z.string(),
-    scope: RuleScopeSchema,
+    scope: DurableRuleScopeSchema,
     adds: z.array(RuleAddSchema),
 })
     .strict();
 const RuleTombstoneSchema = z
-    .object({ rule: z.string(), scope: RuleScopeSchema, removedDots: z.array(RuleDotSchema).min(1), deletedBy: RuleDotSchema })
+    .object({ rule: z.string(), scope: DurableRuleScopeSchema, removedDots: z.array(RuleDotSchema).min(1), deletedBy: RuleDotSchema })
     .strict();
 const QUARANTINE_REASONS = new Set(Object.entries(RULE_SYNC_DROP_CODES)
     .filter(([, side]) => side.includes("local-quarantined"))
@@ -42,14 +42,14 @@ const isQuarantineReason = (v) => typeof v === "string" && QUARANTINE_REASONS.ha
 const QuarantinedRuleAddSchema = z
     .object({
     rule: z.string(),
-    scope: RuleScopeSchema,
+    scope: DurableRuleScopeSchema,
     add: RuleAddSchema,
     reason: z.custom(isQuarantineReason, { message: "not a registered permission-rule quarantine reason" }),
     atMs: z.number().int().nonnegative().safe(),
 })
     .strict();
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
-const RuleCandidateSchema = z.object({ rule: z.string(), scope: RuleScopeSchema }).strict();
+const RuleCandidateSchema = z.object({ rule: z.string(), scope: DurableRuleScopeSchema }).strict();
 const RedeemedDotsSchema = z.record(z.string(), RuleDotSchema);
 const RuleEditedSchema = z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict();
 const RuleOffer2Schema = z.union([
@@ -143,16 +143,41 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     principal VARCHAR(512) NOT NULL,
     approval_id VARCHAR(190) NOT NULL,
     -- payload_hash:载荷绑定(F1 ④)。= prepare 时刻候选集的规范摘要;redeem 时与记录上的候选集
-    -- 重算比对,不符 ⇒ 拒(篡改/重放不可扩权)。
+    -- 重算比对,不符 ⇒ 拒(改动/重放不可扩权)。
     payload_hash VARCHAR(190) NOT NULL,
     payload_json LONGTEXT NOT NULL,
     expires_at_ms BIGINT NOT NULL,
     -- consumed_at_ms:一次性消费位(F1 ③)。消费 = 单条条件 UPDATE(WHERE consumed_at_ms IS NULL),
     -- **禁 read-then-write** —— 并发双 redeem 必须恰一成功,那只能由引擎的行锁回答。
     consumed_at_ms BIGINT NULL,
+    -- claim_id:#265 A7 的**认领代次**(codex 对抗轮 R1-F1,验真后修)。每一次 consume / reclaim
+    -- 铸一枚新的;release / settle 的 WHERE 里**必须**带着它。没有这一列时两条语句问的是"有没有
+    -- 认领",不是"这是**谁的**认领"—— 于是一个跑过头被顶替的旧持有者能清掉现持有者的认领(第三条腿
+    -- 随即又认领一次),或把自己的陈旧终局写成这张票的答案。围栏把"恰一赢者"从一句话变成一条谓词。
+    claim_id VARCHAR(190) NULL,
+    -- purpose:#265 A7 的**车道绑定**(codex 对抗轮 R1-F2,验真后修)。两条导入车道共用这张表,而它们
+    -- 的票语义**刻意不同**(cc-import 一次性 / local-import 可恢复三态)。不刻这一位,一张 cc 票拿到
+    -- local 口就白得三态语义(cc-import 的一次性拒重放在**不改它一行代码**的情况下被绕过),反向则更坏:
+    -- 一张 local 票被 cc 口执行完却不落定,local 口随后按崩溃窗把它再执行一遍。不可变:铸票时定,此后
+    -- 每一次读写都拿它当匹配项(不符 ⇒ 与"票不存在"同形,零存在性 oracle)。
+    purpose VARCHAR(32) NOT NULL,
+    -- redeemed_outcome:#265 A7 的**第三态**(SETTLED)。NULL = 还没落定;非 NULL = 这张票的兑付**已经
+    -- 结束**,里面是那一次的逐字终局(JSON)。它把票的两态(未认领/已认领)扩成三态
+    -- MINTED → CLAIMED → SETTLED,而三态正是"认领之后死进程"这件事唯一能被区分出来的形:
+    -- CLAIMED-未结 = 上一次执行中途没了(可重驱),SETTLED = 已经答过了(逐字回放,零二次执行)。
+    -- 🔴 只服务 local-import 车道;cc-import 的票**语义不变**(一次性,同票二次 redeem 恒拒)——
+    -- 那条车道一个字节都不写这一列,两条车道的语义因此不共享一个开关(purpose 列是那条边界的执法者)。
+    redeemed_outcome LONGTEXT NULL,
+    -- settled_at_ms:落定**发生的时刻**(codex 对抗轮 R3-F2,验真后修)。清扫的「已落定」那一支必须按
+    -- 它判,不能按 expires_at_ms —— 一次**临期恢复**写下终局的那一刻,票早就过期很久了,按过期判会让
+    -- 这份刚生出来的权威回执**下一拍**就被删:规则已经写进店里,而属主的丢响应重放拿到 404。
+    -- 有了这一列,「落定之后必有一个完整的回放窗」对每一条路都成立,而不只是对准时兑付的那条。
+    settled_at_ms BIGINT NULL,
     created_at_ms BIGINT NOT NULL,
     PRIMARY KEY (ticket_id),
     KEY idx_permission_rule_ticket_owner (owner_key),
+    -- 保留期腿 R6-F1 的支撑索引:孤儿 pending 的清扫谓词里有一条按 approval_id 的 NOT EXISTS 内查。
+    KEY idx_permission_rule_ticket_approval (approval_id),
     -- 保留期腿的支撑索引(同上):WHERE expires_at_ms <= ? 是每 tick 一次的区间扫。
     KEY idx_permission_rule_ticket_expires (expires_at_ms)
   ) COLLATE utf8mb4_bin`,
@@ -181,6 +206,25 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
             `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+export async function assertPermissionRuleTicketSchema(query, dialect) {
+    try {
+        await query(`SELECT redeemed_outcome, claim_id, purpose, settled_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE 1=0`);
+    }
+    catch (err) {
+        if (!isMissingColumnError(err, dialect))
+            throw err;
+        throw new Error(`${PERMISSION_RULE_TICKET_TABLE} is missing required columns (redeemed_outcome / claim_id / purpose / settled_at_ms) — refusing to start. This build needs ` +
+            `the #265 A7 three-state redemption columns (MINTED → CLAIMED → SETTLED, the claim generation that fences a superseded ` +
+            `claimant, and the lane binding that keeps cc-import and local-import tickets from being interchangeable): without them a ` +
+            `local-import ticket can be claimed but never settled, so a redemption that already wrote rules to the store answers its ` +
+            `owner with a retry-later it can never satisfy. This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
+            `\`DROP TABLE ${PERMISSION_RULE_TICKET_TABLE};\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and ` +
+            `restart — the schema is recreated at boot. The cost is bounded and small: this table holds minute-TTL single-use import ` +
+            `tickets (a governance transient that dies on expiry), so dropping it only makes anyone mid-preview re-run prepare; ` +
+            `persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. ` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export async function ensurePgPermissionRuleSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TABLE} (
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -237,10 +281,19 @@ export async function ensurePgPermissionRuleSchema(q) {
     payload_json TEXT COLLATE "C" NOT NULL,
     expires_at_ms BIGINT NOT NULL,
     consumed_at_ms BIGINT,
+    -- claim_id / purpose / redeemed_outcome:#265 A7 三列(MySQL 孪生的行内注写了各自的理由 ——
+    -- 认领代次是 release/settle 的围栏、purpose 是两条导入车道的绑定位、redeemed_outcome 是第三态)。
+    claim_id VARCHAR(190) COLLATE "C",
+    purpose VARCHAR(32) COLLATE "C" NOT NULL,
+    redeemed_outcome TEXT COLLATE "C",
+    -- settled_at_ms:落定时刻(MySQL 孪生的行内注写了理由:清扫的已落定支按它判,否则临期恢复出来的
+    -- 权威回执下一拍就没)。
+    settled_at_ms BIGINT,
     created_at_ms BIGINT NOT NULL,
     PRIMARY KEY (ticket_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_approval ON ${PERMISSION_RULE_TICKET_TABLE} (approval_id)`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_expires ON ${PERMISSION_RULE_TICKET_TABLE} (expires_at_ms)`);
 }
 export function buildRuleOwnerKey(owner) {
@@ -398,6 +451,7 @@ class SqlPermissionRuleStore {
                 throw new Error("the SQL permission-rule backend does not implement the sync-join landing pipeline (core's applySyncJoin is not on the package's public export face); " +
                     "no sync client is wired in this deployment, so this arm has no caller — see permission-rule-store-sql.ts header");
             }
+            assertWriteDeltaScopeDurable(delta);
             await this.ensureBucket();
             const cur = await this.read();
             if (cur.rev !== opts.expectedRev)
@@ -558,6 +612,10 @@ export class SqlRuleApprovalRecordStore {
     }
 }
 export const RULE_IMPORT_TICKET_GC_GRACE_MS = 10 * 60_000;
+export const SQL_DB_NOW_MS = {
+    tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
+    pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
+};
 export function buildRulePayloadHash(candidates) {
     return createHash("sha256").update(canonicalJson(candidates), "utf8").digest("hex");
 }
@@ -575,9 +633,9 @@ export class SqlRuleImportTicketStore {
         const nowMs = this.now();
         const expiresAtMs = nowMs + input.ttlMs;
         const payloadHash = buildRulePayloadHash(input.candidates);
-        await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, created_at_ms)
-         VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?)`, `INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, created_at_ms)
-         VALUES ($1, $2, $3, $4, $5, $6, $7, NULL, $8)`), [
+        await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, claim_id, purpose, created_at_ms)
+         VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?)`, `INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, claim_id, purpose, created_at_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, NULL, NULL, $8, $9)`), [
             input.ticketId,
             buildRuleOwnerKey({ kind: "principal", principal: input.principal }),
             input.principal,
@@ -585,44 +643,88 @@ export class SqlRuleImportTicketStore {
             payloadHash,
             dialectProtocolJsonEncoder(this.db.dialect)(input.candidates, "permission_rule_ticket.payload_json"),
             expiresAtMs,
+            input.purpose,
             nowMs,
         ]);
         return { ticketId: input.ticketId, approvalId: input.approvalId, payloadHash, expiresAtMs };
     }
-    async consume(ticketId, principal, opts) {
-        const stampMs = this.now();
-        const decisionNowMs = opts?.decisionNowMs ?? stampMs;
+    async consume(ticketId, principal, purpose, opts) {
+        const decisionNowMs = opts?.decisionNowMs ?? this.now();
         const ownerKey = buildRuleOwnerKey({ kind: "principal", principal });
         const row = await this.readRow(ticketId);
         if (row === undefined)
             return { ok: false, reason: "unknown" };
         if (row.ownerKey !== ownerKey)
             return { ok: false, reason: "wrong-principal" };
+        if (row.purpose !== purpose)
+            return { ok: false, reason: "wrong-purpose" };
         if (row.consumedAtMs !== undefined)
             return { ok: false, reason: "consumed" };
         if (row.expiresAtMs <= decisionNowMs)
             return { ok: false, reason: "expired" };
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ? WHERE ticket_id = ? AND owner_key = ? AND consumed_at_ms IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = $1 WHERE ticket_id = $2 AND owner_key = $3 AND consumed_at_ms IS NULL AND expires_at_ms > $4`), [stampMs, ticketId, ownerKey, decisionNowMs]);
+        const claimId = randomUUID();
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND consumed_at_ms IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND consumed_at_ms IS NULL AND expires_at_ms > $5`), [claimId, ticketId, ownerKey, purpose, decisionNowMs]);
         if (affected === 1)
-            return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
+            return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
         return { ok: false, reason: "consumed" };
     }
-    async release(ticketId, principal, mustRemainValidMs = 0, opts) {
+    async release(ticketId, principal, claimId, mustRemainValidMs = 0, opts) {
         const nowMs = opts?.decisionNowMs ?? this.now();
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL WHERE ticket_id = ? AND owner_key = ? AND consumed_at_ms IS NOT NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL WHERE ticket_id = $1 AND owner_key = $2 AND consumed_at_ms IS NOT NULL AND expires_at_ms > $3`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), nowMs + mustRemainValidMs]);
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = $1 AND owner_key = $2 AND claim_id = $3 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > $4`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), claimId, nowMs + mustRemainValidMs]);
+        return affected === 1;
+    }
+    async settle(ticketId, principal, claimId, outcome) {
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = ?, settled_at_ms = ${SQL_DB_NOW_MS.tidb} WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = $1, settled_at_ms = ${SQL_DB_NOW_MS.pg} WHERE ticket_id = $2 AND owner_key = $3 AND claim_id = $4 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`), [
+            dialectProtocolJsonEncoder(this.db.dialect)(outcome, "permission_rule_ticket.redeemed_outcome"),
+            ticketId,
+            buildRuleOwnerKey({ kind: "principal", principal }),
+            claimId,
+        ]);
         return affected === 1;
     }
+    async peek(ticketId, principal, purpose) {
+        const row = await this.readRow(ticketId);
+        if (row === undefined || row.ownerKey !== buildRuleOwnerKey({ kind: "principal", principal }) || row.purpose !== purpose)
+            return undefined;
+        if (row.redeemedOutcome !== undefined) {
+            let outcome;
+            try {
+                outcome = JSON.parse(row.redeemedOutcome);
+            }
+            catch (err) {
+                throw new Error(`${PERMISSION_RULE_TICKET_TABLE}.redeemed_outcome for ticket ${ticketId} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+            }
+            return { state: "settled", outcome };
+        }
+        if (row.consumedAtMs === undefined)
+            return { state: "minted" };
+        return { state: "claimed", claimAgeMs: Math.max(0, row.dbNowMs - row.consumedAtMs) };
+    }
+    async reclaim(ticketId, principal, purpose, minClaimAgeMs) {
+        const row = await this.readRow(ticketId);
+        if (row === undefined || row.ownerKey !== buildRuleOwnerKey({ kind: "principal", principal }) || row.purpose !== purpose)
+            return { ok: false };
+        if (row.claimId === undefined)
+            return { ok: false };
+        const claimId = randomUUID();
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.tidb} - ? AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND claim_id = $5 AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.pg} - $6 AND redeemed_outcome IS NULL`), [claimId, ticketId, buildRuleOwnerKey({ kind: "principal", principal }), purpose, row.claimId, minClaimAgeMs]);
+        return affected === 1 ? { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId } : { ok: false };
+    }
     async readRow(ticketId) {
-        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, expires_at_ms, consumed_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, expires_at_ms, consumed_at_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
+        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, redeemed_outcome, ${SQL_DB_NOW_MS.tidb} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, redeemed_outcome, ${SQL_DB_NOW_MS.pg} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
         const row = rows[0];
         if (row === undefined)
             return undefined;
         return {
+            dbNowMs: Number(row.db_now_ms),
             ownerKey: String(row.owner_key),
             approvalId: String(row.approval_id),
             payloadHash: String(row.payload_hash),
+            purpose: String(row.purpose),
             expiresAtMs: Number(row.expires_at_ms),
             ...(row.consumed_at_ms === null || row.consumed_at_ms === undefined ? {} : { consumedAtMs: Number(row.consumed_at_ms) }),
+            ...(row.claim_id === null || row.claim_id === undefined ? {} : { claimId: String(row.claim_id) }),
+            ...(row.redeemed_outcome === null || row.redeemed_outcome === undefined ? {} : { redeemedOutcome: String(row.redeemed_outcome) }),
         };
     }
 }
@@ -635,8 +737,8 @@ export function createSqlPermissionRuleStores(db, now) {
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db, now),
         reapExpired: async (nowMs) => {
-            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_IMPORT_TICKET_GC_GRACE_MS]);
-            const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ?) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.tidb} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= $1) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.pg} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_IMPORT_TICKET_GC_GRACE_MS]);
+            const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = ${PERMISSION_RULE_APPROVAL_TABLE}.record_id) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT a.ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} a WHERE a.state = 'pending' AND a.created_at_ms < $1 AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = a.record_id) LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
             return deadTickets.affected + orphanPending.affected;
         },
         countBuckets: async () => {

package/dist/plugins/pg-pool.js

@@ -8,6 +8,7 @@ import { ensurePgOutcomeLedgerSchema as ensureOutcomeLedgerSchema } from "./outc
 import { ensureSchema as ensureImageIndexSchema } from "./image-index-sql.js";
 import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-store-sql.js";
 import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
+import { ensurePgMemoryOptOutGrantSchema } from "./memory-optout-grant-store-sql.js";
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
@@ -165,6 +166,63 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL
    )`,
     `CREATE INDEX IF NOT EXISTS idx_snapshot_blob_created ON snapshot_blob (created_at)`,
+    `CREATE TABLE IF NOT EXISTS file_history_scope (
+     scope         VARCHAR(64) COLLATE "C" NOT NULL,
+     created_at_ms BIGINT                  NOT NULL,
+     PRIMARY KEY (scope)
+   )`,
+    `CREATE TABLE IF NOT EXISTS file_history_tracked (
+     scope          VARCHAR(64) COLLATE "C" NOT NULL,
+     key_hash       CHAR(64) COLLATE "C"    NOT NULL,
+     track_key      TEXT COLLATE "C"        NOT NULL,
+     key_kind       VARCHAR(16) COLLATE "C" NOT NULL,
+     key_family     VARCHAR(8) COLLATE "C"  NOT NULL,
+     base_available BOOLEAN                 NOT NULL,
+     observed_later BOOLEAN                 NOT NULL DEFAULT FALSE,
+     created_at_ms  BIGINT                  NOT NULL,
+     PRIMARY KEY (scope, key_hash)
+   )`,
+    `CREATE TABLE IF NOT EXISTS file_history_version (
+     scope        VARCHAR(64) COLLATE "C" NOT NULL,
+     key_hash     CHAR(64) COLLATE "C"    NOT NULL,
+     version      INT                     NOT NULL,
+     blob_hash    CHAR(64) COLLATE "C"    NULL,
+     mode         INT                     NULL,
+     parent_ident TEXT COLLATE "C"        NULL,
+     backup_time  VARCHAR(40) COLLATE "C" NOT NULL,
+     PRIMARY KEY (scope, key_hash, version)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_file_history_version_blob ON file_history_version (blob_hash)`,
+    `CREATE TABLE IF NOT EXISTS file_history_boundary (
+     scope           VARCHAR(64) COLLATE "C" NOT NULL,
+     entry_id        VARCHAR(64) COLLATE "C" NOT NULL,
+     published_at_ms BIGINT                  NOT NULL,
+     publish_seq     BIGINT                  NOT NULL,
+     PRIMARY KEY (scope, entry_id),
+     CONSTRAINT uq_file_history_boundary_seq UNIQUE (scope, publish_seq)
+   )`,
+    `CREATE TABLE IF NOT EXISTS file_history_boundary_file (
+     scope    VARCHAR(64) COLLATE "C" NOT NULL,
+     entry_id VARCHAR(64) COLLATE "C" NOT NULL,
+     key_hash CHAR(64) COLLATE "C"    NOT NULL,
+     version  INT                     NOT NULL,
+     PRIMARY KEY (scope, entry_id, key_hash)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_file_history_bf_key ON file_history_boundary_file (scope, key_hash)`,
+    `CREATE TABLE IF NOT EXISTS file_history_reaped_entry (
+     scope        VARCHAR(64) COLLATE "C" NOT NULL,
+     entry_id     VARCHAR(64) COLLATE "C" NOT NULL,
+     reaped_at_ms BIGINT                  NOT NULL,
+     PRIMARY KEY (scope, entry_id)
+   )`,
+    `CREATE TABLE IF NOT EXISTS file_history_blob (
+     blob_hash  CHAR(64) COLLATE "C" PRIMARY KEY,
+     byte_len   BIGINT         NOT NULL,
+     -- bytes NULLABLE = the same two-backend (SQL inline / MinIO index-only) contract as snapshot_blob above.
+     bytes      BYTEA          NULL,
+     created_at TIMESTAMPTZ(3) NOT NULL
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_file_history_blob_created ON file_history_blob (created_at)`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) COLLATE "C" NOT NULL,
      ordinal       INT          NOT NULL,
@@ -305,6 +363,7 @@ export async function ensurePgSchema(pool) {
         await ensureImageIndexSchema(client);
         await ensureImageBakeSchema(client);
         await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
+        await ensurePgMemoryOptOutGrantSchema((text, params) => client.query(text, params));
         await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));

package/dist/plugins/pg-safe-json.d.ts

@@ -10,7 +10,7 @@ export declare function pgLosslessJsonStringify(value: unknown): string;
  *  剥离等),CAS/rev 语义的臂必须先 detect 再变换。 */
 export declare function pgHasUnstorable(v: unknown): boolean;
 /** codex R4→R7 终形:协议数据(approval args/checkpoint/ctx/outcome/rules/memory)一律**拒绝式**。
- *  信封方案历经 R4-R7 四轮对抗全灭:行内判别子恒可被 ≤1.240 老行/用户数据撞形(静默解错=approval
+ *  信封方案历经 R4-R7 四轮交叉复审全灭:行内判别子恒可被 ≤1.240 老行/用户数据撞形(静默解错=approval
  *  信任边界破),进程旗恒有混旗副本窗(写读不同解)。唯一无歧义解=**脏值不进库**:PG 存不了
  *  NUL 是后端能力边界,fail-loud 暴露(清晰文案)严格优于修前的 22P05 神秘崩——两者都存不进,
  *  但拒绝式下 review==execute 恒成立(库里只有干净值,展示面=执行面永逐位一致)。 */

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

@@ -0,0 +1,271 @@
+import { ExecutionError, FileError, RemoteExecutionError, type ExecutionEnv, type ExecutionEnvFactory, type ExecStreamOptions, type FileInfo, type OutputChunk, type RemoteConnectConfig, type RemoteExecutionEnv, type Result, type SessionToken, type SnapshotId, type VmLifecycleOptions, type WorkspaceHandle, type WriteExpectation, type WriteReceipt } from "@sema-agent/core";
+import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceStore } from "../device-store.js";
+import type { DeviceEnrollment } from "../device-enrollment.js";
+import type { DeviceWsHub } from "../device-ws-hub.js";
+import type { DeviceInstructionKind, DeviceOutcomeErrorCode } from "../device-ws-protocol.js";
+/** `WorkspaceHandle.provider` 与 `REMOTE_EXEC` 词表的那一个词,单点。 */
+export declare const DEVICE_PROVIDER: "device";
+/** core 没从包根导出 `ExecutionEnvExecOptions` —— 从接口上取,与六条兄弟腿逐字同姿势
+ *  (`remote-env-host.ts` 的 `type ExecOpts = Parameters<ExecutionEnv["exec"]>[1]`)。 */
+type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
+/**
+ * 设备**结局帧**的错误码 → core `FileErrorCode`。
+ *
+ * `Record<DeviceOutcomeErrorCode, …>` 是**穷举**的:协议的结局码闭集加词而此处不加行 = 编译红
+ * (#157 词表纪律;不是运行时 switch 的默认臂)。
+ *
+ * 🔴 三条不许折错的线:
+ *  ① `outcome_unknown` **原样过境**——core 把它排除在 `RETRYABLE_REMOTE_ERROR_CODES` 之外正是为了
+ *     「可能已经执行过」这一格;折成 `timeout`/`transport_lost` 会让上层按可重试处理,重驱已提交副作用。
+ *  ② `target_unavailable`(never-started 的诚实词)在 `FileErrorCode` 上**没有对位词** —— 落
+ *     `transport_lost`:它的契约是「连接故事已知、重连后可重试」,而 never-started 的重试确实是安全的。
+ *     诚实残余:file 面因此**分不出**「从未开始」与「传输中断」,两者都落在同一个可重试桶里(方向对、
+ *     粒度粗)。要分得开需要 core 在 `FileErrorCode` 上补 never-started 词 —— 已作 O12 的后续请托登记。
+ *  ③ exec 专属词(`shell_unavailable`/`spawn_error`/`callback_error`/`suspended`/`auth_failed`)出现在
+ *     file 面上是**设备端协议违约**(它把一个 exec 结局贴到一次文件操作上)⇒ 落 `unknown`,不猜。
+ */
+export declare const DEVICE_OUTCOME_TO_FILE_ERROR: Readonly<Record<DeviceOutcomeErrorCode, FileError["code"]>>;
+/**
+ * 设备**结局帧**的错误码 → core `ExecutionErrorCode`。穷举同上。
+ *
+ * 🔴 file 专属词(`already_exists`/`is_directory`/`not_directory`/`not_found`/`permission_denied`/
+ * `precondition_failed`/`invalid`)出现在 exec 面同样是协议违约 ⇒ `unknown`,不猜。
+ * `not_supported` 在 `ExecutionErrorCode` 上无对位词 —— 落 `shell_unavailable`(它的契约就是「命令
+ * **从未启动**,因为可执行面解析不了」,与「设备没有这条指令面」同侧;never-started 语义保住)。
+ */
+export declare const DEVICE_OUTCOME_TO_EXEC_ERROR: Readonly<Record<DeviceOutcomeErrorCode, ExecutionError["code"]>>;
+type RejectCode = DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+/**
+ * 汇聚端的 **typed 拒**(投递门**之前**,§5.3 投递边界:设备从未可能见过这条指令)→ core 错误码。
+ *
+ * 🔴 全部落在**可安全重试**的那一侧,这是投递边界给的硬事实,不是乐观估计。exec 面用 O12 的
+ * `target_unavailable`(「目标在 commit 前拒了,命令从未启动」的诚实词);file 面无对位词,同上落
+ * `transport_lost`。
+ * 例外 `identity_mismatch` / `revoked` / `not_found`:那是**永久**拒(换设备/吊销/不是你的),重试
+ * 只会同样失败 —— exec 面落 `auth_failed`(NEVER retry 的那一格),file 面无对位词落 `permission_denied`
+ * (「这条路你走不通,而且不是暂时的」是它最近的语义)。
+ */
+export declare const DEVICE_REJECT_TO_EXEC_ERROR: Readonly<Record<RejectCode, ExecutionError["code"]>>;
+export declare const DEVICE_REJECT_TO_FILE_ERROR: Readonly<Record<RejectCode, FileError["code"]>>;
+export interface DeviceEnvLogger {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    info?(msg: string, fields?: Record<string, unknown>): void;
+}
+export interface DeviceEnvFactoryDeps {
+    hub: DeviceWsHub;
+    store: DeviceStore;
+    enrollment: DeviceEnrollment;
+    /** 指令级默认超时(ms;`DEVICE_EXEC_TIMEOUT_MS`,§4.7)。core 的 per-command `timeout` 可收紧它。 */
+    execTimeoutMs?: number;
+    /** §4.3.3 蜂道:`deviceCwdHonored` 闸下由 resolve-spec 注册的 per-session cwd(**单写者**)。 */
+    perSessionCwd?: ReadonlyMap<string, string>;
+    perSessionShellEnv?: ReadonlyMap<string, Record<string, string>>;
+    logger?: DeviceEnvLogger;
+}
+interface DeviceEnvConfig {
+    hub: DeviceWsHub;
+    enrollment: DeviceEnrollment;
+    rootSessionId: string;
+    deviceId: string;
+    owner: DeviceOwner;
+    cwd: string;
+    shellEnv?: Record<string, string>;
+    execTimeoutMs: number;
+    /** 设备当前连接声明的指令面(`undefined` = 铸 env 时设备不在线 ⇒ 可选面一律缺席)。 */
+    supports: ReadonlySet<DeviceInstructionKind> | undefined;
+    logger?: DeviceEnvLogger;
+}
+export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
+    private readonly cfg;
+    /**
+     * 🔴 `suspendable: false` 在 core 契约里**同时断言**「工作区在目标上外部持久」(remote-env.ts 的
+     * load-bearing 不变量)—— 设备工作区 = 员工机磁盘,真持久 ✅,park-only 降级腿因此合法可用。
+     * 谁要把 executor 的工作区改成临时目录,先来改这一行:那一刻这个 `false` 就变成谎话,park 赎回会
+     * 落到一个空工作区上而链路上没有任何一层会报错。
+     */
+    readonly capabilities: {
+        isolation: boolean;
+        suspendable: boolean;
+    };
+    readonly externalContentTarget = true;
+    /** #211:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
+    readonly hostLocalPaths = false;
+    cwd: string;
+    /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */
+    readLink?: (path: string, abortSignal?: AbortSignal) => Promise<Result<string, FileError>>;
+    writeFileExclusive?: (path: string, content: string | Uint8Array, abortSignal?: AbortSignal) => Promise<Result<void, FileError>>;
+    writeFileGuarded?: (path: string, content: string | Uint8Array, expect: WriteExpectation, abortSignal?: AbortSignal) => Promise<Result<WriteReceipt, FileError>>;
+    private connected;
+    /** 拆除是**终态**(六条兄弟腿同纪律:destroy 之后 connect/exec/读面一律 fail-closed,不复活)。 */
+    private destroyed;
+    constructor(cfg: DeviceEnvConfig);
+    /**
+     * 铸造时装配的**保护型**可选面(guarded / exclusive 写)。`connect()` 拿它与设备**此刻**的声明对拍。
+     *
+     * 🔴 为什么只对拍这两条而不是全部 supports(codex R1-F2 的修法边界):这两条是 core 契约里
+     * 「缺席 ⇒ 调用方按 advisory 降级并自担 TOCTOU」的那一类 —— 它们的缺席是**放宽**方向。其余面
+     * (exec/read/…)缺席时调用会得到一条响亮的 `not_supported`,不构成静默降级。
+     */
+    private guardFaceSnapshot;
+    /**
+     * 设备**此刻**多出来的保护面(相对本 env 铸造时的快照)。非空 = 漂移。
+     *
+     * 🔴 **为什么这条判据不能只守 `connect()`**(codex R2-F3,判真):`connect()` 一辈子只跑一两次,而
+     * 设备的 WS 可以**透明重连** —— 断开、以同一 deviceId 连回来,`this.connected` 全程不变,后续
+     * `dispatch` 直接用汇聚端的**当前**连接。于是「弱能力连接上铸的 env + 设备连回时带上了 guarded 面」
+     * 这一形跳过了 connect 期的闸:core 仍看不到 guarded 方法、仍走非原子写降级,而没有任何一层再问一次。
+     * 所以判据要落在**每一次非原子写之前**(那正是被降级的那条路),connect 期的检查是它的早期快门。
+     */
+    private guardFaceDrift;
+    /**
+     * 铸造时**缺席**的保护面 —— 交给 hub 在投递门上原子复核(codex R3-F1)。
+     *
+     * adapter 侧的 {@link guardFaceDrift} 是**早期快门**:它与真正的下发之间隔着 `admitSession` 的一次
+     * SQL 往返,设备可以在那个窗口里以更强的能力连回来。投递门是本进程里唯一同时持有「最终选中的连接」
+     * 与「不可回退的 commit」的地方,所以权威判据在那儿;这里只负责把「我是在没有它们的前提下铸的」这句
+     * 话原样送过去。
+     */
+    private absentGuardFaces;
+    private driftError;
+    private resolve;
+    absolutePath(p: string): Promise<Result<string, FileError>>;
+    joinPath(parts: string[]): Promise<Result<string, FileError>>;
+    workspaceHandle(): WorkspaceHandle;
+    /**
+     * 不建连接:做**准入 + 取活连接**(文件头「唯一范式差」)。
+     *
+     * 🔴 **绝不换设备**:准入解出的 deviceId 与本 env 铸造时钉住的那一台不符 ⇒ typed
+     * `device.identity_mismatch`(lane 是身份不是偏好,§4.5 步 2)。这一格正是 park 赎回期换绑/吊销的
+     * 落点:静默改投等于把一次会话的全部工作区假设搬到另一台机器上。
+     */
+    connect(config?: RemoteConnectConfig): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    /** 控制面重连(core 在 transport 重挂时调)——语义与 connect 逐字同一条:重新准入 + 身份等值。 */
+    reconnect(_sessionToken: SessionToken): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    suspendVM(_options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: SnapshotId;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    resumeVM(_snapshotId: SnapshotId, _options?: VmLifecycleOptions): Promise<{
+        ok: true;
+        value: WorkspaceHandle;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    postResumeInit(): Promise<{
+        ok: true;
+        value: void;
+    } | {
+        ok: false;
+        error: RemoteExecutionError;
+    }>;
+    private unsupported;
+    /**
+     * 解除本 env 与设备的关联。**不动设备上的工作区文件**(与 adb 腿「destroy 只断开不重置手机」同纪律
+     * —— 那是员工自己的盘,§11-O6 才是「要不要清理」这个问题的属主)。幂等,永不抛。
+     */
+    destroy(): Promise<void>;
+    cleanup(): Promise<void>;
+    /** 终态/未连接的 fail-closed 门(exec 面)。 */
+    private shellGate;
+    /** 终态/未连接的 fail-closed 门(文件面)。 */
+    private fsGate;
+    private timeoutMsFor;
+    private dispatch;
+    /**
+     * 三态结果 → 文件面的 `Result`。
+     *
+     * **穷举 switch,无 default 臂**:`DeviceDispatchResult` 加臂而此处不加 = 编译红。三态各自的
+     * 「重试安全性」在 hub 的类型注里逐字定义,本函数只做翻译,不重新判断。
+     */
+    private fileOutcome;
+    /** 结局 kind 与请求面不符 = 设备协议违约:响亮拒,**不猜**(否则一个没发生的操作会被读成成功)。 */
+    private wrongOutcome;
+    exec(command: string, options?: ExecOpts): Promise<Result<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }, ExecutionError>>;
+    /**
+     * 流式 exec。契约:按序 yield `stdout`/`stderr`,末尾**恰好一个** `exit` 片;失败在 exit 之前 throw
+     * `RemoteExecutionError`(core `OutputChunk` 契约)。
+     *
+     * 🔴 「恰好一个 exit」不是本层的信任,是**汇聚端已判过**的事实(hub 的 `expectsStreamTerminator`
+     * 对声明了流的调用强制唯一终止片,缺了就把整条指令判失败而不是静默尾截断)。本层只负责不把它弄丢。
+     */
+    execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
+    exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
+    private doReadLink;
+    readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    readTextLines(p: string, options?: {
+        maxLines?: number;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string[], FileError>>;
+    listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
+    writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    private doWrite;
+    /**
+     * O13 守卫写:前置条件与写入在设备上的**同一原子步**里发生,回一份落盘对象收据。
+     *
+     * 🔴 这是 §4.3.1「把裁决绑定到真实落盘对象」的**唯一**承载。它成立的边界要说清:关掉的是「调用方
+     * 铸前置条件」与「写入」之间那个窗;更早的策略裁决(例如等过人类审批的写门判决)不在这条收据里 ——
+     * core 的方法注对此已逐字声明,本腿不越界宣称。
+     */
+    private doGuardedWrite;
+    private warnMissingCreated;
+    createDir(p: string, options?: {
+        recursive?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    remove(p: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<void, FileError>>;
+    createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    createTempFile(options?: {
+        prefix?: string;
+        suffix?: string;
+        abortSignal?: AbortSignal;
+    }): Promise<Result<string, FileError>>;
+}
+/**
+ * device lane 的 `ExecutionEnvFactory`(`boot/execution-env.ts` 的第七臂)。
+ *
+ * 🔴 **异步工厂,且在铸 env 之前就把绑定读出来** —— 三个理由,每个都不能省:
+ *  ① `cwd` 是 `FileSystem` 的**同步属性**:缺省值 = 设备 hello 声明的 `workspaceRoot`,那在库里;
+ *  ② 可选面的 presence(`writeFileGuarded`…)必须在构造期定(core 降级律,见文件头);
+ *  ③ 「这个 placement 根本没绑设备」是**装配/准入错误**,不是一次运行期业务拒绝 —— 响亮抛,让 spawn
+ *     失败(core 对 `isolation:"worktree"` 的同款姿势:宁可 throw,绝不静默给一个不对的 env)。
+ *     对比:「绑了但现在不在线」是运行期事实 ⇒ 构造成功,`connect()` 回 typed `device.offline`。
+ */
+export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
+/**
+ * §4.3.3 的 cwd 优先序 —— 与 host 腿的 `effectiveHostWorkspace` **同源**:
+ *   ① 本 session 显式注册的 cwd(`deviceCwdHonored` 闸下由 resolve-spec 写);
+ *   ② `ctx.parentCwd`(委派子代:自己没注册过 cwd,继承父的工作目录 —— 少了它子代会丢工作目录);
+ *   ③ 设备 hello 声明并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
+ *      默认根」这种空话)。
+ */
+export declare function effectiveDeviceCwd(sessionCwd: string | undefined, parentCwd: string | undefined, row: Pick<DeviceRow, "workspaceRoot">): string;
+export {};
+//# sourceMappingURL=remote-env-device.d.ts.map