@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/session-sync.js

@@ -6,18 +6,31 @@ import { exportSession, exportSessionManifest, importSession, classifySyncRelati
 import { isUuidV7, isUuidShape } from "../../security.js";
 import { sendJson, sendError, msg } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+/** 2c session-sync PUT /sync/blobs/:hash per-blob upload cap. A snapshot blob is ONE file's bytes, bounded by core's
+ *  DEFAULT_SNAPSHOT_BOUNDS (the whole tree ≤ 64 MiB), so a single blob can never exceed the per-snapshot total — this
+ *  cap (= 64 MiB, ≥ that bound) is the reject-not-OOM ceiling: the blob body is read with a running size guard that
+ *  413s the instant it is exceeded (NEVER buffered unboundedly), the §5 "reject, not OOM" requirement. Larger than
+ *  MAX_BODY (8 MiB, the JSON cap) on purpose — a blob is binary file content, not a JSON request. */
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
+/** 2c session-sync P1d-β: the per-LINE cap on the Phase-B NDJSON entry stream — ONE entry must fit in this (the §1.5
+ *  ruling: a session_event row is ≤~20KB because core offloads >20K tool results, so a few MiB is a generous ceiling).
+ *  A line exceeding it → 413 (reject, not OOM): a single oversized entry would otherwise force an unbounded line buffer. */
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
+/** 2c session-sync P1d-β: the Phase-B entry batch size — entries are fed to `appendBatch` in chunks of this many, so
+ *  in-flight memory is O(batch), not O(session). 500 mirrors the PULL stream's keyset page size (one bounded txn). */
 const SYNC_IMPORT_BATCH = 500;
+/** 64 lowercase-hex chars = a sha256 content-address (the blob hash + the GET :hash param shape). */
 const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
+    /** 租约续期 —— entries 上传腿每收一批就调,所以大会话的长上传不会被误判成陈旧。 */
     const touchImportLease = (sessionId) => {
         const cur = importLeases.get(sessionId);
         if (cur)
             importLeases.set(sessionId, { ...cur, at: Date.now() });
     };
+    /** Drop a finished/aborted staging from the in-process maps + release its per-session import lease. Idempotent. */
     const cleanupStaging = (stagingId) => {
         const p = pendingStagings.get(stagingId);
         if (p)
@@ -31,13 +44,25 @@ export async function handleSessionSync(req, res, url, ctx) {
     await handleSessionSyncBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */
 async function handleSessionSyncBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, readRawBody, safeDecode, sessionOwnerScopeForWrite } = ctx.helpers;
     const { pendingStagings, importLeases, touchImportLease, cleanupStaging } = ctx.local.sessionSync;
+    // ── 2c session-sync (P1d) — the cloud as a SYNC PEER (docs/DESIGN-session-sync.md §15 + §5–§10) ──────────────
+    // The real 2c topology is TWO PROCESSES (the local shell's local backend + this cloud service); these routes let
+    // the local peer PULL a session's whole state out of the cloud or PUSH its own in. exportSession/importSession
+    // (src/session-sync.ts) fan out across ALL four session subsystems (entries + fileSnapshot + sessionPolicy +
+    // resumeAnchor) — they need the WHOLE backend (deps.backend), not the individual stores. Every route is
+    // owner-gated like fork/delete (§9): a PULL 404s a non-owner (no exfiltration oracle); a PUSH re-stamps the
+    // imported owner to the AUTHENTICATED principal (the bundle's owner is ignored). 501 when no durable session
+    // store is wired (parity with fork: capability says yes ⟺ the route resolves).
     {
         const sm = /^\/v1\/sessions\/([^/]+)\/sync\/(manifest|entries|import|plan|blobs(?:\/([^/]+))?|snapshots\/([^/]+)\/blobs\/([^/]+)|import\/([^/]+)\/entries)$/.exec(url);
         if (sm) {
+            // Durable-store gate (501) FIRST is wrong for an auth oracle, so AUTH-FIRST below mirrors fork/delete; but the
+            // backend is needed even to know the owner, so we gate on it up front and rely on AUTH being checked before
+            // any store touch. ownerOf is the existence/authz primitive every branch uses.
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             if (!deps.backend || !ownerOf) {
                 sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
@@ -47,32 +72,44 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
-            }
+            } // auth-first
             const sessionId = safeDecode(sm[1]);
+            // uuid ANY version — a v4-keyed legacy shell session must be pushable (it was
+            // creatable via the lenient submit face); crafted-id classes (LIKE metachars, over-long) still shut out.
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
+            // Two owner gates, BOTH 404 a foreign session with no existence oracle:
+            //  • PULL (read the cloud's session): the session MUST exist (undefined⇒404) AND the caller must own it.
+            //  • PUSH/PLAN (write into / plan against the cloud): own-or-FRESH — `undefined` (no such session yet, the
+            //    caller is about to import it) OR the caller's own ⇒ allowed; a DIFFERENT owner ⇒ 404.
             const owner = await ownerOf(sessionId);
             const ownsOrFleet = (o) => scope.fleetWide || o === scope.gateOwner;
             const pullGateOk = () => {
                 if (owner === undefined) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                }
+                } // must exist to pull
                 if (!ownsOrFleet(owner)) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                }
+                } // no oracle
                 return true;
             };
             const pushGateOk = () => {
                 if (owner !== undefined && !ownsOrFleet(owner)) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return false;
-                }
-                return true;
+                } // foreign → no oracle
+                return true; // undefined (fresh, caller will import) OR own/fleet
             };
