@sema-agent/server 7.149.0 → 7.151.0

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

@@ -1,16 +1,16 @@
 import { once } from "node:events";
 import { sessionLogDigest, sessionLogDigestsComparable, validateFileHistoryExport } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
-import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory, fileHistoryImportFace, replayFileHistory, replayPolicyRecords, wipeSessionAttendants } from "../../session-sync.js";
+import { FileHistoryUnreadableError, blobGetterOf, exportSessionManifest, exportedFileHistory } from "../../session-sync.js";
+import { fileHistoryImportFace } from "../../plugins/landed-attendants.js";
 import * as facts from "../../capability-facts.js";
 import { classifySyncRelationshipByIds, createStagedLogFeed, MalformedImportEntryError, newStagingToken, readImportAnchors, SyncConflictError } from "../../session-sync-kernel.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 { enter, judgeSession, refuse } from "../owner-access.js";
+import { enter, readSessionAgent, readSyncGate, recheckSyncGate, 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;
@@ -18,7 +18,7 @@ import { SHA256_HEX_RE } from "../../digest-form.js";
 import { assertNever } from "../route-ctx.js";
 import { readSessionRulesRecords, describeSessionRulesRecordProblem } from "../../session-policy-wire.js";
 import { readSessionPinned, readSessionTitle } from "../../session-row.js";
-import { deletionHeadReadOf, sessionFaceOfHead } from "../../session-incarnation.js";
+import { incarnationLogPrefix, SessionOccupantChangedError } from "../../session-incarnation.js";
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { SessionActiveRunError, SessionForkInProgressError, SessionWriterPresentError } from "../../execution-placement.js";
 import { probeSessionChildren, sessionTenantScope } from "../../session-children-retire.js";
@@ -94,10 +94,8 @@ export async function handleSessionSync(req, res, match, ctx) {
                 return;
             }
             const judgeSessionGate = async () => {
-                const face = sessionFaceOfHead(sessionId, await sessionStorage.headOf(sessionId));
-                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 };
+                const { face, occupant, mayTouch } = await readSyncGate(syncEntry, sessionStorage, sessionId);
+                return { face, occupant, mayPull: face !== undefined && mayTouch, mayPush: occupant === undefined || mayTouch };
             };
             let gate;
             try {
@@ -125,6 +123,33 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
                 return true;
             };
+            const stillAdmitted = async (port) => {
+                const admitted = port === "pull" ? gate.face : gate.occupant;
+                return admitted === undefined || (await recheckSyncGate(sessionStorage, sessionId, admitted, port));
+            };
+            const pullAnswer = async (send) => {
+                let same;
+                try {
+                    same = await stillAdmitted("pull");
+                }
+                catch (e) {
+                    if (sendPullUnreadable(req, res, deps.logger, e))
+                        return;
+                    throw e;
+                }
+                if (!same) {
+                    sendSessionAbsent("missing");
+                    return;
+                }
+                send();
+            };
+            const pushAnswer = async (send) => {
+                if (!(await stillAdmitted("push"))) {
+                    sendError(res, 409, "conflict", "sync conflict");
+                    return;
+                }
+                send();
+            };
             const replaySessionRow = async (row, face) => {
                 if (Object.keys(row).length === 0)
                     return true;
@@ -170,9 +195,28 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
             };
             const canReplayHistory = fileHistoryImportFace(historyStore) !== undefined;
