sentinelayer-cli 0.46.0 → 0.46.2

package/src/commands/session.js

@@ -76,6 +76,7 @@ import {
 import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
 import {
   getListenerProcessStatus,
+  LISTENER_PROCESS_SCAN_RETRY_TIMEOUT_MS,
   removeListenerPidRecord,
   requestListenerProcessStop,
   summarizeLocalListenerProcesses,
@@ -198,6 +199,7 @@ import {
 import createSentid from "../session/wake/sentid.js";
 import { authLoginHint, preferredCliCommand } from "../ui/command-hints.js";
 import { parseCsvTokens } from "./ai/shared.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
@@ -1515,7 +1517,7 @@ async function verifyRemoteSession(sessionId, { targetPath } = {}) {
   if (!apiUrl) {
     return { ok: false, reason: "no_api_url" };
   }
-  const endpoint = `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
+  const endpoint = `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}`;
   const credential = await credentialFor(auth);
   const firstAttempt = await fetchRemoteSessionDetail(endpoint, credential);
   const detail = firstAttempt.retryable
@@ -3301,7 +3303,7 @@ export function registerSessionCommand(program) {
       }
       const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
       const result = await requestJsonMutation(
-        `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/title`,
+        `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/title`,
         {
           method: "POST",
           operationName: "session.set_title",
@@ -5148,16 +5150,17 @@ export function registerSessionCommand(program) {
       let localProcessScan = {
         ok: false,
         reason: listeners.length > 0 ? "not_scanned" : "no_listener_rows",
-        processCount: 0,
-        duplicateProcessCount: 0,
+        // Not scanned, so no count: null, never 0, so a reader that skips `ok` can't read "no duplicates".
+        processCount: null,
+        duplicateProcessCount: null,
         agents: [],
       };
       if (listeners.length > 0) {
-        try {
-          const summary = await summarizeLocalListenerProcesses(
-            normalizedSessionId,
-            listeners.map((row) => row.agentId),
-          );
+        const summary = await summarizeLocalListenerProcesses(
+          normalizedSessionId,
+          listeners.map((row) => row.agentId),
+        );
+        if (summary.ok) {
           const byAgent = new Map(summary.agents.map((entry) => [entry.agentId, entry]));
           listeners = listeners.map((row) => {
             const local = byAgent.get(row.agentId) || {};
@@ -5175,12 +5178,13 @@ export function registerSessionCommand(program) {
             duplicateProcessCount: Number(summary.duplicateProcessCount || 0),
             agents: summary.agents,
           };
-        } catch (error) {
+        } else {
+          // The rows stay unannotated: an unread process table is not "no local listeners".
           localProcessScan = {
             ok: false,
-            reason: normalizeString(error?.message) || "process_scan_failed",
-            processCount: 0,
-            duplicateProcessCount: 0,
+            reason: summary.reason,
+            processCount: null,
+            duplicateProcessCount: null,
             agents: [],
           };
         }
@@ -5230,6 +5234,11 @@ export function registerSessionCommand(program) {
         else if (row.status === "idle") console.log(pc.cyan(`  ${line}`));
         else console.log(pc.gray(`  ${line}`));
       }
+      if (!localProcessScan.ok) {
+        console.log(pc.yellow(
+          `Local listener processes: unknown. The local process check did not complete (${localProcessScan.reason}), so duplicate local listeners were not checked.`,
+        ));
+      }
       const duplicateLocalRows = listeners.filter((row) => Number(row.localDuplicateProcessCount || 0) > 0);
       if (duplicateLocalRows.length > 0) {
         const summary = duplicateLocalRows
@@ -5483,9 +5492,23 @@ export function registerSessionCommand(program) {
       const singletonEnabled = maxPolls === null && !options.allowDuplicate;
       let listenerPidRecordActive = false;
       if (singletonEnabled) {
-        const existingListener = await getListenerProcessStatus(normalizedSessionId, agentId, {
+        let existingListener = await getListenerProcessStatus(normalizedSessionId, agentId, {
           targetPath,
         });
+        if (existingListener.state === "unknown") {
+          // A busy machine can need longer than the first limit: check once more, slower.
+          existingListener = await getListenerProcessStatus(normalizedSessionId, agentId, {
+            targetPath,
+            scanTimeoutMs: LISTENER_PROCESS_SCAN_RETRY_TIMEOUT_MS,
+          });
+        }
+        if (existingListener.state === "unknown") {
+          // Starting without an answer could add a second listener, so refuse, with or
+          // without --force: --force replaces the listener the check finds.
+          throw new Error(
+            `Could not confirm whether a session listener is already running for session ${normalizedSessionId} as ${agentId}: the local process check did not complete (${existingListener.reason}), including one retry with a longer time limit. No listener was started. Run the command again, or use --allow-duplicate to start without this check (it can then run alongside an existing listener). --force does not skip the check: it stops the listener the check finds, then starts this one.`,
+          );
+        }
         if (existingListener.running && !options.force) {
           throw new Error(
             `A session listener is already running for session ${normalizedSessionId} as ${agentId} (pid ${existingListener.pid}). Use --force to take over or --allow-duplicate if you intentionally need more than one.`,
@@ -5493,8 +5516,19 @@ export function registerSessionCommand(program) {
         }
         if (existingListener.running && options.force) {
           const stopMatchesResult = await stopMatchingListenerProcesses(normalizedSessionId, agentId);
+          if (!stopMatchesResult.ok) {
+            // The listener being replaced is known (a verified pid record or a scan moments
+            // ago), so stopping it and starting this one never adds a listener. Only the
+            // cleanup of extra copies is skipped, and that is said rather than assumed.
+            console.error(
+              pc.yellow(
+                `The local process check did not complete (${stopMatchesResult.reason}); replacing listener pid ${existingListener.pid} only. Other copies of this listener, if any, were not checked.`,
+              ),
+            );
+          }
+          const scannedStops = stopMatchesResult.ok ? stopMatchesResult.results : [];
           const stoppedPids = new Set(
-            stopMatchesResult.results
+            scannedStops
               .filter((result) => result.stopped)
               .map((result) => Number(result.pid)),
           );
@@ -5503,7 +5537,7 @@ export function registerSessionCommand(program) {
             explicitStopResult = await requestListenerProcessStop(existingListener.pid);
           }
           const failedStops = [
-            ...stopMatchesResult.failed,
+            ...scannedStops.filter((result) => !result.stopped),
             ...(explicitStopResult && !explicitStopResult.stopped
               ? [{ pid: existingListener.pid, ...explicitStopResult }]
               : []),
@@ -8744,7 +8778,7 @@ export function registerSessionCommand(program) {
       try {
         result = await postAdminSessionMutation({
           session: apiSession,
-          pathSuffix: `/api/v1/admin/sessions/${encodeURIComponent(normalizedSessionId)}/kill`,
+          pathSuffix: `/api/v1/admin/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/kill`,
           operationName: "session-admin-kill",
           body: { reason },
         });

package/src/legacy-cli.js

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 import crypto from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
@@ -8,7 +6,6 @@ import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { pathToFileURL } from "node:url";
 
 import open from "open";
 import pc from "picocolors";
@@ -31,6 +28,7 @@ import { normalizeAgentEvent } from "./events/schema.js";
 import { collectCodebaseIngest, formatIngestSummary } from "./ingest/engine.js";
 import { getExpressTemplate, getPackageJsonTemplate, buildReadmeContent } from "./scaffold/templates.js";
 import { generateScaffold } from "./scaffold/generator.js";
+import { isGhRepoSlug } from "./net/gh-api-path.js";
 import {
   getCoordinationEtiquetteItems,
   renderCoordinationNumberedList,
@@ -117,8 +115,10 @@ function normalizeRepoSlug(value) {
   return String(value || "").trim().replace(/\.git$/i, "");
 }
 
+// Exactly owner/repo as GitHub names them (src/net/gh-api-path.js): the slug goes into gh API
+// paths and --repo values, and into the clone and remote URLs.
 function isValidRepoSlug(value) {
-  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalizeRepoSlug(value));
+  return isGhRepoSlug(normalizeRepoSlug(value));
 }
 
 function getRepoNameFromSlug(value) {
@@ -3761,10 +3761,3 @@ export async function runLegacyCliWithErrorHandling(rawArgs = process.argv.slice
   }
 }
 
-const invokedAsEntrypoint =
-  process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-
-if (invokedAsEntrypoint) {
-  runLegacyCliWithErrorHandling();
-}
-

package/src/mcp/session-stdio-server.js

@@ -9,6 +9,7 @@ import {
 } from "./cli-command-tools.js";
 import { appendToStream, readStream } from "../session/stream.js";
 import { listFileLocks, lockFile, unlockFile } from "../session/file-locks.js";
+import { resolveSessionDir } from "../session/paths.js";
 import { eventMatchesAgent } from "../session/listener.js";
 import { isSessionControlEvent } from "../session/control-events.js";
 import { buildObservations } from "../session/recall/observations.js";
@@ -594,11 +595,14 @@ async function readSessionHistoryWindow({
   };
 }
 
-function requireSessionId(input = {}) {
+// A native tool's session id also names its local session directory, so it is held to the
+// session-id rule here, before any request is sent or any file is read or written.
+function requireSessionId(input = {}, { targetPath } = {}) {
   const sessionId = normalizeString(input.sessionId || input.session_id || input.session);
   if (!sessionId) {
     throw new Error("sessionId is required.");
   }
+  resolveSessionDir(sessionId, { targetPath });
   return sessionId;
 }
 
@@ -712,7 +716,7 @@ async function runSessionAction({
   targetPath,
   createSessionMessageActionFn,
 } = {}) {
-  const sessionId = requireSessionId(input);
+  const sessionId = requireSessionId(input, { targetPath });
   const agentId = requireAgentId(input);
   const normalizedActionType = normalizeSessionMessageActionType(actionType || input.actionType || input.action_type);
   const target = requireSessionActionTarget(input);
@@ -995,7 +999,7 @@ export function createSessionMcpToolHandlers({
   };
   const handlers = {
     async poll_inbox(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
       const cursor = normalizeString(input.cursor || input.after || input.since) || null;
       const limit = normalizeLimit(input.limit);
@@ -1071,7 +1075,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async read_history(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const cursor = normalizeString(input.cursor || input.after || input.since) || null;
       const beforeSequence = normalizeOptionalPositiveInteger(
         input.beforeSequence || input.before_sequence,
@@ -1164,7 +1168,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async send_message(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
       const recipients = normalizeRecipients(input.to || input.recipient || input.recipients);
       const agent = buildAgentEnvelope(agentId, input);
@@ -1223,7 +1227,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async session_lock(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
       const files = normalizeFileList(input.files || input.file || input.paths);
       const intent = normalizeString(input.intent || input.reason);
@@ -1257,7 +1261,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async session_unlock(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
       const files = normalizeFileList(input.files || input.file || input.paths);
       const reason = normalizeString(input.reason || input.intent) || "manual_release";
@@ -1290,7 +1294,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async session_locks(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const locks = await listFileLocksFn(sessionId, {
         targetPath,
       });
@@ -1304,7 +1308,7 @@ export function createSessionMcpToolHandlers({
     },
 
     async attention_request(input = {}) {
-      const sessionId = requireSessionId(input);
+      const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
       const recipients = normalizeRecipients(input.to || input.recipient || input.recipients);
       const agent = buildAgentEnvelope(agentId, {

package/src/net/gh-api-path.js

@@ -0,0 +1,68 @@
+// gh-api-path.js — the values the CLI puts into GitHub API paths that gh requests.
+//
+// gh sends every request with the signed-in user's GitHub token. The CLI builds `gh api` paths
+// (repos/<owner>/<repo>/...) and passes --repo values that gh turns into paths of its own, so each
+// value is checked for its role before any gh process starts:
+//
+//   ghRepoSlug     exactly "owner/repo". The owner starts with a letter or digit, then letters,
+//                  digits, "-" or "_" (Enterprise Managed User names end in "_shortcode"), at most
+//                  39 characters. The repository is letters, digits, ".", "_" or "-", at most 100
+//                  characters, and not "." or "..".
+//   ghCommitSha    7 to 40 hexadecimal characters.
+//   ghRefSegment   a git branch, tag or ref name under git's ref-name rules, not starting with "-",
+//                  percent-encoded as ONE path segment. A branch name may contain "/", and git also
+//                  allows "#", "%", "{" and other characters that mean something in a URL or to gh;
+//                  encoded, they stay inside the segment. GitHub's compare ({base}...{head}) and
+//                  commits/{ref} endpoints accept a branch name with "/" encoded as %2F.
+//
+// Each returns the value to put in the path, or throws an Error saying what the value must be.
+// These are GitHub-specific rather than a general one-segment encoder: a branch name may contain
+// "/" and still be one segment once encoded, and a slug or a commit SHA has a shape of its own.
+
+const OWNER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$/;
+const REPO = /^[A-Za-z0-9._-]{1,100}$/;
+const COMMIT_SHA = /^[0-9A-Fa-f]{7,40}$/;
+// Control characters, space, and the other characters git does not allow in a ref name.
+const REF_FORBIDDEN = /[\u0000-\u0020\u007f-\u009f~^:?*[\\]/;
+
+/** True when `value` is exactly "owner/repo" as GitHub names them. */
+export function isGhRepoSlug(value) {
+  if (typeof value !== "string") return false;
+  const parts = value.split("/");
+  if (parts.length !== 2) return false;
+  const [owner, repo] = parts;
+  return OWNER.test(owner) && REPO.test(repo) && repo !== "." && repo !== "..";
+}
+
+/** True when `value` is a valid git branch, tag or ref name that does not start with "-". */
+export function isGitRefName(value) {
+  if (typeof value !== "string" || !value || !value.isWellFormed()) return false;
+  if (value === "@" || value.includes("..") || value.includes("@{") || value.includes("//")) return false;
+  if (REF_FORBIDDEN.test(value)) return false;
+  if (value.startsWith("-") || value.startsWith("/") || value.endsWith("/") || value.endsWith(".")) return false;
+  return value.split("/").every((part) => !part.startsWith(".") && !part.endsWith(".lock"));
+}
+
+/** `value` as an owner/repo path, or throws. */
+export function ghRepoSlug(value, { label = "repo" } = {}) {
+  if (!isGhRepoSlug(value)) {
+    throw new Error(`${label} must be a GitHub repository in owner/repo form.`);
+  }
+  return value;
+}
+
+/** `value` as a commit SHA path segment, or throws. */
+export function ghCommitSha(value, { label = "sha" } = {}) {
+  if (typeof value !== "string" || !COMMIT_SHA.test(value)) {
+    throw new Error(`${label} must be a commit SHA of 7 to 40 hexadecimal characters.`);
+  }
+  return value;
+}
+
+/** `value` (a git branch, tag or ref name) percent-encoded as one path segment, or throws. */
+export function ghRefSegment(value, { label = "ref" } = {}) {
+  if (!isGitRefName(value)) {
+    throw new Error(`${label} must be a valid git branch, tag or ref name.`);
+  }
+  return encodeURIComponent(value);
+}

package/src/net/url-path.js

@@ -0,0 +1,41 @@
+// url-path.js — one identifier, one URL path segment.
+//
+// The CLI puts identifiers into API URL paths: session, admission, ticket, lease, checkpoint, run,
+// token, message, reply, scan and AIdenID ids. urlPathSegment encodes each one as exactly one
+// segment, and refuses a value that cannot be one: empty, "." or "..", or containing "/", "\", a
+// control character or an unpaired surrogate. The URL builders that take ids (the session,
+// ticket, admission and lease URL helpers) take the raw id and call it themselves.
+//
+// tests/unit.url-path-segments.test.mjs holds the census of src/ and says exactly which forms it
+// checks. assertCredentialDestination (src/auth/credential-destinations.js) also checks the path
+// of every URL it sends a credential to.
+
+// C0 controls, DEL and C1 controls.
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+
+/** Whether urlPathSegment accepts `value`. Use it to refuse an id before any request work starts. */
+export function isUrlPathSegment(value) {
+  const text = String(value ?? "");
+  return (
+    text !== "" &&
+    text !== "." &&
+    text !== ".." &&
+    !/[/\\]/.test(text) &&
+    !CONTROL_CHARACTER.test(text) &&
+    text.isWellFormed()
+  );
+}
+
+/**
+ * `value` encoded as exactly one URL path segment. Refuses an empty value, "." or "..", and a
+ * value containing "/", "\", a control character or an unpaired surrogate. "%" is encoded, so
+ * "%2e%2e" is sent as "%252e%252e" and stays one literal segment.
+ */
+export function urlPathSegment(value, { label = "identifier" } = {}) {
+  if (!isUrlPathSegment(value)) {
+    throw new Error(
+      `${label} must be a single URL path segment: not empty, "." or "..", and without "/", "\\" or control characters.`,
+    );
+  }
+  return encodeURIComponent(String(value ?? ""));
+}

package/src/review/dd-report-email-client.js

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import { checkedTransport, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { requestJson } from "../auth/http.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 export const DD_REPORT_EMAIL_TIMEOUT_MS = 10_000;
 
@@ -108,9 +109,7 @@ export async function sendDdReportEmail({
   }
 
   const apiUrl = normalizeString(session.apiUrl) || "https://api.sentinelayer.com";
-  const endpoint = `${apiUrl.replace(/\/+$/, "")}/api/v1/runs/${encodeURIComponent(
-    normalizedRunId,
-  )}/send-report-email`;
+  const endpoint = `${apiUrl.replace(/\/+$/, "")}/api/v1/runs/${urlPathSegment(normalizedRunId, { label: "runId" })}/send-report-email`;
   const idempotencyKey = buildReportEmailIdempotencyKey({
     runId: normalizedRunId,
     to: normalizedTo,

package/src/scan/gh-secrets.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import process from "node:process";
 import fs from "node:fs";
 
+import { isGhRepoSlug } from "../net/gh-api-path.js";
+
 function getGhCommand() {
   return String(process.env.SENTINELAYER_GH_BIN || "").trim() || "gh";
 }
@@ -10,8 +12,9 @@ function normalizeRepoSlug(value) {
   return String(value || "").trim().replace(/\.git$/i, "");
 }
 
+// Exactly owner/repo as GitHub names them: gh turns the --repo value into API paths.
 function isValidRepoSlug(value) {
-  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalizeRepoSlug(value));
+  return isGhRepoSlug(normalizeRepoSlug(value));
 }
 
 function isValidSecretName(value) {

package/src/session/admission-access.js

@@ -18,6 +18,7 @@ import {
   createSessionMutationHeaders,
   createSessionMutationIdempotencyKey,
 } from "./invitations.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 /**
  * Approve, deny, revoke and mode changes are the room owner's decisions, made with the
@@ -84,8 +85,13 @@ async function authContext(targetPath, resolveAuthSession) {
   };
 }
 
-function admissionsUrl(apiUrl, sessionId, suffix = "") {
-  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/admissions${suffix}`;
+function admissionsUrl(apiUrl, sessionId) {
+  return `${apiUrl}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/admissions`;
+}
+
+/** One admission's URL: the raw admission id is encoded here; `route` is a fixed route ("/revoke"). */
+function admissionMemberUrl(apiUrl, sessionId, admissionId, route = "") {
+  return `${admissionsUrl(apiUrl, sessionId)}/${urlPathSegment(admissionId, { label: "admissionId" })}${route}`;
 }
 
 function boundedIdempotencyKey(value, operation) {
@@ -96,7 +102,8 @@ function boundedIdempotencyKey(value, operation) {
 
 async function mutateAdmission(
   sessionId,
-  suffix,
+  admissionId,
+  route,
   routeId,
   body,
   {
@@ -110,7 +117,7 @@ async function mutateAdmission(
 ) {
   const key = boundedIdempotencyKey(idempotencyKey, operationName);
   const auth = await authContext(targetPath, resolveAuthSession);
-  const result = await checkedTransport(requestMutation)(admissionsUrl(auth.apiUrl, sessionId, suffix), {
+  const result = await checkedTransport(requestMutation)(admissionMemberUrl(auth.apiUrl, sessionId, admissionId, route), {
     method: "POST",
     operationName,
     idempotencyKey: key,
@@ -163,7 +170,7 @@ export async function getSessionAdmission(
   const sid = required(sessionId, "session id");
   const aid = required(admissionId, "admission id");
   const auth = await authContext(targetPath, resolveAuthSession);
-  return checkedTransport(requestRead)(admissionsUrl(auth.apiUrl, sid, `/${encodeURIComponent(aid)}`), {
+  return checkedTransport(requestRead)(admissionMemberUrl(auth.apiUrl, sid, aid), {
     method: "GET",
     credential: auth.credential,
   });
@@ -201,7 +208,8 @@ export async function decideSessionAdmission(
   await assertOwnerAccessContext();
   return mutateAdmission(
     sid,
-    `/${encodeURIComponent(aid)}/decision`,
+    aid,
+    "/decision",
     ROUTES.decision,
     body,
     {
@@ -233,7 +241,8 @@ export async function revokeSessionAdmission(
   await assertOwnerAccessContext();
   return mutateAdmission(
     sid,
-    `/${encodeURIComponent(aid)}/revoke`,
+    aid,
+    "/revoke",
     ROUTES.revoke,
     normalizedReason ? { reason: normalizedReason } : {},
     {
@@ -267,7 +276,7 @@ export async function setSessionAdmissionMode(
   const key = boundedIdempotencyKey(idempotencyKey, "session.admission_mode");
   const auth = await authContext(targetPath, resolveAuthSession);
   const result = await checkedTransport(requestMutation)(
-    `${auth.apiUrl}/api/v1/sessions/${encodeURIComponent(sid)}/admission-mode`,
+    `${auth.apiUrl}/api/v1/sessions/${urlPathSegment(sid, { label: "sessionId" })}/admission-mode`,
     {
       method: "POST",
       operationName: "session.admission_mode",

package/src/session/admission.js

@@ -41,6 +41,7 @@ import {
   createSessionMutationIdempotencyKey,
 } from "./invitations.js";
 import { resolveSessionPaths } from "./paths.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 export const ADMISSION_ACTIONS = Object.freeze([
   "session.read",
@@ -373,8 +374,14 @@ async function authContext({ targetPath, resolveAuthSession }) {
   return { credential: await credentialFor(auth), apiUrl: normalizeString(auth.apiUrl).replace(/\/+$/, "") };
 }
 
-function admissionUrl(apiUrl, sessionId, suffix = "") {
-  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/admissions${suffix}`;
+/** The session's admissions URL; `route` is a fixed collection route ("/self"). */
+function admissionUrl(apiUrl, sessionId, route = "") {
+  return `${apiUrl}/api/v1/sessions/${urlPathSegment(sessionId, { label: "sessionId" })}/admissions${route}`;
+}
+
+/** One admission's URL: the raw admission id is encoded here; `route` is a fixed route ("/claim"). */
+function admissionMemberUrl(apiUrl, sessionId, admissionId, route = "") {
+  return `${admissionUrl(apiUrl, sessionId)}/${urlPathSegment(admissionId, { label: "admissionId" })}${route}`;
 }
 
 async function mutate(auth, sessionId, routeId, url, body, { requestMutation, operationName, origin }) {
@@ -530,7 +537,7 @@ export async function runAdmissionJoin(
   const deadline = now() + Math.max(0, waitTimeoutMs);
   let polled;
   for (;;) {
-    polled = await checkedTransport(requestRead)(admissionUrl(auth.apiUrl, sid, `/${encodeURIComponent(state.admissionId)}`), {
+    polled = await checkedTransport(requestRead)(admissionMemberUrl(auth.apiUrl, sid, state.admissionId), {
       method: "GET",
       credential: auth.credential,
     });
@@ -599,7 +606,7 @@ export async function runAdmissionJoin(
     auth,
     sid,
     ROUTE.claim,
-    admissionUrl(auth.apiUrl, sid, `/${encodeURIComponent(state.admissionId)}/claim`),
+    admissionMemberUrl(auth.apiUrl, sid, state.admissionId, "/claim"),
     { nonce: fields.nonce, signature: signature.toString("base64url") },
     { ...deps, operationName: "session.admission_claim" }
   );
@@ -702,7 +709,7 @@ export async function cancelAdmission(
     auth,
     sid,
     ROUTE.cancel,
-    admissionUrl(auth.apiUrl, sid, `/${encodeURIComponent(state.admissionId)}/cancel`),
+    admissionMemberUrl(auth.apiUrl, sid, state.admissionId, "/cancel"),
     undefined,
     { requestMutation, origin, operationName: "session.admission_cancel" }
   );

package/src/session/agent-registry.js

@@ -3,6 +3,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
+import { resolveAgentIdPath } from "../agents/agent-id-path.js";
 import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { inferSessionAgentIdentity } from "./agent-identity.js";
 import { resolveSessionPaths } from "./paths.js";
@@ -175,12 +176,10 @@ async function writeAgentSnapshot(snapshotPath, snapshot) {
   }
 }
 
+// <session>/agents/<agentId>.json, refused before any read or write unless the id names one
+// file directly under the agents directory.
 function buildAgentSnapshotPath(paths, agentId) {
-  const normalizedAgentId = normalizeString(agentId);
-  if (!normalizedAgentId) {
-    throw new Error("agentId is required.");
-  }
-  return path.join(paths.agentsDir, `${normalizedAgentId}.json`);
+  return resolveAgentIdPath(paths.agentsDir, normalizeString(agentId), ".json");
 }
 
 export function generateAgentId(modelName) {

package/src/session/checkpoints.js

@@ -5,6 +5,7 @@ import { checkedTransport, credentialFor, isAuthenticated } from "../auth/creden
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { pollSessionEventsBefore } from "./sync.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
 const DEFAULT_CHECKPOINT_LIMIT = 100;
@@ -442,7 +443,7 @@ export async function listSessionCheckpoints(sessionId, {
   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()}`,
+    `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/checkpoints?${params.toString()}`,
     { method: "GET", credential },
   );
   const checkpoints = Array.isArray(response?.checkpoints) ? response.checkpoints : [];
@@ -522,7 +523,7 @@ export async function createSessionCheckpoint(sessionId, options = {}) {
   const { body, idempotencyKey } = buildManualCheckpointPayload(normalizedSessionId, options);
   const { apiUrl, credential } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
   const response = await checkedTransport(requestMutation)(
-    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints`,
+    `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/checkpoints`,
     {
       operationName: "session-checkpoint-create",
       credential,
@@ -549,7 +550,7 @@ export async function generateSessionCheckpoint(sessionId, options = {}) {
   const { body, idempotencyKey } = buildGenerateCheckpointPayload(normalizedSessionId, options);
   const { apiUrl, credential } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
   const response = await checkedTransport(requestMutation)(
-    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints/generate`,
+    `${apiUrl}/api/v1/sessions/${urlPathSegment(normalizedSessionId, { label: "sessionId" })}/checkpoints/generate`,
     {
       operationName: "session-checkpoint-generate",
       credential,