@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/routes/session-memory-sync.d.ts

@@ -28,7 +28,7 @@
  *  2. 多租户部署上没有验过的身份 ⇒ 401/403(`sendPrincipalRefusal`,会话面同一只)。
  *  3. 限流(本口会向远端发请求)。
  *  4. 会话 id 段解码不了 ⇒ 400 `request.path_malformed`。
- *  5. 一次头读:没有这只会话 / 不是你的 ⇒ 404 `not_found.session`(同码同串,无存在性 oracle;属主判据 = 会话面唯一谓词 `sessionOwnerOk`);
+ *  5. 一次头读:没有这只会话 / 不是你的 ⇒ 404 `not_found.session`(同码同串,无存在性 oracle;属主判据 = 会话面唯一谓词 `admitSessionRow`);
  *     同一次头读的叶子 = `sourceRevision`(与 `GET /v1/sessions/:id/head` 的 `leafId` 同一读法)。
  *  6. 体:闭集一键 `{ target }`,否则 400 `request.body_shape`;`target` 不是声明的同步身份 ⇒ 400 `request.field_invalid`(`field` / `reason`,不回显值)。
  *  7. 读集(上一节)。
@@ -50,7 +50,7 @@
  * 零模型工作(不 billable、不吃 drain 503);写的是调用方自己的记忆到它自己配置的中心 ⇒ 属主门兜底,不进无凭据改写门(会话自助抹除同判)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type SettledLegMemoryObservation } from "../../plugins/store-contracts.js";
 /** 收割栅栏的句(本服务铸;码 `session_active` 是引擎报告闭集的成员)。 */
 export declare const SESSION_ACTIVE_SYNC_MESSAGE = "a run in this session is in flight, or the session moved on after the memory it reads was observed (a run was admitted or its transcript advanced) \u2014 wait for it to finish on its own, then sync again (do not cancel it to sync sooner)";

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

@@ -1,10 +1,8 @@
 import { memorySyncReportOf } from "@sema-agent/core";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import {} from "../route-ctx.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { admitSessionById, enter } from "../owner-access.js";
+import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
-import { sessionOwnerCellOf } from "../../security.js";
 import { leafOfAdmittedHead } from "../../session-incarnation.js";
 import { declaredMemorySyncIdentityFlaw, memorySyncIdentityRule } from "../../memory-sync-identity.js";
 import { MEMORY_OBSERVATION_ABSENT_REASONS } from "../../plugins/store-contracts.js";
@@ -86,10 +84,9 @@ export async function handleSessionMemorySync(req, res, match, ctx) {
                 }
             }
             const { leg, runStore, sessionStorage } = fact;