-            const replayHistory = async (envelope, allowReplace) => {
-                const r = await replayFileHistory(historyStore, sessionId, envelope, blobGetterOf(historyStore), { allowReplace });
-                return r.ok ? undefined : r;
+            const landAttendants = async (attendants, landed, plan) => {
+                if (plan.wipe && !(await attendants.wipe(sessionId, landed)).landed)
+                    return { kind: "gone", leg: "wipe" };
+                if (plan.fileHistory !== null && canReplayHistory) {
+                    const h = await attendants.replayHistory(sessionId, landed, plan.fileHistory, blobGetterOf(historyStore), { allowReplace: plan.allowReplace });
+                    if (!h.landed)
+                        return { kind: "gone", leg: "file_history" };
+                    if (!h.value.ok)
+                        return { kind: "history_failed", failure: h.value };
+                }
+                if (plan.policy.length > 0 && !(await attendants.replayPolicy(sessionId, landed, plan.policy, plan.operator)).landed)
+                    return { kind: "gone", leg: "policy" };
+                if (plan.anchors.length > 0 && !(await attendants.putAnchors(sessionId, landed, plan.anchors, plan.owner)).landed)
+                    return { kind: "gone", leg: "anchors" };
+                if (!(await replaySessionRow(plan.row, landed)))
+                    return { kind: "gone", leg: "row" };
+                return { kind: "landed" };
+            };
+            const sendLandedOccupantGone = (arm, leg, landed) => {
+                deps.logger?.warn?.("session_sync_landed_occupant_gone", { sessionId, arm, leg, landed: incarnationLogPrefix(landed.incarnation) });
+                deps.metrics?.inc("session_sync_landed_occupant_gone_total", { arm, leg }, 1);
+                sendError(res, 409, "conflict", "sync conflict");
             };
             if (match.decl.id === "session-sync-manifest") {
                 if (!pullGateOk())
@@ -190,7 +234,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendSessionAbsent("missing");
                     return;
                 }
-                sendJson(res, 200, { manifest: out.manifest });
+                await pullAnswer(() => sendJson(res, 200, { manifest: out.manifest }));
                 return;
             }
             if (match.decl.id === "session-sync-entries") {
@@ -206,9 +250,11 @@ export async function handleSessionSync(req, res, match, ctx) {
                     }
                     afterSeq = n;
                 }
+                const recheck = async () => { if (!(await stillAdmitted("pull")))
+                    throw new SessionOccupantChangedError(sessionId); };
                 let it;
                 try {
-                    it = await sessionStorage.exportEntriesStream(sessionId, afterSeq === undefined ? undefined : { afterSeq });
+                    it = await sessionStorage.exportEntriesStream(sessionId, { ...(afterSeq === undefined ? {} : { afterSeq }), recheck });
                 }
                 catch (e) {
                     if (sendPullUnreadable(req, res, deps.logger, e))
@@ -219,6 +265,19 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendSessionAbsent("missing");
                     return;
                 }
+                let openSame;
+                try {
+                    openSame = await stillAdmitted("pull");
+                }
+                catch (e) {
+                    if (sendPullUnreadable(req, res, deps.logger, e))
+                        return;
+                    throw e;
+                }
+                if (!openSame) {
+                    sendSessionAbsent("missing");
+                    return;
+                }
                 res.writeHead(200, { "content-type": "application/x-ndjson", "transfer-encoding": "chunked" });
                 const write = async (line) => { if (!res.write(line))
                     await once(res, "drain"); };
@@ -233,7 +292,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                     res.end();
                 }
                 catch (e) {
-                    deps.logger?.error?.("sync entries stream failed", { sessionId, count, error: msg(e) });
+                    if (e instanceof SessionOccupantChangedError)
+                        deps.logger?.info?.("session_sync_pull_occupant_changed", { sessionId, count });
+                    else
+                        deps.logger?.error?.("sync entries stream failed", { sessionId, count, error: msg(e) });
                     res.end();
                 }
                 return;
@@ -268,7 +330,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
                 const referenced = envelope !== null && envelope.tracked.some((t) => t.versions.some((v) => v.blobHash === hash));
                 if (!referenced) {
-                    sendError(res, 404, "not_found.blob", "blob not found");
+                    await pullAnswer(() => sendError(res, 404, "not_found.blob", "blob not found"));
                     return;
                 }
                 let bytes;
@@ -280,12 +342,15 @@ export async function handleSessionSync(req, res, match, ctx) {
                         return;
                     throw e;
                 }