+            // GET …/sync/manifest — PULL: export the MANIFEST (entry IDS + per-snapshot relPath→blobHash + policy +
+            // anchors + leafId), NO entry payloads and NO blob bytes (P1d-α §1.5/§5/§15: bounded memory — the entries
+            // stream separately via …/sync/entries). The local peer diffs entryIds → classifySyncRelationshipByIds, then
+            // pulls the entries (NDJSON) + only the blobHashes it lacks. exportSessionManifest returns null ONLY for "no
+            // such session" (the owner gate above already proved existence+ownership, so a null here is a raced delete →
+            // 404).
             if (sm[2] === "manifest" && req.method === "GET") {
                 if (!pullGateOk())
                     return;
@@ -80,13 +117,22 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 if (out === null) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return;
-                }
+                } // raced delete after the gate
                 sendJson(res, 200, { manifest: out.manifest });
                 return;
             }
+            // GET …/sync/entries[?afterSeq=N] — PULL the entry PAYLOADS as an NDJSON stream (P1d-α §1.5/§5/§15). The store
+            // seam keyset-PAGES the durable log (one pooled query per batch → bounded server memory; a slow client can't
+            // pin a connection), and we apply HTTP backpressure (await drain on a full socket buffer) so a slow consumer
+            // can't OOM the server either. The frame: a {"__sync":"begin",…} header line, then one JSON entry per line,
+            // then a {"__sync":"end","count":N} TRAILER line — a MISSING trailer signals a truncated stream to the client.
             if (sm[2] === "entries" && req.method === "GET") {
                 if (!pullGateOk())
                     return;
+                // afterSeq (optional resume cursor): a non-negative integer; reject anything else as a 400 (never a NaN
+                // cursor). It is the BACKEND-NATIVE durable `seq` cursor (yield entries whose seq > afterSeq) — a resume is
+                // always against the SAME backend, so the seq base (durable `seq` column vs. local 0-based index) needn't be
+                // portable across backends.
                 const afterSeqRaw = new URL(req.url ?? "", "http://x").searchParams.get("afterSeq");
                 let afterSeq;
                 if (afterSeqRaw !== null) {
@@ -101,13 +147,16 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 if (!stream) {
                     sendError(res, 501, "capability.session_store_required", "session entry streaming requires a durable session store");
                     return;
-                }
+                } // method absent
                 const it = await stream(sessionId, afterSeq === undefined ? undefined : { afterSeq });
                 if (it === null) {
                     sendError(res, 404, "not_found.session", "session not found");
                     return;
-                }
+                } // raced delete after the gate
+                // Headers committed — past this point we cannot change the status; a mid-stream error just ends the body
+                // WITHOUT the trailer, which the client reads as truncation.
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
+                // backpressure-aware write: if the socket buffer is full (write returns false), await 'drain' before the next.
                 const write = async (line) => { if (!res.write(line))
                     await once(res, "drain"); };
                 let count = 0;
@@ -117,15 +166,21 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         await write(`${JSON.stringify(entry)}\n`);
                         count++;
                     }
-                    await write(`${JSON.stringify({ __sync: "end", count })}\n`);
+                    await write(`${JSON.stringify({ __sync: "end", count })}\n`); // trailer — its ABSENCE = truncated stream
                     res.end();
                 }
                 catch (e) {
+                    // The iterable (or a write) threw mid-stream. Headers are already sent, so we can't 4xx/5xx — just END the
+                    // body. The MISSING trailer tells the client the stream was truncated. Log it for the operator.
                     deps.logger?.error?.("sync entries stream failed", { sessionId, count, error: msg(e) });
                     res.end();
                 }
                 return;
             }
