@sema-agent/server 7.124.1 → 7.125.1

package/dist/http/routes/runs.js

@@ -1,17 +1,13 @@
-import { persistedPlaneOf } from "../../terminal.js";
-import { memoRedactedRead, memoRedactTerminalResult, redactErrorMessage, redactHead, redactLedgerEventForRead, redactTerminalResult } from "../../observability/run-terminal.js";
+import { redactHead, redactLedgerEventForRead } from "../../observability/run-terminal.js";
 import { z } from "zod";
 import { uuidv7, mintCheckpointToken, CheckpointError, policyCannotAnswer, validatePendingSteer, TASK_OUTPUT_REPLAY_KINDS, isSystemInjectionPriority } from "@sema-agent/core";
-import { RUN_HOLDER_DEATH_CODES, isTerminalRunStatus, isParkedRunStatus, runProvenElsewhere } from "../../plugins/store-contracts.js";
+import { isTerminalRunStatus, isParkedRunStatus, runProvenElsewhere } from "../../plugins/store-contracts.js";
 import { LIVE_RUN_GATE_KINDS, TERMINAL_PARK_GATE_KINDS } from "../../plugins/checkpoint-store-sql.js";
 import { redactSecrets } from "../../trace/redact.js";
-import { HttpError, verifiedPrincipal, isUuidV7, encodeCheckpointScope } from "../../security.js";
+import { HttpError, isUuidV7, encodeCheckpointScope } from "../../security.js";
 import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../../orchestration/workflow-agent-steer.js";
 import { defaultSubagentTailBus } from "../../fleet/subagent-tail-bus.js";
-import { composeSupervisorCost, infraCost, infraUsageFromEvents, hasInfraPricing } from "../../observability/cost-taxonomy.js";
-import { recordFailOpen } from "../../observability/fail-open.js";
-import { createHash } from "node:crypto";
-import { scopedIdempotencyKey } from "../idempotency.js";
+import { idemCallerOf, idemKeyOf, inflightKeyOf } from "../idempotency.js";
 import { streamSseLog } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { buildApprovalPreamble, buildApprovalPreambleSseFrames, readClosedWordSeat, storedCardDemandsAPerson } from "../../approval-card.js";
@@ -21,15 +17,15 @@ import { MAX_DECISION_NOTE_CHARS } from "../../approval-ask-machine.js";
 import { causeOfAskRow } from "../../approval-deny-reasons.js";
 import { normalizeRunEventType, screenedStoredEventData } from "../../trace/project.js";
 import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
-import { readTurnActivityMs } from "../../turn-activity.js";
 import { mintCancelledResult } from "../../run-cancel-context.js";
 import { acceptedInputKindOf } from "../../user-input-ledger.js";
 import { INJECTION_TIERS } from "../../trace/injection-tier.js";