-            if (deps.config.requirePrincipal && gatedPrincipal(req, deps.config) === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             if (ctx.helpers.rateLimited(req, res))
                 return;
             const sessionId = ctx.helpers.safeDecode(match.params.sessionId);
@@ -98,13 +95,10 @@ export async function handleSessionMemorySync(req, res, match, ctx) {
                 return;
             }
             const readHead = () => sessionStorage.headOf(sessionId);
-            const head = await readHead();
-            if (head === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return;
-            }
-            if (!ctx.helpers.sessionOwnerOk(req, res, await sessionOwnerCellOf(sessionStorage, sessionId, head.owner)))
+            const admitted = await admitSessionById(entry, res, sessionStorage, sessionId);
+            if (admitted === undefined)
                 return;
+            const head = admitted.row;
             const sourceRevision = leafOfAdmittedHead(head);
             const body = await ctx.helpers.readJson(req);
             if (body === null || typeof body !== "object" || Array.isArray(body) || Object.keys(body).some((k) => k !== "target") || typeof body.target !== "string") {

package/dist/http/routes/session-sync.d.ts

@@ -10,6 +10,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionRulesRecord, type FileHistoryExport } from "@sema-agent/core";
 import { type ImportAnchor, type StagingHandle } from "../../session-sync-kernel.js";
+import type { DurableOwnerKey } from "../../owner-brands.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type SessionRowPatch } from "../../session-row.js";
 export type PendingStaging = {
@@ -29,21 +30,41 @@ export type PendingStaging = {
      *  (a different tree under the same staging would otherwise commit while the parked snapshots/anchors
      *  still reference the DECLARED one). */
     declaredEntryIds: string[];
-    /** The principal that opened this staging — a different caller may not drive it (404, no oracle). */
-    openedBy: string | null;
+    /** The principal that opened this staging, kept as the handle's owner key (`null` = a fleet caller opened it) — a different caller may not drive it
+     *  (404, no oracle; compared through `owner-faces.ts` `sameKey` only). */
+    openedBy: DurableOwnerKey | null;
     /** The owner cell the gate judged when it opened this staging (head-read reading `headOf(id)?.owner`: `undefined` = no such session) — the commit lands only on
      *  this same cell (`StagedCommitOptions.expectedOwner`, `session-sync-kernel.ts`); `owner` above (the re-stamped importing principal) is derived from it for a fleet caller. */
     expectedOwner: string | null | undefined;
+    /** 开这张暂存时占下的导入租约的键({@link importLeaseKey});续期与放掉都按它,不再从会话 id 重算。 */
+    leaseKey: string;
+};
+/**
+ * 导入租约的键 = 这次导入**落在哪一格属主上**(与提交的属主 CAS 同一格)+ 会话 id。一条读法:
+ *  · id 被占着(活行 ∪ 在删行 —— 「被占着」的唯一读法,门读的 `occupant`)⇒ 落点是住客的属主格(`null` = 无主):所有碰得到这一行的调用方(属主、fleet、存量无主互认)共一把 —— 同一份会话上第二份在飞导入,谁发起的都 409;
+ *  · id 空闲 ⇒ 还没有谁的会话,落点是这位调用方自己将成的属主(`importingPrincipal`):各占各的,先提交者得(提交的属主 CAS 要求那一格仍空着,输的那一份
+ *    在提交前复判被拒)。一个主体的在飞导入既不挡、也不透给另一个主体 —— 租约键不含主体时,空闲 id 上任一主体都能占位,并从 409 读到「此 id 此刻有人在导」。
+ * 键的主体只来自门读的 `occupant` 与 `importingPrincipal`(两者都派生自属主存取器的 `listFilterOf` 与门读的会话面,不另读调用方),且占租约在 `pushGateOk` 之后。
+ */
+export declare function importLeaseKey(landingOwner: string | null, sessionId: string): string;
+/** 一把导入租约:最后活动时刻 + 持有它的暂存 + 它守的会话 id(清扫与运维日志用,不从键里反解)。 */
+export type ImportLease = {
+    at: number;
+    stagingId: string;
+    sessionId: string;
 };
 /** 单域独占状态 + 它的两个操作。每个 server 实例一份。 */
 export interface SessionSyncLocal {
     pendingStagings: Map<string, PendingStaging>;
-    importLeases: Map<string, {
-        at: number;
-        stagingId: string;
-    }>;
-    touchImportLease(sessionId: string): void;
+    importLeases: Map<string, ImportLease>;
+    touchImportLease(leaseKey: string): void;
     cleanupStaging(stagingId: string): void;
+    /** 把闲置 ≥ `staleMs` 的租约连同它的暂存登记一并放掉(`staleMs <= 0` = 关,什么都不清);返回被放掉的(供运维日志)。 */
+    sweepStaleLeases(staleMs: number): Array<{
+        readonly sessionId: string;
+        readonly stagingId: string;
+        readonly ageMs: number;
+    }>;
 }
 export declare function createSessionSyncLocal(): SessionSyncLocal;
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。 */

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

@@ -4,39 +4,58 @@ import { StringDecoder } from "node:string_decoder";
 import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
 import * as facts from "../../capability-facts.js";
 import { classifySyncRelationshipByIds, createStagedLogFeed, MalformedImportEntryError, newStagingToken, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.js";
-import { isUuidShape, legacyUnownedSessionOk, sessionOwnerCellOf } from "../../security.js";
+import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, sendSessionError, sendSessionPolicyError, logRequestError, msg } from "../send.js";
 import { StampedSessionArchiveError } from "../../session-error-wire.js";
 import { readSessionAgent } from "../../session-agent.js";
 import { buildDisplaySafeUrl } from "../../trace/redact.js";
 import { storeFaultClassOf } from "../../plugins/store-fault.js";
-import { fleetViewOf, gatedPrincipal, explicitOperatorOk, sendUnauthorized, sessionCallerOf } from "../principal-gate.js";
+import { enter, judgeSession, refuse } from "../owner-access.js";
+import { listFilterOf, ownerKeyOf, sameKey } from "../../owner-faces.js";
 const SYNC_BLOB_MAX_BYTES = 64 * 1024 * 1024;
 const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
 import { SHA256_HEX_RE } from "../../digest-form.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { assertNever } from "../route-ctx.js";
 import { readSessionRulesRecords, describeSessionRulesRecordProblem } from "../../session-policy-wire.js";
 import { readSessionPinned, readSessionTitle } from "../../session-row.js";
-import { sessionFaceOfHead } from "../../session-incarnation.js";
+import { deletionHeadReadOf, sessionFaceOfHead } from "../../session-incarnation.js";
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { SessionActiveRunError, SessionForkInProgressError, SessionWriterPresentError } from "../../execution-placement.js";
-import { probeSessionChildren, sessionChildrenScope } from "../../session-children-retire.js";
+import { probeSessionChildren, sessionTenantScope } from "../../session-children-retire.js";
 import { liveChildrenRefusal } from "./background.js";
+export function importLeaseKey(landingOwner, sessionId) {
+    return JSON.stringify([landingOwner, sessionId]);
+}
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
-    const touchImportLease = (sessionId) => {
-        const cur = importLeases.get(sessionId);
+    const touchImportLease = (leaseKey) => {
+        const cur = importLeases.get(leaseKey);
         if (cur)
-            importLeases.set(sessionId, { ...cur, at: Date.now() });
+            importLeases.set(leaseKey, { ...cur, at: Date.now() });
     };
     const cleanupStaging = (stagingId) => {
         const p = pendingStagings.get(stagingId);
         if (p)
-            importLeases.delete(p.realSessionId);
+            importLeases.delete(p.leaseKey);
         pendingStagings.delete(stagingId);
     };
-    return { pendingStagings, importLeases, touchImportLease, cleanupStaging };
+    const sweepStaleLeases = (staleMs) => {
+        if (staleMs <= 0)
+            return [];
+        const now = Date.now();
+        const swept = [];
+        for (const [key, lease] of [...importLeases]) {
+            const ageMs = now - lease.at;
+            if (ageMs < staleMs)
+                continue;
+            swept.push({ sessionId: lease.sessionId, stagingId: lease.stagingId, ageMs });
+            cleanupStaging(lease.stagingId);
+            importLeases.delete(key);
+        }
+        return swept;
+    };
+    return { pendingStagings, importLeases, touchImportLease, cleanupStaging, sweepStaleLeases };
 }
 async function firstPhaseRefusal(sessionStorage, sessionId, relation, consented) {
     if (consented || (relation !== "fork" && relation !== "stale"))
@@ -56,7 +75,7 @@ async function firstPhaseRefusal(sessionStorage, sessionId, relation, consented)
 export async function handleSessionSync(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson, readRawBody, safeDecode, rateLimited } = ctx.helpers;
-    const { pendingStagings, importLeases, touchImportLease, cleanupStaging } = ctx.local.sessionSync;
+    const { pendingStagings, importLeases, touchImportLease, cleanupStaging, sweepStaleLeases } = ctx.local.sessionSync;
     {
         {
             const sync = facts.sessionSync(deps);
@@ -65,11 +84,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                 return;
             }
             const { backend, sessionStorage, historyStore } = sync;
-            const scope = fleetViewOf(req, deps, "write");
-            if (!scope.fleetWide && scope.gateOwner === null) {
-                sendUnauthorized(res, "identity");
+            const syncEntry = enter(req, res, deps, match.decl.id);
+            if (syncEntry === undefined)
                 return;
-            }
+            const scope = listFilterOf(syncEntry.face, syncEntry.caller);
             const sessionId = safeDecode(match.params.sessionId);
             if (sessionId === null || !isUuidShape(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
@@ -77,8 +95,9 @@ export async function handleSessionSync(req, res, match, ctx) {
             }
             const judgeSessionGate = async () => {
                 const face = sessionFaceOfHead(sessionId, await sessionStorage.headOf(sessionId));
-                const mayTouch = face !== undefined && (scope.fleetWide || face.owner === scope.gateOwner || legacyUnownedSessionOk(deps.config, sessionCallerOf(req, deps), await sessionOwnerCellOf(sessionStorage, sessionId, face.owner)));
-                return { face, mayPull: mayTouch, mayPush: face === undefined || mayTouch };
+                const held = face ?? sessionFaceOfHead(sessionId, await deletionHeadReadOf(sessionStorage)?.(sessionId));
+                const mayTouch = held !== undefined && (await judgeSession(syncEntry, sessionStorage, sessionId, held)) !== undefined;
+                return { face, occupant: held, mayPull: face !== undefined && mayTouch, mayPush: held === undefined || mayTouch };
             };
             let gate;
             try {
@@ -91,17 +110,17 @@ export async function handleSessionSync(req, res, match, ctx) {
             }
             const gateFace = gate.face;
             const owner = gateFace === undefined ? undefined : gateFace.owner;
-            const sendSessionAbsent = () => sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const sendSessionAbsent = (reason) => refuse(syncEntry, res, reason);
             const pullGateOk = () => {
                 if (!gate.mayPull) {
-                    sendSessionAbsent();
+                    sendSessionAbsent(gate.face === undefined ? "missing" : "not_visible");
                     return false;
                 }
                 return true;
             };
             const pushGateOk = () => {
                 if (!gate.mayPush) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("not_visible");
                     return false;
                 }
                 return true;
@@ -125,7 +144,7 @@ export async function handleSessionSync(req, res, match, ctx) {
             };
             const liveChildrenOf = async (face) => face === undefined
                 ? []
-                : (await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, sessionId, sessionChildrenScope(face.owner))).liveChildren;
+                : (await probeSessionChildren({ agentStore: deps.backgroundAgentStore, checkpointStore: deps.checkpointStore, registry: defaultTaskRegistry }, sessionId, sessionTenantScope(face.owner))).liveChildren;
             const activityOf = async (face) => {
                 const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
                 if (activeTaskId)
@@ -168,7 +187,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     throw e;
                 }
                 if (out === null) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("missing");
                     return;
                 }
                 sendJson(res, 200, { manifest: out.manifest });
@@ -197,7 +216,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     throw e;
                 }
                 if (it === null) {
-                    sendSessionAbsent();
+                    sendSessionAbsent("missing");
                     return;
                 }
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
@@ -408,6 +427,8 @@ export async function handleSessionSync(req, res, match, ctx) {
                     if (!payloadVerified)
                         digestSaysDiffer = true;
                 }
+                const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
+                const operatorOk = syncEntry.caller.operator;
                 const placed = gateFace === undefined ? undefined : await sessionStorage.executionPlacement?.read(sessionId);
                 if (placed !== undefined) {
                     switch (placed.cell.role) {
@@ -464,10 +485,9 @@ export async function handleSessionSync(req, res, match, ctx) {
                             return;
                         }
                     }
-                    const opOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
                     if (deps.sessionPolicyStore) {
                         try {
-                            await replayPolicyRecords(deps.sessionPolicyStore, sessionId, policy, opOk);
+                            await replayPolicyRecords(deps.sessionPolicyStore, sessionId, policy, operatorOk);
                         }
                         catch (e) {
                             if (sendSessionPolicyError(res, e))
@@ -475,10 +495,9 @@ export async function handleSessionSync(req, res, match, ctx) {
                             throw e;
                         }
                     }
-                    const importingP = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
                     if (deps.resumeAnchorStore)
                         for (const a of anchors)
-                            await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingP);
+                            await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingPrincipal);
                     if (!(await replaySessionRow(row, gateFace))) {
                         sendError(res, 409, "conflict", "sync conflict");
                         return;
@@ -490,33 +509,26 @@ export async function handleSessionSync(req, res, match, ctx) {
                     });
                     return;
                 }
-                const heldLease = importLeases.get(sessionId);
+                const leaseKey = importLeaseKey(gate.occupant !== undefined ? gate.occupant.owner : importingPrincipal, sessionId);
+                const staleSecRaw = deps.config.syncImportLeaseStaleSec;
+                const staleSec = typeof staleSecRaw === "number" && Number.isFinite(staleSecRaw) ? staleSecRaw : 600;
+                const staleMs = staleSec * 1000;
+                for (const swept of sweepStaleLeases(staleMs))
+                    deps.logger?.warn?.("sync_import_lease_taken_over", { sessionId: swept.sessionId, ageMs: swept.ageMs, staleMs, stagingId: swept.stagingId });
+                const heldLease = importLeases.get(leaseKey);
                 if (heldLease) {
-                    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) {
-                        deps.logger?.warn?.("sync_import_lease_taken_over", { sessionId, ageMs, staleMs, stagingId: heldLease.stagingId });
-                        cleanupStaging(heldLease.stagingId);
-                        importLeases.delete(sessionId);
-                    }
-                    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;
-                    }
+                    const retryAfterSec = staleMs > 0 ? Math.max(1, Math.ceil((staleMs - (Date.now() - heldLease.at)) / 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;
                 }
-                const importingPrincipal = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
-                const operatorOk = explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config);
                 const token = newStagingToken();
                 const handle = sessionStorage.beginImportStaging(sessionId, token);
                 const stagingId = handle.stagingId;
-                importLeases.set(sessionId, { at: Date.now(), stagingId });
+                importLeases.set(leaseKey, { at: Date.now(), stagingId, sessionId });
                 pendingStagings.set(stagingId, {
                     handle, realSessionId: sessionId, owner: importingPrincipal, ...(resolution ? { resolution } : {}), operatorOk,
-                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: scope.gateOwner, expectedOwner: owner,
+                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: ownerKeyOf(scope.gateOwner), expectedOwner: owner, leaseKey,
                 });
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
@@ -532,7 +544,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
-                if (!scope.fleetWide && pending.openedBy !== scope.gateOwner) {
+                if (!scope.fleetWide && !sameKey(scope.gateOwner, pending.openedBy)) {
                     sendError(res, 404, "not_found.staging", "staging not found");
                     return;
                 }
@@ -550,7 +562,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const utf8 = new StringDecoder("utf8");
                 try {
                     for await (const chunk of req) {
-                        touchImportLease(pending.realSessionId);
+                        touchImportLease(pending.leaseKey);
                         lineBuf += utf8.write(chunk);
                         if (Buffer.byteLength(lineBuf, "utf8") > SYNC_NDJSON_LINE_MAX_BYTES)
                             throw new PrecheckError(413, "NDJSON line too large");
@@ -617,7 +629,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 if (!mayPushAtCommit) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
-                    sendSessionAbsent();
+                    sendSessionAbsent("not_visible");
                     return;
                 }
                 if (activeAtCommit !== undefined) {
@@ -740,6 +752,7 @@ function sendPullUnreadable(req, res, logger, e) {
             sendError(res, 503, "state.file_history_unreadable", "this session's stored state cannot be read: the store does not match what this deployment requires (a table is missing or the database account lacks a privilege), so nothing was exported — retrying will not help until an operator repairs the store", { permanence: "terminal" });
             return true;
         case "corrupt":
+        case "defect":
         case "unclassified":
             return false;
         default: {

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

@@ -2,7 +2,7 @@
  * [ref] A9 域模块 —— 会话列表 / 发件链接列表。
  *
  * 路由:`GET /v1/sessions`(CC /resume picker,keyset 分页)、`GET /v1/sendfile-links`。
- * owner-scope 与 trace 列表同一权威模型(`fleetViewOf` 读档:service 凭据不报主体〔部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时不算〕/ 只读 trace 凭据 / dev-open = fleet-wide;带验过的主体 = 钉住那位主体)。本域零可变状态。
+ * owner-scope 与 trace 列表同一权威模型(列表面 `list.read` 读档(`listFilterOf`):service 凭据不报主体〔部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 时不算〕/ 只读 trace 凭据 / dev-open 上不报主体 = fleet-wide;报了主体 = 钉住那位主体,部署形不改这一句)。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionListItem } from "../../security.js";
@@ -14,9 +14,9 @@ import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare function handleSessionsList(req: IncomingMessage, res: ServerResponse, match: RouteMatch<SessionsListRouteId>, ctx: RouteCtx): Promise<void>;
 /**
  * 会话列表行的 **wire 投影** —— `GET /v1/sessions` 的每一行与 `PATCH /v1/sessions/:id` 的 200 回执是**同一只**(店行 → wire 行只有这一处)。
- *  · 预览:店行读的是 run 行预览列的事实位(`""` = 有记录、剥完没有用户正文;NULL = 没记录);本面只说「有没有可显示的预览」⇒ 两者都是 `null`。
  *  · `tempo`:见上方 [ref] 注(由 `lastStatus` 经唯一一张表派生;omit-when-absent)。
- *  · 其余键(含 `title` / `pinned` / `rowTag` / `unreadable`)零投影透传 —— 店行是唯一铸点(`unreadable` 的码出自 `session-error-wire.ts` 的那一张表,
+ *  · 其余键(含 `objectivePreview` / `title` / `pinned` / `rowTag` / `unreadable`)零投影透传 —— 店行是唯一铸点(预览的规则在店层:最近一条预览列
+ *    按字符长度非空的 run 的那一列,没有 ⇒ `null`,店恒不交 `""`;`store-contracts.ts` 的 `SessionRunRollup`)(`unreadable` 的码出自 `session-error-wire.ts` 的那一张表,
  *    与全局兜底对同一只会话答的码同读;SQL 孪生的叶子是行上一列 ⇒ 恒缺席)。
  */
 export declare function projectSessionListRow(r: SessionListItem): SessionListItem & {

package/dist/http/routes/sessions-list.js

@@ -1,15 +1,17 @@
-import { isUuidV7, legacyUnownedAmnestyOpen } from "../../security.js";
+import { isUuidV7 } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
-import { fleetViewOf, sendUnauthorized } from "../principal-gate.js";
+import { sendUnauthorized } from "../principal-gate.js";
+import { routeListFilter } from "../owner-access.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
 import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import { assertNever } from "../route-ctx.js";
+import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
 import * as facts from "../../capability-facts.js";
 export async function handleSessionsList(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
         case "sessions-list": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner, includeUnowned } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -20,12 +22,11 @@ export async function handleSessionsList(req, res, match, ctx) {
                 return;
             }
             const lister = listing.lister;
-            const includeUnowned = !fleetWide && legacyUnownedAmnestyOpen(deps.config, gateOwner);
             await handleSessionList(res, lister, new URLSearchParams(match.search), gateOwner, includeUnowned);
             return;
         }
         case "sendfile-links": {
-            const { fleetWide, gateOwner } = fleetViewOf(req, deps, "read");
+            const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
             if (!fleetWide && gateOwner === null) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -59,8 +60,8 @@ export async function handleSessionsList(req, res, match, ctx) {
                 }
                 else {
                     const s = scopeRaw.trim();
-                    if (s === "" || s.length > 190) {
-                        sendError(res, 400, "request.query_invalid", "scope must be a non-blank tenant principal of at most 190 characters (the sendfile_link.scope column width)");
+                    if (s === "" || Buffer.byteLength(s, "utf8") > PRINCIPAL_MAX_BYTES) {
+                        sendError(res, 400, "request.query_invalid", `scope must be a non-blank tenant principal of at most ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the principal length every identity column holds)`);
                         return;
                     }
                     scope = s;
@@ -128,8 +129,7 @@ async function handleSessionList(res, lister, query, forceOwner, includeUnowned
 }
 export function projectSessionListRow(r) {
     const tempo = sessionTempoOfRunStatus(r.lastStatus);
-    const row = r.objectivePreview === "" ? { ...r, objectivePreview: null } : r;
-    return tempo === undefined ? row : { ...row, tempo };
+    return tempo === undefined ? r : { ...r, tempo };
 }
 export const SESSIONS_LIST_ROUTES = [
     { id: "sessions-list", path: "/v1/sessions", methods: ["GET"] },