+            // GET …/sync/snapshots/:key/blobs/:hash — PULL one content-addressed blob's RAW bytes. The SCOPE CHECK is the
+            // security boundary: a content-addressed blob is shared across sessions, so we must NOT let an owner fetch an
+            // arbitrary hash (another tenant's file content). We require the requested :hash to be a value in THIS
+            // session's snapshot `:key` manifest — a session owner may only fetch blobs ITS OWN snapshots reference.
             if (sm[4] !== undefined && req.method === "GET") {
                 if (!pullGateOk())
                     return;
@@ -141,6 +196,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 const fs = deps.fileSnapshotStore;
                 const manifest = await fs?.exportManifest?.(sessionId, key);
+                // null manifest (no such snapshot) OR the hash is not referenced by it ⇒ 404 (the scope boundary — never a
+                // blind content-addressed read of an unscoped hash).
                 if (!manifest || ![...manifest.values()].includes(hash)) {
                     sendError(res, 404, "not_found.blob", "blob not found");
                     return;
@@ -154,6 +211,10 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 res.end(Buffer.from(bytes));
                 return;
             }
+            // PUT …/sync/blobs/:hash — PUSH one content-addressed blob INTO the cloud's snapshot store, ahead of the bundle
+            // import (§5 streamed negotiation: the local peer GETs the manifest, then PUTs only the blobs the cloud lacks).
+            // own-or-FRESH gate. Verify sha256(body)===:hash (the content-address is the integrity guarantee; a transfer
+            // crosses the net) BEFORE storing. The body is read with a PER-BLOB cap (reject-not-OOM).
             if (sm[3] !== undefined && req.method === "PUT") {
                 if (!pushGateOk())
                     return;
@@ -167,8 +228,12 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 501, "capability.snapshot_store_required", "blob upload requires a durable snapshot store");
                     return;
                 }
-                const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES);
+                const body = await readRawBody(req, SYNC_BLOB_MAX_BYTES); // 413s mid-stream if it exceeds the cap (no unbounded buffer)
+                // (a): SQL-default blob store cap — 413 typed, NOT the 502 the store's never-throw result would become
+                // (502 = "retry"; an over-cap blob can never land, so retrying it forever is the wrong contract).
                 if (deps.snapshotBlobSqlCapBytes !== undefined && body.byteLength > deps.snapshotBlobSqlCapBytes) {
+                    // 复审 D-F1/B-F2:归一漏网(多行体,旧门正则扫不到)——A6 迁移到 sendError 后此站点由
+                    // errorCode 必填位置参数保结构(不再靠源级反射门兜底)。
                     sendError(res, 413, "blob_too_large_for_sql", `blob of ${body.byteLength} bytes exceeds this deployment's SQL snapshot-blob cap (${deps.snapshotBlobSqlCapBytes} bytes — TiDB's txn-entry-size-limit is the low wall at 6MiB by default; the mysql-protocol packet limit sits above it) — configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment lifted those limits`, { code: "blob_too_large_for_sql" });
                     return;
                 }
@@ -176,17 +241,29 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.hash_mismatch", "blob hash mismatch");
                     return;
                 }
+                // core 1.142.0: putBlob is a fail-closed never-throw seam — a backend write error (e.g. a MinIO non-2xx PUT)
+                // is {ok:false}, NOT a thrown 500. Surface it as 502 so the local peer retries rather than treating the bundle
+                // blob as durably stored when it isn't.
                 const put = await fs.putBlob(hash, new Uint8Array(body));
                 if (!put.ok) {
                     sendError(res, 502, put.error.code, "blob store write failed", { code: put.error.code });
                     return;
                 }
-                res.writeHead(204).end();
+                res.writeHead(204).end(); // no body
                 return;
             }