-import { buildCrossSliceUsage, readResourceWindow } from "../../resource-window.js";
 import { headerStr, gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { ActorAssertionWire } from "@sema-agent/settings-schema";
 import * as facts from "../../capability-facts.js";
 import { assertNever } from "../route-ctx.js";
+import { readRunFace } from "../run-read-face.js";
+import { replayOfExistingRun } from "../submit-replay.js";
 import { mintAndDriveDurableRun } from "../durable-run-leg.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
 import { withPrincipal } from "../../observability/principal-context.js";
@@ -191,16 +187,27 @@ export async function handleRuns(req, res, match, ctx) {
         }
         const runStore = runs.runStore;
         const rawIdem = headerStr(req.headers["idempotency-key"]);
-        const idemKey = rawIdem ? scopedIdempotencyKey(rawIdem, source, gatedPrincipal(req, deps.config)) : undefined;
-        const cached = idemKey ? idemCache.peek(idemKey) : undefined;
-        if (cached) {
-            const resp = await cached;
-            sendJson(res, resp.status, resp.body);
-            return;
+        const submitter = gatedPrincipal(req, deps.config);
+        const idemKey = rawIdem ? idemKeyOf(rawIdem, idemCallerOf(req, ctx), "run") : undefined;
+        let keyedBody;
+        if (idemKey) {
+            keyedBody = await readJson(req);
+            const clientTaskId = clientTaskIdOf(keyedBody);
+            if (clientTaskId === false) {
+                sendError(res, 400, "request.id_invalid", "body.taskId must be a uuidv7 string (caller-minted idempotency key)");
+                return;
+            }
+            const inflight = idemCache.peek(inflightKeyOf(idemKey, "durable", clientTaskId));
+            const keyedRow = inflight ? undefined : await runStore.getRunByIdem(idemKey);
+            if (inflight || keyedRow) {
+                const resp = inflight ? await inflight : await replayOfExistingRun(keyedRow, { principal: submitter, ...(clientTaskId !== undefined ? { clientTaskId } : {}) }, "durable", deps, runStore);
+                sendJson(res, resp.status, resp.body);
+                return;
+            }
         }
         if (rateLimited(req, res) || quotaExceeded(req, res))
             return;
-        const prepared = await prepareSpec(req, res);
+        const prepared = await prepareSpec(req, res, keyedBody);
         if (!prepared)
             return;
         const resp = await createDurableRun(req, res, ctx, prepared, idemKey);
@@ -209,23 +216,38 @@ export async function handleRuns(req, res, match, ctx) {
         sendJson(res, resp.status, resp.body);
         return;
     }
-    if (match.decl.id === "run-detail" || match.decl.id === "run-events") {
+    if (match.decl.id === "run-detail" || match.decl.id === "run-events" || match.decl.id === "runs-by-idem") {
         const runs = facts.durableRuns(deps);
         if (!runs.available) {
             sendError(res, 501, "capability.run_store_required", "async runs require a durable run store (DB_BACKEND=mysql|pg|local)");
             return;
         }
         const runStore = runs.runStore;
-        const taskId = match.params.taskId;
         if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
             sendPrincipalRefusal(res, req, deps.config);
             return;
         }
-        const run = await runStore.getRun(taskId);
+        let run;
+        let notFound;
+        if (match.decl.id === "runs-by-idem") {
+            const rawKey = new URLSearchParams(match.search).get("idempotencyKey");
+            if (!rawKey) {
+                sendError(res, 400, "request.query_invalid", "idempotencyKey is required: pass the raw Idempotency-Key the submission was sent with");
+                return;
+            }
+            run = await runStore.getRunByIdem(idemKeyOf(rawKey, idemCallerOf(req, ctx), "run"));
+            notFound = RUN_NOT_FOUND_MESSAGE;
+        }
+        else {
+            const taskId = match.params.taskId;
+            run = await runStore.getRun(taskId);
+            notFound = runNotFoundMessage(taskId);
+        }
         if (!run) {
-            sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
+            sendError(res, 404, "not_found.run", notFound);
             return;
         }
+        const taskId = run.taskId;
         if (!runOwnerOk(req, res, run.owner))
             return;
         if (!runSessionAcceptOk(req, res, run, match.decl.id === "run-events" ? "run.events" : "run.poll"))
@@ -234,62 +256,7 @@ export async function handleRuns(req, res, match, ctx) {
             await streamRunEvents(req, res, deps, runStore, taskId, deps.config.runStaleSec * 1000);
         }
         else {
-            const stale = run.status === "running" && Date.now() - new Date(run.updatedAt).getTime() > deps.config.runStaleSec * 1000;
-            const infraRates = deps.config.infraCostRates;
-            const needCost = Boolean(run.result?.stats && !stale && infraRates && hasInfraPricing(infraRates));
-            const needSuggestions = !stale && run.status === "completed";
-            const resourceWindow = run.status === "running" && !stale ? readResourceWindow(run.taskId) : undefined;
-            let events;
-            let eventsUnavailable = false;
-            if (needCost || needSuggestions || resourceWindow !== undefined) {
-                if (runStore.getEvents) {
-                    events = await runStore.getEvents(taskId, 0).catch(() => {
-                        eventsUnavailable = true;
-                        return [];
-                    });
-                }
-                else {
-                    eventsUnavailable = true;
-                }
-            }
-            let supervisorCost;
-            if (needCost && events && run.result?.stats) {
-                const durMs = new Date(run.updatedAt).getTime() - new Date(run.createdAt).getTime();
-                const usage = infraUsageFromEvents(events, Number.isFinite(durMs) ? durMs : 0);
-                const st = run.result.stats;
-                supervisorCost = composeSupervisorCost(st.costBreakdown ?? null, st.costMicroUsd ?? 0, infraCost(usage, infraRates));
-            }
-            let suggestions;
-            if (needSuggestions && events) {
-                const sug = [...events].reverse().find((e) => e.type === "suggestions");
-                const arr = sug?.data?.suggestions;
-                if (Array.isArray(arr))
-                    suggestions = arr.map((s) => String(s));
-            }
-            const lastActivityAt = run.status === "running" && !stale ? readTurnActivityMs(run.taskId) : undefined;
-            let crossSliceUsage;
-            if (resourceWindow !== undefined) {
-                if (eventsUnavailable || events === undefined)
-                    recordFailOpen("server.runs.cross-slice-usage-unavailable");
-                else
-                    crossSliceUsage = buildCrossSliceUsage(resourceWindow, events);
-            }
-            sendJson(res, 200, {
-                taskId: run.taskId,
-                sessionId: run.sessionId,
-                status: stale ? "failed" : run.status,
-                ...(lastActivityAt !== undefined ? { msSinceLastActivity: Math.max(0, Date.now() - lastActivityAt) } : {}),
-                ...(crossSliceUsage !== undefined ? { crossSliceUsage } : {}),
-                result: isTerminalRunStatus(run.status) ? memoRedactTerminalResult("run.result", run.result ?? undefined) : redactTerminalResult(run.result ?? undefined),
-                supervisorCost,
-                suggestions,
-                errorCode: stale ? RUN_HOLDER_DEATH_CODES.stalled : (persistedPlaneOf(run.result).errorCode ?? run.errorCode ?? undefined),
-                error: stale ? "run stalled (instance lost?)" : isTerminalRunStatus(run.status) ? memoRedactedRead("run.error", run.error ?? undefined, redactErrorMessage) : redactErrorMessage(run.error ?? undefined),
-                jobId: run.jobId ?? undefined,
-                source: run.source ?? undefined,
-                heldBy: run.instanceId ?? null,
-                cancelRequested: run.cancelRequested,
-            });
+            sendJson(res, 200, await readRunFace(deps, runStore, run));
         }
         return;
     }
@@ -458,8 +425,7 @@ export async function handleRuns(req, res, match, ctx) {
         const text = body.text;
         const priority = body.priority;
         const steerIdemRaw = headerStr(req.headers["idempotency-key"]);
-        const steerScoped = steerIdemRaw ? scopedIdempotencyKey(steerIdemRaw, source, principal) : undefined;
-        const steerInputId = steerScoped ? `idem-${createHash("sha256").update(steerScoped).digest("hex").slice(0, 32)}` : undefined;
+        const steerInputId = steerIdemRaw ? `idem-${idemKeyOf(steerIdemRaw, idemCallerOf(req, ctx), "run").slice(0, 32)}` : undefined;
         const messageId = steerInputId ?? uuidv7();
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         const steerInput = () => ({
@@ -774,8 +740,7 @@ export async function handleRuns(req, res, match, ctx) {
             text = interruptBody.text;
         }
         const interruptIdemRaw = headerStr(req.headers["idempotency-key"]);
-        const interruptScoped = interruptIdemRaw ? scopedIdempotencyKey(interruptIdemRaw, source, principal) : undefined;
-        const interruptInputId = interruptScoped ? `idem-${createHash("sha256").update(interruptScoped).digest("hex").slice(0, 32)}` : uuidv7();
+        const interruptInputId = interruptIdemRaw ? `idem-${idemKeyOf(interruptIdemRaw, idemCallerOf(req, ctx), "run").slice(0, 32)}` : uuidv7();
         const interruptMessageId = interruptInputId;
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
         if (!interruptBare) {
@@ -1623,7 +1588,7 @@ export async function handleRunVerbs(req, res, match, ctx) {
 }
 export async function createDurableRun(req, res, ctx, prepared, idemKey) {
     const { deps } = ctx;
-    const { idemCache, inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
+    const { idemCache } = ctx.registry;
     const { leaseDenied, usageWindowDenied } = ctx.helpers;
     const source = ctx.req.source;
     const runs = facts.durableRuns(deps);
@@ -1632,36 +1597,41 @@ export async function createDurableRun(req, res, ctx, prepared, idemKey) {
         return null;
     }
     const runStore = runs.runStore;
-    const rawClientTaskId = prepared.body.taskId;
-    if (rawClientTaskId !== undefined && (typeof rawClientTaskId !== "string" || !isUuidV7(rawClientTaskId))) {
+    const clientTaskId = clientTaskIdOf(prepared.body);
+    if (clientTaskId === false) {
         sendError(res, 400, "request.id_invalid", "body.taskId must be a uuidv7 string (caller-minted idempotency key)");
         return null;
     }
-    const clientTaskId = rawClientTaskId;
+    const submitter = gatedPrincipal(req, deps.config);
+    const caller = { principal: submitter, ...(clientTaskId !== undefined ? { clientTaskId } : {}) };
     if (clientTaskId) {
         const existing = await runStore.getRun(clientTaskId);
-        if (existing) {
-            const verified = verifiedPrincipal(req, deps.config);
-            if (existing.owner !== null && existing.owner !== verified) {
-                sendError(res, 409, "conflict.run_exists", "taskId already exists");
-                return null;
-            }
-            return { status: 202, body: { taskId: existing.taskId, sessionId: existing.sessionId, status: existing.status } };
-        }
+        if (existing)
+            return await replayOfExistingRun(existing, caller, "durable", deps, runStore);
     }
     if ((await leaseDenied(req, res)) || (await usageWindowDenied(req, res)))
         return null;
-    const resp = await idemCache.run(idemKey, async () => await mintAndDriveDurableRun({ deps, registry: ctx.registry, helpers: ctx.helpers, local: ctx.local, legs: ctx.legs }, runStore, {
-        prepared,
-        ...(clientTaskId !== undefined ? { clientTaskId } : {}),
-        fleetScope: gatedPrincipal(req, deps.config) ?? "default",
-        elicitOwner: gatedPrincipal(req, deps.config) ?? null,
-        source,
-    }), (r) => r.status === 202);
-    return resp;
+    return await idemCache.run(idemKey !== undefined ? inflightKeyOf(idemKey, "durable", clientTaskId) : undefined, async () => {
+        const out = await mintAndDriveDurableRun({ deps, registry: ctx.registry, helpers: ctx.helpers, local: ctx.local, legs: ctx.legs }, runStore, {
+            prepared,
+            ...(clientTaskId !== undefined ? { clientTaskId } : {}),
+            ...(idemKey !== undefined ? { idemKey } : {}),
+            fleetScope: submitter ?? "default",
+            elicitOwner: submitter ?? null,
+            source,
+        });
+        return out.existing ? await replayOfExistingRun(out.existing, caller, "durable", deps, runStore) : out;
+    });
+}
+function clientTaskIdOf(body) {
+    const raw = typeof body === "object" && body !== null ? body.taskId : undefined;
+    if (raw === undefined)
+        return undefined;
+    return typeof raw === "string" && isUuidV7(raw) ? raw : false;
 }
 export const RUNS_ROUTES = [
     { id: "runs-submit", path: "/v1/runs", billable: "submit", methods: ["POST"] },
+    { id: "runs-by-idem", path: "/v1/runs", methods: ["GET"] },
     { id: "run-steer", pattern: /^\/v1\/runs\/(?<taskId>[^/]+)\/steer$/, label: "/v1/runs/:id/steer", methods: ["POST"] },
     { id: "run-interrupt", pattern: /^\/v1\/runs\/(?<taskId>[^/]+)\/interrupt$/, label: "/v1/runs/:id/interrupt", methods: ["POST"] },
     { id: "run-detach", pattern: /^\/v1\/runs\/(?<taskId>[^/]+)\/detach$/, label: "/v1/runs/:id/detach", methods: ["POST"] },

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

@@ -11,6 +11,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { type SessionRulesRecord, type FileHistoryExport } from "@sema-agent/core";
 import { type StagingHandle } from "../../session-sync-kernel.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+import { type SessionRowPatch } from "../../session-row.js";
 export type PendingStaging = {
     handle: StagingHandle;
     realSessionId: string;
@@ -25,6 +26,8 @@ export type PendingStaging = {
         entryId: string;
         owner: string | null;
     }>;
+    /** 会话行的两位可写位(Phase A 体里带了哪几键就重放哪几键;老客户端不带 ⇒ `{}`,目的端两位不动)。提交后经会话店唯一写口落。 */
+    row: SessionRowPatch;
     /** 交叉复查 A-3(HIGH):Phase A's DECLARED entry-id set — Phase B verifies the streamed NDJSON matches it
      *  (a different tree under the same staging would otherwise commit while the parked snapshots/anchors
      *  still reference the DECLARED one). */

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

@@ -15,6 +15,7 @@ const SYNC_IMPORT_BATCH = 500;
 import { SHA256_HEX_RE } from "../../digest-form.js";
 import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
 import { readSessionRulesRecords, describeSessionRulesRecordProblem, legacyToolNameProblemOf } from "../../session-policy-wire.js";
+import { readSessionPinned, readSessionTitle } from "../../session-row.js";
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
@@ -74,6 +75,14 @@ export async function handleSessionSync(req, res, match, ctx) {
                 }
                 return true;
             };
+            const replaySessionRow = async (row, importedOwner) => {
+                if (Object.keys(row).length === 0)
+                    return;
+                const face = await sessionStorage.sessionFaceOf(sessionId);
+                if (face === undefined || face.owner !== importedOwner)
+                    return;
+                await sessionStorage.patchSessionMeta(sessionId, row, face);
+            };
             if (match.decl.id === "session-sync-manifest") {
                 if (!pullGateOk())
                     return;
@@ -247,6 +256,23 @@ export async function handleSessionSync(req, res, match, ctx) {
                     sendError(res, 400, "request.field_invalid", "resolution must be 'overwrite-dst'");
                     return;
                 }
+                let row = {};
+                if ("title" in body) {
+                    const read = readSessionTitle(body.title);
+                    if ("problem" in read) {
+                        sendError(res, 400, read.problem.code, read.problem.message);
+                        return;
+                    }
+                    row = { ...row, title: read.title };
+                }
+                if ("pinned" in body) {
+                    const read = readSessionPinned(body.pinned);
+                    if ("problem" in read) {
+                        sendError(res, 400, read.problem.code, read.problem.message);
+                        return;
+                    }
+                    row = { ...row, pinned: read.pinned };
+                }
                 const resolution = body.resolution;
                 const srcLogDigest = typeof body.logDigest === "string" && body.logDigest.length > 0 ? body.logDigest : undefined;
                 const entryIds = body.entryIds;
@@ -305,6 +331,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     if (deps.resumeAnchorStore)
                         for (const a of anchors)
                             await deps.resumeAnchorStore.put(sessionId, a.eventId, a.entryId, importingP);
+                    await replaySessionRow(row, owner);
                     sendJson(res, 200, {
                         relation: "identical",
                         basis: payloadVerified ? "entry-ids+digest" : "entry-ids",
@@ -368,7 +395,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                 importLeases.set(sessionId, { at: Date.now(), stagingId });
                 pendingStagings.set(stagingId, {
                     handle, realSessionId: sessionId, owner: importingPrincipal, ...(resolution ? { resolution } : {}), operatorOk,
-                    fileHistory, policy, anchors, declaredEntryIds: entryIds, openedBy: scope.gateOwner, openedFleetWide: scope.fleetWide,
+                    fileHistory, policy, anchors, row, declaredEntryIds: entryIds, openedBy: scope.gateOwner, openedFleetWide: scope.fleetWide,
                 });
                 sendJson(res, 200, { stagingId, relation: relA.relation });
                 return;
@@ -494,6 +521,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     if (anchorStore)
                         for (const a of pending.anchors)
                             await anchorStore.put(sessionId, a.eventId, a.entryId, pending.owner);
+                    await replaySessionRow(pending.row, pending.owner);
                     sessionStorage.evict?.(sessionId);
                     cleanupStaging(stagingId);
                     sendJson(res, 200, { relation: committed.relation });
@@ -540,6 +568,7 @@ function sendSessionSyncUnavailable(res, why) {
     switch (why) {
         case "store_backend_absent":
         case "session_owner_face_absent":
+        case "session_row_faces_absent":
             sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
             return;
         case "session_export_absent":

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

@@ -5,11 +5,22 @@
  * owner-scope 与 trace 列表同一权威模型(system/traceToken=fleet-wide,principal=钉住本人)。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type SessionListItem } from "../../security.js";
+import { sessionTempoOfRunStatus } from "../../plugins/store-contracts.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
  *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
  *  跨域的东西(deps / 助手 / 单域状态)一律在首行解构出来,于是下面每一行都逐字不变。 */
 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`)零投影透传 —— 店行是唯一铸点。
+ */
+export declare function projectSessionListRow(r: SessionListItem): SessionListItem & {
+    tempo?: ReturnType<typeof sessionTempoOfRunStatus>;
+};
 export declare const SESSIONS_LIST_ROUTES: readonly [{
     readonly id: "sessions-list";
     readonly path: "/v1/sessions";

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

@@ -125,12 +125,12 @@ async function handleSessionList(res, lister, query, forceOwner, includeUnowned
     const page = hasMore ? rows.slice(0, limit) : rows;
     const last = page[page.length - 1];
     const nextCursor = hasMore && last ? encodeSessionCursor({ lastActivityAt: last.lastActivityAt, sessionId: last.sessionId }, f) : undefined;
-    const sessions = page.map((r) => {
-        const tempo = sessionTempoOfRunStatus(r.lastStatus);
-        const row = r.objectivePreview === "" ? { ...r, objectivePreview: null } : r;
-        return tempo === undefined ? row : { ...row, tempo };
-    });
-    sendJson(res, 200, { sessions, ...(nextCursor ? { nextCursor } : {}) });
+    sendJson(res, 200, { sessions: page.map(projectSessionListRow), ...(nextCursor ? { nextCursor } : {}) });
+}
+export function projectSessionListRow(r) {
+    const tempo = sessionTempoOfRunStatus(r.lastStatus);
+    const row = r.objectivePreview === "" ? { ...r, objectivePreview: null } : r;
+    return tempo === undefined ? row : { ...row, tempo };
 }
 export const SESSIONS_LIST_ROUTES = [
     { id: "sessions-list", path: "/v1/sessions", methods: ["GET"] },

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

@@ -1,7 +1,7 @@
 /**
  * [ref] A9 域模块 —— 单会话面。
  *
- * 路由:`/v1/sessions/:id` 的 init / settings / mcp / head / events(SSE)/ fork / DELETE / policy / workspace,
+ * 路由:`/v1/sessions/:id` 的 init / settings / mcp / head / events(SSE)/ fork / PATCH(会话行可写位)/ DELETE / policy / workspace,
  * 外加同段的 `deps.sessionAudit` 只读审计面。
  *
  * 单域独占状态(lens1 §C2 的 12 条里的 5 条)全部收进 `SessionsLocal`,每个 server 实例一份:
@@ -115,6 +115,11 @@ export declare const SESSIONS_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/sessions/:id";
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "session-patch";
+    readonly pattern: RegExp;
+    readonly label: "/v1/sessions/:id";
+    readonly methods: readonly ["PATCH"];
 }, {
     readonly id: "session-delete";
     readonly pattern: RegExp;

package/dist/http/routes/sessions.js

@@ -1,6 +1,6 @@
 import { SessionError, materializeA2aTools, materializeMcpTools, sanitizePathComponent } from "@sema-agent/core";
 import { a2aForScenario, mcpForScenario } from "../../web-admin-client/facade.js";
-import { isUuidV7, isUuidShape, legacyUnownedSessionOk } from "../../security.js";
+import { isUuidShape, legacyUnownedSessionOk } from "../../security.js";
 import { windowMessages, truncateMessageBlobs, redactSessionViewForRead } from "../../audit.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { recordFailOpen } from "../../observability/fail-open.js";
@@ -13,6 +13,8 @@ import { gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefu
 import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { rosterAgentId } from "./agents-roster.js";
+import { projectSessionListRow } from "./sessions-list.js";
+import { readSessionRowPatch } from "../../session-row.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const A2A_STATUS_TTL_MS = 5_000;
 const A2A_MATERIALIZE_TIMEOUT_MS = 10_000;
@@ -69,7 +71,7 @@ async function readLastLegMcp(deps, sessionId, principal) {
 export async function handleSessions(req, res, match, ctx) {
     const { deps } = ctx;
     const { readJson, safeDecode, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite } = ctx.helpers;
-    const readOwnedSessionView = async (sessionAudit, sessionId) => {
+    const readOwnedSessionView = async (sessionAudit, sessionId, readOpts) => {
         const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
         if (ownerOf !== undefined) {
             const owner = await ownerOf(sessionId);
@@ -82,7 +84,7 @@ export async function handleSessions(req, res, match, ctx) {
         }
         let audit;
         try {
-            audit = await sessionAudit(sessionId);
+            audit = await sessionAudit(sessionId, readOpts);
         }
         catch (e) {
             if (ownerOf !== undefined)
@@ -596,7 +598,7 @@ export async function handleSessions(req, res, match, ctx) {
                 sendError(res, 501, "capability.session_store_required", "the session audit view requires a durable session store (DB_BACKEND=mysql|pg|local)");
                 return;
             }
-            const owned = await readOwnedSessionView(auditFact.sessionAudit, match.params.sessionId);
+            const owned = await readOwnedSessionView(auditFact.sessionAudit, match.params.sessionId, { reader: gatedPrincipal(req, deps.config) ?? null });
             if (owned === undefined)
                 return;
             if (!Array.isArray(owned.messages)) {
@@ -651,6 +653,34 @@ export async function handleSessions(req, res, match, ctx) {
             return;
         }
     }
+    if (match.decl.id === "session-patch") {
+        const rowFact = facts.sessionPatch(deps);
+        if (!rowFact.available) {
+            sendError(res, 501, "capability.session_store_required", "renaming or pinning a session requires a durable session store (DB_BACKEND=mysql|pg|local)");
+            return;
+        }
+        const store = rowFact.sessionStorage;
+        const sessionId = match.params.sessionId;
+        const face = await store.sessionFaceOf(sessionId);
+        if (face === undefined) {
+            sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            return;
+        }
+        if (!runOwnerOk(req, res, face.owner, "session"))
+            return;
+        const read = readSessionRowPatch(await readJson(req));
+        if ("problem" in read) {
+            sendError(res, 400, read.problem.code, read.problem.message);
+            return;
+        }
+        const row = await store.patchSessionMeta(sessionId, read.patch, face);
+        if (row === undefined) {
+            sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            return;
+        }
+        sendJson(res, 200, projectSessionListRow(row));
+        return;
+    }
     {
         if (match.decl.id === "session-fork") {
             const forkFact = facts.sessionFork(deps);
@@ -666,8 +696,8 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const sourceId = safeDecode(match.params.sessionId);
-            if (sourceId === null || !isUuidV7(sourceId)) {
-                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
+            if (sourceId === null || !isUuidShape(sourceId)) {
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
             const owner = await ownerOf(sourceId);
@@ -704,8 +734,8 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const sessionId = safeDecode(match.params.sessionId);
-            if (sessionId === null || !isUuidV7(sessionId)) {
-                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
+            if (sessionId === null || !isUuidShape(sessionId)) {
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
             const owner = await ownerOf(sessionId);
@@ -750,8 +780,8 @@ export async function handleSessions(req, res, match, ctx) {
                 return;
             }
             const sessionId = safeDecode(match.params.sessionId);
-            if (sessionId === null || !isUuidV7(sessionId)) {
-                sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
+            if (sessionId === null || !isUuidShape(sessionId)) {
+                sendError(res, 400, "request.id_invalid", "invalid session id (must be a canonical uuid)");
                 return;
             }
             const owner = await ownerOf(sessionId);
@@ -849,6 +879,7 @@ export const SESSIONS_ROUTES = [
     { id: "session-memory-status", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/memory-status$/, label: "/v1/sessions/:id/memory-status", methods: ["GET"] },
     { id: "session-workspace", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/workspace(?:\/(?<key>[^/]+)(?:\/(?<sub>tree|file|archive))?)?$/, label: "/v1/sessions/:id/workspace", methods: ["GET"] },
     { id: "session-detail", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["GET"] },
+    { id: "session-patch", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["PATCH"] },
     { id: "session-delete", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)$/, label: "/v1/sessions/:id", methods: ["DELETE"] },
 ];
 //# sourceMappingURL=sessions.js.map