-                if (!bytes) {
-                    sendError(res, 404, "not_found.blob", "blob not found");
+                const found = bytes;
+                if (!found) {
+                    await pullAnswer(() => sendError(res, 404, "not_found.blob", "blob not found"));
                     return;
                 }
-                res.writeHead(200, { "content-type": "application/octet-stream" });
-                res.end(Buffer.from(bytes));
+                await pullAnswer(() => {
+                    res.writeHead(200, { "content-type": "application/octet-stream" });
+                    res.end(Buffer.from(found));
+                });
                 return;
             }
             if (match.decl.id === "session-sync-blob-put") {
@@ -390,10 +455,14 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const entryIds = body.entryIds;
                 const policy = policyRead.records;
                 const anchors = anchorsRead.anchors;
-                const dstIds = (await sessionStorage.listEntryIds?.(sessionId)) ?? null;
+                const dstIds = gate.occupant === undefined ? null : ((await sessionStorage.listEntryIds?.(sessionId)) ?? null);
                 const relA = classifySyncRelationshipByIds(entryIds, dstIds);
                 const refusalA = await firstPhaseRefusal(sessionStorage, sessionId, relA.relation, resolution === "overwrite-dst");
                 if (refusalA !== undefined) {
+                    if (!(await stillAdmitted("push"))) {
+                        sendError(res, 409, "conflict", "sync conflict");
+                        return;
+                    }
                     if (refusalA.kind === "stamped") {
                         if (sendSessionError(res, refusalA.error, "import"))
                             return;
@@ -409,7 +478,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                             if (v.blobHash !== null)
                                 distinct.add(v.blobHash);
                     if (await firstMissingBlob(facts.sessionSyncFileHistory(deps), [...distinct]) !== undefined) {
-                        sendMissingBlob(res);
+                        await pushAnswer(() => sendMissingBlob(res));
                         return;
                     }
                 }
@@ -436,10 +505,10 @@ export async function handleSessionSync(req, res, match, ctx) {
                         case "mirror":
                             break;
                         case "writer":
-                            sendSessionWriter(res);
+                            await pushAnswer(() => sendSessionWriter(res));
                             return;
                         case "forking":
-                            sendError(res, 409, "conflict.fork_in_progress", new SessionForkInProgressError(sessionId).message);
+                            await pushAnswer(() => sendError(res, 409, "conflict.fork_in_progress", new SessionForkInProgressError(sessionId).message));
                             return;
                         default: {
                             const unknownRole = placed.cell;
@@ -447,12 +516,13 @@ export async function handleSessionSync(req, res, match, ctx) {
                         }
                     }
                 }
-                const activeNow = await activityOf(gateFace);
+                const activeNow = gate.occupant === undefined ? undefined : await activityOf(gateFace);
                 if (activeNow !== undefined) {
-                    sendActivity(activeNow, "open");
+                    await pushAnswer(() => sendActivity(activeNow, "open"));
                     return;
                 }
                 if (relA.relation === "identical" && !digestSaysDiffer) {
+                    const attendantsA = backend.landedAttendants();
                     const seat = sessionStorage.executionPlacement;
                     if (seat !== undefined) {
                         if (gateFace === undefined) {
@@ -478,35 +548,38 @@ export async function handleSessionSync(req, res, match, ctx) {
                             }
                         }
                     }
-                    if (fileHistory !== null && canReplayHistory) {
-                        const failed = await replayHistory(fileHistory, resolution === "overwrite-dst");
-                        if (failed !== undefined) {
-                            sendFileHistoryReplayFailure(res, failed);
+                    if (gateFace === undefined) {
+                        sendError(res, 409, "conflict", "sync conflict");
+                        return;
+                    }
+                    let landedA;
+                    try {
+                        landedA = await landAttendants(attendantsA, gateFace, { wipe: false, fileHistory, allowReplace: resolution === "overwrite-dst", policy, operator: operatorOk, anchors, owner: importingPrincipal, row });
+                    }
+                    catch (e) {
+                        if (sendSessionPolicyError(res, e))
                             return;
-                        }
+                        throw e;
                     }
-                    if (deps.sessionPolicyStore) {
-                        try {
-                            await replayPolicyRecords(deps.sessionPolicyStore, sessionId, policy, operatorOk);
-                        }
-                        catch (e) {
-                            if (sendSessionPolicyError(res, e))
-                                return;
-                            throw e;
+                    switch (landedA.kind) {
+                        case "landed":
+                            break;
+                        case "gone":
+                            sendLandedOccupantGone("identical", landedA.leg, gateFace);
+                            return;
+                        case "history_failed":
+                            sendFileHistoryReplayFailure(res, landedA.failure);
+                            return;
+                        default: {
+                            const unhandled = landedA;
+                            throw new Error(`session sync: unknown landing answer ${JSON.stringify(unhandled)}`);
                         }
                     }
-                    if (deps.resumeAnchorStore)
-                        for (const a of anchors)
-                            await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingPrincipal);
-                    if (!(await replaySessionRow(row, gateFace))) {
-                        sendError(res, 409, "conflict", "sync conflict");
-                        return;
-                    }
-                    sendJson(res, 200, {
+                    await pushAnswer(() => sendJson(res, 200, {
                         relation: "identical",
                         basis: payloadVerified ? "entry-ids+digest" : "entry-ids",
                         payloadVerified,
-                    });
+                    }));
                     return;
                 }
                 const leaseKey = importLeaseKey(gate.occupant !== undefined ? gate.occupant.owner : importingPrincipal, sessionId);
@@ -518,8 +591,12 @@ export async function handleSessionSync(req, res, match, ctx) {
                 const heldLease = importLeases.get(leaseKey);
                 if (heldLease) {
                     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);
+                    await pushAnswer(() => 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;
+                }
+                if (!(await stillAdmitted("push"))) {
+                    sendError(res, 409, "conflict", "sync conflict");
                     return;
                 }
                 const token = newStagingToken();
@@ -528,7 +605,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 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: ownerKeyOf(scope.gateOwner), expectedOwner: owner, leaseKey,
+                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: ownerKeyOf(scope.gateOwner), expectedOccupant: gateFace, leaseKey,
                 });
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
@@ -614,19 +691,22 @@ export async function handleSessionSync(req, res, match, ctx) {
                         return;
                     throw e;
                 }
-                let mayPushAtCommit;
+                let gateAtCommit;
                 let activeAtCommit;
+                let activeStillAdmitted = true;
                 try {
-                    const gateAtCommit = await judgeSessionGate();
-                    mayPushAtCommit = gateAtCommit.mayPush;
-                    activeAtCommit = mayPushAtCommit ? await activityOf(gateAtCommit.face) : undefined;
+                    gateAtCommit = await judgeSessionGate();
+                    const atCommit = gateAtCommit.occupant;
+                    activeAtCommit = gateAtCommit.mayPush && atCommit !== undefined ? await activityOf(gateAtCommit.face) : undefined;
+                    if (activeAtCommit !== undefined && atCommit !== undefined)
+                        activeStillAdmitted = await recheckSyncGate(sessionStorage, sessionId, atCommit, "push");
                 }
                 catch (e) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
                     throw e;
                 }
-                if (!mayPushAtCommit) {
+                if (!gateAtCommit.mayPush) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
                     sendSessionAbsent("not_visible");
@@ -635,37 +715,43 @@ export async function handleSessionSync(req, res, match, ctx) {
                 if (activeAtCommit !== undefined) {
                     await pending.handle.abort().catch(() => undefined);
                     cleanupStaging(stagingId);
+                    if (!activeStillAdmitted) {
+                        sendError(res, 409, "conflict", "sync conflict");
+                        return;
+                    }
                     sendActivity(activeAtCommit, "streamed");
                     return;
                 }
                 try {
-                    const committed = await pending.handle.commit(pending.owner, { expectedOwner: pending.expectedOwner, ...(pending.resolution ? { resolution: pending.resolution } : {}) });
-                    if (pending.resolution === "overwrite-dst" && (committed.relation === "fork" || committed.relation === "stale")) {
-                        await wipeSessionAttendants({ fileHistoryStore: historyStore, sessionPolicyStore: deps.sessionPolicyStore, resumeAnchorStore: deps.resumeAnchorStore }, sessionId);
-                    }
-                    if (pending.fileHistory !== null && canReplayHistory) {
-                        const failed = await replayHistory(pending.fileHistory, pending.resolution === "overwrite-dst");
-                        if (failed !== undefined) {
-                            sendFileHistoryReplayFailure(res, failed);
-                            cleanupStaging(stagingId);
-                            return;
-                        }
-                    }
-                    const policyStore = deps.sessionPolicyStore;
-                    if (policyStore)
-                        await replayPolicyRecords(policyStore, sessionId, pending.policy, pending.operatorOk);
-                    const anchorStore = deps.resumeAnchorStore;
-                    if (anchorStore)
-                        for (const a of pending.anchors)
-                            await anchorStore.put(sessionId, a.eventId, a.entryId, pending.owner);
-                    const rowLanded = await replaySessionRow(pending.row, committed.face);
+                    const attendantsB = backend.landedAttendants();
+                    const committed = await pending.handle.commit(pending.owner, { expectedOccupant: pending.expectedOccupant, ...(pending.resolution ? { resolution: pending.resolution } : {}) });
                     sessionStorage.evict?.(sessionId);
+                    const landedB = await landAttendants(attendantsB, committed.face, {
+                        wipe: pending.resolution === "overwrite-dst" && (committed.relation === "fork" || committed.relation === "stale"),
+                        fileHistory: pending.fileHistory,
+                        allowReplace: pending.resolution === "overwrite-dst",
+                        policy: pending.policy,
+                        operator: pending.operatorOk,
+                        anchors: pending.anchors,
+                        owner: pending.owner,
+                        row: pending.row,
+                    });
                     cleanupStaging(stagingId);
-                    if (!rowLanded) {
-                        sendError(res, 409, "conflict", "sync conflict");
-                        return;
+                    switch (landedB.kind) {
+                        case "landed":
+                            sendJson(res, 200, { relation: committed.relation });
+                            return;
+                        case "gone":
+                            sendLandedOccupantGone("commit", landedB.leg, committed.face);
+                            return;
+                        case "history_failed":
+                            sendFileHistoryReplayFailure(res, landedB.failure);
+                            return;
+                        default: {
+                            const unhandled = landedB;
+                            throw new Error(`session sync: unknown landing answer ${JSON.stringify(unhandled)}`);
+                        }
                     }
-                    sendJson(res, 200, { relation: committed.relation });
                 }
                 catch (e) {
                     await pending.handle.abort().catch(() => undefined);
@@ -704,9 +790,17 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.field_invalid", "entryIds must be an array of strings");
                     return;
                 }
-                const dst = await sessionStorage.exportEntries(sessionId);
+                const dst = gate.occupant === undefined ? null : await sessionStorage.exportEntries(sessionId);
                 const relation = classifySyncRelationshipByIds(body.entryIds, dst ? dst.map((e) => e.id) : null);
+                if (gate.occupant === undefined) {
+                    sendJson(res, 200, relation);
+                    return;
+                }
                 const refusal = await firstPhaseRefusal(sessionStorage, sessionId, relation.relation, false);
+                if (!(await stillAdmitted("push"))) {
+                    sendError(res, 409, "conflict", "sync conflict");
+                    return;
+                }
                 if (refusal?.kind === "stamped") {
                     if (sendSessionError(res, refusal.error, "import"))
                         return;
@@ -795,9 +889,6 @@ function sendSessionSyncUnavailable(res, why) {
         case "session_import_staging_absent":
             sendError(res, 501, "capability.session_store_required", "staged session import requires a durable session store");
             return;
-        case "file_history_store_absent":
-            sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: no file-history store is wired, so there is no file history to export or import");
-            return;
         case "policy_purge_absent":
             sendError(res, 501, "capability.policy_purge_required", "session sync is not available on this deployment: the session-policy store has no deleteBySession purge verb, so an overwrite-dst import could not wipe the destination's stale policy rows. Every in-tree policy store carries it since core 1.423 — upgrade the policy store");
             return;

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

@@ -1,8 +1,9 @@
 import { isUuidV7 } from "../../security.js";
 import { sendJson, sendError } from "../send.js";
 import { sendUnauthorized } from "../principal-gate.js";
-import { routeListFilter } from "../owner-access.js";
+import { listOwnerOf, listVisibleSessions, routeListFilter } from "../owner-access.js";
 import { filterFingerprint } from "../cursor-fingerprint.js";
+import { SESSION_KINDS, isSessionKind } from "../../session-kind.js";
 import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import { assertNever } from "../route-ctx.js";
 import { PRINCIPAL_MAX_BYTES } from "../../principal-shape.js";
@@ -21,8 +22,7 @@ export async function handleSessionsList(req, res, match, ctx) {
                 sendError(res, 501, "capability.session_store_required", "session list requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
-            const lister = listing.lister;
-            await handleSessionList(res, lister, new URLSearchParams(match.search), gateOwner, includeUnowned);
+            await handleSessionList(res, listing.lister, new URLSearchParams(match.search), { fleetWide, gateOwner, includeUnowned });
             return;
         }
         case "sendfile-links": {
@@ -109,18 +109,24 @@ function decodeSessionCursor(s, expectF) {
         return undefined;
     }
 }
-async function handleSessionList(res, lister, query, forceOwner, includeUnowned = false) {
-    const owner = forceOwner != null ? forceOwner : (query.get("owner") ?? undefined);
+async function handleSessionList(res, lister, query, filter) {
+    const kindRaw = query.get("sessionKind");
+    if (kindRaw !== null && !isSessionKind(kindRaw)) {
+        sendError(res, 400, "request.query_invalid", `sessionKind must be one of ${SESSION_KINDS.map((w) => JSON.stringify(w)).join(" | ")} when present (absent = the default view: top-level sessions only)`);
+        return;
+    }
+    const sessionKind = kindRaw ?? undefined;
+    const owner = listOwnerOf(filter, query.get("owner") ?? undefined);
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 50) || 50));
     const qRaw = (query.get("q") ?? "").trim();
     const q = qRaw ? qRaw.slice(0, 256) : undefined;
-    const f = filterFingerprint([owner, includeUnowned, q]);
+    const f = filterFingerprint(sessionKind === undefined ? [owner, filter.includeUnowned, q] : [owner, filter.includeUnowned, q, sessionKind]);
     const cursor = decodeSessionCursor(query.get("cursor"), f);
     if (cursor === "mismatch") {
         sendError(res, 400, "request.cursor_filter_mismatch", "cursor was issued under a different filter (owner/q) — restart from the first page without a cursor");
         return;
     }
-    const rows = await lister({ ...(owner !== undefined ? { owner } : {}), ...(includeUnowned ? { includeUnowned: true } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1, ...(q ? { q } : {}) });
+    const rows = await listVisibleSessions(lister, filter, query.get("owner") ?? undefined, { ...(cursor ? { cursor } : {}), limit: limit + 1, ...(q ? { q } : {}), ...(sessionKind !== undefined ? { sessionKind } : {}) });
     const hasMore = rows.length > limit;
     const page = hasMore ? rows.slice(0, limit) : rows;
     const last = page[page.length - 1];

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

@@ -26,7 +26,7 @@ export interface SessionsLocal {
             degraded?: boolean;
         }>;
     }>;
-    /** DESIGN-269 件4:`/a2a` 面板的短 TTL single-flight 缓存。与 `mcpStatusCache` **分开一张表**而不是
+    /** [ref] 件4:`/a2a` 面板的短 TTL single-flight 缓存。与 `mcpStatusCache` **分开一张表**而不是
      *  共用带前缀的键:两张面板的体不同形(`peers` vs `servers`),塞进一张表就得靠 unknown 兜住两形,
      *  于是「取到的是哪一形」变成运行期约定 —— 两张表让它回到类型上。 */
     a2aStatusCache: Map<string, {