+            // POST …/sync/import — PHASE A (PUSH, P1d-β §15.2): a SMALL JSON body — `{entryIds, snapshots, policy, anchors,
+            // resolution?}` — NO entries (they stream in Phase B). Classify (§7), pre-check blob presence (§10), guard the
+            // §4 import-vs-import lease + the active-run window, then mint a stagingId, open a StagingHandle, and park the
+            // Phase-A metadata. Returns `200 {stagingId, relation}`. The entries-inline whole-bundle import is GONE (the
+            // §1.5 OOM offender) — Phase B streams the log into the shadow id so server memory is bounded by batch.
             if (sm[2] === "import" && req.method === "POST") {
                 if (!pushGateOk())
                     return;
+                // sessionMirror 观测面(裁定 (c),论证在 ServiceDeps.sessionMirrorRuling 注释):Phase A
+                // 到达 = 一次镜像 push 落到本 server 的时点信号。该 principal 若处 org 治理态(required=true),记
+                // audit 日志 + metric,把「治理生效」与「到达流」在运营面对上——这是 server 侧唯一诚实可观测的面
+                // (没到达的会话 server 看不见,真执法在壳)。fire-and-forget + 双层吞错:观测绝不拖慢/拖垮 sync。
                 if (deps.sessionMirrorRuling && !scope.fleetWide && scope.gateOwner !== null) {
                     const auditPrincipal = scope.gateOwner;
                     void deps.sessionMirrorRuling(auditPrincipal).then((mirror) => {
@@ -208,6 +285,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.invalid_json", "invalid JSON body");
                     return;
                 }
+                // Shape validation (§10): entryIds must be a string[]; snapshots an array of {key:string, manifest:array};
+                // policy/anchors arrays. A malformed shape → 400 (never a 500 from a downstream TypeError).
                 if (!Array.isArray(body.entryIds) || !body.entryIds.every((x) => typeof x === "string")) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
@@ -222,19 +301,56 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const resolution = body.resolution;
+                // 🔴 方案 B(黑板 [1701]→[1702]→[1707] 三端对齐):**可选** `logDigest` = 源端整条日志的内容摘要
+                // (core 1.414 `sessionLogDigest`)。老客户端不送 ⇒ 行为与此前逐字相同。坏形**不拒**,当作没送
+                // (core 口径:摘要不符/不可比永远不得变成 error / 409 / 拒绝同步 —— 它只意味着"多干一趟活")。
                 const srcLogDigest = typeof body.logDigest === "string" && body.logDigest.length > 0 ? body.logDigest : undefined;
                 const entryIds = body.entryIds;
                 const snapshots = body.snapshots;
                 const policy = body.policy;
                 const anchors = body.anchors;
+                // §7 classify (BEFORE issuing a stagingId): dst current ids → classifySyncRelationshipByIds. A fork/stale
+                // without overwrite-dst → 409 (no stream needed). `identical` → 200 {relation:"identical"} (no Phase B; the
+                // snapshot/policy/anchor replay is idempotent and not strictly needed — the dst already holds this log; the
+                // shell may re-push with no consequence). NB the AUTHORITATIVE re-classify is in commit() (the TOCTOU close).
                 const dstIds = (await deps.sessionStorage.listEntryIds?.(sessionId)) ?? null;
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
                 if ((relA.relation === "fork" || relA.relation === "stale") && resolution !== "overwrite-dst") {
                     sendError(res, 409, "conflict", "sync conflict", { relation: relA });
                     return;
                 }
+                // 🔴 内容判据(方案 B 的 Phase A 半场):`identical` 只说明 **id 集合**相等。源端内容在 Phase A 还没上传,
+                // 所以这里只能靠调用方送来的 `logDigest`;拿目的端自己的日志算一次摘要跟它比。
+                // ⚠️ 目的端全量读**只在这条路上做**(要短路、且调用方送了摘要)—— 成本只花在它能改变结论的地方。
+                // 三态:相等 ⇒ 可以短路;不等 ⇒ **不短路**(照常开 staging 走完整同步);判不可比(scheme 不同/
+                // 对端没送)⇒ 同样**不短路**,退回完整同步 = 安全方向。
                 let payloadVerified = false;
                 let digestSaysDiffer = false;
+                // ── 这条路依赖的那条**性质**,以及它为什么由依赖下限 + 一条行为测试守着(不是由版本名判断守着)──
+                // 本路要求:**同一份日志,内存形与 JSON 往返形必须同摘要**。因为它比的正是「客户端从**内存**算的
+                // `logDigest`」对「server 从**已持久化**(JSON 往返过)的日志算的摘要」。
+                // `sessionLogDigest` 的 **v1** 不满足它:v1 走引擎那个规范化序列化器,**刻意**区分 `{a: undefined}`
+                // 与 `{}`,而 core 自己成规模产 own-key=undefined 的 entry(清除标签、无 data 的 custom entry)
+                // ⇒ 两形必然不等 ⇒ **永不短路**,却看起来像在工作(症状只是「Phase B 总在跑」,查不出原因):
+                // 纯成本、零收益,还多一次目的端全量读。core 黑板 [1709] 明确「别接 v1」,1.415.0 改算法并升 scheme v1→v2。
+                //
+                // 🔴 我一开始写的是 `SESSION_LOG_DIGEST_SCHEME !== "sema-log-v1"` 这道**名字门**。升上 1.415 后
+                // `tsc` 直接判它恒真(core 把 scheme 收成了字面量类型)—— 而这提醒了一件更要紧的事:名字门本来就
+                // **守不住这条性质**。它只认识"v1 这个名字",对将来任何一个同样破坏往返稳定性的 v3 一样放行。
+                // ⇒ 改成两道**真守得住**的:
+                //   ① **依赖下限** `@sema-agent/core: ^1.416.0`。⚠️ package.json 是 JSON、写不了旁注,所以"这条下限是
+                //      承重的、不是随手升的"记在两处:**本注释** + `CHANGELOG.md` 1.277.0/1.277.1 两条。
+                //      降回更低的下限,tsc 不会有任何抱怨 —— 拦它的是 ② 那两道行为门。
+                //   ② **行为门**(都在 `test/sync-content-digest.test.ts`),两条**方向相反**、缺一不可:
+                //      · **往返稳定**:同一份含 own-key=undefined 的日志,内存形与 JSON 往返形必须同摘要。
+                //        它坏 ⇒ **永不短路**(纯成本,安全方向)。core 摘要 v1 不满足它(v1 刻意区分 `{a:undefined}`
+                //        与 `{}`,而 core 成规模产这种 entry),黑板 [1709] 明确「别接 v1」。
+                //      · 🔴 **防撞**:内容不同 ⇒ 摘要必须不同,**按深度枚举**(坏值与真实内容同级)。
+                //        它坏 ⇒ **错误短路** = 静默丢数据,方向与上面相反、后果严重得多。core 摘要 **v2** 不满足它
+                //        (逐键降级只做在 entry 顶层,而真实内容在深度 ≥2 ⇒ 一个 bigint 吃掉同级全部内容),
+                //        1.416.0 / v3 修复(黑板 [1714])。
+                //      两条钉的都是**性质**、不是版本名 —— 任何 scheme 再破坏其一都会红。
+                //      (教训同形于 core 的 RB-149:源码/名字级判据挡的是写法,不是行为。)
                 if (relA.relation === "identical" && srcLogDigest !== undefined) {
                     const dstEntries = await deps.sessionStorage.exportEntries?.(sessionId).catch(() => null) ?? null;
                     const dstDigest = dstEntries === null ? undefined : sessionLogDigest(dstEntries);
@@ -244,10 +360,16 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         else
                             digestSaysDiffer = true;
                     }
+                    // 不可比 ⇒ 两个标志都保持 false ⇒ 走下面「不短路」那一支(退回完整同步)
                     if (!payloadVerified)
                         digestSaysDiffer = true;
                 }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
+                    // 对抗复查 A-2(CRITICAL):identical 不能裸短路——若上一轮 commit 后 snapshot/policy/anchor 重放
+                    // 失败(422),entries 已落库,重试的 Phase A 就落在这里;裸 200 会把「对话已同步但文件树缺失」
+                    // 焊死成永久分裂(Phase B 的重放永远不再运行)。identical 时把附随物幂等重放(snapshot=
+                    // content-addressed importManifest,已存在=no-op;policy/anchor put=幂等),失败=同款 422,
+                    // 客户端 re-PUT blob 再重试——自愈闭环。
                     const fss = deps.fileSnapshotStore;
                     if (fss?.importManifest && fss.getBlob && snapshots.length > 0) {
                         const getBlobA = (h) => fss.getBlob(h);
@@ -267,13 +389,23 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     if (deps.resumeAnchorStore)
                         for (const a of anchors)
                             await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingP);
+                    // 🔴 措辞诚实化(2026-07-25,深挖第一轮 B2/B3/B4/G1):`identical` 的判据是 **entry id 集合相等**,
+                    // 分类器(`classifySyncRelationshipByIds`)**从不看载荷/父子结构** —— 而 entry id 是 uuidv7、
+                    // **不是内容寻址**,所以「同 id 异载荷」结构上完全可能。此时 entries 被**整段跳过**,客户端拿到 200,
+                    // 目的端却仍是它自己那份内容(探针用真 HTTP 复现过:本地改过内容再 push,云端保持原样、200)。
+                    // 现在把判据写进响应(`basis`)并显式声明**未验证载荷**,这样客户端不会把它读成"内容已同步"。
+                    // ⚠️ 这只是止谎,**不是修**:真修要 Phase A 能拿到内容摘要(Phase A 只收 entryIds,载荷在 Phase B),
+                    // 那是跨仓 wire 契约改动,已带证据上黑板与 cli/core 对齐。别把 `basis` 当成问题已解决。
                     sendJson(res, 200, {
                         relation: "identical",
+                        // 判据如实:调用方送了可比摘要且相等 ⇒ 内容**真的**验过;否则仍只是 id 集合相等。
                         basis: payloadVerified ? "entry-ids+digest" : "entry-ids",
                         payloadVerified,
                     });
                     return;
                 }
+                // §4 active-run guard (don't drop a live append) + per-session import lease (don't let two staged imports race
+                // to commit the same session). Both 409.
                 const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeTaskId) {
                     sendError(res, 409, "session_active", "session has an active run; sync after it settles", { activeTaskId });
@@ -281,22 +413,34 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 const heldLease = importLeases.get(sessionId);
                 if (heldLease) {
+                    // 🔴 数值守卫而不是直接乘:任何**早于这个字段**的 config 对象(旧部署配置、精简的测试 harness)
+                    // 会让它是 `undefined` ⇒ `undefined * 1000 = NaN` ⇒ `NaN > 0` 为假 ⇒ **接管静默不发生**,
+                    // 自愈通道在不报错的情况下消失。实测撞到过(一份最小 config 的探针 harness)。缺省取与 config
+                    // 同一个默认值(600s),而不是 0 —— 0 的语义是"明确关掉",不该由"漏配"来选中它。
                     const staleSecRaw = deps.config.syncImportLeaseStaleSec;
                     const staleSec = typeof staleSecRaw === "number" && Number.isFinite(staleSecRaw) ? staleSecRaw : 600;
                     const staleMs = staleSec * 1000;
                     const ageMs = Date.now() - heldLease.at;
                     if (staleMs > 0 && ageMs >= staleMs) {
+                        // 接管:上一个持有者已经 staleMs 没有任何活动(既没上传 entries 也没 commit)⇒ 判它死了。
+                        // 先清掉它的 staging(否则那份 staged 行会留成孤儿),再让本次 Phase A 正常继续。
                         deps.logger?.warn?.("sync_import_lease_taken_over", { sessionId, ageMs, staleMs, stagingId: heldLease.stagingId });
                         cleanupStaging(heldLease.stagingId);
-                        importLeases.delete(sessionId);
+                        importLeases.delete(sessionId); // cleanupStaging 只在 pendingStagings 里还有它时才删租约,这里兜底
                     }
                     else {
+                        // 错误文案点明**会自愈**:此前的措辞让客户端以为是永久状态,而它其实等一会儿就能重试。
                         const retryAfterSec = staleMs > 0 ? Math.max(1, Math.ceil((staleMs - ageMs) / 1000)) : undefined;
                         sendError(res, 409, "import_in_flight", "an import is already in flight for this session"
                             + (retryAfterSec !== undefined ? ` (a stalled holder is taken over after ${staleSec}s of inactivity; retry in ~${retryAfterSec}s)` : ""), retryAfterSec !== undefined ? { retryAfterSec } : undefined);
                         return;
                     }
                 }
+                // §10 blob-presence pre-check (BEFORE staging): every referenced blobHash must be present in the cloud's OWN
+                // snapshot store (blobs were pre-PUT). A missing one → 422 (PUT it, then retry) — fail FAST so we never open a
+                // staging that can only fail at commit. Uses the store's hasBlobs (a single SQL INDEX probe — finding 12) NOT
+                // a full getBlob GET-per-hash (under MinIO that would download + re-hash every ≤64 MiB object just to test
+                // presence). Feature-detect hasBlobs; if a store lacks it, fall back to getBlob (parity for older stores).
                 const fss = deps.fileSnapshotStore;
                 const canImportSnapshots = typeof fss?.importManifest === "function";
                 if (canImportSnapshots) {
@@ -322,8 +466,15 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         }
                     }
                 }
