@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/send-user-file.js

@@ -1,18 +1,73 @@
+/**
+ * SendUserFile — the dual-track public-link ISSUER (design: sema-deploy docs/design/S3-PUBLIC-LINKS.md,
+ * settled cross-repo 2026-07-14; tool name SendUserFile is final).
+ *
+ * The LLM hands a user a file over the web session as a URL the browser fetches DIRECTLY from S3/MinIO
+ * (server relay was rejected: double bandwidth on third-party S3 + loses CDN). Two tracks, keyed on ttl:
+ *
+ *  - ttl == 0 (PERMANENT, the default): upload to the anonymous-GET public bucket under an unguessable
+ *    `<scopeSeg>/<uuidv7>/<name>` key (capability URL — GET-only bucket policy, List disabled, so the prefix IS
+ *    the secret; scopeSeg = hashed tenant segment, see {@link scopeSegment} — multi-tenant list/revoke handle,
+ *    1.190.0 [768]②a). URL = plain `<publicEndpoint>/<bucket>/<key>` — no signature, never expires, CDN-cacheable.
+ *    Revocation = delete the object.
+ *    ⚠️ Bucket-policy footgun (live-verified 2026-07-14): `mc anonymous set download` ALSO enables
+ *    ListBucket — an anonymous `GET /<bucket>/?list-type=2` then enumerates every uuidv7 key and the
+ *    capability design collapses. Deployments MUST use a GetObject-only JSON policy
+ *    (`mc anonymous set-json` with Action=["s3:GetObject"] on `arn:aws:s3:::<bucket>/*`): GET 200, LIST 403.
+ *  - 0 < ttl ≤ 7d: upload to the PRIVATE bucket and return a SigV4 presigned GET. The signature is
+ *    computed against the PUBLIC endpoint (SigV4 binds Host — signing with the internal host would 403
+ *    the user's browser; the reverse proxy must pass Host through).
+ *  - ttl > 7d: fail-loud — SigV4 caps presign at 7 days (physical limit); the caller should use ttl=0.
+ *
+ * Uploads always go through the INTERNAL endpoint (server-side PUT, its own signed request — Host binding
+ * is per-request, so internal-for-write + public-for-read coexist). Zero-dependency posture: presignS3Url
+ * + fetch, same as MinioBlobBackend / the k8s adapter.
+ */
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
+/** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
 export const PRESIGN_MAX_TTL_SEC = 604_800;
+/**
+ * Multi-tenant governance (clay ruling 2026-07-14, blackboard [768]② variant a with a HASHED segment): every
+ * object key carries a per-tenant SCOPE SEGMENT so tenants can be listed/revoked by prefix on the store itself,
+ * WITHOUT leaking the principal into the (user-visible, forwardable) URL. The segment is
+ * `HMAC-SHA256(secretKey, "sendfile-scope:" + scope)` hex, truncated to 32 chars:
+ *  - keyed on the S3 SECRET KEY — server-held and stable, so the mapping is deterministic per deployment but
+ *    unforgeable/unenumerable from outside (a URL holder cannot test principal guesses without the key);
+ *  - the "sendfile-scope:" DOMAIN SEPARATOR pins this HMAC use — the same secret signs SigV4 requests, and a
+ *    cross-protocol collision between "scope segment" and any other HMAC-of-attacker-controlled-string use is
+ *    exactly what domain separation exists to prevent;
+ *  - 32 hex chars (128 bits) is a NAMESPACE label, not a secret: the cross-tenant BIRTHDAY bound at even a
+ *    billion tenants is ~n²/2^129 ≈ 2^-69 — negligible. (The earlier 16-hex/64-bit cut had a ~2.7% birthday
+ *    collision probability at that scale — n²/2^65, NOT the per-pair 2^-32 the old note claimed; codex audit
+ *    F4, widened pre-release at zero cost.) Capability secrecy still lives in the uuidv7 segment. Key budget
+ *    stays comfortable: worst-case private-track key = 9 ("sendfile/") + 32 + 1 + 36 + 1 + 128 = 207 chars,
+ *    under both sendfile_link.object_key VARCHAR(512) and S3's 1024-byte key ceiling.
+ * scope undefined/"" (single-user deployments have no principal) → the literal "_" sentinel (same sentinel the
+ * checkpoint scope column uses for anonymous), so the key SHAPE is uniform across deployments.
+ * ⚠️ Objects issued before 1.190.0 have NO scope segment (`<uuidv7>/<name>`); they stay valid — the segment is
+ * purely additive (URLs are capability-complete either way), zero migration.
+ */
 export function scopeSegment(secretKey, scope) {
     if (scope === undefined || scope === "")
         return "_";
     return createHmac("sha256", secretKey).update(`sendfile-scope:${scope}`).digest("hex").slice(0, 32);
 }
