@sema-agent/server 7.136.0 → 7.138.0

package/dist/plain-string-record.js

@@ -29,4 +29,42 @@ export function readPlainStringRecord(v) {
     }
     return { ok: true, record, stripped };
 }
+export function declarationKeys(table) {
+    return Object.freeze(Object.keys(table));
+}
+export function splitDeclaration(declaration, table) {
+    const dispositions = table;
+    const engine = {};
+    let pieces;
+    let seatSeen = false;
+    for (const [key, value] of Object.entries(declaration)) {
+        if (value === undefined)
+            continue;
+        const disposition = Object.hasOwn(dispositions, key) ? dispositions[key] : undefined;
+        switch (disposition) {
+            case "engine":
+                engine[key] = value;
+                break;
+            case "seat": {
+                if (seatSeen)
+                    throw new Error("request declaration: two members are marked as pieces in one disposition table");
+                seatSeen = true;
+                const record = value;
+                if (Object.keys(record).length > 0)
+                    pieces = record;
+                break;
+            }
+            case "withheld":
+                break;
+            case undefined:
+                throw new Error(`request declaration: a member the disposition table does not classify (${JSON.stringify(key.slice(0, 40))})`);
+            default: {
+                const unknownDisposition = disposition;
+                void unknownDisposition;
+                throw new Error("request declaration: a disposition outside the closed set");
+            }
+        }
+    }
+    return { engine: engine, ...(pieces === undefined ? {} : { pieces }) };
+}
 //# sourceMappingURL=plain-string-record.js.map

package/dist/plugins/background-agent-store-sql.js