+                // importingPrincipal (§9) + operatorOk (E6 tighten-only) — mirror the v1 fixes; applied at commit (policy replay).
                 const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                 const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals);
+                // Mint the stagingId TOKEN (the route supplies it, NOT the store) + open the handle + take the lease + park
+                // the metadata. Phase B drives it; abandoned ones are reaped (durable rows) / dropped on restart. The token is
+                // a SHORT random hex (8 bytes = 16 chars), NOT a full uuidv7: the staging id is `${sessionId}#stg-${token}` and
+                // session_event.session_id is VARCHAR(64) — a 36-char uuidv7 session id + "#stg-" (5) leaves 23 chars, so a
+                // 16-char token fits (and is collision-resistant for the few in-flight stagings of ONE session — the lease
+                // already serializes them per session). randomBytes is unguessable (it rides the URL the client gets back).
                 const token = randomBytes(8).toString("hex");
                 const handle = deps.sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
@@ -335,6 +486,11 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
             }
+            // POST …/sync/import/:stagingId/entries — PHASE B (PUSH, P1d-β §15.3): stream the entry log as an NDJSON request
+            // body into the staged shadow id (bounded memory — line buffer + batch), driving core's STREAMING import gate
+            // ({@link StreamingImportValidator}) ONE entry per line, then `finish()` at stream end (exactly-one-root +
+            // leaf-resolvable) → commit (the atomic swap) → replay snapshots/policy/anchors. Re-POSTing the same stagingId is
+            // idempotent (appendBatch dedups; the commit re-runs). sm[6] = the stagingId.
             if (sm[6] !== undefined && req.method === "POST") {
                 const stagingId = safeDecode(sm[6]);
                 if (stagingId === null) {
@@ -342,6 +498,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const pending = pendingStagings.get(stagingId);
+                // A wrong/foreign/already-finished stagingId → 404 (no oracle). It must also belong to THIS url's session and
+                // to the caller (the principal that opened it), unless the caller is fleet-wide (ops on-behalf).
                 if (!pending || pending.realSessionId !== sessionId) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
@@ -350,15 +508,24 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                const getBlob = (h) => deps.fileSnapshotStore.getBlob(h);
+                const getBlob = (h) => deps.fileSnapshotStore.getBlob(h); // cloud's OWN store
                 const canImportSnapshots = typeof deps.fileSnapshotStore?.importManifest === "function";
+                // ── Stream the NDJSON request body → core's StreamingImportValidator per line → batched appendBatch (bounded
+                //    memory: line buffer + batch). The streaming validator IS the single invariant gate (unique ids /
+                //    parent-before-child / structural refs / one-root / leaf-resolvable) — core 1.143.0 — so the service
+                //    no longer re-states ANY of those rules (no ad-hoc Tier-1 pre-check, no Tier-2 read-back-and-re-validate;
+                //    the invariant gate belongs to core and the service does not duplicate it). `step()` throws SessionError("invalid_session") on a per-entry violation;
+                //    `finish()` throws on the end-of-stream invariants. The route keeps ONLY the TRANSPORT-level guards (the
+                //    per-line byte cap → 413, JSON parse → 400, and the object/string-id shape so a `null`/non-object line maps
+                //    to a typed 422 instead of an unmapped TypeError); these are NOT session-tree invariants. ──
                 const validator = new StreamingImportValidator();
-                let lineBuf = "";
+                let lineBuf = ""; // the partial-line accumulator (bytes counted against the per-line cap)
                 let pendingBatch = [];
                 const flush = async () => { if (pendingBatch.length) {
                     await pending.handle.appendBatch(pendingBatch);
                     pendingBatch = [];
                 } };
+                // Map a transport-level violation to a typed 4xx WITHOUT committing (the handle's staged rows are abandoned → reaped).
                 class PrecheckError extends Error {
                     status;
                     constructor(status, msg) {
@@ -366,16 +533,21 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         this.status = status;
                     }
                 }
-                const streamedIds = new Set();
+                const streamedIds = new Set(); // A-3: bind the actual stream to Phase A's declaration
                 const onEntry = (e) => {
                     if (!e || typeof e !== "object" || typeof e.id !== "string")
                         throw new PrecheckError(422, "malformed entry (missing id)");
                     streamedIds.add(e.id);
-                    validator.step(e);
+                    validator.step(e); // core's invariant gate, one entry at a time (oldest-first) — throws SessionError on a tree violation
                 };
+                // 对抗复查 A-7(HIGH):per-chunk Buffer.toString("utf8") mangles a MULTI-BYTE character that
+                // straddles a network chunk boundary (each half decodes to U+FFFD; the JSON often stays valid →
+                // the payload is SILENTLY rewritten — CJK content is the common casualty). StringDecoder holds the
+                // partial sequence across chunks — the standard Node fix.
                 const utf8 = new StringDecoder("utf8");
                 try {
                     for await (const chunk of req) {
+                        // 租约续期(见 importLeases 旁注):上传本身就是活性证据 —— 大会话的长上传不该被判成"持有者死了"。
                         touchImportLease(pending.realSessionId);
                         lineBuf += utf8.write(chunk);
                         if (Buffer.byteLength(lineBuf, "utf8") > SYNC_NDJSON_LINE_MAX_BYTES)
@@ -385,7 +557,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                             const line = lineBuf.slice(0, nl).trim();
                             lineBuf = lineBuf.slice(nl + 1);
                             if (line.length === 0)
-                                continue;
+                                continue; // tolerate blank lines / a trailing newline
                             let e;
                             try {
                                 e = JSON.parse(line);
@@ -399,7 +571,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                                 await flush();
                         }
                     }
-                    lineBuf += utf8.end();
+                    // any trailing partial line (no final newline) is still a complete entry to honor.
+                    lineBuf += utf8.end(); // flush a dangling partial sequence (A-7)
                     const tail = lineBuf.trim();
                     if (tail.length > 0) {
                         let e;
@@ -413,12 +586,21 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         pendingBatch.push(e);
                     }
                     await flush();
+                    // End-of-stream invariants (exactly-one-root + leaf-resolvable) — finish() throws SessionError on violation.
                     validator.finish();
+                    // 对抗复查 A-3(HIGH):the streamed tree must BE the Phase-A-declared one — same count, same id set.
+                    // Without this, a caller could open a staging with ids=A (snapshots/anchors parked against A) and
+                    // stream a different-but-valid tree B to commit; the classification and parked artifacts would
+                    // silently reference the wrong log. Set equality (order is core-validated separately).
                     if (streamedIds.size !== pending.declaredEntryIds.length || !pending.declaredEntryIds.every((id) => streamedIds.has(id))) {
                         throw new PrecheckError(422, "streamed entries do not match the Phase-A declared entryIds");
                     }
                 }
                 catch (e) {
+                    // A transport-level PrecheckError carries its own status; a core SessionError("invalid_session") (a step()
+                    // or finish() invariant violation) maps to 422. Either way: drop the staged rows + the lease/map entry up
+                    // front (a malformed stream won't be retried under THIS stagingId; the client re-opens Phase A). The reaper
+                    // is the backstop if the abort itself fails. Anything else re-throws to the outer handler.
                     if (e instanceof PrecheckError) {
                         await pending.handle.abort().catch(() => undefined);
                         cleanupStaging(stagingId);
@@ -431,10 +613,20 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                         sendError(res, 422, "invalid_entries", "staged session log failed validation");
                         return;
                     }
+                    // 对抗复查 A-4(HIGH):a NON-validation exception (storage blip, dropped connection) used to re-throw
+                    // with the lease + pendingStagings entry INTACT — the outer handler 500s, and every later Phase A for
+                    // this session 409s `import_in_flight` until the process restarts (the DB reaper can't clear the
+                    // in-memory Set). Clean up here too: abort the staged rows (best-effort; reaper backstops) + release
+                    // the lease, so the client's retry re-opens Phase A instead of wedging. Then re-throw for the 500.
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
                     throw e;
                 }
+                // 对抗复查 A-6(HIGH,route 半件):re-check the ACTIVE-RUN guard right before commit — Phase A's check
+                // can be minutes stale by the time the stream finishes, and an overwrite-dst commit would purge a log a
+                // LIVE run is appending to. (The owner half lives in the store commit's in-txn re-classify + FOR UPDATE;
+                // a residual sub-second TOCTOU between this check and the txn remains — documented, not load-bearing for
+                // correctness since the commit txn serializes against appends via FOR UPDATE.)
                 const activeAtCommit = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeAtCommit) {
                     await pending.handle.abort().catch(() => undefined);
@@ -442,8 +634,13 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 409, "session_active", "session started an active run while the import streamed; sync after it settles", { activeTaskId: activeAtCommit });
                     return;
                 }
