sentinelayer-cli 0.45.0 → 0.46.1

package/src/session/file-locks.js

@@ -12,6 +12,7 @@ import {
 import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { resolveSessionPaths } from "./paths.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 const FILE_LEASE_CAPABILITY_SCHEMA_VERSION = "1.0.0";
 const DEFAULT_FILE_LOCK_TTL_SECONDS = 300;
@@ -490,11 +491,12 @@ async function resolveLeaseApi({
 }
 
 function leaseCollectionUrl(apiUrl, sessionId) {
-  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/file-leases`;
+  return `${apiUrl}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/file-leases`;
 }
 
-function leaseMemberUrl(apiUrl, sessionId, leaseId, action) {
-  return `${leaseCollectionUrl(apiUrl, sessionId)}/${encodeURIComponent(leaseId)}/${action}`;
+/** One lease's URL: the raw lease id is encoded here; `route` is a fixed route ("/renew"). */
+function leaseMemberUrl(apiUrl, sessionId, leaseId, route) {
+  return `${leaseCollectionUrl(apiUrl, sessionId)}/${urlPathSegment(leaseId, { label: "leaseId" })}${route}`;
 }
 
 async function listRemoteLeases(
@@ -794,7 +796,7 @@ export async function lockFile(
     let compensated = false;
     try {
       const release = await checkedTransport(requestMutation)(
-        leaseMemberUrl(apiUrl, normalizedSessionId, lease.leaseId, "release"),
+        leaseMemberUrl(apiUrl, normalizedSessionId, lease.leaseId, "/release"),
         {
           method: "POST",
           operationName: "session-file-lease-acquire-compensation",
@@ -850,7 +852,7 @@ async function releaseCapabilityClaim(
   let response;
   try {
     response = await checkedTransport(requestMutation)(
-      leaseMemberUrl(apiUrl, sessionId, claim.leaseId, "release"),
+      leaseMemberUrl(apiUrl, sessionId, claim.leaseId, "/release"),
       {
         method: "POST",
         operationName: "session-file-lease-release",
@@ -1010,7 +1012,7 @@ export async function renewFileLease(
 
   const { apiUrl, credential } = await resolveLeaseApi({ targetPath, resolveAuthSession });
   const response = await checkedTransport(requestMutation)(
-    leaseMemberUrl(apiUrl, normalizedSessionId, claim.leaseId, "renew"),
+    leaseMemberUrl(apiUrl, normalizedSessionId, claim.leaseId, "/renew"),
     {
       method: "POST",
       operationName: "session-file-lease-renew",

package/src/session/invitations.js

@@ -8,6 +8,7 @@ import { requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { renderCoordinationBulletList } from "./coordination-guidance.js";
 import { resolveSessionPaths } from "./paths.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 export const SESSION_INVITATION_ACCEPT_ROUTE_ID =
   "POST /api/v1/sessions/{session_id}/invitations/accept";
@@ -128,7 +129,7 @@ export async function acceptSessionInvitation(
   if (normalizedAgentId) body.agentId = normalizedAgentId;
 
   const result = await checkedTransport(requestMutation)(
-    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
+    `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/invitations/accept`,
     {
       method: "POST",
       operationName: "session.invitation_accept",

package/src/session/listener-process.js

@@ -7,7 +7,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { promisify } from "node:util";
 
 import { isProcessAlive } from "./daemon-spawn.js";
-import { resolveSessionPaths } from "./paths.js";
+import { normalizeSessionId, resolveSessionChildDir, resolveSessionPaths } from "./paths.js";
 
 const LISTENER_DIR_NAME = "listeners";
 const GLOBAL_LISTENER_DIR_NAME = "session-listeners";
@@ -244,13 +244,12 @@ export function resolveGlobalListenerPidPath(
   agentId,
   { homeDir = os.homedir() } = {},
 ) {
-  return path.join(
-    path.resolve(String(homeDir || os.homedir())),
-    ".sentinelayer",
-    GLOBAL_LISTENER_DIR_NAME,
-    normalizeListenerProcessKey(sessionId),
-    `${normalizeListenerProcessKey(agentId)}.json`,
+  // The id is held to the session-id rule as given; its directory is the lower-cased key.
+  const sessionDir = resolveSessionChildDir(
+    path.join(path.resolve(String(homeDir || os.homedir())), ".sentinelayer", GLOBAL_LISTENER_DIR_NAME),
+    normalizeListenerProcessKey(normalizeSessionId(sessionId)),
   );
+  return path.join(sessionDir, `${normalizeListenerProcessKey(agentId)}.json`);
 }
 
 async function readPidRecordAtPath(pidPath) {

package/src/session/live-source.js

@@ -27,6 +27,7 @@ import {
   sessionEventIdentityKeys,
   sessionEventUpgradesExisting,
 } from "./event-identity.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 const DEFAULT_RECONNECT_BACKOFF_MS = 2_000;
 const MAX_RECONNECT_BACKOFF_MS = 30_000;
@@ -162,9 +163,7 @@ export async function* watchRemoteStream({
   reconnectBackoffMs = DEFAULT_RECONNECT_BACKOFF_MS,
 } = {}) {
   if (!apiBaseUrl || !sessionId || !credential) return;
-  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${encodeURIComponent(
-    sessionId,
-  )}/stream`;
+  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/stream`;
   let backoff = reconnectBackoffMs;
   // Highest server sequence actually DELIVERED to the consumer. SSE is a live push with no
   // backlog: reconnecting without it silently drops everything published while we were away,

package/src/session/paths.js

@@ -1,20 +1,69 @@
 import path from "node:path";
 import process from "node:process";
 
-function normalizeSessionId(sessionId) {
+// A session id names exactly one directory directly under <target>/.sentinelayer/sessions/.
+// Every id in use fits: randomUUID() ids, run-derived billing ids such as
+// omargate-<ms>-<hex>-<persona>-swarm-<n>-ai, chat ids such as 20261010-123456-k3j9x2, and API ids.
+// No trailing '.': Windows drops it, so "abc." and "abc" would name the same directory.
+const SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9_-])?$/;
+// Windows device names, with or without an extension, are refused on every platform.
+const RESERVED_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+
+export const SESSION_ID_RULE =
+  "sessionId must be 1-128 characters: letters, digits, '.', '_' or '-', starting with a letter or digit and not ending with '.'.";
+export const SESSION_ID_RESERVED_RULE = "sessionId must not be a reserved device name.";
+export const SESSION_ID_SEGMENT_RULE = "sessionId must name one directory directly under the sessions root.";
+
+function sessionIdProblem(id) {
+  if (!SESSION_ID_PATTERN.test(id)) return SESSION_ID_RULE;
+  if (RESERVED_DEVICE_NAME.test(id)) return SESSION_ID_RESERVED_RULE;
+  return "";
+}
+
+/** True when `value` is a session id as stored on disk (no trimming). */
+export function isValidSessionId(value) {
+  return typeof value === "string" && !sessionIdProblem(value);
+}
+
+/** The trimmed session id, or an error when it is empty, outside the allowlist or a device name. */
+export function normalizeSessionId(sessionId) {
   const normalized = String(sessionId || "").trim();
   if (!normalized) {
     throw new Error("sessionId is required.");
   }
+  const problem = sessionIdProblem(normalized);
+  if (problem) {
+    throw new Error(problem);
+  }
   return normalized;
 }
 
+/**
+ * `<root>/<sessionId>`, refused unless the result is exactly one directory directly under `root`
+ * and the id passes normalizeSessionId. The one-directory check runs first, on the raw id, so it
+ * holds by itself whatever the allowlist admits.
+ */
+export function resolveSessionChildDir(root, sessionId) {
+  const resolvedRoot = path.resolve(String(root || "."));
+  const raw = String(sessionId || "").trim();
+  if (!raw) {
+    throw new Error("sessionId is required.");
+  }
+  const dir = path.join(resolvedRoot, raw);
+  const relative = path.relative(resolvedRoot, dir);
+  if (!relative || relative === ".." || /[\\/]/.test(relative) || path.isAbsolute(relative)) {
+    throw new Error(SESSION_ID_SEGMENT_RULE);
+  }
+  normalizeSessionId(raw);
+  return dir;
+}
+
 export function resolveSessionsRoot({ targetPath = process.cwd() } = {}) {
   return path.join(path.resolve(String(targetPath || ".")), ".sentinelayer", "sessions");
 }
 
 export function resolveSessionDir(sessionId, { targetPath = process.cwd() } = {}) {
-  return path.join(resolveSessionsRoot({ targetPath }), normalizeSessionId(sessionId));
+  return resolveSessionChildDir(resolveSessionsRoot({ targetPath }), sessionId);
 }
 
 export function resolveSessionPaths(sessionId, { targetPath = process.cwd() } = {}) {

package/src/session/store.js

@@ -6,7 +6,7 @@ import process from "node:process";
 import { buildArtifactLineageIndex, verifyArtifactChain } from "../daemon/artifact-lineage.js";
 import { readSessionCodebaseContext } from "./codebase-context.js";
 import { computeSessionAnalytics } from "./analytics.js";
-import { resolveSessionPaths, resolveSessionsRoot } from "./paths.js";
+import { isValidSessionId, resolveSessionPaths, resolveSessionsRoot } from "./paths.js";
 import { appendToStream, withSessionStreamLock } from "./stream.js";
 
 const SESSION_SCHEMA_VERSION = "1.0.0";
@@ -637,7 +637,7 @@ export async function listActiveSessions({ targetPath = process.cwd() } = {}) {
 
   const sessions = [];
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
+    if (!entry.isDirectory() || !isValidSessionId(entry.name)) continue;
     const loaded = await loadMetadata(entry.name, { targetPath: resolvedTargetPath });
     if (!loaded) continue;
     if (isExpired(loaded.metadata)) continue;
@@ -677,7 +677,7 @@ export async function listAllSessions({ targetPath = process.cwd() } = {}) {
 
   const sessions = [];
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
+    if (!entry.isDirectory() || !isValidSessionId(entry.name)) continue;
     const loaded = await loadMetadata(entry.name, { targetPath: resolvedTargetPath });
     if (!loaded) continue;
 

package/src/session/sync.js

@@ -11,6 +11,7 @@ import { isSessionControlEvent } from "./control-events.js";
 import { createSessionMutationHeaders } from "./invitations.js";
 import { messageRevision } from "./message-edits.js";
 import { installTestEgressGuard } from "../net/test-egress-guard.js";
+import { isUrlPathSegment, urlPathSegment } from "../net/url-path.js";
 
 // No-op outside tests; inside a test process (or a child it spawned) every fetch
 // to a non-loopback host is refused before a socket opens.
@@ -1023,7 +1024,7 @@ export async function syncSessionEventToApi(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/events`;
   const requestBody = JSON.stringify({
     event,
     source: "cli",
@@ -1221,7 +1222,7 @@ async function syncSessionAuxPayload(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}${pathSuffix}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}${pathSuffix}`;
   try {
     const { response } = await fetchJsonWithFullTimeout(
       endpoint,
@@ -1351,7 +1352,7 @@ export async function pollHumanMessages(
     query.set("since", normalizedSince);
   }
   query.set("limit", String(Math.max(1, Math.min(HUMAN_MESSAGE_FETCH_LIMIT, normalizePositiveInteger(limit, HUMAN_MESSAGE_FETCH_LIMIT)))));
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/human-messages?${query.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/human-messages?${query.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -1526,7 +1527,7 @@ export async function pollSessionEvents(
     "limit",
     String(Math.max(1, Math.min(SESSION_EVENT_FETCH_LIMIT, normalizePositiveInteger(limit, SESSION_EVENT_FETCH_LIMIT))))
   );
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events?${query.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/events?${query.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -1681,7 +1682,7 @@ export async function fetchSessionPresence(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/presence`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/presence`;
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
@@ -1832,7 +1833,7 @@ export async function renewSessionPresence(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/presence`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/presence`;
   const body = {
     agentId: normalizedAgentId,
     state: normalizeString(state).toLowerCase() || "idle",
@@ -1955,7 +1956,7 @@ export async function requestSessionListenerStop(
   const normalizedIdempotencyKey =
     normalizeString(idempotencyKey) || `sl-listener-stop-${randomUUID()}`;
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/listener-controls/stop`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/listener-controls/stop`;
   const body = normalizedTargetAgentId
     ? { targetAgentId: normalizedTargetAgentId }
     : { broadcast: true };
@@ -2080,7 +2081,7 @@ export async function updateSessionReadCursor(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/read-cursor`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/read-cursor`;
   const body = {
     targetSequenceId:
       Number.isFinite(normalizedTargetSequence) && normalizedTargetSequence > 0
@@ -2225,7 +2226,7 @@ export async function streamSessionEvents(
     query.set("after", normalizedSince);
   }
   const suffix = query.toString() ? `?${query.toString()}` : "";
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/stream${suffix}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/stream${suffix}`;
   const controller = new AbortController();
   const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
   const normalizedIdleTimeoutMs = normalizePositiveInteger(idleTimeoutMs, 0);
@@ -2450,7 +2451,7 @@ export async function pollSessionEventsBefore(
     "limit",
     String(Math.max(1, Math.min(SESSION_EVENT_FETCH_LIMIT, normalizePositiveInteger(limit, 50))))
   );
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events/before?${query.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/events/before?${query.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -2571,7 +2572,7 @@ export async function listSessionMessageActions(
     "limit",
     String(Math.max(1, Math.min(SESSION_ACTION_FETCH_LIMIT, normalizePositiveInteger(limit, 200))))
   );
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/actions?${query.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/actions?${query.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -2668,7 +2669,7 @@ export async function fetchSessionUsageLedger(
     "limit",
     String(Math.max(1, Math.min(500, normalizePositiveInteger(limit, 500))))
   );
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/usage?${query.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/usage?${query.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -2847,7 +2848,10 @@ export async function editSessionMessage(sessionId, {
   let revision = expectedRevision === null || expectedRevision === undefined ? null : Number(expectedRevision);
   const validSequence = Number.isSafeInteger(sequence) && sequence > 0;
   const mutationKey = normalizeString(idempotencyKey) || `sl-message-edit-${randomUUID()}`;
-  if (!sid || typeof text !== "string" || !text.trim() || (!replyId && !messageId && !validSequence) ||
+  // Every id is checked here, before the request try below: an id that is not one URL path
+  // segment sends nothing and is never counted against the outbound breaker.
+  const idsAreSegments = isUrlPathSegment(sid) && [replyId, messageId].every((id) => !id || isUrlPathSegment(id));
+  if (!idsAreSegments || typeof text !== "string" || !text.trim() || (!replyId && !messageId && !validSequence) ||
       (revision !== null && (!Number.isSafeInteger(revision) || revision <= 0)) || mutationKey.length > 128) {
     return { ok: false, reason: "invalid_input" };
   }
@@ -2858,7 +2862,11 @@ export async function editSessionMessage(sessionId, {
   try { auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false }); }
   catch { return { ok: false, reason: "no_session" }; }
   if (!isAuthenticated(auth)) return { ok: false, reason: "not_authenticated" };
-  const base = `${resolveApiBaseUrl(auth)}/api/v1/sessions/${encodeURIComponent(sid)}`;
+  const base = `${resolveApiBaseUrl(auth)}/api/v1/sessions/${urlPathSegment(sid, { label: "sessionId" })}`;
+  // The edit target: a reply by its id, or a message by its id (checked above, or from the lookup).
+  const targetUrl = (id) => (replyId
+    ? `${base}/replies/${urlPathSegment(replyId, { label: "replyId" })}`
+    : `${base}/messages/${urlPathSegment(id, { label: "messageId" })}`);
   const credential = await credentialFor(auth);
   const failure = (response, payload) => {
     const code = normalizeString(payload?.detail?.code || payload?.error?.code || payload?.code);
@@ -2869,21 +2877,23 @@ export async function editSessionMessage(sessionId, {
   try {
     // Sequence resolution and omitted-revision lookup are one authenticated GET.
     if ((!replyId && !messageId) || revision === null) {
-      const resource = replyId ? `replies/${encodeURIComponent(replyId)}` : messageId
-        ? `messages/${encodeURIComponent(messageId)}` : `messages/by-sequence/${sequence}`;
+      const lookupUrl = replyId || messageId
+        ? targetUrl(messageId)
+        : `${base}/messages/by-sequence/${urlPathSegment(sequence, { label: "targetSequenceId" })}`;
       const authorQuery = normalizeString(agentId) ? `?agentId=${encodeURIComponent(normalizeString(agentId))}` : "";
-      const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}${authorQuery}`, { method: "GET", credential, signal }, timeoutMs, fetchImpl, { readErrorBody: true });
+      const { response, payload } = await fetchJsonWithFullTimeout(`${lookupUrl}${authorQuery}`, { method: "GET", credential, signal }, timeoutMs, fetchImpl, { readErrorBody: true });
       if (!response?.ok || payload?.ok === false) return failure(response, payload);
       const current = replyId ? payload?.reply : payload?.event;
       const fetchedRevision = Number(current?.messageRevision ?? 1);
-      if (!current?.id || (replyId && current.id !== replyId) || !Number.isSafeInteger(fetchedRevision) || fetchedRevision <= 0) return { ok: false, reason: "invalid_edit_target" };
+      // A message id from the lookup is held to the same rule before it is used in a URL.
+      if (!current?.id || (replyId ? current.id !== replyId : !isUrlPathSegment(current.id)) ||
+          !Number.isSafeInteger(fetchedRevision) || fetchedRevision <= 0) return { ok: false, reason: "invalid_edit_target" };
       if (current.canEdit === false) return { ok: false, reason: "MESSAGE_EDIT_FORBIDDEN", status: 403 };
       if (!replyId) messageId = current.id;
       if (revision === null) revision = fetchedRevision;
     }
-    const resource = replyId ? `replies/${encodeURIComponent(replyId)}` : `messages/${encodeURIComponent(messageId)}`;
     const body = { text, expectedRevision: revision, ...(normalizeString(agentId) ? { agentId: normalizeString(agentId) } : {}) };
-    const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}`, {
+    const { response, payload } = await fetchJsonWithFullTimeout(targetUrl(messageId), {
       method: "PATCH",
       headers: {
         ...createSessionMutationHeaders({ credential, sessionId: sid, routeId: replyId
@@ -2985,7 +2995,7 @@ export async function createSessionMessageAction(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/actions`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/actions`;
   const body = {
     actionType: normalizedActionType,
     metadata: metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {},
@@ -3143,7 +3153,7 @@ export async function searchSessionEvents(
     "limit",
     String(Math.max(1, Math.min(SESSION_SEARCH_FETCH_LIMIT, normalizePositiveInteger(limit, 20))))
   );
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events/search?${queryParams.toString()}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/events/search?${queryParams.toString()}`;
 
   try {
     const { response, payload } = await fetchJsonWithFullTimeout(
@@ -3389,7 +3399,7 @@ export async function fetchSessionFromApi(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}`;
 
   let response;
   let body;
@@ -3468,9 +3478,7 @@ export async function probeSessionAccess(
   }
 
   const apiBaseUrl = resolveApiBaseUrl(session);
-  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(
-    normalizedSessionId,
-  )}/events?limit=1`;
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/events?limit=1`;
 
   let response;
   try {

package/src/session/tickets.js

@@ -22,6 +22,7 @@ import process from "node:process";
 import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 function normalizeString(value) {
   return String(value ?? "").trim();
@@ -75,8 +76,14 @@ async function auth(targetPath, resolveAuthSession) {
   return { credential: await credentialFor(session), apiUrl: normalizeString(session.apiUrl).replace(/\/+$/, "") };
 }
 
-function ticketsUrl(apiUrl, sessionId, suffix = "") {
-  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/tickets${suffix}`;
+/** The room's tickets URL; `route` is a fixed collection route ("/events"). */
+function ticketsUrl(apiUrl, sessionId, route = "") {
+  return `${apiUrl}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/tickets${route}`;
+}
+
+/** One ticket's URL: the raw ticket id is encoded here; `route` is a fixed route ("/claim"). */
+function ticketUrl(apiUrl, sessionId, ticketId, route) {
+  return `${ticketsUrl(apiUrl, sessionId)}/${urlPathSegment(ticketId, { label: "ticketId" })}${route}`;
 }
 
 /** The Idempotency-Key for this logical write: reused until its response is stored. */
@@ -226,7 +233,7 @@ export async function claimTicket(
   const statePath = ticketLeasePath(sessionId, ticketId, identity, { homeDir });
   const { credential, apiUrl } = await auth(targetPath, resolveAuthSession);
   const { key } = await operationKey(statePath, "claim", String(expectedVersion ?? "any"));
-  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/claim`), {
+  const response = await mutate(ticketUrl(apiUrl, sessionId, ticketId, "/claim"), {
     credential, key, operation: "claim", requestMutation,
     body: expectedVersion == null ? {} : { expectedVersion: Number(expectedVersion) },
   });
@@ -262,7 +269,7 @@ export async function renewTicketLease(
   const held = await heldLease(statePath);
   const { credential, apiUrl } = await auth(targetPath, resolveAuthSession);
   const { key } = await operationKey(statePath, "renew", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
-  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/lease/renew`), {
+  const response = await mutate(ticketUrl(apiUrl, sessionId, ticketId, "/lease/renew"), {
     credential, key, operation: "renew", requestMutation, body: { leaseId: held.leaseId, fence: held.fence },
   });
   await writeState(statePath, leaseState(response));
@@ -278,7 +285,7 @@ export async function releaseTicketLease(
   const held = await heldLease(statePath);
   const { credential, apiUrl } = await auth(targetPath, resolveAuthSession);
   const { key } = await operationKey(statePath, "release", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
-  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/lease/release`), {
+  const response = await mutate(ticketUrl(apiUrl, sessionId, ticketId, "/lease/release"), {
     credential, key, operation: "release", requestMutation,
     body: { leaseId: held.leaseId, fence: held.fence, expectedVersion: held.ticketVersion, ...(reason ? { reason } : {}) },
   });
@@ -303,7 +310,7 @@ export async function submitTicket(
   const held = await heldLease(statePath);
   const { credential, apiUrl } = await auth(targetPath, resolveAuthSession);
   const { key } = await operationKey(statePath, "submit", `${held.leaseId}:${held.fence}:${held.ticketVersion}`);
-  const response = await mutate(ticketsUrl(apiUrl, sessionId, `/${encodeURIComponent(ticketId)}/submit`), {
+  const response = await mutate(ticketUrl(apiUrl, sessionId, ticketId, "/submit"), {
     credential, key, operation: "submit", requestMutation,
     body: {
       leaseId: held.leaseId,

package/src/session/title-sync.js

@@ -4,6 +4,7 @@ import { checkedTransport, credentialFor, isAuthenticated } from "../auth/creden
 import { SentinelayerApiError, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { recordSessionRemoteTitleSync } from "./store.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 const DEFAULT_TITLE_SYNC_TIMEOUT_MS = 2_000;
 const DEFAULT_TITLE_SYNC_RETRY_DELAY_MS = 200;
@@ -78,7 +79,7 @@ export async function pushSessionTitleToApi(
     }
     const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
     const result = await checkedTransport(requestMutation)(
-      `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/title`,
+      `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/title`,
       {
         method: "POST",
         operationName: "session.set_title",