sentinelayer-cli 0.46.0 → 0.46.2

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,12 +7,18 @@ 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";
 const execFileAsync = promisify(execFile);
 
+// Time allowed for one scan of the process table. A busy machine can need longer than the
+// first limit, so a caller that must not guess (the one-listener check in `session listen`)
+// retries once with the longer one before it reports the check as incomplete.
+export const LISTENER_PROCESS_SCAN_TIMEOUT_MS = 3_000;
+export const LISTENER_PROCESS_SCAN_RETRY_TIMEOUT_MS = 10_000;
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -88,7 +94,7 @@ function normalizeProcessRows(rows = []) {
     .filter((row) => Number.isInteger(row.pid) && row.pid > 0 && row.commandLine);
 }
 
-async function listWindowsProcesses() {
+async function listWindowsProcesses({ timeoutMs }) {
   const command = [
     "$ErrorActionPreference = 'Stop';",
     "$rows = Get-CimInstance Win32_Process |",
@@ -99,7 +105,7 @@ async function listWindowsProcesses() {
   const { stdout } = await execFileAsync(
     "powershell.exe",
     ["-NoProfile", "-NonInteractive", "-Command", command],
-    { windowsHide: true, timeout: 3000, maxBuffer: 10 * 1024 * 1024 },
+    { windowsHide: true, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 },
   );
   const text = normalizeString(stdout);
   if (!text) return [];
@@ -107,9 +113,9 @@ async function listWindowsProcesses() {
   return normalizeProcessRows(Array.isArray(parsed) ? parsed : [parsed]);
 }
 
-async function listPosixProcesses() {
+async function listPosixProcesses({ timeoutMs }) {
   const { stdout } = await execFileAsync("ps", ["-eo", "pid=,command="], {
-    timeout: 3000,
+    timeout: timeoutMs,
     maxBuffer: 10 * 1024 * 1024,
   });
   return String(stdout || "")
@@ -121,30 +127,73 @@ async function listPosixProcesses() {
     .filter(Boolean);
 }
 
-async function listProcessTable() {
+// Resolves to the process rows, or rejects when the table cannot be read (a timeout, a
+// missing tool, unreadable output). It never turns a failed read into an empty table.
+async function listProcessTable({ timeoutMs = LISTENER_PROCESS_SCAN_TIMEOUT_MS } = {}) {
+  return process.platform === "win32"
+    ? listWindowsProcesses({ timeoutMs })
+    : listPosixProcesses({ timeoutMs });
+}
+
+// The probes `session listen` uses; replaced only through setListenerProcessProbesForTests.
+let activeListProcessTable = listProcessTable;
+let activeReadProcessCommandLine = readProcessCommandLine;
+
+/**
+ * Test seam: replace the process-table scan and the per-pid command-line read that the
+ * listener commands use. Call with no argument to restore the real probes.
+ */
+export function setListenerProcessProbesForTests({ listProcesses = null, readCommandLine = null } = {}) {
+  activeListProcessTable = listProcesses || listProcessTable;
+  activeReadProcessCommandLine = readCommandLine || readProcessCommandLine;
+}
+
+function processScanFailureReason(error) {
+  const code = normalizeString(error?.code);
+  // execFile kills the scan at its timeout and reports it as killed with no code.
+  if (code === "ETIMEDOUT" || (!code && error?.killed)) return "process_scan_timeout";
+  if (error instanceof SyntaxError) return "process_scan_unreadable";
+  return code ? `process_scan_failed:${code}` : "process_scan_failed";
+}
+
+// One scan of the process table: { ok: true, rows } or { ok: false, reason }.
+async function scanProcessTable(listProcesses, timeoutMs) {
+  let rows;
   try {
-    return process.platform === "win32"
-      ? await listWindowsProcesses()
-      : await listPosixProcesses();
-  } catch {
-    return [];
+    rows = await listProcesses({ timeoutMs });
+  } catch (error) {
+    return { ok: false, reason: processScanFailureReason(error) };
+  }
+  if (!Array.isArray(rows)) {
+    return { ok: false, reason: "process_scan_unreadable" };
   }
+  return { ok: true, rows: normalizeProcessRows(rows) };
 }
 
+/**
+ * Listener processes for this session and agent: { ok: true, matches } when the process
+ * table was read, { ok: false, reason } when it could not be. A failed scan has no
+ * `matches`, so it can never be read as "no listener".
+ */
 export async function listMatchingListenerProcesses(
   sessionId,
   agentId,
   {
     excludePid = process.pid,
-    _listProcesses = listProcessTable,
+    timeoutMs = LISTENER_PROCESS_SCAN_TIMEOUT_MS,
+    _listProcesses = activeListProcessTable,
   } = {},
 ) {
-  const rows = normalizeProcessRows(await _listProcesses());
+  const scan = await scanProcessTable(_listProcesses, timeoutMs);
+  if (!scan.ok) return scan;
   const excluded = Number(excludePid);
-  return rows.filter((row) =>
-    row.pid !== excluded &&
-    listenerCommandLineMatches(row.commandLine, { sessionId, agentId })
-  );
+  return {
+    ok: true,
+    matches: scan.rows.filter((row) =>
+      row.pid !== excluded &&
+      listenerCommandLineMatches(row.commandLine, { sessionId, agentId })
+    ),
+  };
 }
 
 export async function summarizeLocalListenerProcesses(
@@ -152,16 +201,20 @@ export async function summarizeLocalListenerProcesses(
   agentIds = [],
   {
     excludePid = process.pid,
-    _listProcesses = listProcessTable,
+    timeoutMs = LISTENER_PROCESS_SCAN_TIMEOUT_MS,
+    _listProcesses = activeListProcessTable,
   } = {},
 ) {
   const normalizedSessionId = normalizeString(sessionId);
   const uniqueAgentIds = [...new Set((Array.isArray(agentIds) ? agentIds : [])
     .map((agentId) => normalizeString(agentId))
     .filter(Boolean))];
-  const rows = normalizeProcessRows(await _listProcesses());
+  const scan = await scanProcessTable(_listProcesses, timeoutMs);
+  if (!scan.ok) {
+    return { ok: false, reason: scan.reason, sessionId: normalizedSessionId };
+  }
   const excluded = Number(excludePid);
-  const candidates = rows.filter((row) => row.pid !== excluded);
+  const candidates = scan.rows.filter((row) => row.pid !== excluded);
   const agents = uniqueAgentIds.map((agentId) => {
     const matches = candidates
       .filter((row) => listenerCommandLineMatches(row.commandLine, {
@@ -178,6 +231,7 @@ export async function summarizeLocalListenerProcesses(
     };
   });
   return {
+    ok: true,
     sessionId: normalizedSessionId,
     processCount: agents.reduce((sum, agent) => sum + agent.processCount, 0),
     duplicateProcessCount: agents.reduce((sum, agent) => sum + agent.duplicateProcessCount, 0),
@@ -244,13 +298,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) {
@@ -368,12 +421,13 @@ async function listenerStatusFromRecord(
     sessionId,
     agentId,
     recordScope,
-    _readProcessCommandLine = readProcessCommandLine,
+    _readProcessCommandLine = activeReadProcessCommandLine,
   } = {},
 ) {
   const alive = isProcessAlive(record.pid);
   if (!alive) {
     return {
+      state: "not_running",
       running: false,
       pid: null,
       stale: true,
@@ -385,6 +439,7 @@ async function listenerStatusFromRecord(
   const commandLine = await _readProcessCommandLine(record.pid);
   if (!listenerCommandLineMatches(commandLine, { sessionId, agentId })) {
     return {
+      state: "not_running",
       running: false,
       pid: null,
       stale: true,
@@ -397,6 +452,7 @@ async function listenerStatusFromRecord(
     };
   }
   return {
+    state: "running",
     running: true,
     pid: Number(record.pid),
     stale: false,
@@ -407,14 +463,21 @@ async function listenerStatusFromRecord(
   };
 }
 
+/**
+ * Whether a listener for this session and agent is running on this machine. `state` is
+ * "running", "not_running" or "unknown". A live pid record whose command line matches is
+ * "running" without a scan. Otherwise the process table decides, and when it cannot be read
+ * the answer is "unknown" (`running: null`, with `reason`), never "not_running".
+ */
 export async function getListenerProcessStatus(
   sessionId,
   agentId,
   {
     targetPath = process.cwd(),
     homeDir = os.homedir(),
-    _readProcessCommandLine = readProcessCommandLine,
-    _listProcesses = listProcessTable,
+    scanTimeoutMs = LISTENER_PROCESS_SCAN_TIMEOUT_MS,
+    _readProcessCommandLine = activeReadProcessCommandLine,
+    _listProcesses = activeListProcessTable,
   } = {},
 ) {
   const records = [
@@ -441,11 +504,24 @@ export async function getListenerProcessStatus(
     }
     staleStatuses.push(status);
   }
-  const matchingProcesses = await listMatchingListenerProcesses(sessionId, agentId, {
+  const scan = await listMatchingListenerProcesses(sessionId, agentId, {
+    timeoutMs: scanTimeoutMs,
     _listProcesses,
   });
+  if (!scan.ok) {
+    return {
+      state: "unknown",
+      running: null,
+      pid: null,
+      reason: scan.reason,
+      record: staleStatuses[0]?.record || null,
+      listenerKey: normalizeListenerProcessKey(agentId),
+    };
+  }
+  const matchingProcesses = scan.matches;
   if (matchingProcesses.length > 0) {
     return {
+      state: "running",
       running: true,
       pid: matchingProcesses[0].pid,
       stale: false,
@@ -459,6 +535,7 @@ export async function getListenerProcessStatus(
   }
   if (staleStatuses.length === 0) {
     return {
+      state: "not_running",
       running: false,
       pid: null,
       stale: false,
@@ -469,6 +546,10 @@ export async function getListenerProcessStatus(
   return staleStatuses[0];
 }
 
+/**
+ * Stops every listener process the scan finds for this session and agent. When the process
+ * table cannot be read it stops nothing and returns { ok: false, reason }.
+ */
 export async function stopMatchingListenerProcesses(
   sessionId,
   agentId,
@@ -476,13 +557,17 @@ export async function stopMatchingListenerProcesses(
     excludePid = process.pid,
     timeoutMs = 3000,
     pollIntervalMs = 100,
-    _listProcesses = listProcessTable,
+    scanTimeoutMs = LISTENER_PROCESS_SCAN_TIMEOUT_MS,
+    _listProcesses = activeListProcessTable,
   } = {},
 ) {
-  const matches = await listMatchingListenerProcesses(sessionId, agentId, {
+  const scan = await listMatchingListenerProcesses(sessionId, agentId, {
     excludePid,
+    timeoutMs: scanTimeoutMs,
     _listProcesses,
   });
+  if (!scan.ok) return scan;
+  const matches = scan.matches;
   const results = [];
   for (const match of matches) {
     const result = await requestListenerProcessStop(match.pid, {
@@ -497,6 +582,7 @@ export async function stopMatchingListenerProcesses(
   }
   const failed = results.filter((result) => !result.stopped);
   return {
+    ok: true,
     matches,
     results,
     stoppedCount: results.filter((result) => result.stopped).length,

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;