@@ -3,6 +3,7 @@ import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
+import { backgroundAgentNameOf } from "../background-agent-name.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 function summaryCols(dialect) {
     return ("handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, " +
@@ -11,12 +12,14 @@ function summaryCols(dialect) {
 const readAgentRecordBody = createObjectColumnReader();
 const readUsageBody = createObjectColumnReader();
 function readRecordColumn(v, handle) {
+    let record;
     try {
-        return decodeJsonColumn(v, readAgentRecordBody, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`);
+        record = decodeJsonColumn(v, readAgentRecordBody, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`);
     }
     catch (e) {
         throw foldJsonColumn(e, (m) => `BackgroundAgentStore: ${m} — refusing rather than serve a hollow agent record`);
     }
+    return { ...record, name: backgroundAgentNameOf(record) };
 }
 function readUsageColumn(v, handle) {
     try {
@@ -45,7 +48,7 @@ function projParams(stored, json, text) {
         stored.parentSessionId ?? null,
         stored.rootSessionId ?? null,
         (stored.sessionScoped ? stored.owner : stored.parentSessionId) ?? null,
-        stored.name !== undefined ? text(stored.name).slice(0, 255) : null,
+        text(backgroundAgentNameOf(stored)).slice(0, 255),
         stored.agentType !== undefined ? text(stored.agentType).slice(0, 190) : null,
         stored.status,
         stored.spawnedAt,
@@ -68,7 +71,7 @@ function rowToSummary(r) {
         ...(r.session_id !== null && r.session_id !== undefined ? { sessionId: String(r.session_id) } : {}),
         ...(r.parent_session_id !== null && r.parent_session_id !== undefined ? { parentSessionId: String(r.parent_session_id) } : {}),
         ...(r.root_session_id !== null && r.root_session_id !== undefined ? { rootSessionId: String(r.root_session_id) } : {}),
-        ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}),
+        name: backgroundAgentNameOf({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }),
         ...(r.agent_type !== null && r.agent_type !== undefined ? { agentType: String(r.agent_type) } : {}),
         status: String(r.status),
         spawnedAt: Number(r.spawned_at_ms),

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

@@ -3,6 +3,7 @@ import type { OwnerAwareSessionStore, SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import type { InstructionSourceStore } from "../instruction-source-notice.js";
+import type { SessionWorkspaceStore } from "../session-workspace.js";
 import type { OwnerlessClaim } from "../delegated-session-owner.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
@@ -85,6 +86,10 @@ export declare class CachingSessionStore implements SessionStore {
      *  而装配点按「店上两个方法都在」判席 —— 不转发 = 默认部署上换源通告**静默不发**,且没有任何一处报错。 */
     readonly readInstructionSource?: InstructionSourceStore["readInstructionSource"];
     readonly recordInstructionSource?: InstructionSourceStore["recordInstructionSource"];
+    /** 会话行的位置与项目那一格(`session_meta.workspace` / local sidecar;`session-workspace.ts`),纯转发、不经暖缓存。
+     *  🔴 必须转发(同上一条教训):装配点与 resolveSpec 按「店上两个方法都在」判这一面 —— 不转发 = 默认部署上不记行、续跑腿不续声明项目,且没有任何一处报错。 */
+    readonly readSessionWorkspace?: SessionWorkspaceStore["readSessionWorkspace"];
+    readonly recordSessionWorkspace?: SessionWorkspaceStore["recordSessionWorkspace"];
     /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
      *  list/fork: an export reads the full durable log, an import writes durable state). */
     readonly exportEntries?: (sessionId: string) => Promise<SessionTreeEntry[] | null>;

package/dist/plugins/caching-session-store.js

@@ -19,6 +19,8 @@ export class CachingSessionStore {
     probeTitle;
     readInstructionSource;
     recordInstructionSource;
+    readSessionWorkspace;
+    recordSessionWorkspace;
     exportEntries;
     listEntryIds;
     exportEntriesStream;
@@ -65,6 +67,10 @@ export class CachingSessionStore {
             this.readInstructionSource = ownerAware.readInstructionSource.bind(inner);
         if (ownerAware.recordInstructionSource)
             this.recordInstructionSource = ownerAware.recordInstructionSource.bind(inner);
+        if (ownerAware.readSessionWorkspace)
+            this.readSessionWorkspace = ownerAware.readSessionWorkspace.bind(inner);
+        if (ownerAware.recordSessionWorkspace)
+            this.recordSessionWorkspace = ownerAware.recordSessionWorkspace.bind(inner);
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
         if (ownerAware.exportEntries)

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

@@ -3,15 +3,29 @@ import type { Pool as PgPool } from "pg";
 import { type ExecutionOutcomeRecordWord, type GateOutcome, type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolvedOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity, type ToolApprovalCard } from "@sema-agent/core";
 import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { type SqlDialect, type SqlDriver } from "./sql-driver.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
-/** M28 店腿的读数(两孪生同形;随 M28 删):扫到的可读行 · 回写成的行 · 回写成的行里被改写的值 · 读不出的行 · 封好之后一行装不下的行。 */
-export interface CtxRowsRewriteM28 {
+/** ctx 行改写店腿的读数(两孪生同形):扫到的可读行 · 回写成的行 · 回写成的行里改写函数报的改动数 · 读不出的行 · 改写之后一行装不下的行。 */
+export interface CtxRowsRewrite {
     readonly scanned: number;
     readonly rewritten: number;
     readonly valuesRewritten: number;
     readonly unreadable: number;
     readonly tooLarge: number;
 }
+/** 一行的改写:交回新的落盘形(只有封口模块的铸点产得出 —— 品牌型)与这一行的改动数;`undefined` = 这一行不写。 */
+export type CtxRowRewrite = (sessionId: string, ctx: object) => {
+    readonly ctx: SealedCheckpointCtx;
+    readonly values: number;
+} | undefined;
+/**
+ * 🔴 **一次性迁移的 ctx 行改写店腿**(两孪生:`SqlCheckpointStore` / `LocalCheckpointStore` 的 `rewriteCtxRows`;逐行判词两孪生同):扫全部 `checkpoint_ctx` 行、
+ * 交给 `rewrite`、交回新体的行原地回写(续跑时钟不动)。店不知道改写是什么 —— 用它的迁移各自带行改写:M28(凭据位明文封好)、M30(退役请求键改写)。
+ * 窗与删法逐条在 `plugins/one-time-migrations.ts` 登记表;登记表里最后一条用它的迁移删码时,本腿、读数型与扫描页一起删。
+ */
+export interface CheckpointCtxRowsRewriter {
+    rewriteCtxRows(rewrite: CtxRowRewrite): Promise<CtxRowsRewrite>;
+}
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 /**
  * [ref] D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
@@ -451,9 +465,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     protected readonly logger?: {
         info?(msg: string, meta?: unknown): void;
     } | undefined;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
-     *  逐字见 {@link MANAGED_RETENTION}(本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
+     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
+    readonly retention: RetentionDeclaration;
     /**
      * `CheckpointStore.durability` 声明([ref] 欠账,[ref] 件5)—— 行落在 MySQL-protocol / PostgreSQL 的
      * `checkpoint` 表里,进程重启、副本轮换、整机重建都不丢 ⇒ `"durable"`,如实。
@@ -487,25 +501,13 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * `wiring-governance-operator.test.ts` 的 [ref] 组;已上报上游求一个能表达该宽度的词。
      */
     readonly fidelity: StoreFidelity;
-    /**
-     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[ref] clay 裁放行)——**如实按能力判**:
-     * 本店的 {@link SqlCheckpointStore.reopen} 是真 CAS 实现(`resolved`→`pending` 原子翻回 + `reopen_reason`
-     * 权威列,[ref] D-1 的两条重开腿都走它),声明 `reopen: true` 是读数不是抬举。core 的沙箱准入
-     * 模式(pre-flight 要求 `redecision.reopen === true`,declaration never duck-typing——方法在场不算数)
-     * 由这一格武装:Kata 腿(`capabilities.isolation` 真声明)+ durable park 部署下,`sandbox_local` ask
-     * 自动放行并以 `permission.sandbox_admitted` durable 事件披露(缺席披露=core 侧变异恰红)。
-     * `validatingLease` **不声明**:本店没有 durable validating-lease 纪律,不承诺没有的东西。
-     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
-     */
-    readonly redecision: {
-        readonly reopen: true;
-    };
     /**
      * `CheckpointStore.execution` 声明(core 7.7.0 [ref];[ref])——**必填**,且必须恰是 `{ outcome: true }`:
      * 店在此承诺 {@link SqlCheckpointStore.recordExecutionOutcome} 是契约描述的那条真 CAS(谓词、四词、
-     * 冲突抛),且 {@link SqlCheckpointStore.reopen} 认这条记录。与 `durability`/`fidelity`/`redecision`
-     * 三格同一条「声明而非鸭子判」姿势,区别只在这一格**不可缺席**:缺席的店会被 core 在 store 席的
-     * 第一次读(`resolveCheckpointStore`)以 `config.invalid_checkpoint_store` 拒启 —— 那是契约的正确行为,
+     * 冲突抛),且 {@link SqlCheckpointStore.reopen} 认这条记录。与 `durability`/`fidelity` 两格同一条
+     * 「声明而非鸭子判」姿势,区别只在这一格**不可缺席**:缺席的店(以及缺 `reopen` 动词的店 —— core 7.57.0 起它是必备
+     * 动词,原先的 `redecision` 声明格随之退役)会被 core 在 store 席的第一次读(`resolveCheckpointStore`)以
+     * `config.invalid_checkpoint_store` 拒启、句子点名缺的每一个成员 —— 那是契约的正确行为,
      * 因为一台记不下「已决动作最后被怎么处置」的部署,它手里每一条 resolved 行在这条轴上都永远读不出来。
      */
     readonly execution: {
@@ -513,7 +515,9 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     };
     constructor(db: SqlDriver, logger?: {
         info?(msg: string, meta?: unknown): void;
-    } | undefined);
+    } | undefined, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** JSON column binding. TiDB: plain `JSON.stringify`, stored verbatim. PG: `pgProtocolJsonStringify` —
@@ -832,17 +836,14 @@ export declare class SqlCheckpointStore implements CheckpointStore {
     putCtx(sessionId: string, ctx: SealedCheckpointCtx): Promise<void>;
     getCtx<T extends object = object>(sessionId: string): Promise<T | null>;
     /**
-     * 🔴 **一次性迁移 M28 的店腿**(窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28;编排 = `checkpoint-ctx-seal-m28.ts`,行改写 =
-     * `http/checkpoint-ctx.ts` 的 `sealStoredCheckpointCtxM28`;本店不知道「封」是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
+     * 🔴 **一次性迁移的 ctx 行改写店腿**({@link CheckpointCtxRowsRewriter};用它的迁移与各自的行改写见那里,窗与删法见 `plugins/one-time-migrations.ts` 登记表;
+     * 本店不知道改写是什么,只负责扫与回写):按 `session_id` 键集分页扫 `checkpoint_ctx`
      * (每页 {@link CTX_REWRITE_PAGE} 行,只取会话 id 与 ctx 文本),行体经读腿**同一只**判形({@link decodeCtxColumn})—— 读不出 ⇒ 计数、跳过、不动;
      * `rewrite` 交回新体 ⇒ 经写腿同一只编码与形闸,**按原文 CAS** 回写(MySQL 协议两边 `CAST(… AS BINARY)`,与 M17 / M18 同一条理由:连接排序规则大小写
      * 不敏感;PG `text` 等值)。`updated_at_ms` **不动**(收割按它判,迁移不许延长或缩短一行的寿命)。CAS 打空(扫描与回写之间这一行被续跑腿 / 别的副本写过)
-     * ⇒ 不计、不重试(新写者是本版就已封好;是旧版副本就由之后的起服再扫到)。一行装不下(封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
+     * ⇒ 不计、不重试(新写者是本版写下的、已是新形;是旧版副本就由之后的起服再扫到)。一行装不下(如封签比明文长)⇒ 计 `tooLarge`、那一行留原样,其余照扫。
      */
-    rewriteCtxRowsM28(rewrite: (sessionId: string, ctx: object) => {
-        readonly ctx: SealedCheckpointCtx;
-        readonly values: number;
-    } | undefined): Promise<CtxRowsRewriteM28>;
+    rewriteCtxRows(rewrite: CtxRowRewrite): Promise<CtxRowsRewrite>;
     /**
      * GC ctx rows whose lifecycle is over (bound to the checkpoint, don't leak):
      * a session with NO pending checkpoint, NO active run, AND not touched since `cutoff`.
@@ -881,12 +882,16 @@ export declare class SqlCheckpointStore implements CheckpointStore {
 export declare class TiDBCheckpointStore extends SqlCheckpointStore {
     constructor(pool: MySqlPool, logger?: {
         info?(msg: string, meta?: unknown): void;
+    }, opts?: {
+        readonly retention?: RetentionDeclaration;
     });
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgCheckpointStore extends SqlCheckpointStore {
     constructor(pool: PgPool, logger?: {
         info?(msg: string, meta?: unknown): void;
+    }, opts?: {
+        readonly retention?: RetentionDeclaration;
     });
 }
 //# sourceMappingURL=checkpoint-store-sql.d.ts.map

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

@@ -1,7 +1,7 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "./checkpoint-index-columns.js";
-import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, MAX_SUPPORTED_CHECKPOINT_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, parkRowCarriesSkillCardFacts, parkRowFacts, readRuleOfferList, skillCardFacts } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
@@ -9,7 +9,7 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
-import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const CTX_REWRITE_PAGE = 500;
 export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
@@ -336,14 +336,14 @@ const EXECUTION_RECORD_CAS_ATTEMPTS = 8;
 export class SqlCheckpointStore {
     db;
     logger;
-    retention = MANAGED_RETENTION;
+    retention;
     durability = "durable";
     fidelity = "json";
-    redecision = { reopen: true };
     execution = { outcome: true };
-    constructor(db, logger) {
+    constructor(db, logger, opts = {}) {
         this.db = db;
         this.logger = logger;
+        this.retention = opts.retention ?? UNMANAGED_RETENTION;
     }
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
@@ -412,7 +412,7 @@ export class SqlCheckpointStore {
                 cells.risk_descriptor === null ? null : this.json(cells.risk_descriptor, "risk descriptor"),
                 ruleOffers === undefined ? null : this.json(ruleOffers, "rule offers"),
                 cells.has_bidi_controls,
-                cp.rev ?? 0,
+                checkpointRevOf(cp),
                 cp.reopenReason ?? null,
                 executionOutcome,
                 executionAtMs,
@@ -738,7 +738,7 @@ export class SqlCheckpointStore {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
-    async rewriteCtxRowsM28(rewrite) {
+    async rewriteCtxRows(rewrite) {
         const out = { scanned: 0, rewritten: 0, valuesRewritten: 0, unreadable: 0, tooLarge: 0 };
         let after = "";
         for (;;) {
@@ -748,7 +748,7 @@ export class SqlCheckpointStore {
                 after = sessionId;
                 let ctx;
                 try {
-                    ctx = decodeCtxColumn(row.ctx, `for session ${JSON.stringify(sessionId)} (M28 scan)`);
+                    ctx = decodeCtxColumn(row.ctx, `for session ${JSON.stringify(sessionId)} (ctx row rewrite scan)`);
                 }
                 catch {
                     out.unreadable += 1;
@@ -759,13 +759,13 @@ export class SqlCheckpointStore {
                 if (next === undefined)
                     continue;
                 const text = this.json(next.ctx, "checkpoint ctx");
-                assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (ctx row rewrite)`);
                 let affected;
                 try {
                     ({ affected } = await this.db.query(this.q("UPDATE checkpoint_ctx SET ctx = ? WHERE session_id = ? AND CAST(CAST(ctx AS CHAR) AS BINARY) = CAST(? AS BINARY)", "UPDATE checkpoint_ctx SET ctx = $1::jsonb WHERE session_id = $2 AND ctx::text = $3"), [text, sessionId, String(row.ctx)]));
                 }
                 catch (e) {
-                    const folded = rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (M28 write)`);
+                    const folded = rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (ctx row rewrite)`);
                     if (!(folded instanceof StoreRowTooLargeError))
                         throw folded;
                     out.tooLarge += 1;
@@ -798,13 +798,13 @@ export class SqlCheckpointStore {
     }
 }
 export class TiDBCheckpointStore extends SqlCheckpointStore {
-    constructor(pool, logger) {
-        super(mysqlDriver(pool), logger);
+    constructor(pool, logger, opts) {
+        super(mysqlDriver(pool), logger, opts);
     }
 }
 export class PgCheckpointStore extends SqlCheckpointStore {
-    constructor(pool, logger) {
-        super(pgDriver(pool), logger);
+    constructor(pool, logger, opts) {
+        super(pgDriver(pool), logger, opts);
     }
 }
 //# sourceMappingURL=checkpoint-store-sql.js.map

package/dist/plugins/file-history-store-sql.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
+import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
 import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
@@ -149,15 +149,8 @@ export class SqlFileHistoryStore {
                 const baseAvailable = truthy(t.rows[0].base_available);
                 const mintedBlobHash = v1.rows[0]?.blob_hash != null ? String(v1.rows[0].blob_hash) : null;
                 const proof = await worldStillMatchesMint(verify.env, absPath, root, baseAvailable, mintedBlobHash, verify.signal);
-                if (!proof.unchanged) {
-                    return {
-                        ok: false,
-                        error: {
-                            code: "conflict",
-                            message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file, and deleting the only baseline of a modified file is worse than keeping a stale record`,
-                        },
-                    };
-                }
+                if (proof.verdict !== "unchanged")
+                    return annulProofFailure(proof, absPath);
             }
             const conn = await this.db.connect();
             try {
@@ -441,7 +434,7 @@ export class SqlFileHistoryStore {
                 let targetVersion = boundary.get(t.keyHash);
                 if (targetVersion === undefined) {
                     if (!t.baseAvailable) {
-                        ledger.refused.push({ path: t.trackKey, reason: "base_unavailable" });
+                        ledger.refused.push({ path: t.trackKey, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -452,12 +445,12 @@ export class SqlFileHistoryStore {
                     continue;
                 }
                 if (rec.mode !== undefined && !(Number.isInteger(rec.mode) && rec.mode >= 0 && rec.mode <= 0o7777)) {
-                    ledger.refused.push({ path: t.trackKey, reason: `recorded mode ${String(rec.mode)} is not a valid POSIX permission value — refusing to apply a corrupted permission record` });
+                    ledger.failed.push({ path: t.trackKey, reason: `recorded mode ${String(rec.mode)} is not a valid POSIX permission value (store integrity) — refusing to apply a corrupted permission record` });
                     continue;
                 }
                 const resolved = fileHistoryResolveTrackKey(root, t.trackKey, t.keyDesc);
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: t.trackKey, reason: resolved.reason });
+                    ledger.refused.push({ path: t.trackKey, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let applied;
@@ -488,7 +481,7 @@ export class SqlFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(t.trackKey);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: t.trackKey, reason: applied.reason });
+                    ledger.refused.push({ path: t.trackKey, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: t.trackKey, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)
@@ -728,12 +721,13 @@ export class SqlFileHistoryStore {
                 bytes = await srcGetBlob(hash);
             }
             catch (err) {
-                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${foldCaughtFailure(err).text}` } };
+                const f = foldCaughtFailure(err);
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${f.text}`, ...f.fault } };
             }
             if (bytes === undefined)
                 return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
             if (sha256hex(bytes) !== hash) {
-                return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
+                return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} served bytes that do not hash to its address — the source cannot supply this blob, so nothing is published` } };
             }
             await onVerified?.(hash, bytes);
         }

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

@@ -9,6 +9,7 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError, buildRunOrphanedError, readLegacyHolderDeathCode } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
+import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal, SPACE_COMMIT_RECORD_SCHEMA } from "../workspace-space-commit.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isParseableDate = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
@@ -140,16 +141,19 @@ export class FileRunStore {
         return this.spaceCommits.abandonSpaceCommit(spaceKey, taskId);
     }
     toRow(d) {
+        const { identitySource, identityScope, identityPrincipalInc, ...rest } = d;
         return {
-            ...d,
+            ...rest,
             idemKey: typeof d.idemKey === "string" ? d.idemKey : null,
             idemBodyFingerprint: typeof d.idemBodyFingerprint === "string" ? d.idemBodyFingerprint : null,
+            identity: readRunIdentityCells(identitySource, identityScope, identityPrincipalInc),
             createdAt: new Date(d.createdAt),
             updatedAt: new Date(d.updatedAt),
         };
     }
     toDisk(r) {
-        return { ...r, createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
+        const { identity, ...rest } = r;
+        return { ...rest, ...runIdentityCells(identity), createdAt: r.createdAt.toISOString(), updatedAt: r.updatedAt.toISOString() };
     }
     toRecord(r) {
         return {
@@ -162,6 +166,7 @@ export class FileRunStore {
             errorCode: r.errorCode,
             jobId: r.jobId,
             source: r.source,
+            identity: r.identity,
             instanceId: r.instanceId,
             cancelRequested: r.cancelRequested,
             objectivePreview: r.objectivePreview,
@@ -376,6 +381,7 @@ export class FileRunStore {
                 objectivePreview: meta.objectivePreview ?? null,
                 idemKey,
                 idemBodyFingerprint: meta.idem?.bodyFingerprint ?? null,
+                identity: meta.identity ?? null,
                 createdAt: now,
                 updatedAt: now,
                 cancelRequested: false,

package/dist/plugins/k8s-exec-protocol.d.ts

@@ -1,9 +1,51 @@
 /**
- * The confined, ADDITIVE pod-spec patch ({@link PodSpecPatch}/{@link applyPodSpecPatch}) + the exec-socket TLS
- * shape ({@link execSocketTlsOptions}) + the v4 channel status-frame parse ({@link exitCodeFromStatus}) — the
- * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` ([ref]
- * A13, internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
+ * The identity labels every sandbox pod carries — the ONE spelling (RBAC selectors, the reaper's listing and the egress self-check key on
+ * them; a pod-spec patch can add labels, never set or replace one of these).
  */
+export declare const SANDBOX_POD_LABELS: {
+    readonly app: "sema-sandbox";
+    readonly "managed-by": "sema-server";
+};
+/**
+ * The pod's owning run: label key, value = the server run id (the task id) of the TOP-LEVEL run whose env created the pod. Minted only by the
+ * adapter from `K8sEnvConfig.runId` (the per-run binding decides who has one); absent ⇒ the pod names no run, and the reaper removes it only once
+ * its containers have ended. An identity label: a patch can neither set nor replace it.
+ */
+export declare const SANDBOX_RUN_LABEL = "sema.io/run";
+/**
+ * The pod's own reaper hold: annotation key, value = the decimal milliseconds the reaper must wait after the owning run turned terminal before it
+ * removes the pod (`k8s-pod-reaper.ts` `sandboxRunEndHoldMs` of the CREATING replica's data bound). Written once, by the adapter, on every pod that
+ * carries {@link SANDBOX_RUN_LABEL} (the hold is only read for those); the reaper reads this and nothing else — never its own replica's config, so a
+ * rolling change of the snapshot bound never shortens another replica's pod. A pod-spec patch reaches labels only, never annotations.
+ */
+export declare const SANDBOX_RUN_END_HOLD_ANNOTATION = "sema.io/run-end-hold-ms";
+/** The two per-pod Secret seats: `env` = the pod's env Secret (the values `K8S_SANDBOX_ENV` names); `lease` = the member-credential broker's lease Secret. */
+export type SandboxSecretSeatKind = "env" | "lease";
+/**
+ * Per seat, the secrets verbs the adapter sends for it in the sandbox namespace — the ONE table, and each row is exactly that seat's calls:
+ * `env` = `create` (the env Secret, POSTed after its pod, never touched again); `lease` = `create` (the lease Secret) + `patch` (the lease rewrite,
+ * a merge-patch of `broker.json`). Nothing else: the adapter never reads a Secret back (no `get` — which would also let the service account read
+ * every Secret in the namespace) and never deletes one (no `delete`) — each Secret is owned by its pod (`ownerReferences`, `blockOwnerDeletion:
+ * false`), so the cluster's garbage collector removes it with the pod under its own identity. A seat in play asks only its own row: the boot gate
+ * (`K8S_SANDBOX_ENV` non-empty) asks `env`, the member-credential plane judge asks `lease` — an env-only deployment is never asked for `patch`.
+ * Readers: the SelfSubjectAccessReview (`readSandboxSecretSeat`), the refusal sentences that name the Role rule, the plane's off-reason text, the
+ * catalog sentence. `test/k8s-sandbox-secret.test.ts` pins row ≡ calls per seat, both directions.
+ */
+export declare const SANDBOX_SECRET_SEAT_VERBS: {
+    readonly env: readonly ["create"];
+    readonly lease: readonly ["create", "patch"];
+};
+export type SandboxSecretVerb = (typeof SANDBOX_SECRET_SEAT_VERBS)[SandboxSecretSeatKind][number];
+export declare function isLabelValue(v: string): boolean;
+/**
+ * The volume names the adapter itself mints on a sandbox pod — the ONE table (a patch volume / volumeMount must not reuse one: it would collide
+ * with, or mount, the adapter's own volume). Today: the space's build-cache claim and the member-credential broker's lease volume. A volume the
+ * adapter adds later is added HERE, and the patch judge below refuses it with no second guard.
+ */
+export declare const ADAPTER_VOLUME_NAMES: {
+    readonly cache: "ws-cache";
+    readonly brokerLease: "sema-broker-lease";
+};
 /**
  * The confined, ADDITIVE pod-spec patch. Every field is purely additive —
  * none can override the hard isolation invariants. This is the seam the RSI L8 immutable-mount probe + the
@@ -22,19 +64,32 @@ export interface PodSpecPatch {
     /** Extra labels merged into metadata.labels (e.g. a grader/probe tag). */
     labels?: Record<string, string>;
 }
-/**
- * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE. Volumes + volumeMounts are
- * APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are merged. It
- * deliberately touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
- * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken,
- * restartPolicy, activeDeadlineSeconds, image, command) are preserved by construction. Pure + exported for testing.
- */
-export declare function applyPodSpecPatch(pod: {
+type SandboxPodShape = {
     metadata: {
         labels?: Record<string, string>;
     };
     spec: Record<string, unknown>;
-}, patch: PodSpecPatch): void;
+};
+/** Which pod a patch lands on: one that carries the broker container or not. */
+export interface PodPatchPresence {
+    readonly broker: boolean;
+}
+/**
+ * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE, through the one field table
+ * ({@link POD_SPEC_PATCH_FIELDS}): a key outside the table is refused; EVERY present field is judged before ANY lands (a refusal leaves the pod
+ * byte-identical). Volumes + volumeMounts are APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are
+ * merged under the identity keys. It touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
+ * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken, restartPolicy, activeDeadlineSeconds, image,
+ * command) are preserved by construction. Throws (the caller surfaces it as a provisioning failure). Pure + exported for testing.
+ * `presence.broker` ⇒ the table's broker column judges first (see {@link POD_SPEC_PATCH_FIELDS}).
+ */
+export declare function applyPodSpecPatch(pod: SandboxPodShape, patch: PodSpecPatch, presence?: PodPatchPresence): void;
+/**
+ * The patch judge alone — the same one {@link applyPodSpecPatch} runs — for a pod that carries the broker: the refusal sentence, or `undefined`
+ * when the patch may land. The boot reads it on the deployment's static patch (a refusal turns the member-credential plane off,
+ * `pod_patch_reaches_broker`); the adapter runs it again on every pod it builds with the broker.
+ */
+export declare function podSpecPatchBrokerRefusal(patch: PodSpecPatch | undefined): string | undefined;
 /**
  * TLS options for the exec WebSocket, shaped for BOTH runtimes (2026-06-11 in-cluster drill finding):
  * Bun's `ws` shim IGNORES node-ws's top-level `ca`/`rejectUnauthorized` (handshake fails against a
@@ -50,4 +105,5 @@ export declare function exitCodeFromStatus(statusJson: string): {
 } | {
     error: string;
 };
+export {};
 //# sourceMappingURL=k8s-exec-protocol.d.ts.map