sentinelayer-cli 0.44.0 → 0.46.0

package/src/session/admission-auth.js

@@ -25,7 +25,12 @@ import path from "node:path";
 import process from "node:process";
 
 import { admittedAgentScope } from "../auth/admission-scope.js";
-import { readAdmissionCredentialState } from "./admission.js";
+import {
+  hasStoredAdmissionCredentials,
+  readAdmissionCredentialState,
+  storedAdmissionAgentsForSession,
+} from "./admission.js";
+import { sessionRouteClass } from "./route-classes.js";
 
 export class AdmissionCredentialRefused extends Error {
   constructor(message, { reason, sessionId, agentId } = {}) {
@@ -238,26 +243,89 @@ export async function resolveAgentAdmissionTarget(args = [], { env = process.env
   return null;
 }
 
-/**
- * preAction guard: the identity Commander ACTUALLY resolved for this action must be
- * the one whose admission scope (if any) the dispatch was wrapped in. Computed from
- * Commander's own resolved options -- counting only values given on the command line,
- * not defaults such as read's `--agent cli-user` -- so no argv reading of ours can
- * disagree with execution. A mismatch refuses before the action runs.
- */
-export async function assertDispatchMatchesScope(actionCommand, { env = process.env, homeDir } = {}) {
+// What Commander parsed for the action about to run: its `session` command path, its
+// options (and which of them were given on the command line, not defaulted, such as read's
+// `--agent cli-user`), and its operands. The preAction guard reads only these, the same values
+// the action itself uses, so no reading of the raw argv can disagree with execution.
+function parsedSessionAction(actionCommand) {
   const names = [];
   for (let cmd = actionCommand; cmd && cmd.parent; cmd = cmd.parent) names.unshift(cmd.name());
-  if (String(names[0] || "").toLowerCase() !== "session") return;
-  const command = names.slice(1).join(" ").toLowerCase();
-  const principal = SESSION_AGENT_PRINCIPAL[command];
+  if (String(names[0] || "").toLowerCase() !== "session") return null;
   const opts = actionCommand.opts();
   const given = (key) =>
     actionCommand.getOptionValueSource?.(key) === "cli" ? String(opts[key] ?? "").trim() : "";
+  const processed = Array.isArray(actionCommand.processedArgs) ? actionCommand.processedArgs : [];
+  return {
+    route: `cli:${names.join(" ").toLowerCase()}`,
+    command: names.slice(1).join(" ").toLowerCase(),
+    opts,
+    given,
+    first: String(processed[0] ?? "").trim(),
+    operands: processed.flat().map((value) => String(value ?? "").trim()).filter(Boolean),
+  };
+}
+
+// Through the MCP CLI bridge (which marks its child processes with SENTINELAYER_MCP_BRIDGE=1)
+// in an agent context (SENTINELAYER_AGENT_ID is set, or this machine stores any agent
+// admission), by the command's class in SESSION_ROUTE_CLASSES:
+//   - exempt-local: runs as before
+//   - owner: refused
+//   - a session the command will use (its --session or --id value, given or defaulted, or any
+//     operand) stores an admission, in any state: the action must be running in that
+//     session's admission scope, or it is refused before it runs
+//   - no session it uses stores one: legacy-data-plane runs as before; control and
+//     unclassified commands are refused
+async function assertBridgedRoute(action, { env, homeDir }) {
+  if (env.SENTINELAYER_MCP_BRIDGE !== "1") return;
+  const agentContext =
+    Boolean(String(env.SENTINELAYER_AGENT_ID || "").trim()) || (await hasStoredAdmissionCredentials({ homeDir }));
+  if (!agentContext) return;
+  const routeClass = sessionRouteClass(action.route);
+  const refuse = (why) => {
+    throw new AdmissionCredentialRefused(
+      `\`sl ${action.route.slice("cli:".length)}\` runs for an agent here and needs an admission it can bind to: ` +
+        `${why}. It will not fall back to other credentials.`,
+      { reason: "bridged_route_refused" },
+    );
+  };
+  if (routeClass === "exempt-local") return;
+  if (routeClass === "owner") refuse("owner actions are not available to agents");
+  const named = [action.opts.session, action.opts.id, ...action.operands]
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean);
+  const admitted = [];
+  for (const sessionId of named) {
+    if ((await storedAdmissionAgentsForSession(sessionId, { homeDir })).length > 0) admitted.push(sessionId);
+  }
+  if (admitted.length > 0) {
+    const bound = String(currentAdmittedAgent()?.sessionId || "").toLowerCase();
+    if (!bound || !admitted.some((sid) => sid.toLowerCase() === bound)) {
+      refuse(`session ${admitted[0]} stores an admission and this command's agent is not bound to it`);
+    }
+    return;
+  }
+  if (routeClass === "legacy-data-plane") return;
+  refuse(routeClass === "control" ? "it is a control operation" : "it is not classified for agents");
+}
+
+/**
+ * preAction guard, run before ANY action, on Commander's parsed values only:
+ *   1. a bridged command in an agent context binds to its session's admission, runs as a
+ *      legacy data-plane route, or is refused (assertBridgedRoute above);
+ *   2. the identity Commander resolved for the action must be the one whose admission scope
+ *      (if any) the dispatch was wrapped in.
+ * Either refusal happens before the action runs, so before any request.
+ */
+export async function assertDispatchMatchesScope(actionCommand, { env = process.env, homeDir } = {}) {
+  const action = parsedSessionAction(actionCommand);
+  if (!action) return;
+  await assertBridgedRoute(action, { env, homeDir });
+  const { command, given } = action;
+  const principal = SESSION_AGENT_PRINCIPAL[command];
   let actual = null;
   if (principal === "actor" || (!principal && given("agent"))) {
-    const sessionId = given("session") || given("id") || String(actionCommand.processedArgs?.[0] ?? "").trim();
-    const targetPath = path.resolve(process.cwd(), String(opts.path || "."));
+    const sessionId = given("session") || given("id") || action.first;
+    const targetPath = path.resolve(process.cwd(), String(action.opts.path || "."));
     const agentId =
       given("agent") ||
       String(env.SENTINELAYER_AGENT_ID || "").trim() ||
@@ -279,9 +347,20 @@ export async function assertDispatchMatchesScope(actionCommand, { env = process.
 }
 
 /** Run `fn` with the right credential for (sessionId, agentId). See the module header. */
-export async function withAgentAdmission(sessionId, agentId, fn, { homeDir, now } = {}) {
+export async function withAgentAdmission(sessionId, agentId, fn, { homeDir, now, requireStored = false } = {}) {
   const held = await readAdmissionCredentialState(sessionId, agentId, { homeDir, now });
-  if (held.state === "none") return fn({ admitted: false });
+  if (held.state === "none") {
+    // A caller that already decided this must bind (it saw a stored admission) never runs
+    // without one: a credential file that vanished in between is a refusal, not absence.
+    if (requireStored) {
+      throw new AdmissionCredentialRefused(
+        `Agent "${agentId}"'s stored admission for session ${sessionId} is no longer present. ` +
+          `It will not fall back to your own credentials.`,
+        { reason: "admission_removed", sessionId, agentId },
+      );
+    }
+    return fn({ admitted: false });
+  }
   if (held.state !== "live") {
     const why = REFUSAL_HINT[held.reason] || `its stored admission is unusable (${held.reason})`;
     throw new AdmissionCredentialRefused(

package/src/session/admission.js

@@ -30,6 +30,7 @@ import path from "node:path";
 import process from "node:process";
 import { setTimeout as sleepMs } from "node:timers/promises";
 
+import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { canonicalize } from "../engram/canonical.js";
@@ -271,6 +272,39 @@ export async function hasStoredAdmissionCredentials({ homeDir } = {}) {
   return false;
 }
 
+/**
+ * The agents for which this machine stores an admission credential file for this
+ * session, usable or not (`<home>/.sentinelayer/agents/<agent>/admissions/<session>.json`).
+ * An unreadable agents directory is reported as a stored entry, never as absence.
+ */
+export async function storedAdmissionAgentsForSession(sessionId, { homeDir } = {}) {
+  let sessionFile;
+  try {
+    sessionFile = `${safeSegment(sessionId, "sessionId")}.json`;
+  } catch {
+    return []; // not a storable session id, so nothing can be stored for it
+  }
+  const agentsDir = path.join(sentinelayerHome(homeDir), "agents");
+  let agents;
+  try {
+    agents = await fsp.readdir(agentsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return [];
+    return ["(unreadable)"];
+  }
+  const found = [];
+  for (const agent of agents) {
+    if (!agent.isDirectory()) continue;
+    try {
+      await fsp.access(path.join(agentsDir, agent.name, "admissions", sessionFile));
+      found.push(agent.name.replace(/%3a/g, ":"));
+    } catch (error) {
+      if (!(error && error.code === "ENOENT")) found.push(agent.name.replace(/%3a/g, ":"));
+    }
+  }
+  return found;
+}
+
 /**
  * What this machine holds for (session, agent):
  *   { state: "none" }                        -- never admitted here: the legacy path applies
@@ -333,10 +367,10 @@ function requestFingerprint({ apiUrl, agentId, publicKey, goal, actions, ttlSeco
 
 async function authContext({ targetPath, resolveAuthSession }) {
   const auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false });
-  if (!auth?.token || !auth?.apiUrl) {
+  if (!isAuthenticated(auth) || !auth?.apiUrl) {
     throw new Error("Not authenticated. Run `sl auth login` first.");
   }
-  return { token: auth.token, apiUrl: normalizeString(auth.apiUrl).replace(/\/+$/, "") };
+  return { credential: await credentialFor(auth), apiUrl: normalizeString(auth.apiUrl).replace(/\/+$/, "") };
 }
 
 function admissionUrl(apiUrl, sessionId, suffix = "") {
@@ -345,12 +379,13 @@ function admissionUrl(apiUrl, sessionId, suffix = "") {
 
 async function mutate(auth, sessionId, routeId, url, body, { requestMutation, operationName, origin }) {
   const idempotencyKey = createSessionMutationIdempotencyKey(operationName);
-  return requestMutation(url, {
+  return checkedTransport(requestMutation)(url, {
     method: "POST",
     operationName,
     idempotencyKey,
+    credential: auth.credential,
     headers: createSessionMutationHeaders({
-      bearerToken: auth.token,
+      credential: auth.credential,
       sessionId,
       routeId,
       idempotencyKey,
@@ -495,9 +530,9 @@ export async function runAdmissionJoin(
   const deadline = now() + Math.max(0, waitTimeoutMs);
   let polled;
   for (;;) {
-    polled = await requestRead(admissionUrl(auth.apiUrl, sid, `/${encodeURIComponent(state.admissionId)}`), {
+    polled = await checkedTransport(requestRead)(admissionUrl(auth.apiUrl, sid, `/${encodeURIComponent(state.admissionId)}`), {
       method: "GET",
-      headers: { Authorization: `Bearer ${auth.token}` },
+      credential: auth.credential,
     });
     state.status = polled.status;
     // Identity readiness is a server capability: a server that gates the claim on
@@ -635,13 +670,13 @@ export async function fetchOwnAdmissionReceipt(
 ) {
   const sid = normalizeString(sessionId);
   const auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false });
-  if (!auth?.token || auth.source !== "session_admission") {
+  if (!isAuthenticated(auth) || auth.source !== "session_admission") {
     throw new Error("The admission receipt must be fetched with the admission credential.");
   }
   const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
-  return requestRead(admissionUrl(apiUrl, sid, "/self"), {
+  return checkedTransport(requestRead)(admissionUrl(apiUrl, sid, "/self"), {
     method: "GET",
-    headers: { Authorization: `Bearer ${auth.token}` },
+    credential: await credentialFor(auth),
   });
 }
 

package/src/session/checkpoints.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import process from "node:process";
 
+import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { pollSessionEventsBefore } from "./sync.js";
@@ -419,12 +420,12 @@ async function resolveCheckpointApi({
     env: process.env,
     autoRotate: false,
   });
-  if (!auth || !auth.token) {
+  if (!isAuthenticated(auth)) {
     throw new Error("Sentinelayer auth is required. Run `sl auth login` first.");
   }
   return {
     apiUrl: normalizeApiUrl(auth.apiUrl),
-    headers: { Authorization: `Bearer ${auth.token}` },
+    credential: await credentialFor(auth),
   };
 }
 
@@ -438,11 +439,11 @@ export async function listSessionCheckpoints(sessionId, {
   if (!normalizedSessionId) {
     throw new Error("session id is required.");
   }
-  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const { apiUrl, credential } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
   const params = new URLSearchParams({ limit: String(normalizeLimit(limit)) });
   const response = await request(
     `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints?${params.toString()}`,
-    { method: "GET", headers },
+    { method: "GET", credential },
   );
   const checkpoints = Array.isArray(response?.checkpoints) ? response.checkpoints : [];
   return {
@@ -519,12 +520,12 @@ export async function createSessionCheckpoint(sessionId, options = {}) {
     requestMutation = requestJsonMutation,
   } = options;
   const { body, idempotencyKey } = buildManualCheckpointPayload(normalizedSessionId, options);
-  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
-  const response = await requestMutation(
+  const { apiUrl, credential } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await checkedTransport(requestMutation)(
     `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints`,
     {
       operationName: "session-checkpoint-create",
-      headers,
+      credential,
       body,
       idempotencyKey,
     },
@@ -546,12 +547,12 @@ export async function generateSessionCheckpoint(sessionId, options = {}) {
     requestMutation = requestJsonMutation,
   } = options;
   const { body, idempotencyKey } = buildGenerateCheckpointPayload(normalizedSessionId, options);
-  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
-  const response = await requestMutation(
+  const { apiUrl, credential } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await checkedTransport(requestMutation)(
     `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints/generate`,
     {
       operationName: "session-checkpoint-generate",
-      headers,
+      credential,
       body,
       idempotencyKey,
     },

package/src/session/file-locks.js

@@ -9,6 +9,7 @@ import {
   requestJson,
   requestJsonMutation,
 } from "../auth/http.js";
+import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { resolveSessionPaths } from "./paths.js";
 
@@ -477,14 +478,14 @@ async function resolveLeaseApi({
     env: process.env,
     autoRotate: false,
   });
-  if (!auth?.token || !auth?.apiUrl) {
+  if (!isAuthenticated(auth) || !auth?.apiUrl) {
     throw new Error(
       "Authoritative session file leases require Sentinelayer auth. Run `sl auth login` first.",
     );
   }
   return {
     apiUrl: normalizeApiUrl(auth.apiUrl),
-    headers: { Authorization: `Bearer ${auth.token}` },
+    credential: await credentialFor(auth),
   };
 }
 
@@ -505,10 +506,10 @@ async function listRemoteLeases(
   } = {},
 ) {
   const normalizedSessionId = normalizeSessionId(sessionId);
-  const { apiUrl, headers } = await resolveLeaseApi({ targetPath, resolveAuthSession });
+  const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
   const response = await request(leaseCollectionUrl(apiUrl, normalizedSessionId), {
     method: "GET",
-    headers,
+    credential,
   });
   if (response?.authoritative !== true || !Array.isArray(response?.leases)) {
     throw new Error("File-lease authority returned an invalid list response; refusing local fallback.");
@@ -529,13 +530,13 @@ async function guardRemoteClaims(
 ) {
   const normalizedSessionId = normalizeSessionId(sessionId);
   const normalizedHolderId = normalizeAgentId(holderId);
-  const { apiUrl, headers } = await resolveLeaseApi({ targetPath, resolveAuthSession });
-  const response = await requestMutation(
+  const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
+  const response = await checkedTransport(requestMutation)(
     `${leaseCollectionUrl(apiUrl, normalizedSessionId)}/guard`,
     {
       method: "POST",
       operationName: "session-file-lease-guard",
-      headers,
+      credential,
       body: {
         holderId: normalizedHolderId,
         claims: paths.map((file, index) => ({
@@ -712,15 +713,15 @@ export async function lockFile(
   }
 
   const leaseToken = exactClaim?.leaseToken || newCapabilityToken();
-  const { apiUrl, headers } = await resolveLeaseApi({ targetPath, resolveAuthSession });
+  const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
   let response;
   try {
-    response = await requestMutation(
+    response = await checkedTransport(requestMutation)(
       leaseCollectionUrl(apiUrl, normalizedSessionId),
       {
         method: "POST",
         operationName: "session-file-lease-acquire",
-        headers,
+        credential,
         body: {
           path: normalizedFilePath,
           holderId: normalizedAgentId,
@@ -792,12 +793,12 @@ export async function lockFile(
   } catch (cacheError) {
     let compensated = false;
     try {
-      const release = await requestMutation(
+      const release = await checkedTransport(requestMutation)(
         leaseMemberUrl(apiUrl, normalizedSessionId, lease.leaseId, "release"),
         {
           method: "POST",
           operationName: "session-file-lease-acquire-compensation",
-          headers,
+          credential,
           body: {
             holderId: normalizedAgentId,
             leaseToken,
@@ -845,15 +846,15 @@ async function releaseCapabilityClaim(
     requestMutation,
   },
 ) {
-  const { apiUrl, headers } = await resolveLeaseApi({ targetPath, resolveAuthSession });
+  const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
   let response;
   try {
-    response = await requestMutation(
+    response = await checkedTransport(requestMutation)(
       leaseMemberUrl(apiUrl, sessionId, claim.leaseId, "release"),
       {
         method: "POST",
         operationName: "session-file-lease-release",
-        headers,
+        credential,
         body: {
           holderId: agentId,
           leaseToken: claim.leaseToken,
@@ -1007,13 +1008,13 @@ export async function renewFileLease(
     };
   }
 
-  const { apiUrl, headers } = await resolveLeaseApi({ targetPath, resolveAuthSession });
-  const response = await requestMutation(
+  const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
+  const response = await checkedTransport(requestMutation)(
     leaseMemberUrl(apiUrl, normalizedSessionId, claim.leaseId, "renew"),
     {
       method: "POST",
       operationName: "session-file-lease-renew",
-      headers,
+      credential,
       body: {
         holderId: normalizedAgentId,
         leaseToken: claim.leaseToken,

package/src/session/invitations.js

@@ -3,6 +3,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
+import { checkedTransport, credentialFor, credentialHmac, isAuthenticated, isCredential } from "../auth/credential-destinations.js";
 import { requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { renderCoordinationBulletList } from "./coordination-guidance.js";
@@ -30,6 +31,16 @@ export function canonicalSessionRef(value) {
   return raw.toLowerCase();
 }
 
+function sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey } = {}) {
+  return [
+    "session-mutation-csrf:v1",
+    canonicalSessionRef(sessionId),
+    normalizeString(routeId),
+    normalizeString(idempotencyKey),
+  ].join("\0");
+}
+
+// The API's CSRF proof for a given bearer: what the server (or a test fixture) checks against.
 export function createSessionMutationCsrfToken({
   bearerToken,
   sessionId,
@@ -38,35 +49,29 @@ export function createSessionMutationCsrfToken({
 } = {}) {
   const secret = normalizeString(bearerToken);
   if (!secret) return "";
-  const message = [
-    "session-mutation-csrf:v1",
-    canonicalSessionRef(sessionId),
-    normalizeString(routeId),
-    normalizeString(idempotencyKey),
-  ].join("\0");
-  return createHmac("sha256", secret).update(message, "utf-8").digest("hex");
+  return createHmac("sha256", secret)
+    .update(sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey }), "utf-8")
+    .digest("hex");
 }
 
+// The session-mutation headers: origin and a CSRF proof derived from the credential the request
+// is sent with. The credential itself is attached by credentialedRequest, never here.
 export function createSessionMutationHeaders({
-  bearerToken,
+  credential,
   sessionId,
   routeId,
   idempotencyKey,
   origin = SESSION_MUTATION_ORIGIN,
 } = {}) {
-  const token = normalizeString(bearerToken);
   const normalizedOrigin = normalizeString(origin) || SESSION_MUTATION_ORIGIN;
   return {
-    Authorization: `Bearer ${token}`,
     Origin: normalizedOrigin,
     "Sec-Fetch-Site": "same-site",
     "X-Sentinelayer-Session-Mutation": "session-mutation",
-    "X-CSRF-Token": createSessionMutationCsrfToken({
-      bearerToken: token,
-      sessionId,
-      routeId,
-      idempotencyKey,
-    }),
+    // keyed inside src/auth/credential-destinations.js; the token never leaves it
+    "X-CSRF-Token": isCredential(credential)
+      ? credentialHmac(credential, sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey }))
+      : "",
   };
 }
 
@@ -106,10 +111,11 @@ export async function acceptSessionInvitation(
     env: process.env,
     autoRotate: false,
   });
-  if (!auth?.token || !auth?.apiUrl) {
+  if (!isAuthenticated(auth) || !auth?.apiUrl) {
     throw new Error("Not authenticated. Run `sl auth login` first.");
   }
 
+  const credential = await credentialFor(auth);
   const resolvedIdempotencyKey =
     normalizeString(idempotencyKey) || createSessionMutationIdempotencyKey("session-invite-accept");
   const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
@@ -121,14 +127,15 @@ export async function acceptSessionInvitation(
   if (normalizedSeatKey) body.seatKey = normalizedSeatKey;
   if (normalizedAgentId) body.agentId = normalizedAgentId;
 
-  const result = await requestMutation(
+  const result = await checkedTransport(requestMutation)(
     `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
     {
       method: "POST",
       operationName: "session.invitation_accept",
       idempotencyKey: resolvedIdempotencyKey,
+      credential,
       headers: createSessionMutationHeaders({
-        bearerToken: auth.token,
+        credential,
         sessionId: normalizedSessionId,
         routeId: SESSION_INVITATION_ACCEPT_ROUTE_ID,
         idempotencyKey: resolvedIdempotencyKey,

package/src/session/live-source.js

@@ -18,6 +18,7 @@
 import fs from "node:fs";
 import { setTimeout as sleep } from "node:timers/promises";
 
+import { CredentialDestinationRefused, credentialedRequest } from "../auth/credential-destinations.js";
 import { resolveSessionPaths } from "./paths.js";
 import { readStream } from "./stream.js";
 import {
@@ -155,12 +156,12 @@ export async function* watchLocalStream({
 export async function* watchRemoteStream({
   apiBaseUrl,
   sessionId,
-  token,
+  credential,
   signal,
   _sseFetch = fetch,
   reconnectBackoffMs = DEFAULT_RECONNECT_BACKOFF_MS,
 } = {}) {
-  if (!apiBaseUrl || !sessionId || !token) return;
+  if (!apiBaseUrl || !sessionId || !credential) return;
   const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${encodeURIComponent(
     sessionId,
   )}/stream`;
@@ -182,17 +183,16 @@ export async function* watchRemoteStream({
         ? `${endpoint}?fromSequence=${encodeURIComponent(String(resumeSequence))}`
         : endpoint;
     try {
-      response = await _sseFetch(url, {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          Accept: "text/event-stream",
-        },
-        signal,
-      });
+      response = await credentialedRequest(
+        credential,
+        url,
+        { method: "GET", headers: { Accept: "text/event-stream" }, signal },
+        { fetchImpl: _sseFetch },
+      );
     } catch (err) {
       if (signal?.aborted) return;
       yield { source: "sse", error: String(err?.message || err) };
+      if (err instanceof CredentialDestinationRefused) return; // final: no reconnect can change it
       await sleep(backoff);
       backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
       continue;
@@ -267,7 +267,7 @@ export async function* mergeLiveSources({
   sessionId,
   targetPath,
   apiBaseUrl,
-  token,
+  credential,
   signal,
   _localIterator,
   _remoteIterator,
@@ -278,10 +278,10 @@ export async function* mergeLiveSources({
     ? _localIterator
     : watchLocalStream({ sessionId, targetPath, signal });
   const remoteIterable =
-    _remoteIterator || (apiBaseUrl && token)
+    _remoteIterator || (apiBaseUrl && credential)
       ? _remoteIterator
         ? _remoteIterator
-        : watchRemoteStream({ apiBaseUrl, sessionId, token, signal })
+        : watchRemoteStream({ apiBaseUrl, sessionId, credential, signal })
       : null;
 
   const seen = new Map();