sentinelayer-cli 0.46.0 → 0.46.1

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,

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;