+/**
+ * Collapse an arbitrary client-supplied name to ONE safe path segment: strip directories (both
+ * separators), control/bidi characters (the session-title sanitize class), leading dots (no hidden
+ * files / no "." ".."), and cap the length (S3 key segment budget; keep the extension when truncating).
+ * Empty in ⇒ "file".
+ */
 export function sanitizeSendFileName(name) {
     const base = (name ?? "").split(/[/\\]/).pop() ?? "";
     let clean = base.replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").replace(/^\.+/, "").trim();
     if (clean.length > 128) {
         const dot = clean.lastIndexOf(".");
         const ext = dot > 0 && clean.length - dot <= 16 ? clean.slice(dot) : "";
+        // code-point 安全截断:UTF-16 slice 会切断代理对,留下 lone surrogate → encodeURIComponent 抛
+        // URIError(此时对象已上传,链接却铸不出来)。按 code point 截,预算=128-ext 的 UTF-16 units。
         const budget = 128 - ext.length;
         let head = "";
         for (const ch of clean) {
@@ -51,9 +106,11 @@ export function createSendUserFileIssuer(cfg, deps) {
             throw new Error(`SendUserFile ttl must be a non-negative INTEGER of seconds (0 = permanent; SigV4 X-Amz-Expires is integer-only); got ${ttl}`);
         const name = sanitizeSendFileName(filename);
         const publicBase = cfg.publicEndpoint.replace(/\/+$/, "");
-        const seg = scopeSegment(cfg.secretKey, scope);
+        const seg = scopeSegment(cfg.secretKey, scope); // hashed tenant segment ("_" single-user) — see scopeSegment doc
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         if (ttl === 0) {
+            // Permanent track: capability URL on the anonymous-GET bucket. Key = <scopeSeg>/<uuidv7>/<name>
+            // (pre-1.190 objects have no scope segment — additive, both shapes stay valid).
             const key = `${seg}/${uuidv7()}/${name}`;
             await upload(cfg.publicBucket, key, bytes);
             const url = `${publicBase}/${cfg.publicBucket}/${key.split("/").map(encodeURIComponent).join("/")}`;
@@ -62,6 +119,7 @@ export function createSendUserFileIssuer(cfg, deps) {
         if (ttl > PRESIGN_MAX_TTL_SEC) {
             throw new Error(`SendUserFile ttl ${ttl}s exceeds the SigV4 presign ceiling (${PRESIGN_MAX_TTL_SEC}s = 7 days) — use ttl=0 for a permanent link`);
         }
+        // Presigned track: private bucket upload, GET signed against the PUBLIC endpoint (Host-bound).
         const key = `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
         await upload(cfg.privateBucket, key, bytes);
         const url = presignS3Url({
@@ -77,6 +135,9 @@ export function createSendUserFileIssuer(cfg, deps) {
         });
         return { url, filename: name, size: bytes.byteLength, ttlSec: ttl, track: "presigned", bucket: cfg.privateBucket, key, ...scopeField };
     };
+    // v2 (sandbox direct-upload): same key/track/URL algebra as issue(), split into sign-then-finalize so
+    // the BYTES move sandbox→S3 directly (server never relays; creds never enter the sandbox — only a
+    // single-object, method-bound, 120s PUT capability on a STAGING key does; see PreparedDirectUpload).
     const prepareDirectUpload = (filename, ttlSec, scope) => {
         if (cfg.publicEndpoint === undefined) {
             throw new Error("SendUserFile is not configured for public links: set S3_PUBLIC_ENDPOINT (the S3/MinIO base URL users can reach; falls back to S3_ENDPOINT when that is already public)");
@@ -91,11 +152,21 @@ export function createSendUserFileIssuer(cfg, deps) {
         const publicBase = cfg.publicEndpoint.replace(/\/+$/, "");
         const putBase = (cfg.sandboxPutEndpoint ?? cfg.publicEndpoint).replace(/\/+$/, "");
         const bucket = ttl === 0 ? cfg.publicBucket : cfg.privateBucket;
+        // Same key algebra as issue() incl. the hashed tenant segment — prepare/finalize share ONE key, so the
+        // segment is fixed here (the PUT capability is already scoped to it).
         const seg = scopeSegment(cfg.secretKey, scope);
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         const key = ttl === 0 ? `${seg}/${uuidv7()}/${name}` : `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
+        // 修3 staging two-phase: the sandbox-visible PUT capability is scoped to a STAGING key in the PRIVATE
+        // bucket (never anonymous-readable, never handed out as a URL) — the final key above gets its bytes via
+        // a server-side CopyObject only, so no /proc reader of the exec argv can ever rewrite what the user's
+        // link points at. The staging key keeps the tenant segment (orphan attribution on manual cleanup).
         const stagingBucket = cfg.privateBucket;
         const stagingKey = `${cfg.privateKeyPrefix}staging/${seg}/${uuidv7()}`;
+        // TTL 120s, not the uploader default 600: the URL rides the sandbox exec argv (visible to the sandbox's
+        // own processes / possibly an apiserver audit log) — anyone who reads it gains nothing they don't already
+        // have DURING the upload (the sandbox owns the file), and since 修3 the writable object is only the
+        // staging key anyway. Keep the window as short as a slow 100MiB upload allows.
         const putUrl = presignS3Url({
             endpoint: putBase,
             bucket: stagingBucket,
@@ -120,16 +191,21 @@ export function createSendUserFileIssuer(cfg, deps) {
                 ...(cfg.region !== undefined ? { region: cfg.region } : {}),
                 expiresSec: 60,
             });
+            // 修2: best-effort reclaim — any failure AFTER the object landed must delete it before throwing
+            // (a transient HEAD 5xx used to strand an unledgered, undelivered orphan in the bucket). Returns the
+            // TRUE outcome so error messages never claim "reclaimed" for a delete that itself failed (F2 posture).
             const reclaim = async (b, k) => {
                 try {
                     const r = await fetch(sign("DELETE", b, k), { method: "DELETE" });
-                    return r.ok || r.status === 404;
+                    return r.ok || r.status === 404; // S3 DELETE is idempotent — a missing key IS reclaimed
                 }
                 catch {
                     return false;
                 }
             };
             const outcome = (ok, what) => (ok ? `${what} reclaimed` : `${what} reclaim FAILED (orphan; operator cleanup needed)`);
+            // ① HEAD the STAGING object (internal endpoint, adapter creds): existence + a cheap early cap gate
+            // (fail before copying a huge object). Advisory only for size — the authoritative reading is ④.
             let head;
             try {
                 head = await fetch(sign("HEAD", stagingBucket, stagingKey), { method: "HEAD" });
@@ -141,7 +217,7 @@ export function createSendUserFileIssuer(cfg, deps) {
             if (head.status === 404)
                 throw new Error("SendUserFile upload verification failed: object not found after upload (HEAD 404)");
             if (!head.ok) {
-                const r = await reclaim(stagingBucket, stagingKey);
+                const r = await reclaim(stagingBucket, stagingKey); // transient 5xx ≠ missing — the object may be live; reclaim it
                 throw new Error(`SendUserFile upload verification failed: store error (HEAD ${head.status}) — ${outcome(r, "staged object")}`);
             }
             const staged = Number.parseInt(head.headers.get("content-length") ?? "", 10);
@@ -153,6 +229,9 @@ export function createSendUserFileIssuer(cfg, deps) {
                 await reclaim(stagingBucket, stagingKey);
                 throw new Error(`file exceeds the ${maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / (1024 * 1024))} MiB` : `${maxBytes} byte`} per-file cap (uploaded object was ${staged} bytes — deleted)`);
             }
+            // ② Server-side CopyObject staging→final (internal endpoint, signed x-amz-copy-source): the ONLY
+            // write the final key ever receives. NB: S3 can return 200 with an error BODY on slow copies — require
+            // the CopyObjectResult marker, not just the status.
             const copy = presignS3CopyUrl({
                 endpoint: cfg.endpoint,
                 bucket,
@@ -173,10 +252,15 @@ export function createSendUserFileIssuer(cfg, deps) {
             }
             catch (e) {
                 const r1 = await reclaim(stagingBucket, stagingKey);
-                const r2 = await reclaim(bucket, key);
+                const r2 = await reclaim(bucket, key); // the copy may have half-landed — reclaim both sides
                 throw new Error(`SendUserFile upload verification failed: staging promotion failed (${e instanceof Error ? e.message : String(e)}) — ${outcome(r1 && r2, "uploaded object")}`);
             }
+            // ③ Staging object served its purpose — reclaim (best-effort: a leftover is a private-bucket blob
+            // whose write capability expires in ≤120s; it can't become a public link).
             await reclaim(stagingBucket, stagingKey);
+            // ④ Authoritative HEAD of the FINAL object — immutable to the sandbox, so THIS size is what the copy
+            // pinned and what the card must carry (re-checked against the cap: a /proc reader could have re-PUT
+            // staging between ① and ②, swapping in different bytes).
             let fin;
             try {
                 fin = await fetch(sign("HEAD", bucket, key), { method: "HEAD" });
@@ -220,6 +304,10 @@ export function createSendUserFileIssuer(cfg, deps) {
         };
         return { putUrl, verifySize, finalize };
     };
+    // Ledger reclaim (fail-loud record path): delete an already-uploaded object whose ledger record failed —
+    // a public-track object with no ledger row would be unmanageable (no per-tenant list/revoke handle). Signed
+    // DELETE against the INTERNAL endpoint (adapter creds, same posture as verifySize). S3 DELETE is idempotent
+    // (204 on a missing key), so callers may retry safely.
     const deleteObject = async (bucket, key) => {
         if (deps?.remove)
             return deps.remove(bucket, key);

package/dist/plugins/session-policy-store-sql.d.ts

@@ -2,20 +2,35 @@ import { type SessionPolicyStore, type SessionPermissionRules, type StoredSessio
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+/** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     private isDupKey;
+    /** Read the stored rules for (session, principal-owner); null when none (parity with InMemory). */
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
+    /** 2c session-sync: every (principal, rules) record for a session across ALL principals — getRules is
+     *  per-(session,principal), but a cross-backend session EXPORT must bundle the WHOLE session's policy (the importer
+     *  replays each via putRules). principal is read from the DENORMALIZED column (the sha256 policy_key is one-way);
+     *  NULL → undefined = the session-wide row (parity with core's InMemory `principal ?? undefined`). Rules carry rev. */
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
+    /** Operator/owner write: CAS + tighten-only (unless operator) + rev bump, atomic in one txn; first-write race retried. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
+    /** E21 purge — drop ALL policy rows for a session (every principal). Scoped by session_id (the route owner-gates).
+     *  Return shape aligned to core 1.423's optional interface seam (`Promise<void>`) — the affectedRows count was
+     *  incidental and unconsumed; the integration test asserts the post-state (listBySession empty) instead. */
     deleteBySession(sessionId: string): Promise<void>;
+    /** `begin()` (NOT `beginPessimistic()`) — matches both twins' original call shape: TiDB's native
+     *  `beginTransaction()` (optimistic), PG's plain `BEGIN`. Normalized by SqlDriver's shared tx plumbing. */
     private tx;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgSessionPolicyStore extends SqlSessionPolicyStore {
     constructor(pool: PgPool);
 }

package/dist/plugins/session-policy-store-sql.js

@@ -1,14 +1,57 @@
+/**
+ * Durable `SessionPolicyStore` (E6) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场). ONE
+ * implementation, TWO dialects; the historical `TiDBSessionPolicyStore` / `PgSessionPolicyStore` class
+ * names survive as thin ctor subclasses so every consumer (store-backend.ts, the session-sync
+ * fanout/push/pull suites, the E6 equivalence suite) is untouched.
+ *
+ * Operator-tightened per-session tool-permission rules (CAS-versioned, tighten-only) — the cross-replica
+ * twin of core's InMemorySessionPolicyStore (`@sema-agent/core` session-policy-store.js), backing core's
+ * `RunnerDeps.sessionPolicyStore`. core READS via getRules at prepare-time and folds the rules into the
+ * ToolPolicy FIRST (subtract-only); the service's operator endpoint WRITES via putRules.
+ *
+ * BYTE-MATCH discipline (the env-gated equivalence test vs InMemorySessionPolicyStore is the contract):
+ *  - Key = `sha256(JSON.stringify([sessionId, principal ?? null]))` — the SHA of core's exact composite key. The hash
+ *    (a) gives a FIXED 64-char PK regardless of how long / JSON-escapable the principal is (a VARCHAR(190) principal of
+ *    control chars JSON-escapes past any fixed width — review finding), and (b) sidesteps PK collation pitfalls
+ *    (trailing-space PAD). `principal` undefined/null collapse to one row, "" stays distinct (core's `?? null`).
+ *  - putRules order is LOAD-BEARING: (1) CAS expectedRev (stale → `conflict`), (2) normalize+stripRev the incoming
+ *    rules, (3) tighten gate via the REUSED core `loosenReasons` (non-operator loosen → `loosen_forbidden`), (4) rev
+ *    bump (+1; first = 1). A missing row reads as rev 0 (so expectedRev:0 = create-once). The conflict + loosen_forbidden
+ *    MESSAGES match core verbatim. read-check-write runs in ONE txn (SELECT…FOR UPDATE the prior so the loosen diff +
+ *    CAS are atomic; the InMemory gets this free from single-threaded JS). The UPDATE additionally guards `AND rev=?`
+ *    (defense beyond the row lock); a concurrent FIRST-write (no row → FOR UPDATE takes no lock) loses the PK race and
+ *    is RETRIED (re-read takes the UPDATE path) so a no-expectedRev create matches core's serialized rev-2 outcome
+ *    rather than a spurious conflict.
+ *  - allowDirs is stored NORMALIZED (`..`-free) so a later read-back `prior` feeds loosenReasons in the same canonical
+ *    shape as `clean` (the /work/../etc tighten-bypass blocker). The return is structuredClone'd (core's isolation).
+ * `operator` is honored verbatim — core never adjudicates it; the HTTP route FREEZES it from a verified principal
+ * (mirrors steer.trusted). `deleteBySession` is a service extension (E21 purge), not core's interface.
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - dup-key errno `1062`/`ER_DUP_ENTRY` vs SQLSTATE `23505`
+ *   - PG-only genuinely-divergent ALGORITHM: `pgHasUnstorable` rejects rules containing NUL / lone-surrogate
+ *     bytes (fail-loud, never rewritten) before the write; TiDB has no equivalent guard. Kept as an explicit
+ *     `if (this.db.dialect === "pg")` branch in putRules — see the inline 🔴 comment there for the codex
+ *     R2-H1→R3 rationale (rules are the authorization semantic body: reject-only, never silently rewritten).
+ *   - transaction plumbing: TiDB's native `beginTransaction/commit/rollback` vs PG's statement-issued
+ *     `BEGIN/COMMIT/ROLLBACK` — normalized by `SqlDriver`'s shared `connect()`/`begin()`/`commit()`/`rollback()`
+ *     (see sql-driver.ts); this store's original `beginTransaction()` call shape maps onto the driver's plain
+ *     `begin()` (NOT `beginPessimistic()` — the original TiDB store never opted into `BEGIN PESSIMISTIC`).
+ */
 import { createHash } from "node:crypto";
 import { loosenReasons, SessionPolicyError, normalizeRules, stripRev } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 const policyKey = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
-const parseRules = (v) => (typeof v === "string" ? JSON.parse(v) : v);
+const parseRules = (v) => (typeof v === "string" ? JSON.parse(v) : v); // R7 终形:拒绝式下库内恒干净,直读
+/** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export class SqlSessionPolicyStore {
     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;
     }
@@ -17,12 +60,17 @@ export class SqlSessionPolicyStore {
             ? e?.code === "ER_DUP_ENTRY" || e?.errno === 1062
             : e?.code === "23505";
     }
+    /** Read the stored rules for (session, principal-owner); null when none (parity with InMemory). */
     async getRules(sessionId, principal) {
         const { rows } = await this.db.query(this.q("SELECT rules, rev FROM session_policy WHERE policy_key = ?", "SELECT rules, rev FROM session_policy WHERE policy_key = $1"), [policyKey(sessionId, principal)]);
         if (!rows[0])
             return null;
         return { ...parseRules(rows[0].rules), rev: Number(rows[0].rev) };
     }
+    /** 2c session-sync: every (principal, rules) record for a session across ALL principals — getRules is
+     *  per-(session,principal), but a cross-backend session EXPORT must bundle the WHOLE session's policy (the importer
+     *  replays each via putRules). principal is read from the DENORMALIZED column (the sha256 policy_key is one-way);
+     *  NULL → undefined = the session-wide row (parity with core's InMemory `principal ?? undefined`). Rules carry rev. */
     async listBySession(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT principal, rules, rev FROM session_policy WHERE session_id = ?", "SELECT principal, rules, rev FROM session_policy WHERE session_id = $1"), [sessionId]);
         return rows.map((r) => ({
@@ -30,6 +78,7 @@ export class SqlSessionPolicyStore {
             rules: { ...parseRules(r.rules), rev: Number(r.rev) },
         }));
     }
+    /** Operator/owner write: CAS + tighten-only (unless operator) + rev bump, atomic in one txn; first-write race retried. */
     async putRules(sessionId, principal, rules, opts) {
         const key = policyKey(sessionId, principal);
         for (let attempt = 0;; attempt++) {
@@ -38,16 +87,24 @@ export class SqlSessionPolicyStore {
                     const { rows } = await conn.query(this.q("SELECT rules, rev FROM session_policy WHERE policy_key = ? FOR UPDATE", "SELECT rules, rev FROM session_policy WHERE policy_key = $1 FOR UPDATE"), [key]);
                     const prior = rows[0] ? { rules: parseRules(rows[0].rules), rev: Number(rows[0].rev) } : undefined;
                     const priorRev = prior?.rev ?? 0;
+                    // (1) CAS — checked BEFORE the tighten gate; a missing row is rev 0 (expectedRev:0 = create-once).
                     if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
                         throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${priorRev})`);
                     }
+                    // (2) normalize+stripRev the INCOMING rules (allowDirs `..`-free before store AND before the loosen diff).
                     const clean = normalizeRules(stripRev(rules));
+                    // (3) tighten gate — ONLY when a prior exists AND not an operator write (strict !== true). REUSE core loosenReasons.
                     if (prior && opts?.operator !== true) {
                         const loosens = loosenReasons(prior.rules, clean);
                         if (loosens.length > 0) {
                             throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
                         }
                     }
+                    // 🔴 PG-only genuinely-divergent ALGORITHM (not a syntax difference): codex R2-H1→R3(NUL 批终形):
+                    // rules=授权语义本体,**拒绝式**——含不可存字节的规则是垃圾输入(NUL 路径本不可用),fail-loud
+                    // 拒收;绝不改写(有损=写读不一致)、绝不信封(R3:滚动部署/回滚窗口老 replica 读信封=字段全缺=
+                    // fail-open 放行,授权面不赌版本偏斜)。TiDB's VARBINARY/utf8mb4 storage never chokes on these bytes
+                    // the way PG's protocol-byte encoding does, so it carries no equivalent guard.
                     if (this.db.dialect === "pg" && pgHasUnstorable(clean)) {
                         throw new SessionPolicyError("loosen_forbidden", "rules contain unstorable bytes (NUL / lone surrogate) — refused; strip them at the source (authorization rules are never rewritten by the store)");
                     }
@@ -55,26 +112,38 @@ export class SqlSessionPolicyStore {
                     const json = JSON.stringify(clean);
                     const now = new Date();
                     if (prior) {
+                        // `principal` is enumeration-only (not a key, not CAS): write it on UPDATE too so a pre-migration
+                        // row (principal NULL) SELF-HEALS to its real principal on the next write — never changes the rev/CAS path.
                         const upd = await conn.query(this.q("UPDATE session_policy SET principal = ?, rules = ?, rev = ?, updated_at = ? WHERE policy_key = ? AND rev = ?", "UPDATE session_policy SET principal = $1, rules = $2::jsonb, rev = $3, updated_at = $4 WHERE policy_key = $5 AND rev = $6"), [principal ?? null, json, nextRev, now, key, priorRev]);
+                        // Defense beyond the FOR UPDATE row lock: if rev moved under us, the CAS lost (treat as conflict).
                         if (upd.affected !== 1)
                             throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts?.expectedRev ?? priorRev}, have ${priorRev})`);
                     }
                     else {
+                        // No prior → FOR UPDATE took no row lock; a concurrent first-writer can win the PK. Let the dup-key
+                        // PROPAGATE (do NOT convert to conflict here) so the outer loop RETRIES — the re-read then finds the row
+                        // and takes the UPDATE path (matching core's serialized rev-2 outcome / or an honest CAS conflict if
+                        // expectedRev was supplied), instead of a spurious conflict. `principal ?? null` = the enumeration column.
                         await conn.query(this.q("INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, created_at, updated_at) VALUES (?,?,?,?,?,?,?)", "INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, created_at, updated_at) VALUES ($1,$2,$3,$4::jsonb,$5,$6,$7)"), [key, sessionId, principal ?? null, json, nextRev, now, now]);
                     }
-                    return structuredClone({ ...clean, rev: nextRev });
+                    return structuredClone({ ...clean, rev: nextRev }); // core hands back a fully isolated tree
                 });
             }
             catch (e) {
                 if (this.isDupKey(e) && attempt < 4)
-                    continue;
+                    continue; // concurrent first-write — re-read takes the UPDATE/CAS path
                 throw e;
             }
         }
     }
+    /** E21 purge — drop ALL policy rows for a session (every principal). Scoped by session_id (the route owner-gates).
+     *  Return shape aligned to core 1.423's optional interface seam (`Promise<void>`) — the affectedRows count was
+     *  incidental and unconsumed; the integration test asserts the post-state (listBySession empty) instead. */
     async deleteBySession(sessionId) {
         await this.db.query(this.q("DELETE FROM session_policy WHERE session_id = ?", "DELETE FROM session_policy WHERE session_id = $1"), [sessionId]);
     }
+    /** `begin()` (NOT `beginPessimistic()`) — matches both twins' original call shape: TiDB's native
+     *  `beginTransaction()` (optimistic), PG's plain `BEGIN`. Normalized by SqlDriver's shared tx plumbing. */
     async tx(fn) {
         const conn = await this.db.connect();
         try {
@@ -88,6 +157,7 @@ export class SqlSessionPolicyStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -96,11 +166,13 @@ export class SqlSessionPolicyStore {
         }
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgSessionPolicyStore extends SqlSessionPolicyStore {
     constructor(pool) {
         super(pgDriver(pool));

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

@@ -1,10 +1,55 @@
 import { type SessionStore } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { StoreBackend } from "./store-backend.js";
+/**
+ * Session-store plugin seam.
+ *
+ * - `memory` (default): core's in-memory `TtlSessionStore` (lost on restart, 7-day idle TTL).
+ * - `tidb`: the durable "Session event-log center" (L1) — append-only events + wake/resume +
+ *   cross-instance CAS (F2), on whichever SQL engine `DB_BACKEND` selects (TiDB or PG, via the store backend).
+ *   Optionally wrapped in a warm cache (reuse a hot session across turns; requires session affinity) —
+ *   set `SESSION_CACHE_TTL_SEC=0` to disable.
+ */
 export declare function createSessionStore(config: ServiceConfig, backend?: StoreBackend, metrics?: {
     inc(name: string, labels?: Record<string, string>, n?: number): void;
 }): SessionStore;
+/**
+ * core 1.382(design/153,[1561] 提货单①②)`SubagentToolOptions.background.ensureChildSessionDurable`
+ * 的实现体——从 main.ts 装配点抽出为可独立测试的纯函数(main.ts 里的其余装配闭包历来无单测覆盖,
+ * 这条因为承载真实的 park/veto 裁决,拆出来直接钉)。
+ *
+ * 只在 `sessionId` 已经真正路由到 HOST(durable)会话店、且**真有内容**时 resolve;其余(未路由到 host/
+ * 两店皆无/host 店只有一行空壳)一律 reject——veto,core 侧子代按 pre-153 settle failed,零回归,不是
+ * 危险失败模式(见函数体内注释)。
+ *
+ * 传入必须是 HOST 店本身(main.ts 里 `createSessionStore(...)` 的返回值),不能是 subRunner 用的
+ * `ForkRoutingSessionStore` 包装店——那层包装对 `acquire(id,{requireExisting:true})` 是 transient-优先
+ * (F-7 案:让"真会话在 transient"赢过"host 店里的同 id 空壳"),会把"只在 transient 店有真内容"误判成
+ * "host 店已经有了"。这里要问的是纯粹"host 店本身是否已经有这份真内容",必须绕开那层路由。
+ *
+ * 🔴 [1575] F3(cli 复查抓获,真红确认)调用方前提——**本函数假设 `hostStore.release()` 是"归还租约"
+ * 语义(不销毁内容)**,这对 core `TiDBSessionStore` 成立(`release()` 逐字注释「Durable history is
+ * retained; just drop any in-flight cache entry」),但对无 repo 构造的 `TtlSessionStore`(`createSessionStore`
+ * 在 `SESSION_BACKEND !== "tidb"` 时返回的那种)**不成立**——那个店形的 `release()` 是整删会话
+ * (`evictPolicy="delete"`)。本函数自己**不做**、也无法通用地做"这个 store 实例的 release 是否安全"的
+ * 判别(`SessionStore` 接口没有暴露这个信息,类型层面区分不了两种店形)——上文"误判方向永远偏保守"
+ * 只覆盖 `getLeafId` 那道校验,不覆盖"传了一个 release=delete 的店进来"这个前提违反。**调用方必须
+ * 保证只在真正 durable(release 非破坏性)的店上调用本函数**——server 侧的强制点在 main.ts 装配区:
+ * `ensureChildSessionDurable` 闭包只在 `config.sessionBackend === "tidb"` 时构造。
+ */
 export declare function ensureSessionDurable(hostStore: SessionStore, sessionId: string): Promise<void>;
+/**
+ * [1593] 主动晋升版 ensureChildSessionDurable(cli TiDB 真机撞获:1.263 的只查不迁形在拆店生产形下
+ * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
+ * (14ms~2s)+ settle failed,赎回窗口不存在):
+ *   1. 快路:已在 host 店且有真内容 → 直接通过(幂等/重入)。
+ *   2. 晋升:routing.promoteToHost 把子会话整树从私店拷进 host 店(拷贝→私店 forget→路由记 host,
+ *      三步见 ForkRoutingSessionStore.promoteToHost)。
+ *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)——晋升产物必须达到与既有校验完全相同的
+ *      durable 标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ * 调用方纪律与 {@link ensureSessionDurable} 同款:hostStore 必须是 release 非破坏性的真 durable 店
+ * (main.ts 的 `config.sessionBackend === "tidb"` 门不变)。
+ */
 export declare function ensureChildSessionDurableWithPromotion(hostStore: SessionStore, routing: {
     promoteToHost(sessionId: string): Promise<void>;
 }, sessionId: string): Promise<void>;

package/dist/plugins/session-store.js

@@ -1,5 +1,14 @@
 import { TtlSessionStore } from "@sema-agent/core";
 import { CachingSessionStore } from "./caching-session-store.js";
+/**
+ * Session-store plugin seam.
+ *
+ * - `memory` (default): core's in-memory `TtlSessionStore` (lost on restart, 7-day idle TTL).
+ * - `tidb`: the durable "Session event-log center" (L1) — append-only events + wake/resume +
+ *   cross-instance CAS (F2), on whichever SQL engine `DB_BACKEND` selects (TiDB or PG, via the store backend).
+ *   Optionally wrapped in a warm cache (reuse a hot session across turns; requires session affinity) —
+ *   set `SESSION_CACHE_TTL_SEC=0` to disable.
+ */
 export function createSessionStore(config, backend, metrics) {
     if (config.sessionBackend === "tidb") {
         if (!backend)
@@ -11,9 +20,38 @@ export function createSessionStore(config, backend, metrics) {
     }
     return new TtlSessionStore({ defaultTtlDays: 7 });
 }
+/**
+ * core 1.382(design/153,[1561] 提货单①②)`SubagentToolOptions.background.ensureChildSessionDurable`
+ * 的实现体——从 main.ts 装配点抽出为可独立测试的纯函数(main.ts 里的其余装配闭包历来无单测覆盖,
+ * 这条因为承载真实的 park/veto 裁决,拆出来直接钉)。
+ *
+ * 只在 `sessionId` 已经真正路由到 HOST(durable)会话店、且**真有内容**时 resolve;其余(未路由到 host/
+ * 两店皆无/host 店只有一行空壳)一律 reject——veto,core 侧子代按 pre-153 settle failed,零回归,不是
+ * 危险失败模式(见函数体内注释)。
+ *
+ * 传入必须是 HOST 店本身(main.ts 里 `createSessionStore(...)` 的返回值),不能是 subRunner 用的
+ * `ForkRoutingSessionStore` 包装店——那层包装对 `acquire(id,{requireExisting:true})` 是 transient-优先
+ * (F-7 案:让"真会话在 transient"赢过"host 店里的同 id 空壳"),会把"只在 transient 店有真内容"误判成
+ * "host 店已经有了"。这里要问的是纯粹"host 店本身是否已经有这份真内容",必须绕开那层路由。
+ *
+ * 🔴 [1575] F3(cli 复查抓获,真红确认)调用方前提——**本函数假设 `hostStore.release()` 是"归还租约"
+ * 语义(不销毁内容)**,这对 core `TiDBSessionStore` 成立(`release()` 逐字注释「Durable history is
+ * retained; just drop any in-flight cache entry」),但对无 repo 构造的 `TtlSessionStore`(`createSessionStore`
+ * 在 `SESSION_BACKEND !== "tidb"` 时返回的那种)**不成立**——那个店形的 `release()` 是整删会话
+ * (`evictPolicy="delete"`)。本函数自己**不做**、也无法通用地做"这个 store 实例的 release 是否安全"的
+ * 判别(`SessionStore` 接口没有暴露这个信息,类型层面区分不了两种店形)——上文"误判方向永远偏保守"
+ * 只覆盖 `getLeafId` 那道校验,不覆盖"传了一个 release=delete 的店进来"这个前提违反。**调用方必须
+ * 保证只在真正 durable(release 非破坏性)的店上调用本函数**——server 侧的强制点在 main.ts 装配区:
+ * `ensureChildSessionDurable` 闭包只在 `config.sessionBackend === "tidb"` 时构造。
+ */
 export async function ensureSessionDurable(hostStore, sessionId) {
     const acquired = await hostStore.acquire(sessionId, { requireExisting: true });
     try {
+        // security.ts 的 authorizer 对任意调用方自报的 body.sessionId(无主时)会经 `register()` 在 host 店
+        // 插一行 session_meta(leaf_id NULL,零内容)——那是 claim-create 的副作用,不是真正落过内容的会话。
+        // 裸 acquire 命中不足以证明"这份 durable 记录里有真内容可供跨进程恢复";真实会话到 park 这一步
+        // (需要模型已经产出过至少一次带工具调用的回复)恒已有 ≥1 条树内条目。校验失败的唯一后果是多一次
+        // reject=veto=pre-153 行为,不会放大权限或掩盖错误——误判方向永远偏保守。
         const leafId = await acquired.session.getLeafId();
         if (leafId === null)
             throw new Error(`session "${sessionId}" exists in the durable store but is empty (no leaf entry) — likely a claim-create shell row, not real durable content`);
@@ -22,12 +60,25 @@ export async function ensureSessionDurable(hostStore, sessionId) {
         await hostStore.release(acquired.sessionId);
     }
 }
+/**
+ * [1593] 主动晋升版 ensureChildSessionDurable(cli TiDB 真机撞获:1.263 的只查不迁形在拆店生产形下
+ * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
+ * (14ms~2s)+ settle failed,赎回窗口不存在):
+ *   1. 快路:已在 host 店且有真内容 → 直接通过(幂等/重入)。
+ *   2. 晋升:routing.promoteToHost 把子会话整树从私店拷进 host 店(拷贝→私店 forget→路由记 host,
+ *      三步见 ForkRoutingSessionStore.promoteToHost)。
+ *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)——晋升产物必须达到与既有校验完全相同的
+ *      durable 标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ * 调用方纪律与 {@link ensureSessionDurable} 同款:hostStore 必须是 release 非破坏性的真 durable 店
+ * (main.ts 的 `config.sessionBackend === "tidb"` 门不变)。
+ */
 export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId) {
     try {
         await ensureSessionDurable(hostStore, sessionId);
         return;
     }
     catch {
+        // 不在 host 店(或空壳行)→ 走晋升;晋升自身的失败在下方如实上浮
     }
     await routing.promoteToHost(sessionId);
     await ensureSessionDurable(hostStore, sessionId);