+                // ── commit (the atomic swap) → replay snapshots/policy/anchors → cache evict → release lease ──
                 try {
                     const committed = await pending.handle.commit(pending.owner, pending.resolution ? { resolution: pending.resolution } : undefined);
+                    // ① snapshots — content-addressed import (idempotent). importManifest never throws → a {ok:false} is a
+                    //    fail-closed 422 (a blob the Phase-A presence check couldn't catch — corrupted in transit). Note: the
+                    //    ENTRIES are already committed (the swap), so a snapshot failure here means the conversation synced but a
+                    //    file tree did not — we surface 422 so the client re-PUTs the blob and re-POSTs (idempotent).
                     if (canImportSnapshots) {
                         const importManifest = deps.fileSnapshotStore.importManifest.bind(deps.fileSnapshotStore);
                         for (const snap of pending.snapshots) {
@@ -455,25 +652,32 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                             }
                         }
                     }
+                    // ② policy — replay each record; the E6 tighten-only gate applies unless the importer is a verified operator.
                     const policyStore = deps.sessionPolicyStore;
                     if (policyStore)
                         for (const rec of pending.policy)
                             await policyStore.putRules(sessionId, rec.principal, rec.rules, { operator: pending.operatorOk });
+                    // ③ anchors — owner RE-KEYED to the importing principal (§9).
                     const anchorStore = deps.resumeAnchorStore;
                     if (anchorStore)
                         for (const a of pending.anchors)
                             await anchorStore.put(sessionId, a.eventId, a.entryId, pending.owner);
