@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/workflow-journal-store-sql.js

@@ -1,7 +1,7 @@
 import { callKeyOrdinal } from "@sema-agent/core";
 import { oversizeJournalResult } from "./workflow-journal-limits.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-const DEFAULT_RESUME_CLAIM_TTL_MS = 15 * 60 * 1000;
+const DEFAULT_RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
 export class SqlWorkflowJournalStore {
     db;
     resumeClaimTtlMs;
@@ -9,38 +9,83 @@ export class SqlWorkflowJournalStore {
         this.db = db;
         this.resumeClaimTtlMs = opts?.resumeClaimTtlMs ?? DEFAULT_RESUME_CLAIM_TTL_MS;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** Record one agent's result. Idempotent per (run_id, ordinal): the PK upsert OVERWRITES (last-write-wins), so a
+     *  resumed run re-appending its replayed prefix verbatim leaves no duplicate. callKeyOrdinal is the SOLE ordinal
+     *  source (core's parser — a malformed key collapses to 0, matching InMemory). Throws on a REAL failure
+     *  (LOAD-BEARING), EXCEPT an oversize result is skip-journaled (see below) rather than throwing the workflow dead. */
     async append(runId, scope, entry) {
+        // codex R10 定谳:result 列=TEXT(PG)/MEDIUMTEXT(TiDB),存的是 stringify 输出——NUL/lone surrogate
+        // 在输出里恒为 \uXXXX 六字符**转义形**(纯 ASCII),TEXT 列可精确存取;22P05 只咬 ::jsonb cast。
+        // 故 journal 无需任何 NUL 守卫:直存=逐位回放(R8 skip/R9 invalidate 均为过度修,已撤——那会把
+        // 可精确回放的完成结果作废成不必要的活跑重执行,外部副作用可能重复)。
         const serialized = JSON.stringify(entry.result);
+        // TiDB rejects a row over the ~6 MiB txn-entry-size-limit ("entry too large"); a large agent TaskResult would
+        // make this LOAD-BEARING append THROW + kill the workflow — and the PG twin (no such limit) would NOT, a
+        // dialect divergence. DEGRADE identically on both: skip-journal an oversize result (no-op, never insert/throw)
+        // → its ordinal isn't cached, so a resume re-runs that one agent live (resume is an optimization).
         if (oversizeJournalResult(serialized))
             return;
         await this.db.query(this.q("INSERT INTO workflow_journal (run_id, ordinal, scope, call_key, result, created_at) VALUES (?,?,?,?,?,?) " +
+            // scope NOT in the UPDATE: a re-append keeps the FIRST writer's scope (fail-closed — a re-append must never
+            // reassign tenancy). The owner is the sole writer + runId is unique per scope, so this never fires
+            // cross-scope in practice; the secure choice over matching InMemory's last-write-wins on scope.
             "ON DUPLICATE KEY UPDATE call_key = VALUES(call_key), result = VALUES(result)", "INSERT INTO workflow_journal (run_id, ordinal, scope, call_key, result, created_at) VALUES ($1,$2,$3,$4,$5,$6) " +
             "ON CONFLICT (run_id, ordinal) DO UPDATE SET call_key = EXCLUDED.call_key, result = EXCLUDED.result"), [runId, callKeyOrdinal(entry.callKey), scope, entry.callKey, serialized, Date.now()]);
     }
+    /** Entries for `runId` IF its recorded scope === `scope`, ASCENDING by ordinal; otherwise EMPTY. CORE-9 audit
+     *  BLOCKER: scope in the WHERE (twin of WorkflowRunStore) — the LLM controls `resumeFromRunId`, so a cross-scope
+     *  runId resolves to an empty journal (resume safely diverges to live, never discloses another tenant's results).
+     *  Each row's `result` is the persisted JSON.stringify(TaskResult) → JSON.parse back. Throws on failure (LOAD-BEARING). */
     async load(runId, scope) {
         const { rows } = await this.db.query(this.q("SELECT call_key, result FROM workflow_journal WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC", "SELECT call_key, result FROM workflow_journal WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC"), [runId, scope]);
         return rows.map((r) => ({ callKey: String(r.call_key), result: JSON.parse(String(r.result)) }));
     }
+    /** [1412] locator 云形(core 1.353 WorkflowJournalStore.locator additive):SQL 店的 journal 坐标=
+     *  [1402] HTTP 读面路由(file 店返 jsonl 路径=CC 本地形;此处返云形,core 铸 diagnostics 教句时单源引用)。 */
     locator(runId, _scope) {
         return `/v1/workflows/${runId}/journal`;
     }
+    /** codex R1-H2:分页投影读——LIMIT/OFFSET 界行数,字节门界单行字节(超限行不取 result 全文,只回字节数;
+     *  读面标 truncated)。ORDER BY ordinal 与 load 同轴。
+     *  🔴 param ORDER differs by dialect (see file header): TiDB's `?`s bind in text order (maxResultBytes first,
+     *  inside the CASE); PG's `$n` are positional, so its array keeps runId/scope first. Never unify — a swap
+     *  silently mis-binds the OTHER dialect's placeholders. */
     async loadPage(runId, scope, opts) {
         const params = this.db.dialect === "tidb"
             ? [opts.maxResultBytes, runId, scope, opts.limit, opts.offset]
             : [runId, scope, opts.maxResultBytes, opts.limit, opts.offset];
-        const { rows } = await this.db.query(this.q("SELECT call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE result END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC LIMIT ? OFFSET ?", "SELECT call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE result END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC LIMIT $4 OFFSET $5"), params);
+        const { rows } = await this.db.query(this.q("SELECT call_key, CASE WHEN LENGTH(result) > ? THEN NULL ELSE result END AS result_json, LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = ? AND scope = ? ORDER BY ordinal ASC LIMIT ? OFFSET ?", 
+        // codex R3: PG's LENGTH(text) is CHARACTER count (TiDB's LENGTH is byte count) — a multi-byte UTF-8 row
+        // would slip past the byte-budget door on plain LENGTH; OCTET_LENGTH keeps this the byte count PG-side
+        // too (real dual-DB-suite-confirmed anti-drift).
+        "SELECT call_key, CASE WHEN OCTET_LENGTH(result) > $3 THEN NULL ELSE result END AS result_json, OCTET_LENGTH(result) AS result_bytes FROM workflow_journal WHERE run_id = $1 AND scope = $2 ORDER BY ordinal ASC LIMIT $4 OFFSET $5"), params);
         return rows.map((r) => ({ callKey: String(r.call_key), resultJson: r.result_json === null ? null : String(r.result_json), resultBytes: Number(r.result_bytes) }));
     }
+    /** GC — purge ALL journal entries for a run (the run reaper calls this once the run is terminal + retained). Scoped
+     *  by run_id alone; idempotent (affected-row count). Mirrors the resume-anchor store's deleteBySession. */
     async deleteByRun(runId) {
         const res = await this.db.query(this.q("DELETE FROM workflow_journal WHERE run_id = ?", "DELETE FROM workflow_journal WHERE run_id = $1"), [runId]);
         return res.affected;
     }
+    /** RB-242 / WF2([1981] core 拍板 a 形,签名逐字)—— cross-replica resume admission lease。
+     *
+     *  语义(bake-store `idem_key UNIQUE` 先例):PK (source_run_id, scope) 上的原子赢或观察。四步,每步
+     *  单语句原子,并发交叉在任一步都收敛到「恰一个持有者」:
+     *   ① 抢空位:INSERT..DO NOTHING / ON DUP KEY 无操作 —— affected=1 即赢;
+     *   ② 同持有者幂等重入(engine 重试同一 resume):按 (键, new_run_id) 守卫的 claimed_at 刷新;
+     *   ③ TTL 崩溃兜底接管:claimed_at < now-ttl 守卫下的原子改持有者(engine 终态会显式释放,
+     *     走到这步=上一持有 engine 崩了没释放;两层分工见 SqlWorkflowJournalStoreOptions 注);
+     *   ④ 都没赢 ⇒ 读在位者返 {granted:false, holder}(holder 进 engine 的拒绝文案供归因)。 */
     async resumeClaim(input) {
         const now = Date.now();
-        const ins = await this.db.query(this.q("INSERT IGNORE INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES (?, ?, ?, ?)", "INSERT INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES ($1, $2, $3, $4) ON CONFLICT (source_run_id, scope) DO NOTHING"), [input.sourceRunId, input.scope, input.newRunId, now]);
+        const ins = await this.db.query(this.q(
+        // INSERT IGNORE(非 ON DUP KEY 无操作形):TiDB 对「无变化的 DUP KEY UPDATE」affected 报 1
+        // (MySQL 报 0)——真双库跑出来的方言差;IGNORE 形两家都在冲突时报 0。
+        "INSERT IGNORE INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES (?, ?, ?, ?)", "INSERT INTO workflow_resume_claim (source_run_id, scope, new_run_id, claimed_at) VALUES ($1, $2, $3, $4) ON CONFLICT (source_run_id, scope) DO NOTHING"), [input.sourceRunId, input.scope, input.newRunId, now]);
         if (ins.affected === 1)
             return { granted: true };
         const refresh = await this.db.query(this.q("UPDATE workflow_resume_claim SET claimed_at = ? WHERE source_run_id = ? AND scope = ? AND new_run_id = ?", "UPDATE workflow_resume_claim SET claimed_at = $1 WHERE source_run_id = $2 AND scope = $3 AND new_run_id = $4"), [now, input.sourceRunId, input.scope, input.newRunId]);
@@ -50,25 +95,36 @@ export class SqlWorkflowJournalStore {
         if (takeover.affected >= 1)
             return { granted: true };
         const holder = await this.db.query(this.q("SELECT new_run_id FROM workflow_resume_claim WHERE source_run_id = ? AND scope = ?", "SELECT new_run_id FROM workflow_resume_claim WHERE source_run_id = $1 AND scope = $2"), [input.sourceRunId, input.scope]);
+        // 行在①-③间被释放的窄窗:holder 读空 ⇒ 如实返 denied 无 holder(engine 下一次重试会在①赢)。
         const row = holder.rows[0];
         const holderId = row?.new_run_id === undefined ? undefined : String(row.new_run_id);
+        // ②的 UPDATE 在 MySQL 缺省协议下只数**被改变**的行——同毫秒重入(claimed_at 未变)会 affected=0
+        // 掉到这里;持有者==自己仍是 granted(幂等重入语义不依赖 affected 的方言细节)。
         if (holderId === input.newRunId)
             return { granted: true };
         return { granted: false, holder: holderId };
     }
+    /** 只有 holder 能释放(new_run_id 守卫)—— engine 在 newRunId 终态/放弃时调;非 holder 调用=no-op。 */
     async releaseResumeClaim(input) {
         await this.db.query(this.q("DELETE FROM workflow_resume_claim WHERE source_run_id = ? AND scope = ? AND new_run_id = ?", "DELETE FROM workflow_resume_claim WHERE source_run_id = $1 AND scope = $2 AND new_run_id = $3"), [input.sourceRunId, input.scope, input.newRunId]);
     }
+    /** GC — time-based sweep: purge journal entries older than `maxAgeMs` (created_at < now - maxAgeMs). The
+     *  per-run deleteByRun has no production caller (a run-store reap gives no per-run hook), so this bounded sweep
+     *  — wired into the service reaper — is what keeps the heaviest table (TaskResult-bearing) from growing without
+     *  bound. A resume of a journal older than the retention window simply re-runs live (resume is an optimization).
+     *  Idempotent; returns the rows purged. */
     async reapExpired(now, maxAgeMs) {
         const res = await this.db.query(this.q("DELETE FROM workflow_journal WHERE created_at < ?", "DELETE FROM workflow_journal WHERE created_at < $1"), [now - maxAgeMs]);
         return res.affected;
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBWorkflowJournalStore extends SqlWorkflowJournalStore {
     constructor(pool, opts) {
         super(mysqlDriver(pool), opts);
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgWorkflowJournalStore extends SqlWorkflowJournalStore {
     constructor(pool, opts) {
         super(pgDriver(pool), opts);

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

@@ -1,3 +1,59 @@
+/**
+ * P1 (fleet failover correctness, clay 2026-07-05) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场).
+ * ONE implementation, TWO dialects; the historical `TiDBWorkflowRunStore`/`PgWorkflowRunStore`,
+ * `TiDBWorkflowCompletionInbox`/`PgWorkflowCompletionInbox`, `TiDBWorkflowNotifyJournalStore`/
+ * `PgWorkflowNotifyJournalStore` class names survive as thin ctor subclasses so every consumer
+ * (store-backend.ts, the DB-integration + slim-oversize-run suites) is untouched.
+ *
+ * These are the TiDB/PG twins of core's `WorkflowRunStore` and the service `WorkflowCompletionInbox`,
+ * closing the LAST replica-local gap in the fleet story: dispatch failover (taskId idempotency +
+ * announce/lease, 1.98–1.103) can land a session on ANOTHER instance, where a File-backed workflow
+ * record / completion inbox strands the run's history and its pending push.
+ *
+ * ## WorkflowRunStore twin
+ * One row per run: the full `WorkflowRun` as a JSON blob + EXTRACTED columns for everything SQL needs to
+ * index/filter (scope, status, created_at, ended_at) + an authoritative `rev` column (the OCC key — the
+ * blob's own `rev` is OVERLAID from the column on every read, so writes never have to know the bumped value
+ * up front). `update` is a single-statement CAS (`WHERE id AND scope [AND rev]`, `SET rev = rev + 1`);
+ * `listByScope` projects через core's SHARED `summarizeWorkflowRun` (anti-drift — identical to InMemory/File).
+ *
+ * ## Completion inbox twin
+ * The File inbox's fences (purge / poll-served) are in-memory BY DESIGN there (single box); here they are
+ * ROWS (`workflow_inbox_fence`), which is the actual point of the port — a poll served on replica A must
+ * fence the late notify landing on replica B, or the double-push returns the moment a fleet has two
+ * replicas. Fences are swept opportunistically on every write verb. Entry order rides an auto-incrementing
+ * `seq` (re-enqueue = atomic move-to-tail → fresh seq = tail, matching the File/InMemory Map semantics; 1.108
+ * review hardening: post-insert fence RE-CHECK closes the cross-replica check-then-insert TOCTOU).
+ *
+ * ## Notify-journal twin
+ * 1.108 review fix (lens③ HIGH): with a SQL run store + inbox, a replica-local File journal was the last
+ * replica-local piece of the at-least-once completion-notify chain (a replica that died holding an un-acked
+ * entry stranded the notify forever). Semantics mirror `FileWorkflowNotifyJournalStore` verb-for-verb:
+ * `record` is idempotent and NEVER resets an acked row; `ack` flips pending→acked once; `listPending` is the
+ * recovery backlog (any replica may sweep it — the receiver is idempotent on runId, so a double recovery
+ * across replicas is at-least-once, not N-times).
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n` (and the OPTIONAL `AND rev = ?` / `AND rev = $6` OCC tail on `update`)
+ *   - create-once dup-key: errno-string `ER_DUP_ENTRY` vs SQLSTATE `23505`
+ *   - `listByScope`'s optional-session filter: `JSON_UNQUOTE(JSON_EXTRACT(run, '$.originatingSessionId'))`
+ *     vs `run::json->>'originatingSessionId'` — AND the placeholder-numbering shape that follows (PG's `$n`
+ *     is POSITIONAL and must track `params.length` as each optional clause is appended; TiDB's `?` is not),
+ *     so this method keeps an explicit tidb/pg branch rather than a single `q()` pair.
+ *   - completion-inbox move-to-tail: TiDB `REPLACE INTO …` (atomic delete-conflicting-row + insert, omitted
+ *     `seq` mints a fresh AUTO_INCREMENT = tail) vs PG `INSERT … ON CONFLICT … DO UPDATE SET seq = nextval(…)`
+ *     (re-mint `seq` off the BIGSERIAL's own sequence) — same outcome, structurally different statements.
+ *   - the inbox overflow-scan needs `LIMIT 100000 OFFSET ?` on TiDB (MySQL-protocol requires a LIMIT
+ *     alongside OFFSET) but plain `OFFSET $2` on PG.
+ *   - bulk delete-by-id-set: `id IN (?,?,…)` (dynamic placeholder count) vs `id = ANY($n::text[])` /
+ *     `seq = ANY($n::bigint[])` (array bind) — both twins do this for `reap` and the inbox overflow drop.
+ *   - `run` is TEXT (not jsonb) on PG — matches TiDB's plain string column, so JSON binding is
+ *     `JSON.stringify` verbatim on BOTH dialects (no `pgProtocolJsonStringify` envelope needed here; that
+ *     concern belongs to stores whose column IS jsonb, e.g. checkpoint-store-sql.ts).
+ *   - affectedRows vs rowCount (via SqlDriver's normalized `affected`).
+ *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates
+ *     tables).
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { summarizeWorkflowRun, type WorkflowRunStore } from "@sema-agent/core";
@@ -5,16 +61,29 @@ import { type WorkflowCompletionInbox, type WorkflowCompletionInboxEntry } from
 import type { WorkflowNotifyJournalStore, WorkflowNotifyJournalEntry } from "../orchestration/workflow-notify-journal.js";
 import { type SqlDriver } from "./sql-driver.js";
 type WorkflowRun = Parameters<WorkflowRunStore["put"]>[1];
+/** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
+ *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
+ *  `put` (create, small) still throws on a real failure. Mirrors the journal's oversize skip-degrade. */
 export declare const MAX_RUN_BLOB_BYTES: number;
 declare const onWarnType: (msg: string, meta: Record<string, unknown>) => void;
 export type InboxWarn = typeof onWarnType;
+/** Review fix (1.108, lens④ HIGH): an oversize blob must NOT fail the update outright — core's persist chain
+ *  treats `false` as a CAS loss and does NOT advance its tracked rev, so once a run outgrows the cap EVERY later
+ *  write (including the TERMINAL one) keeps failing → the durable row is stuck `running` forever and the 24h
+ *  orphan sweep finalizes a genuinely-completed run as `abandoned`. Instead degrade the PAYLOAD, not the write:
+ *  step 1 truncate the two unbounded strings (result/error); step 2 drop the heavy arrays (phases/agents/groups)
+ *  with an explicit marker. Returns null only when even the skeleton is oversize (physics — caller keeps the
+ *  prior revision, matching the old behavior for that corner). Dialect-neutral (pure JS, no SQL) — shared
+ *  verbatim by both twins. */
 export declare function slimOversizeRun(run: WorkflowRun & {
     id: string;
     scope: string;
 }, maxBytes: number): string | null;
+/** Dual-dialect durable `WorkflowRunStore`. See the file header for the dialect-delta ledger. */
 export declare class SqlWorkflowRunStore implements WorkflowRunStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     put(id: string, run: WorkflowRun): Promise<void>;
     get(id: string): Promise<WorkflowRun | null>;
@@ -26,6 +95,11 @@ export declare class SqlWorkflowRunStore implements WorkflowRunStore {
         limit?: number;
         session?: string;
     }): Promise<ReturnType<typeof summarizeWorkflowRun>[]>;
+    /** Retention (the store never auto-purges; reap is explicit): the contract's `reap` is scope-keyed and the
+     *  contract deliberately has NO cross-scope enumeration — but the SQL twin CAN enumerate (DISTINCT on the
+     *  extracted scope column), which is exactly what a periodic deployment sweep needs. Walks every scope through
+     *  the contract-faithful `reap` (terminal-only; running rows are the orphan-grace sweep's business). Service
+     *  extension, not a contract member. Byte-identical text on both dialects (no params) — no q() needed. */
     reapAllScopes(now: number, opts: {
         maxAgeMs?: number;
         keep?: number;
@@ -35,6 +109,7 @@ export declare class SqlWorkflowRunStore implements WorkflowRunStore {
         keep?: number;
     }): Promise<number>;
 }
+/** Dual-dialect `WorkflowCompletionInbox`. See the file header for the dialect-delta ledger. */
 export declare class SqlWorkflowCompletionInbox implements WorkflowCompletionInbox {
     protected readonly db: SqlDriver;
     private readonly onWarn?;
@@ -47,6 +122,10 @@ export declare class SqlWorkflowCompletionInbox implements WorkflowCompletionInb
     purge(sessionId: string, purgedOwner?: string | null): Promise<void>;
     markTerminalServed(sessionId: string, runId: string): Promise<void>;
 }
+/**
+ * Dual-dialect `WorkflowNotifyJournalStore` — the crash-safe recovery backlog for at-least-once completion
+ * notify. See the file header for the dialect-delta ledger.
+ */
 export declare class SqlWorkflowNotifyJournalStore implements WorkflowNotifyJournalStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
@@ -60,9 +139,13 @@ export declare class SqlWorkflowNotifyJournalStore implements WorkflowNotifyJour
     }): Promise<void>;
     ack(runId: string, ackedAt: number): Promise<void>;
     listPending(): Promise<WorkflowNotifyJournalEntry[]>;
+    /** Retention (same sweep as reapAllScopes): ACKED rows are pure history — without this the twin re-opens
+     *  the unbounded-growth hole the same release closed for workflow_run. Pending rows are NEVER reaped (they
+     *  are the recovery backlog; the orphan-grace sweep is what retires a stuck pending run). */
     reapAcked(before: number): Promise<number>;
     get(runId: string): Promise<WorkflowNotifyJournalEntry | null>;
 }
+/** MySQL-protocol (TiDB) bindings — historical class names + ctor shapes preserved. */
 export declare class TiDBWorkflowRunStore extends SqlWorkflowRunStore {
     constructor(pool: MySqlPool);
 }
@@ -72,6 +155,7 @@ export declare class TiDBWorkflowCompletionInbox extends SqlWorkflowCompletionIn
 export declare class TiDBWorkflowNotifyJournalStore extends SqlWorkflowNotifyJournalStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL bindings — historical class names + ctor shapes preserved. */
 export declare class PgWorkflowRunStore extends SqlWorkflowRunStore {
     constructor(pool: PgPool);
 }

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

@@ -1,8 +1,19 @@
 import { summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError } from "@sema-agent/core";
 import { foldKeyFamily, MAX_PENDING_PER_SESSION, PURGE_FENCE_MS, SERVED_FENCE_MS, } from "../orchestration/workflow-completion-inbox.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
+ *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
+ *  `put` (create, small) still throws on a real failure. Mirrors the journal's oversize skip-degrade. */
 export const MAX_RUN_BLOB_BYTES = 4 * 1024 * 1024;
 const onWarnType = (msg, meta) => void [msg, meta];
+/** Review fix (1.108, lens④ HIGH): an oversize blob must NOT fail the update outright — core's persist chain
+ *  treats `false` as a CAS loss and does NOT advance its tracked rev, so once a run outgrows the cap EVERY later
+ *  write (including the TERMINAL one) keeps failing → the durable row is stuck `running` forever and the 24h
+ *  orphan sweep finalizes a genuinely-completed run as `abandoned`. Instead degrade the PAYLOAD, not the write:
+ *  step 1 truncate the two unbounded strings (result/error); step 2 drop the heavy arrays (phases/agents/groups)
+ *  with an explicit marker. Returns null only when even the skeleton is oversize (physics — caller keeps the
+ *  prior revision, matching the old behavior for that corner). Dialect-neutral (pure JS, no SQL) — shared
+ *  verbatim by both twins. */
 export function slimOversizeRun(run, maxBytes) {
     const MARK = "…[truncated: run blob exceeded the store cap]";
     const cut = (s) => s.slice(0, 4000) + MARK;
@@ -18,20 +29,24 @@ export function slimOversizeRun(run, maxBytes) {
     blob = JSON.stringify(step2);
     return Buffer.byteLength(blob) <= maxBytes ? blob : null;
 }
+/** Dual-dialect durable `WorkflowRunStore`. See the file header for the dialect-delta ledger. */
 export class SqlWorkflowRunStore {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
     async put(id, run) {
-        const stored = { ...run, id, rev: run.rev ?? 0 };
+        const stored = { ...run, id, rev: run.rev ?? 0 }; // key authoritative + observed-rev base (InMemory parity)
         try {
             await this.db.query(this.q("INSERT INTO workflow_run (id, scope, status, run, rev, created_at, ended_at) VALUES (?,?,?,?,?,?,?)", "INSERT INTO workflow_run (id, scope, status, run, rev, created_at, ended_at) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [id, run.scope, run.status, JSON.stringify(stored), stored.rev, run.createdAt, run.endedAt ?? null]);
         }
         catch (e) {
+            // create-once error every backend throws (contract) — dup-key classification is dialect-specific:
+            // TiDB's errno-string ER_DUP_ENTRY vs PG's SQLSTATE 23505.
             const isDupKey = this.db.dialect === "tidb" ? e.code === "ER_DUP_ENTRY" : e.code === "23505";
             if (isDupKey) {
                 throw new WorkflowRunStoreError("workflow_run.already_exists", "workflow run id already exists");
@@ -45,23 +60,32 @@ export class SqlWorkflowRunStore {
         if (!r)
             return null;
         const run = JSON.parse(String(r.run));
-        run.rev = Number(r.rev);
+        run.rev = Number(r.rev); // the COLUMN is the OCC authority — overlay it (the blob's rev may predate a CAS bump)
         return run;
     }
     async update(id, scope, run, expect) {
+        // id/scope immutable in the stored payload (InMemory parity: key + partition are authoritative). The blob's
+        // rev is NOT trusted (see get's overlay) — write it as-is; the column bump below is the real OCC state.
         let blob = JSON.stringify({ ...run, id, scope });
         if (Buffer.byteLength(blob) > MAX_RUN_BLOB_BYTES) {
+            // Oversize degrade (1.108 review fix): slim the payload so the write — critically the TERMINAL one —
+            // still lands (a `false` here would never be retried with a smaller payload; see slimOversizeRun).
             const slim = slimOversizeRun({ ...run, id, scope }, MAX_RUN_BLOB_BYTES);
             if (slim === null)
-                return false;
+                return false; // even the skeleton is oversize — keep the prior revision
             blob = slim;
         }
         const res = await this.db.query(this.q(`UPDATE workflow_run SET run = ?, rev = rev + 1, status = ?, ended_at = ? WHERE id = ? AND scope = ?${expect !== undefined ? " AND rev = ?" : ""}`, `UPDATE workflow_run SET run = $1, rev = rev + 1, status = $2, ended_at = $3 WHERE id = $4 AND scope = $5${expect !== undefined ? " AND rev = $6" : ""}`), expect !== undefined
             ? [blob, run.status, run.endedAt ?? null, id, scope, expect.rev]
             : [blob, run.status, run.endedAt ?? null, id, scope]);
-        return res.affected === 1;
+        return res.affected === 1; // rev always bumps → affected is a faithful CAS verdict
     }
     async listByScope(scope, opts) {
+        // 🔴 genuinely-divergent CONSTRUCTION (not just SQL text): PG's `$n` placeholders are POSITIONAL and must
+        // track `params.length` as each optional clause is appended, while TiDB's `?` is positionless — a single
+        // `q()` pair can't express that, so the where/limit assembly forks per dialect. The FILTER logic itself
+        // (status → session → limit, session dropping unmatched/absent-key rows via JSON extraction, limit applied
+        // last) is identical; only the placeholder bookkeeping differs.
         const params = [scope];
         let where;
         let limit = "";
@@ -72,6 +96,9 @@ export class SqlWorkflowRunStore {
                 params.push(opts.status);
             }
             if (opts?.session !== undefined) {
+                // core 1.368([1516]②)session 下推臂:limit 前应用、严格等值、无字段行剔除(JSON path 缺席 →
+                // NULL → `= ?` 恒假 ✓)。JSON 提取而非投影列:对存量行零迁移直接生效;行量有 retention 界,
+                // 与本函数固有的全行 JSON.parse 同量级。
                 where += " AND JSON_UNQUOTE(JSON_EXTRACT(run, '$.originatingSessionId')) = ?";
                 params.push(opts.session);
             }
@@ -87,6 +114,7 @@ export class SqlWorkflowRunStore {
                 where += ` AND status = $${params.length}`;
             }
             if (opts?.session !== undefined) {
+                // core 1.368([1516]②)session 下推臂(TiDB twin 同案注释):JSON 提取、limit 前、缺席键 → NULL → 拒 ✓
                 params.push(opts.session);
                 where += ` AND run::json->>'originatingSessionId' = $${params.length}`;
             }
@@ -95,6 +123,7 @@ export class SqlWorkflowRunStore {
                 limit = ` LIMIT $${params.length}`;
             }
         }
+        // Sort in SQL (newest first), summarize via core's SHARED projection (anti-drift).
         const { rows } = await this.db.query(`SELECT run, rev FROM workflow_run WHERE ${where} ORDER BY created_at DESC, id DESC${limit}`, params);
         return rows.map((r) => {
             const run = JSON.parse(String(r.run));
@@ -102,6 +131,11 @@ export class SqlWorkflowRunStore {
             return summarizeWorkflowRun(run);
         });
     }
+    /** Retention (the store never auto-purges; reap is explicit): the contract's `reap` is scope-keyed and the
+     *  contract deliberately has NO cross-scope enumeration — but the SQL twin CAN enumerate (DISTINCT on the
+     *  extracted scope column), which is exactly what a periodic deployment sweep needs. Walks every scope through
+     *  the contract-faithful `reap` (terminal-only; running rows are the orphan-grace sweep's business). Service
+     *  extension, not a contract member. Byte-identical text on both dialects (no params) — no q() needed. */
     async reapAllScopes(now, opts) {
         const { rows } = await this.db.query("SELECT DISTINCT scope FROM workflow_run");
         let total = 0;
@@ -111,7 +145,9 @@ export class SqlWorkflowRunStore {
     }
     async reap(scope, now, opts) {
         if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
-            return 0;
+            return 0; // retention is always explicit
+        // Cheap columns only; terminal-set + keep-N semantics computed in JS to match InMemory EXACTLY
+        // (isTerminalWorkflowStatus is core's — no status list duplicated into SQL).
         const { rows } = await this.db.query(this.q("SELECT id, status, created_at, ended_at FROM workflow_run WHERE scope = ? ORDER BY created_at DESC, id DESC", "SELECT id, status, created_at, ended_at FROM workflow_run WHERE scope = $1 ORDER BY created_at DESC, id DESC"), [scope]);
         const terminal = rows.filter((r) => isTerminalWorkflowStatus(String(r.status)));
         const doomed = [];
@@ -125,12 +161,16 @@ export class SqlWorkflowRunStore {
         }
         if (doomed.length === 0)
             return 0;
+        // Bulk delete-by-id-set: TiDB expands a dynamic `IN (?,?,…)` (one placeholder per id, spread params);
+        // PG binds the whole set as one array via `= ANY($2::text[])`. Same result set, different statement shape.
         const res = await this.db.query(this.q(`DELETE FROM workflow_run WHERE scope = ? AND id IN (${doomed.map(() => "?").join(",")})`, "DELETE FROM workflow_run WHERE scope = $1 AND id = ANY($2::text[])"), this.db.dialect === "tidb" ? [scope, ...doomed] : [scope, doomed]);
         return res.affected;
     }
 }
+/** The SQL fence row kinds. `run_id = ''` on a purge fence (session-wide). */
 const KIND_SERVED = "served";
 const KIND_PURGE = "purge";
+/** Dual-dialect `WorkflowCompletionInbox`. See the file header for the dialect-delta ledger. */
 export class SqlWorkflowCompletionInbox {
     db;
     onWarn;
@@ -147,26 +187,43 @@ export class SqlWorkflowCompletionInbox {
     async enqueue(entry) {
         const now = Date.now();
         await this.sweepFences(now);
+        // Served fence FIRST (per-runId — cross-replica: a poll served on ANOTHER replica fences us here).
         const served = await this.db.query(this.q("SELECT 1 FROM workflow_inbox_fence WHERE session_id = ? AND kind = ? AND run_id IN (?, ?) AND until_ms >= ?", "SELECT 1 FROM workflow_inbox_fence WHERE session_id = $1 AND kind = $2 AND run_id IN ($3, $4) AND until_ms >= $5"), [entry.sessionId, KIND_SERVED, entry.runId, foldKeyFamily(entry.runId), now]);
         if (served.rows.length > 0) {
             this.onWarn?.("workflow_completion_enqueue_after_poll_served", { sessionId: entry.sessionId, runId: entry.runId });
             return;
         }
+        // Purge fence: owner-scoped exactly like the File impl (owner_known=0 → conservative fence-all;
+        // owner_known=1 → fences only the SAME owner; a different owner = a new legitimate claimant, passes).
         const purge = await this.db.query(this.q("SELECT owner, owner_known FROM workflow_inbox_fence WHERE session_id = ? AND kind = ? AND run_id = '' AND until_ms >= ?", "SELECT owner, owner_known FROM workflow_inbox_fence WHERE session_id = $1 AND kind = $2 AND run_id = '' AND until_ms >= $3"), [entry.sessionId, KIND_PURGE, now]);
         const pf = purge.rows[0];
         if (pf && (Number(pf.owner_known) === 0 || (pf.owner === null ? entry.owner === null : String(pf.owner) === entry.owner))) {
             this.onWarn?.("workflow_completion_enqueue_after_purge", { sessionId: entry.sessionId, runId: entry.runId });
             return;
         }
+        // Atomic move-to-tail (1.108 review fix — the prior DELETE-then-INSERT had a crash window that dropped the
+        // old entry; self-healing via the notify journal, but atomic is free here). Genuinely divergent statement:
+        // TiDB `REPLACE` = delete-conflicting-row + insert atomically, and omitting `seq` mints a fresh
+        // AUTO_INCREMENT = tail. PG has no REPLACE, so the twin is an upsert that explicitly re-mints `seq` off the
+        // BIGSERIAL's own sequence — same outcome (idempotent-on-runId + move-to-tail in ONE statement).
         await this.db.query(this.q("REPLACE INTO workflow_completion_inbox (session_id, run_id, owner, status, summary, enqueued_at, kind, payload) VALUES (?,?,?,?,?,?,?,?)", "INSERT INTO workflow_completion_inbox (session_id, run_id, owner, status, summary, enqueued_at, kind, payload) VALUES ($1,$2,$3,$4,$5,$6,$7,$8) " +
             "ON CONFLICT (session_id, run_id) DO UPDATE SET seq = nextval(pg_get_serial_sequence('workflow_completion_inbox','seq')), " +
             "owner = EXCLUDED.owner, status = EXCLUDED.status, summary = EXCLUDED.summary, enqueued_at = EXCLUDED.enqueued_at, kind = EXCLUDED.kind, payload = EXCLUDED.payload"), [entry.sessionId, entry.runId, entry.owner, entry.status, entry.summary, entry.enqueuedAt, entry.kind ?? null, entry.payload ?? null]);
+        // 1.108 review (lens① MAJOR ×2): the File impl's check-then-set is atomic on one event loop; here the
+        // fence check and the INSERT are two network statements, so a fence written IN BETWEEN (a poll served on
+        // another replica, or a racing purge) would leave fence + pending row coexisting → the next drain re-pushes
+        // an already-served/purged completion. Close the window by RE-CHECKING after the insert and self-revoking —
+        // ordering guarantees the loser is always visible to someone: markTerminalServed/purge write their fence
+        // BEFORE their delete, so either their delete kills our row, or our re-check sees their fence.
+        // (Residual, documented: a purge racing a NEW claimant's enqueue between fence-write and session-DELETE can
+        // still drop that one push — ms window + sessionId reclaim in it is contrived; the WorkflowStatus poll floor
+        // + notify-journal recovery cover it. File parity: purge drops the whole session queue there too.)
         const confirm = await this.db.query(this.q("SELECT kind, owner, owner_known FROM workflow_inbox_fence WHERE session_id = ? AND until_ms >= ? AND (run_id IN (?, ?) OR (kind = ? AND run_id = ''))", "SELECT kind, owner, owner_known FROM workflow_inbox_fence WHERE session_id = $1 AND until_ms >= $2 AND (run_id IN ($3, $4) OR (kind = $5 AND run_id = ''))"), [entry.sessionId, now, entry.runId, foldKeyFamily(entry.runId), KIND_PURGE]);
         for (const f of confirm.rows) {
             const isServed = String(f.kind) === KIND_SERVED;
             const purgeFencesUs = !isServed && (Number(f.owner_known) === 0 || (f.owner === null ? entry.owner === null : String(f.owner) === entry.owner));
             if (isServed || purgeFencesUs) {
-                await this.ack(entry.sessionId, entry.runId);
+                await this.ack(entry.sessionId, entry.runId); // self-revoke: the fence won the race
                 this.onWarn?.(isServed ? "workflow_completion_enqueue_after_poll_served" : "workflow_completion_enqueue_after_purge", {
                     sessionId: entry.sessionId,
                     runId: entry.runId,
@@ -174,14 +231,21 @@ export class SqlWorkflowCompletionInbox {
                 return;
             }
         }
+        // Cap: drop-oldest beyond MAX_PENDING_PER_SESSION (warn per drop, File parity). TiDB requires a LIMIT
+        // alongside OFFSET (MySQL-protocol syntax); PG's OFFSET stands alone.
         const over = await this.db.query(this.q("SELECT seq, run_id FROM workflow_completion_inbox WHERE session_id = ? ORDER BY seq DESC LIMIT 100000 OFFSET ?", "SELECT seq, run_id FROM workflow_completion_inbox WHERE session_id = $1 ORDER BY seq DESC OFFSET $2"), [entry.sessionId, MAX_PENDING_PER_SESSION]);
         if (over.rows.length > 0) {
+            // Bulk delete-by-seq-set: dynamic `IN (?,?,…)` on TiDB vs array-bound `= ANY($2::bigint[])` on PG.
             await this.db.query(this.q(`DELETE FROM workflow_completion_inbox WHERE session_id = ? AND seq IN (${over.rows.map(() => "?").join(",")})`, "DELETE FROM workflow_completion_inbox WHERE session_id = $1 AND seq = ANY($2::bigint[])"), this.db.dialect === "tidb" ? [entry.sessionId, ...over.rows.map((r) => r.seq)] : [entry.sessionId, over.rows.map((r) => r.seq)]);
             for (const r of over.rows)
                 this.onWarn?.("workflow_completion_inbox_overflow", { sessionId: entry.sessionId, droppedRunId: String(r.run_id) });
         }
     }
     async pending(sessionId) {
+        // 2026-07-11(同一缺陷的 SQL 半场):filter SERVED-fenced rows like the in-memory
+        // inbox does — markTerminalServed's fence-INSERT and ack-DELETE are two statements, and a drain on
+        // another replica between them re-emitted an already-served completion (the in-memory pending()
+        // filters by servedAt; this brings the SQL twin to the same semantics).
         const { rows } = await this.db.query(this.q("SELECT i.run_id, i.owner, i.status, i.summary, i.enqueued_at, i.kind, i.payload FROM workflow_completion_inbox i " +
             "WHERE i.session_id = ? AND NOT EXISTS (SELECT 1 FROM workflow_inbox_fence f WHERE f.session_id = i.session_id AND f.kind = ? AND f.run_id IN (i.run_id, REGEXP_REPLACE(i.run_id, '#[0-9]+$', '')) AND f.until_ms >= ?) " +
             "ORDER BY i.seq ASC", "SELECT i.run_id, i.owner, i.status, i.summary, i.enqueued_at, i.kind, i.payload FROM workflow_completion_inbox i " +
@@ -204,6 +268,7 @@ export class SqlWorkflowCompletionInbox {
     async purge(sessionId, purgedOwner) {
         const now = Date.now();
         await this.sweepFences(now);
+        // Fence FIRST (an enqueue racing the purge must lose), then clear. Upsert = a re-purge refreshes the window.
         await this.db.query(this.q("INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES (?,?,?,?,?,?) " +
             "ON DUPLICATE KEY UPDATE owner = VALUES(owner), owner_known = VALUES(owner_known), until_ms = VALUES(until_ms)", "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,'',$3,$4,$5) " +
             "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET owner = EXCLUDED.owner, owner_known = EXCLUDED.owner_known, until_ms = EXCLUDED.until_ms"), this.db.dialect === "tidb"
@@ -218,9 +283,15 @@ export class SqlWorkflowCompletionInbox {
             "ON DUPLICATE KEY UPDATE until_ms = VALUES(until_ms)", "INSERT INTO workflow_inbox_fence (session_id, kind, run_id, owner, owner_known, until_ms) VALUES ($1,$2,$3,NULL,0,$4) " +
             "ON CONFLICT (session_id, kind, run_id) DO UPDATE SET until_ms = EXCLUDED.until_ms"), [sessionId, KIND_SERVED, runId, now + SERVED_FENCE_MS]);
         await this.ack(sessionId, runId);
+        // design/144 家族 ack(与 in-memory 语义对齐):fleet 帧无 seq 传家族前缀,park 行是 seq 键——
+        // 精确 DELETE 必 miss。剥行键尾部 #digits 与传入前缀比对(REGEXP_REPLACE/regexp_replace 语义=foldKeyFamily)。
         await this.db.query(this.q("DELETE FROM workflow_completion_inbox WHERE session_id = ? AND run_id <> ? AND REGEXP_REPLACE(run_id, '#[0-9]+$', '') = ?", "DELETE FROM workflow_completion_inbox WHERE session_id = $1 AND run_id <> $2 AND regexp_replace(run_id, '#[0-9]+$', '') = $3"), [sessionId, runId, runId]);
     }
 }
+/**
+ * Dual-dialect `WorkflowNotifyJournalStore` — the crash-safe recovery backlog for at-least-once completion
+ * notify. See the file header for the dialect-delta ledger.
+ */
 export class SqlWorkflowNotifyJournalStore {
     db;
     constructor(db) {
@@ -230,6 +301,8 @@ export class SqlWorkflowNotifyJournalStore {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
     async record(input) {
+        // Idempotent-on-runId (a second record for the same run — incl. an acked one — is a no-op): TiDB
+        // `INSERT IGNORE` vs PG `ON CONFLICT (run_id) DO NOTHING`.
         await this.db.query(this.q("INSERT IGNORE INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at) VALUES (?,?,0,?,?,?)", "INSERT INTO workflow_notify_journal (run_id, scope, acked, source_task_id, principal, created_at) VALUES ($1,$2,0,$3,$4,$5) ON CONFLICT (run_id) DO NOTHING"), [input.runId, input.scope, input.sourceTaskId ?? null, input.principal ?? null, input.createdAt]);
     }
     async ack(runId, ackedAt) {
@@ -246,6 +319,9 @@ export class SqlWorkflowNotifyJournalStore {
             createdAt: Number(r.created_at),
         }));
     }
+    /** Retention (same sweep as reapAllScopes): ACKED rows are pure history — without this the twin re-opens
+     *  the unbounded-growth hole the same release closed for workflow_run. Pending rows are NEVER reaped (they
+     *  are the recovery backlog; the orphan-grace sweep is what retires a stuck pending run). */
     async reapAcked(before) {
         const res = await this.db.query(this.q("DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at < ?", "DELETE FROM workflow_notify_journal WHERE acked = 1 AND acked_at < $1"), [before]);
         return res.affected;
@@ -266,6 +342,7 @@ export class SqlWorkflowNotifyJournalStore {
         };
     }
 }
+/** MySQL-protocol (TiDB) bindings — historical class names + ctor shapes preserved. */
 export class TiDBWorkflowRunStore extends SqlWorkflowRunStore {
     constructor(pool) {
         super(mysqlDriver(pool));
@@ -281,6 +358,7 @@ export class TiDBWorkflowNotifyJournalStore extends SqlWorkflowNotifyJournalStor
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL bindings — historical class names + ctor shapes preserved. */
 export class PgWorkflowRunStore extends SqlWorkflowRunStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/worktree-isolation.d.ts

@@ -1,16 +1,61 @@
 import { type ExecutionEnv, type ExecutionEnvFactory } from "@sema-agent/core";
+/** Structured logger surface this wrapper uses (matches the service `logger`; all calls optional-chained). */
 export interface WorktreeIsolationLogger {
     info?(event: string, fields?: Record<string, unknown>): void;
     warn?(event: string, fields?: Record<string, unknown>): void;
 }
+/** Options for {@link withWorktreeIsolation}. ALL fields are operator-supplied (config/closure) — NONE come
+ *  from a `TaskSpec` or the factory `ctx` (that is the trust boundary; see the file header). */
 export interface WorktreeIsolationOptions {
+    /**
+     * The operator-trusted base repository root — where `git worktree add/remove/prune` run (the base env's cwd
+     * for the git command). MUST be an absolute path to a git repo. This is a CLOSURE value (config), never a
+     * task input, so an untrusted caller can never redirect worktree creation to another path.
+     */
     repoRoot: string;
+    /**
+     * Operator-trusted allowlist of permitted repo roots. {@link repoRoot} MUST be contained within (or equal
+     * to) one of these — checked at wrap time, fails LOUD otherwise. Defence in depth against a mis-wired
+     * deployment (e.g. a `REPO_ROOT` env accidentally pointed outside the intended tree). Default: `[repoRoot]`
+     * (repoRoot trivially permits itself) — pass a broader set only when the operator intends multiple roots.
+     */
     allowedRoots?: string[];
+    /**
+     * The SHARED base {@link ExecutionEnv} used to run the git worktree commands (`add`/`remove`/`prune`). Its
+     * own cwd is irrelevant (core passes `cwd: repoRoot` explicitly on every git call) — it only needs a working
+     * `exec` with `git` on PATH. For the host lane this is a host env; we keep it as a single long-lived env per
+     * deployment (git ops are cheap and serial-safe). The reaper reuses it for {@link pruneWorktrees}.
+     */
     baseEnvForGit: ExecutionEnv;
+    /**
+     * Env-SPECIFIC constructor of a worktree-ROOTED {@link ExecutionEnv} (the only lane-specific bit). Host lane:
+     * `(dir) => new RemoteHostExecutionEnv({ workspaceDir: dir })` — a host env whose fs/shell operate relative
+     * to `dir` AND whose own `destroy()` does NOT delete `dir` (persistent-dir mode), so core's destroy wrapper
+     * owns removal via `git worktree remove`. A single-E2B/k8s deployment would pass a remote env rooted at the
+     * worktree dir (follow-on — see file header re: suspend incompatibility on the host lane).
+     */
     rootEnvAt: (worktreeDir: string) => ExecutionEnv | Promise<ExecutionEnv>;
+    /** Base commit/ref for every worktree (default core's `HEAD` at creation time). Operator-supplied. */
     commit?: string;
     logger?: WorktreeIsolationLogger;
 }
+/**
+ * Wrap a deployment's `executionEnvFactory` so an agent with `ctx.isolation === "worktree"` runs in its own
+ * detached git worktree. See the file header for the full contract + trust gate + caveats.
+ *
+ * Throws at WRAP time (fail-loud, not faked) if `repoRoot` is not contained within `allowedRoots` — a
+ * mis-wired deployment must not silently git-worktree an arbitrary path.
+ */
 export declare function withWorktreeIsolation(baseFactory: ExecutionEnvFactory, opts: WorktreeIsolationOptions): ExecutionEnvFactory;
+/**
+ * Best-effort reaper hook: deregister worktrees orphaned by a process crash (the Runner never reached
+ * `destroy`). Core's {@link pruneWorktrees} runs `git worktree prune` against the base repo — it cleans up
+ * registrations whose worktree dirs are already gone. Wired into the service reaper (userland; core ships no
+ * post-kill Runner hook). NEVER throws (a prune failure is logged, never fatal).
+ *
+ * NOTE: `git worktree prune` only deregisters worktrees whose DIRECTORY is missing. A crashed run that left
+ * the dir intact is NOT reaped by prune alone — that is acceptable for v1 (the worktree lives under the known
+ * `.sema-worktrees/` parent and is human-/script-reapable; a stricter age-based sweep is a follow-on).
+ */
 export declare function reapOrphanWorktrees(baseEnvForGit: ExecutionEnv, repoRoot: string, logger?: WorktreeIsolationLogger): Promise<void>;
 //# sourceMappingURL=worktree-isolation.d.ts.map