sentinelayer-cli 0.46.4 → 0.48.0

package/src/session/standup.js

@@ -0,0 +1,192 @@
+import process from "node:process";
+import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
+import { requestJson } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { urlPathSegment } from "../net/url-path.js";
+
+const SECTIONS = [
+  ["accepted", "Accepted"],
+  ["ownerAttested", "Owner-attested (unverified)"],
+  ["reportedButUnverified", "Reported but unverified"],
+  ["inProgress", "In progress"],
+  ["open", "Open"],
+  ["blocked", "Blocked"],
+  ["inReview", "In review"],
+  ["needsOwnerDecision", "Needs an owner decision"],
+  ["unknown", "Unknown"],
+];
+const BOARD_LIMIT = 200;
+const EVIDENCE_KINDS = new Set(["pr-merged", "sha-on-branch", "check-conclusive", "deploy-sha"]);
+
+const text = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+const boolean = (value) => typeof value === "boolean" ? value : null;
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+function timestamp(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value)) return null;
+  const ms = Date.parse(value), day = Date.parse(`${value.slice(0, 10)}T00:00:00Z`);
+  if (!Number.isFinite(ms) || !Number.isFinite(day) || new Date(day).toISOString().slice(0, 10) !== value.slice(0, 10)) return null;
+  return new Date(ms).toISOString();
+}
+
+function sinceTime(since, now) {
+  if (since === undefined) return null;
+  if (since === "24h") return new Date(now - 24 * 60 * 60 * 1000).toISOString();
+  const parsed = timestamp(since);
+  if (!parsed) throw new Error("--since must be 24h or an ISO timestamp with a timezone.");
+  return parsed;
+}
+
+function evidenceClaim(claim) {
+  let reference = null;
+  if (claim.kind === "pr-merged") {
+    const pr = Number.isSafeInteger(claim.pr) ? String(claim.pr) : text(claim.pr);
+    if (pr && /^[1-9]\d*$/.test(pr)) reference = `#${pr}`;
+  } else if (claim.kind === "sha-on-branch" || claim.kind === "deploy-sha") {
+    reference = text(claim.sha)?.slice(0, 12) || null;
+  } else if (claim.kind === "check-conclusive") {
+    reference = text(claim.check);
+  }
+  reference ||= text(claim.url);
+  if (reference?.length > 80) reference = `${reference.slice(0, 79)}…`;
+  return { kind: claim.kind, reference };
+}
+
+function ticketRecord(raw) {
+  const t = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const evidence = Array.isArray(t.doneVerdict?.evidence)
+    ? t.doneVerdict.evidence.filter((claim) => claim && EVIDENCE_KINDS.has(claim.kind)).map(evidenceClaim) : [];
+  const ownerAttested = t.doneVerdict?.kind === "owner-attested" || t.completion?.source === "owner_attested";
+  return {
+    id: text(t.id), title: text(t.title), status: text(t.status),
+    assignee: text(t.assignee), acceptedBy: text(t.acceptedBy),
+    claimedAt: timestamp(t.claimedAt), createdAt: timestamp(t.createdAt), updatedAt: timestamp(t.updatedAt),
+    hasDoneVerdict: boolean(t.hasDoneVerdict), unaccepted: boolean(t.unaccepted), staleClaim: boolean(t.staleClaim),
+    lastVerdict: t.lastVerdict && typeof t.lastVerdict === "object"
+      ? { verdict: text(t.lastVerdict.verdict), checkedAt: timestamp(t.lastVerdict.checkedAt) } : null,
+    completion: t.completion && typeof t.completion === "object"
+      ? { source: text(t.completion.source), verified: boolean(t.completion.verified) } : null,
+    verdict: { kind: evidence[0]?.kind || null, reference: evidence[0]?.reference || null, evidence },
+    ownerAttestation: ownerAttested ? {
+      statement: text(t.doneVerdict?.statement), attestedBy: text(t.doneVerdict?.attestedBy),
+      attestedAt: timestamp(t.doneVerdict?.attestedAt), verified: false,
+    } : null,
+    unknown: [],
+  };
+}
+
+// Select a whole record, never graft a prior verdict onto a newer claim. When
+// timestamps cannot resolve different records, retain only their shared identity.
+function coalesce(items) {
+  const groups = new Map();
+  for (const raw of items) {
+    const item = ticketRecord(raw);
+    const key = item.id ? `id:${item.id}` : `record:${JSON.stringify(item)}`;
+    if (!groups.has(key)) groups.set(key, new Map());
+    groups.get(key).set(JSON.stringify(item), item);
+  }
+  return [...groups.values()].map((group) => {
+    const records = [...group.values()].sort((a, b) => compare(b.updatedAt || "", a.updatedAt || ""));
+    if (records.length === 1) return records[0];
+    if (records.every((t) => t.updatedAt) && records[0].updatedAt !== records[1].updatedAt) return records[0];
+    const conflict = ticketRecord({ id: records[0].id,
+      updatedAt: records.every((t) => t.updatedAt) ? records[0].updatedAt : null });
+    conflict.unknown.push("conflicting duplicate records");
+    return conflict;
+  }).sort((a, b) => compare(a.id || "", b.id || "") || compare(JSON.stringify(a), JSON.stringify(b)));
+}
+
+export function buildSessionStandup(items, { sessionId, since, now = Date.now(), truncated = false } = {}) {
+  const cutoff = sinceTime(since, now);
+  const report = { sessionId, since: cutoff, truncated: truncated === true || items.length >= BOARD_LIMIT,
+    ...Object.fromEntries(SECTIONS.map(([key]) => [key, []])) };
+  for (const item of coalesce(items)) {
+    if (cutoff && item.updatedAt && item.updatedAt < cutoff) continue;
+    for (const field of ["id", "title", "status", "updatedAt"]) {
+      if (item[field] === null) item.unknown.push(field);
+    }
+    let section = "unknown";
+    if (!item.id || item.unknown.includes("conflicting duplicate records") || (cutoff && !item.updatedAt)) {
+      // There is not enough evidence to identify or date this work.
+    } else if (item.status === "done") {
+      if (item.hasDoneVerdict === true && item.ownerAttestation) {
+        section = "ownerAttested";
+        for (const field of ["statement", "attestedBy", "attestedAt"]) {
+          if (item.ownerAttestation[field] === null) item.unknown.push(`ownerAttestation.${field}`);
+        }
+      } else {
+        section = item.hasDoneVerdict === true ? "accepted" : "reportedButUnverified";
+        if (item.hasDoneVerdict === null) item.unknown.push("hasDoneVerdict");
+        if (!item.verdict.kind) item.unknown.push("verdict.kind");
+        if (!item.verdict.evidence.length || item.verdict.evidence.some((claim) => !claim.reference)) item.unknown.push("verdict.reference");
+      }
+    } else if (item.unaccepted === true) {
+      section = "needsOwnerDecision";
+      if (!item.createdAt) item.unknown.push("createdAt");
+    } else if (["working", "in_progress"].includes(item.status)) {
+      section = "inProgress";
+      for (const field of ["assignee", "claimedAt", "staleClaim"]) {
+        if (item[field] === null) item.unknown.push(field);
+      }
+    } else if (["open", "assigned", "accepted"].includes(item.status)) {
+      section = "open";
+    } else if (item.status === "blocked") {
+      section = "blocked";
+    } else if (item.status === "in_review") {
+      section = "inReview";
+    } else {
+      item.unknown.push("classification");
+      if (item.unaccepted === null) item.unknown.push("unaccepted");
+    }
+    report[section].push(item);
+  }
+  report.needsOwnerDecision.sort((a, b) => compare(a.createdAt || "~", b.createdAt || "~") || compare(a.id, b.id));
+  return report;
+}
+
+export async function sessionStandup(sessionId, {
+  since, targetPath = process.cwd(), now = Date.now(),
+  resolveAuthSession = resolveActiveAuthSession, requestRead = requestJson,
+} = {}) {
+  const cutoff = sinceTime(since, now); // Invalid windows refuse before any request.
+  const auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false });
+  if (!isAuthenticated(auth) || !auth?.apiUrl) throw new Error("Not authenticated for this session.");
+  let body;
+  try {
+    body = await checkedTransport(requestRead)(`${auth.apiUrl.replace(/\/+$/, "")}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/tickets?limit=${BOARD_LIMIT}`, {
+      method: "GET", credential: await credentialFor(auth),
+    });
+  } catch (error) {
+    if (error?.status === 403 || error?.status === 404) {
+      throw new Error(`Standup refused (HTTP ${error.status}): this session's tickets are unavailable or you do not have permission to read them.`, { cause: error });
+    }
+    throw error;
+  }
+  if (!Array.isArray(body?.items)) throw new Error("The ticket response has no items array; refusing to invent a standup.");
+  const truncated = body.hasMore === true || Boolean(text(body.nextBeforeId) || text(body.nextCursor) || text(body.nextAfterId));
+  return buildSessionStandup(body.items, { sessionId, ...(cutoff ? { since: cutoff } : {}), now, truncated });
+}
+
+export function formatSessionStandup(report) {
+  // Keep untrusted server text on one terminal line, without directional overrides.
+  const display = (value) => String(value ?? "unknown").replace(/[\u0000-\u001f\u007f-\u009f\u2028-\u202e\u2066-\u2069]/g, " ");
+  const lines = [`Standup ${display(report.sessionId)} · since ${report.since || "all returned records"}`];
+  if (report.truncated) lines.push("Warning: ticket board is truncated; more tickets may exist beyond this page.");
+  for (const [key, heading] of SECTIONS) {
+    lines.push("", heading);
+    if (!report[key].length) lines.push("  (none)");
+    for (const item of report[key]) {
+      let detail = "";
+      if (key === "accepted") detail = item.verdict.evidence.length
+        ? ` · verdict: ${item.verdict.evidence.map((claim) => `${display(claim.kind)} ${display(claim.reference)}`).join("; ")}`
+        : ` · re-checkable verdict on record (details not in this read; checked ${display(item.lastVerdict?.checkedAt)})`;
+      if (key === "ownerAttested") detail = ` · owner statement by ${display(item.ownerAttestation.attestedBy)} (unverified): ${display(item.ownerAttestation.statement ?? "statement not in this read")}`;
+      if (key === "reportedButUnverified") detail = " · no re-checkable done verdict";
+      if (key === "inProgress") detail = ` · assignee: ${display(item.assignee)} · since: ${display(item.claimedAt)}${item.staleClaim === true ? " · STALE claim" : ""}`;
+      if (key === "needsOwnerDecision") detail = ` · created: ${display(item.createdAt)}`;
+      const missing = item.unknown.length ? ` · unknown: ${item.unknown.join(", ")}` : "";
+      lines.push(`  ${display(item.id)}  ${display(item.title)}${detail}${missing}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/session/sync.js

@@ -8,8 +8,10 @@ import { credentialedRequest, credentialFor, isAuthenticated } from "../auth/cre
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { createAgentEvent } from "../events/schema.js";
 import { isSessionControlEvent } from "./control-events.js";
-import { createSessionMutationHeaders } from "./invitations.js";
+import { createSessionMutationHeaders, throwIfPendingSessionInvitation } from "./invitations.js";
 import { messageRevision } from "./message-edits.js";
+import { appendAttachmentSummary } from "./attachment-summary.js";
+import { readAdmissionCredentialState } from "./admission.js";
 import { installTestEgressGuard } from "../net/test-egress-guard.js";
 import { isUrlPathSegment, urlPathSegment } from "../net/url-path.js";
 
@@ -660,9 +662,12 @@ async function readResponseJsonWithTimeout(
   }
 }
 
-async function readResponseJsonSafely(response, timeoutMs = DEFAULT_SYNC_TIMEOUT_MS) {
+async function readResponseJsonSafely(response, timeoutMs = DEFAULT_SYNC_TIMEOUT_MS, controller = null) {
   try {
-    return await readResponseJsonWithTimeout(response, timeoutMs, { fallback: null });
+    return await readResponseJsonWithTimeout(response, timeoutMs, {
+      fallback: null,
+      onTimeout: () => abortRequestController(controller, "response_body_timeout"),
+    });
   } catch {
     return null;
   }
@@ -701,6 +706,7 @@ export async function fetchJsonWithFullTimeout(
     },
   );
 
+  const sessionRequest = new URL(url).pathname.startsWith("/api/v1/sessions/");
   let payload = {};
   if ((response?.ok && readSuccessBody) || readErrorBody || errorBodyStatuses.includes(response?.status)) {
     const elapsedMs = Math.max(0, Date.now() - startedAtMs);
@@ -709,9 +715,15 @@ export async function fetchJsonWithFullTimeout(
       fallback: {},
       onTimeout: () => abortRequestController(controller, "response_body_timeout"),
     });
+  } else if (sessionRequest && (response?.status === 403 || response?.status === 404)) {
+    // Older callers discard refusal bodies. Inspect only the invitation signal,
+    // within the request deadline; unreadable bodies keep the existing refusal.
+    const remainingMs = Math.max(1, resolvedTimeoutMs - (Date.now() - startedAtMs));
+    payload = await readResponseJsonSafely(response, remainingMs, controller);
   } else {
     cancelResponseBody(response);
   }
+  if (sessionRequest) throwIfPendingSessionInvitation(payload, response?.status);
   return { response, payload };
 }
 
@@ -957,6 +969,8 @@ export async function syncSessionEventToApi(
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetchWithTimeout,
     nowMs = Date.now,
+    noAutoGrant = false,
+    readCredential = readAdmissionCredentialState,
   } = {}
 ) {
   const normalizedSessionId = normalizeString(sessionId);
@@ -1069,6 +1083,31 @@ export async function syncSessionEventToApi(
           return { synced: false, reason: "api_403" };
         }
         const agentId = normalizeString(event?.agent?.id);
+        if (noAutoGrant) {
+          return { synced: false, reason: "api_403" };
+        }
+        // Check the stored admission credential: a keeper that joined with
+        // --no-auto-grant persists the preference.
+        if (!noAutoGrant && agentId) {
+          try {
+            const cred = await readCredential(normalizedSessionId, agentId);
+            // A present-but-unreadable or corrupt credential (state "refused")
+            // means the preference cannot be determined; fail closed rather than
+            // silently treating it as "no preference" and auto-granting.
+            if (cred?.state === "refused") {
+              return { synced: false, reason: "api_403" };
+            }
+            if (cred?.credential?.noAutoGrant) {
+              return { synced: false, reason: "api_403" };
+            }
+          } catch (error) {
+            // Only a missing file means no preference. Any other read error
+            // (permissions, corruption, transient I/O) must fail closed: a
+            // 403 must NOT auto-grant because the preference is unreadable.
+            if (!error || error.code !== "ENOENT") throw error;
+            // credential file absent — no preference to apply
+          }
+        }
         if (!agentId || isReservedAgentIdForGrant(agentId)) {
           // Reserved or empty — server enforcement is intentional, no grant
           // attempt is meaningful. Treat as a normal 403 failure.
@@ -1104,6 +1143,7 @@ export async function syncSessionEventToApi(
             remainingMs(), fetchImpl, { readSuccessBody: false },
           ));
         } catch (grantError) {
+          if (grantError?.code === "INVITATION_PENDING") throw grantError;
           recordCircuitFailure(outboundCircuit, normalizedNowMs);
           return {
             synced: false,
@@ -1130,6 +1170,7 @@ export async function syncSessionEventToApi(
             endpoint, requestInit, remainingMs(), fetchImpl, { readSuccessBody: false },
           ));
         } catch (retryError) {
+          if (retryError?.code === "INVITATION_PENDING") throw retryError;
           recordCircuitFailure(outboundCircuit, normalizedNowMs);
           return {
             synced: false,
@@ -1158,6 +1199,7 @@ export async function syncSessionEventToApi(
       reason: `api_${response ? response.status : "no_response"}`,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       synced: false,
@@ -1254,6 +1296,7 @@ async function syncSessionAuxPayload(
       status: response.status,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       synced: false,
@@ -1284,6 +1327,63 @@ export async function syncSessionErrorToApi(sessionId, error, options = {}) {
   return syncSessionAuxPayload(sessionId, "/errors", { error }, options);
 }
 
+/**
+ * POST a validated judge-verdict document to the room's judge-verdicts route. The body is the
+ * document only: the server decides who judged from the credential. Never throws; returns
+ * `{ ok, status, code, body, reason }` so the caller can tell "route not here" (404 without a
+ * room or target code) from a refusal it must report.
+ */
+export async function postJudgeVerdictToApi(
+  sessionId,
+  verdict,
+  {
+    targetPath = process.cwd(),
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!isUrlPathSegment(normalizedSessionId) || !verdict || typeof verdict !== "object" || Array.isArray(verdict)) {
+    return { ok: false, status: 0, code: "", body: null, reason: "invalid_input" };
+  }
+  if (String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1") {
+    return { ok: false, status: 0, code: "", body: null, reason: "remote_sync_disabled_env" };
+  }
+  let session = null;
+  try {
+    session = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false });
+  } catch {
+    return { ok: false, status: 0, code: "", body: null, reason: "no_session" };
+  }
+  if (!isAuthenticated(session)) {
+    return { ok: false, status: 0, code: "", body: null, reason: "not_authenticated" };
+  }
+  const endpoint = `${resolveApiBaseUrl(session)}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/judge-verdicts`;
+  try {
+    const { response, payload } = await fetchJsonWithFullTimeout(
+      endpoint,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        credential: await credentialFor(session),
+        body: JSON.stringify(verdict),
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
+      { readErrorBody: true },
+    );
+    const status = response ? response.status : 0;
+    const body = payload && typeof payload === "object" ? payload : null;
+    const code = normalizeString(body?.detail?.error?.code || body?.error?.code || body?.code);
+    if (response?.ok) return { ok: true, status, code: "", body, reason: "" };
+    return { ok: false, status, code, body, reason: `api_${status || "no_response"}` };
+  } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
+    return { ok: false, status: 0, code: "", body: null, reason: normalizeString(error?.message) || "request_failed" };
+  }
+}
+
 /**
  * Poll human messages for a session from sentinelayer-api and map them into
  * canonical high-priority session events for local relay.
@@ -1417,6 +1517,7 @@ export async function pollHumanMessages(
       dropped,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -1603,6 +1704,7 @@ export async function pollSessionEvents(
       scanExhausted: typeof rawScanExhausted === "boolean" ? rawScanExhausted : null,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -1745,6 +1847,7 @@ export async function fetchSessionPresence(
       present,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -1771,6 +1874,7 @@ export async function renewSessionPresence(
     displayName = "",
     provider = "",
     clientKind = "cli",
+    minimalPresence = false,
     observedAt = new Date().toISOString(),
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
     signal = undefined,
@@ -1854,11 +1958,12 @@ export async function renewSessionPresence(
           "Content-Type": "application/json",
         },
         credential: await credentialFor(session),
-        body: JSON.stringify(body),
+        body: JSON.stringify(minimalPresence ? { agentId: body.agentId, model: body.model } : body),
         signal,
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
+      { errorBodyStatuses: [403] },
     );
     if (!response?.ok) {
       if (response?.status === 404) {
@@ -1882,6 +1987,7 @@ export async function renewSessionPresence(
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
+        code: normalizeString(payload?.error?.code || payload?.code || payload?.detail?.code).toUpperCase(),
         status: "degraded",
         recorded: false,
         retryAfterMs: retryAfterMsFromResponse(response, payload, normalizedNowMs),
@@ -1897,6 +2003,7 @@ export async function renewSessionPresence(
       ttlSeconds: normalizePositiveInteger(payload?.ttlSeconds || payload?.ttl_seconds, null),
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2017,6 +2124,7 @@ export async function requestSessionListenerStop(
       control,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2139,6 +2247,7 @@ export async function updateSessionReadCursor(
       ),
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2230,6 +2339,7 @@ export async function streamSessionEvents(
   const controller = new AbortController();
   const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
   const normalizedIdleTimeoutMs = normalizePositiveInteger(idleTimeoutMs, 0);
+  const deadlineMs = Date.now() + normalizedTimeoutMs;
   const timeoutHandle = setTimeout(() => controller.abort(), normalizedTimeoutMs);
   if (typeof timeoutHandle.unref === "function") {
     timeoutHandle.unref();
@@ -2321,6 +2431,11 @@ export async function streamSessionEvents(
 
   try {
     if (!response || !response.ok || !response.body) {
+      if (response?.status === 403 || response?.status === 404) {
+        const remainingMs = Math.max(1, deadlineMs - Date.now());
+        const payload = await readResponseJsonSafely(response, remainingMs, controller);
+        throwIfPendingSessionInvitation(payload, response.status);
+      }
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2347,6 +2462,7 @@ export async function streamSessionEvents(
       await processSseBlock(buffer, handlers);
     }
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     return {
       ok: false,
       reason: idleTimedOut
@@ -2495,8 +2611,13 @@ export async function pollSessionEventsBefore(
       events,
       cursor: normalizeString(lastEvent?.cursor) || null,
       beforeSequence: nextBeforeSequenceFromPayload(payload, payload?.events || []),
+      hasMore: typeof payload?.has_more === "boolean" ? payload.has_more : null,
+      partial: typeof payload?.partial === "boolean" ? payload.partial : null,
+      rawEvents: payload?.events,
+      rawNextBeforeSequence: payload?.next_before_sequence ?? null,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2607,6 +2728,7 @@ export async function listSessionMessageActions(
         : null,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2698,6 +2820,7 @@ export async function fetchSessionUsageLedger(
       payload: payload && typeof payload === "object" ? payload : {},
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -2807,7 +2930,10 @@ export async function fetchSessionPinnedMessages(
           null;
         if (match) {
           base.author = pinnedEventAuthorId(match);
-          base.content = pinnedEventContentText(match);
+          base.content = appendAttachmentSummary(pinnedEventContentText(match), { sessionId: normalizedSessionId, ...match });
+          if (Array.isArray(match.payload?.attachments) && match.payload.attachments.length) {
+            base.attachments = match.payload.attachments;
+          }
           base.resolved = true;
         }
       }
@@ -2825,6 +2951,92 @@ export async function fetchSessionPinnedMessages(
   };
 }
 
+// An attachment id as the API accepts it in a path.
+const SESSION_ATTACHMENT_ID_PATTERN = /^[A-Za-z0-9._:-]{8,120}$/;
+
+/**
+ * Read one room attachment's metadata and a short-lived signed download link:
+ * `GET /api/v1/sessions/{id}/attachments/{attachmentId}?download=true`, which answers
+ * `{ ok, attachment, download: { url, method, expiresIn, expiresAt } }`. The link points at the
+ * file store and carries its own signature; fetch it without API credentials. Someone other
+ * than the uploader gets 404 for a file no sent message has published yet.
+ *
+ * Never throws; a refusal reports the HTTP status and the API error code.
+ */
+export async function fetchSessionAttachment(
+  sessionId,
+  attachmentId,
+  {
+    targetPath = process.cwd(),
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAttachmentId = normalizeString(attachmentId);
+  if (!isUrlPathSegment(normalizedSessionId)) {
+    return { ok: false, reason: "invalid_session_id", status: null };
+  }
+  if (!SESSION_ATTACHMENT_ID_PATTERN.test(normalizedAttachmentId) || normalizedAttachmentId.includes("..")) {
+    return { ok: false, reason: "invalid_attachment_id", status: null };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { ok: false, reason: "no_session", status: null };
+  }
+  if (!isAuthenticated(session)) {
+    return { ok: false, reason: "not_authenticated", status: null };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const endpoint =
+    `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}` +
+    `/attachments/${urlPathSegment(normalizedAttachmentId, { label: "attachmentId" })}?download=true`;
+  try {
+    const { response, payload } = await fetchJsonWithFullTimeout(
+      endpoint,
+      {
+        method: "GET",
+        credential: await credentialFor(session),
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
+      { readErrorBody: true },
+    );
+    if (!response || !response.ok) {
+      const status = response ? response.status : null;
+      return {
+        ok: false,
+        reason: `api_${status ?? "no_response"}`,
+        status,
+        errorCode: normalizeString(payload?.error?.code) || null,
+        retryAfterMs: isRateLimitResponse(response, payload)
+          ? retryAfterMsFromResponse(response, payload, Number(nowMs()) || Date.now())
+          : null,
+      };
+    }
+    return {
+      ok: true,
+      reason: "",
+      status: response.status,
+      attachment: payload?.attachment && typeof payload.attachment === "object" ? payload.attachment : null,
+      download: payload?.download && typeof payload.download === "object" ? payload.download : null,
+    };
+  } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
+    return { ok: false, reason: normalizeString(error?.message) || "attachment_read_failed", status: null };
+  }
+}
+
 // Native edits never fall back to POST /events or mutate an optimistic local row.
 export async function editSessionMessage(sessionId, {
   targetSequenceId = null,
@@ -2912,6 +3124,7 @@ export async function editSessionMessage(sessionId, {
     recordCircuitSuccess(outboundCircuit);
     return { ok: true, changed: Boolean(payload.changed), replayed: Boolean(payload.replayed), event: payload.event || null, reply: payload.reply || null, notification: payload.notification || null };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, timestamp);
     return { ok: false, reason: normalizeString(error?.message) || "message_edit_failed" };
   }
@@ -3063,6 +3276,7 @@ export async function createSessionMessageAction(
       action: payload?.action && typeof payload.action === "object" ? payload.action : null,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -3189,6 +3403,7 @@ export async function searchSessionEvents(
       nextBeforeSequence: Number(payload?.next_before_sequence ?? payload?.nextBeforeSequence) || null,
     };
   } catch (error) {
+    if (error?.code === "INVITATION_PENDING") throw error;
     recordCircuitFailure(inboundCircuit, normalizedNowMs);
     return {
       ok: false,
@@ -3294,6 +3509,7 @@ export async function listSessionsFromApi({
         fetchImpl,
       ));
     } catch (err) {
+      if (err?.code === "INVITATION_PENDING") throw err;
       return {
         ok: false,
         reason: normalizeString(err?.message) || "list_failed",
@@ -3414,6 +3630,7 @@ export async function fetchSessionFromApi(
       fetchImpl,
     ));
   } catch (err) {
+    if (err?.code === "INVITATION_PENDING") throw err;
     return {
       ok: false,
       reason: normalizeString(err?.message) || "fetch_failed",
@@ -3482,13 +3699,15 @@ export async function probeSessionAccess(
 
   let response;
   try {
-    response = await credentialedRequest(
-      await credentialFor(session),
+    ({ response } = await fetchJsonWithFullTimeout(
       endpoint,
-      { method: "GET" },
-      { fetchImpl: (target, init) => fetchImpl(target, init, normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)) },
-    );
+      { method: "GET", credential: await credentialFor(session) },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
+      { readSuccessBody: false },
+    ));
   } catch (err) {
+    if (err?.code === "INVITATION_PENDING") throw err;
     return {
       accessible: false,
       reason: normalizeString(err?.message) || "probe_failed",