+                    // The commit wrote durable state via the RAW store, bypassing the CachingSessionStore wrapper → evict the warm handle.
                     deps.sessionStorage.evict?.(sessionId);
                     cleanupStaging(stagingId);
                     sendJson(res, 200, { relation: committed.relation });
                 }
                 catch (e) {
+                    // A commit-time conflict (the in-txn re-classify flipped to fork/stale, TOCTOU close) rolled the swap back →
+                    // the staging rows still exist → abort them; the client must restart from Phase A with a fresh resolution.
                     if (e instanceof SyncConflictError) {
                         await pending.handle.abort().catch(() => undefined);
                         cleanupStaging(stagingId);
                         sendError(res, 409, "conflict", "sync conflict", { relation: e.relation });
                         return;
                     }
+                    // A SessionPolicyError happens AFTER the swap committed (the policy replay is post-commit) → the conversation
+                    // synced, only the loosen is refused (fail-closed). The staging rows were already renamed away (abort no-op).
                     if (e instanceof SessionPolicyError) {
                         cleanupStaging(stagingId);
                         sendError(res, e.code === "loosen_forbidden" ? 403 : 409, e.code, e.message);
@@ -484,6 +688,11 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 }
                 return;
             }
+            // POST …/sync/plan — DRY-RUN: classify what a PUSH of the LOCAL peer's log (body.entryIds, the OTHER process's
+            // entry-id list) WOULD do against the cloud's current log, WITHOUT writing. The same-process planSync(both
+            // backends) doesn't map the HTTP topology (one peer is remote) → the route classifies by ids: the client ids
+            // are the SOURCE (oldest-first), the cloud's current entries are the DST. own-or-FRESH gate (a fresh cloud
+            // session ⇒ the relation is `fresh`).
             if (sm[2] === "plan" && req.method === "POST") {
                 if (!pushGateOk())
                     return;
@@ -499,11 +708,12 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
-                const dst = await deps.sessionStorage?.exportEntries?.(sessionId);
+                const dst = await deps.sessionStorage?.exportEntries?.(sessionId); // the cloud's current log (null if fresh)
                 const relation = classifySyncRelationshipByIds(body.entryIds, dst ? dst.map((e) => e.id) : null);
                 sendJson(res, 200, relation);
                 return;
             }
+            // A matched sync path but a wrong METHOD (e.g. POST /manifest) → 404 (no method-specific 405 elsewhere).
             sendError(res, 404, "not_found.route", "not found");
             return;
         }

package/dist/http/routes/sessions-list.d.ts

@@ -1,3 +1,9 @@
+/**
+ * design/158 A9 域模块 —— 会话列表 / 发件链接列表。
+ *
+ * 路由:`GET /v1/sessions`(CC /resume picker,keyset 分页)、`GET /v1/sendfile-links`。
+ * owner-scope 与 trace 列表同一权威模型(system/traceToken=fleet-wide,principal=钉住本人)。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleSessionsList(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;