sentinelayer-cli 0.45.0 → 0.46.1

package/src/daemon/ast-parser-layer.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
-import { extname } from "node:path";
+import os from "node:os";
+import { extname, resolve as resolvePath } from "node:path";
 import { promisify } from "node:util";
 
 import { parse } from "@babel/parser";
@@ -149,7 +150,7 @@ async function resolvePythonExecutable() {
     pythonExecutablePromise = (async () => {
       for (const executable of PYTHON_EXECUTABLE_CANDIDATES) {
         try {
-          await execFileAsync(executable, ["--version"], { timeout: 5000 });
+          await execFileAsync(executable, ["--version"], { timeout: 5000, cwd: os.tmpdir() });
           return executable;
         } catch {
           continue;
@@ -193,9 +194,13 @@ async function parsePythonAstSpecifiers(absolutePath = "") {
     };
   }
   try {
-    const { stdout } = await execFileAsync(executable, ["-c", PYTHON_AST_SCRIPT, absolutePath], {
+    // Isolated (-I: no script or working directory on sys.path, no PYTHON* variables) and run from
+    // a neutral directory, so a repository's own ast.py or json.py is never imported; the file to
+    // parse is passed as an argument.
+    const { stdout } = await execFileAsync(executable, ["-I", "-c", PYTHON_AST_SCRIPT, resolvePath(absolutePath)], {
       timeout: 10000,
       maxBuffer: 1024 * 1024,
+      cwd: os.tmpdir(),
     });
     const parsed = JSON.parse(String(stdout || "{}"));
     const specifiers = Array.isArray(parsed.specifiers) ? parsed.specifiers : [];

package/src/daemon/callgraph-overlay.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import fsp from "node:fs/promises";
+import os from "node:os";
 import path, { extname } from "node:path";
 import { promisify } from "node:util";
 
@@ -370,7 +371,7 @@ async function resolvePythonExecutable() {
     pythonExecutablePromise = (async () => {
       for (const executable of PYTHON_EXECUTABLE_CANDIDATES) {
         try {
-          await execFileAsync(executable, ["--version"], { timeout: 5000 });
+          await execFileAsync(executable, ["--version"], { timeout: 5000, cwd: os.tmpdir() });
           return executable;
         } catch {
           continue;
@@ -454,9 +455,13 @@ async function parsePythonCallgraph(absolutePath = "", content = "", normalizedL
     };
   }
   try {
-    const { stdout } = await execFileAsync(executable, ["-c", PYTHON_CALLGRAPH_SCRIPT, absolutePath], {
+    // Isolated (-I: no script or working directory on sys.path, no PYTHON* variables) and run from
+    // a neutral directory, so a repository's own ast.py or json.py is never imported; the file to
+    // parse is passed as an argument.
+    const { stdout } = await execFileAsync(executable, ["-I", "-c", PYTHON_CALLGRAPH_SCRIPT, path.resolve(absolutePath)], {
       timeout: 15000,
       maxBuffer: 1024 * 1024,
+      cwd: os.tmpdir(),
     });
     const parsed = JSON.parse(String(stdout || "{}"));
     return {

package/src/legacy-cli.js

@@ -31,6 +31,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 +118,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) {

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/program-lookup.js

@@ -0,0 +1,54 @@
+import process from "node:process";
+
+// Windows looks up a program named without a path in the working directory before PATH. The CLI
+// runs git, gh, python, npm and other tools by name, often from inside a repository, so it turns
+// that lookup off with NoDefaultCurrentDirectoryInExePath. Node.js spawns through libuv, which
+// honours that variable from libuv 1.48.0 (Node.js 22); an older libuv ignores it. On such a
+// runtime the CLI does not run at all on Windows, rather than run with the lookup on.
+export const MIN_WINDOWS_LIBUV = Object.freeze([1, 48, 0]);
+
+function parseVersion(value) {
+  const parts = String(value || "").split(".");
+  if (parts.length < 2 || parts.length > 3) {
+    return null;
+  }
+  const numbers = parts.map((part) => (/^\d+$/.test(part) ? Number(part) : NaN));
+  return numbers.every(Number.isInteger) ? [...numbers, 0].slice(0, 3) : null;
+}
+
+function atLeast(version, minimum) {
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (version[index] !== minimum[index]) {
+      return version[index] > minimum[index];
+    }
+  }
+  return true;
+}
+
+/**
+ * Turn off working-directory program lookup for this process and the children that inherit its
+ * environment. Returns { ok: false, message } instead when this is Windows and the runtime would
+ * ignore the setting.
+ */
+export function restrictProgramLookupToPath({
+  platform = process.platform,
+  libuv = process.versions.uv,
+  nodeVersion = process.version,
+  env = process.env,
+} = {}) {
+  if (platform !== "win32") {
+    return { ok: true };
+  }
+  const version = parseVersion(libuv);
+  if (!version || !atLeast(version, MIN_WINDOWS_LIBUV)) {
+    return {
+      ok: false,
+      message:
+        `On Windows, sentinelayer-cli needs Node.js 22 or later (libuv ${MIN_WINDOWS_LIBUV.join(".")} or later). ` +
+        `This is Node.js ${nodeVersion} with libuv ${libuv || "unknown"}, which looks up programs in the current ` +
+        "directory before PATH. Upgrade Node.js and run the command again.",
+    };
+  }
+  env.NoDefaultCurrentDirectoryInExePath = "1";
+  return { ok: true };
+}

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/review/local-review.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { buildScrubbedEnv } from "../agents/shared-tools/shell.js";
 import { resolveOutputRoot } from "../config/service.js";
 import { resolveCodebaseIngest } from "../ingest/engine.js";
 import { runSpecBindingChecks } from "./spec-binding.js";
@@ -844,6 +845,13 @@ function buildStaticChecks(ingest = {}) {
   ];
 }
 
+// The repository's own scripts run here (lint, typecheck, format check, tests). Running its code is
+// the point; handing it this machine's credentials is not. SentinelLayer, provider, GitHub, cloud
+// and other secret-looking variables are removed from its environment.
+export function staticCheckEnv(env = process.env) {
+  return { ...buildScrubbedEnv(env), CI: "1", FORCE_COLOR: "0" };
+}
+
 async function executeStaticCheck({ check, targetPath, runDir } = {}) {
   const checksDir = path.join(runDir, "checks");
   await fsp.mkdir(checksDir, { recursive: true });
@@ -853,11 +861,7 @@ async function executeStaticCheck({ check, targetPath, runDir } = {}) {
     cwd: targetPath,
     encoding: "utf-8",
     timeout: STATIC_CHECK_TIMEOUT_MS,
-    env: {
-      ...process.env,
-      CI: "1",
-      FORCE_COLOR: "0",
-    },
+    env: staticCheckEnv(),
   });
 
   const durationMs = Date.now() - startedAt;
@@ -927,6 +931,8 @@ async function executeStaticCheck({ check, targetPath, runDir } = {}) {
   };
 }
 
+export const __localReviewForTests = Object.freeze({ executeStaticCheck });
+
 async function runStaticAnalysisLayer({ targetPath, ingest, runDir, maxFindings = MAX_FINDINGS } = {}) {
   const checks = buildStaticChecks(ingest);
   const results = [];

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,