sentinelayer-cli 0.46.1 → 0.46.3

package/bin/create-sentinelayer.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.js";
+import { bootstrapCli } from "../src/cli-bootstrap.js";
 
-await runCli();
+await bootstrapCli();

package/bin/sentinelayer-cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.js";
+import { bootstrapCli } from "../src/cli-bootstrap.js";
 
-await runCli();
+await bootstrapCli();

package/bin/sl.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.js";
+import { bootstrapCli } from "../src/cli-bootstrap.js";
 
-await runCli();
+await bootstrapCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.46.1",
+  "version": "0.46.3",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/cli-bootstrap.js

@@ -0,0 +1,20 @@
+import process from "node:process";
+
+import { restrictProgramLookupToPath } from "./program-lookup.js";
+
+/**
+ * Entry for the bin scripts. Checks the runtime before the rest of the CLI is loaded: importing
+ * cli.js loads every command module, and some modules do work as they load (for example, creating
+ * ~/.sentinelayer), so this module and program-lookup.js are the only ones a bin script imports
+ * statically. runCli repeats the check for callers that import cli.js directly.
+ */
+export async function bootstrapCli() {
+  const programLookup = restrictProgramLookupToPath();
+  if (!programLookup.ok) {
+    console.error(programLookup.message);
+    process.exitCode = 1;
+    return;
+  }
+  const { runCli } = await import("./cli.js");
+  await runCli();
+}

package/src/cli.js

@@ -244,7 +244,9 @@ export async function buildCliProgram({
 
 export async function runCli(rawArgs = process.argv.slice(2)) {
   // Programs named without a path come from PATH only, never from the working directory, before
-  // anything is spawned. On a Windows runtime that cannot guarantee that, nothing runs.
+  // anything is spawned. On a Windows runtime that cannot guarantee that, nothing runs. The bin
+  // scripts check this before loading this module (cli-bootstrap.js); here it covers callers that
+  // import runCli directly.
   const programLookup = restrictProgramLookupToPath();
   if (!programLookup.ok) {
     console.error(programLookup.message);

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,
@@ -5149,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) || {};
@@ -5176,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: [],
           };
         }
@@ -5231,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
@@ -5484,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.`,
@@ -5494,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)),
           );
@@ -5504,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 }]
               : []),

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";
@@ -3764,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/session/listener-process.js

@@ -13,6 +13,12 @@ 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();
 }
@@ -34,6 +40,31 @@ function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// The CLI's entry points as package.json "bin" declares them (a test keeps the two in step):
+// the scripts node runs, and the command names npm links to them.
+const CLI_ENTRY_SCRIPTS = ["create-sentinelayer.js", "sentinelayer-cli.js", "sl.js"];
+const CLI_COMMAND_NAMES = ["create-sentinelayer", "sentinel", "sentinelayer-cli", "sl-cli", "slc", "sl"];
+
+/**
+ * The one test of "this command line runs this CLI": an argument that is a path ending in an
+ * entry point (a path separator, the entry name, then the end of the argument). So
+ * `.../bin/create-sentinelayer.js` counts, but `xcreate-sentinelayer.js`,
+ * `create-sentinelayer.json` and a directory named after a command do not.
+ *
+ * On POSIX, npm links each command name to its script and the kernel hands node the link path
+ * (`node /usr/local/bin/sl ...`), so the command names count there too. On Windows npm's shims
+ * start node on the script itself, and the sh shim Git Bash runs stays alive as node's parent
+ * with only the command name on its command line, so there only the scripts count.
+ *
+ * The pattern is valid in JavaScript and in .NET (the Windows scan runs it in PowerShell), and
+ * writes its quotes as \x22 and \x27 so it can sit inside a quoted PowerShell string.
+ */
+function cliEntryPattern(platform) {
+  const entries =
+    platform === "win32" ? CLI_ENTRY_SCRIPTS : [...CLI_ENTRY_SCRIPTS, ...CLI_COMMAND_NAMES];
+  return `[\\\\/](?:${entries.map(escapeRegExp).join("|")})(?=$|[\\s\\x22\\x27])`;
+}
+
 function commandLineFlagValueMatches(commandLine, flagName, expectedValue) {
   const expected = normalizeString(expectedValue).toLowerCase();
   if (!expected) return { found: false, matches: true };
@@ -52,15 +83,20 @@ function commandLineFlagValueMatches(commandLine, flagName, expectedValue) {
   return { found, matches: false };
 }
 
-function listenerCommandLineMatches(commandLine, { sessionId = "", agentId = "" } = {}) {
+/**
+ * Whether a command line is `session listen` for this session and agent, run through any of
+ * this CLI's entry points. `platform` is the system the command line was read on.
+ */
+export function listenerCommandLineMatches(
+  commandLine,
+  { sessionId = "", agentId = "", platform = process.platform } = {},
+) {
   const rawCommandLine = normalizeString(commandLine);
   const normalized = normalizeCommandLine(rawCommandLine);
   if (!normalized) return false;
   const normalizedSessionId = normalizeString(sessionId).toLowerCase();
   const normalizedAgentId = normalizeString(agentId).toLowerCase();
-  const hasCliEntry =
-    normalized.includes("sentinelayer-cli") ||
-    /[\\/](?:sl|sentinelayer-cli)\.js\b/.test(normalized);
+  const hasCliEntry = new RegExp(cliEntryPattern(platform)).test(normalized);
   const sessionFlagMatch = commandLineFlagValueMatches(rawCommandLine, "session", normalizedSessionId);
   const agentFlagMatch = commandLineFlagValueMatches(rawCommandLine, "agent", normalizedAgentId);
   return (
@@ -88,18 +124,18 @@ 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 |",
-    "Where-Object { $_.CommandLine -and ($_.CommandLine -match 'sentinelayer-cli|[\\\\/](sl|sentinelayer-cli)\\.js') } |",
+    `Where-Object { $_.CommandLine -and ($_.CommandLine -match '${cliEntryPattern("win32")}') } |`,
     "Select-Object ProcessId,CommandLine;",
     "if ($rows) { $rows | ConvertTo-Json -Compress }",
   ].join(" ");
   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 +143,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 +157,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 +231,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 +261,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),
@@ -367,12 +451,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,
@@ -384,6 +469,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,
@@ -396,6 +482,7 @@ async function listenerStatusFromRecord(
     };
   }
   return {
+    state: "running",
     running: true,
     pid: Number(record.pid),
     stale: false,
@@ -406,14 +493,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 = [
@@ -440,11 +534,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,
@@ -458,6 +565,7 @@ export async function getListenerProcessStatus(
   }
   if (staleStatuses.length === 0) {
     return {
+      state: "not_running",
       running: false,
       pid: null,
       stale: false,
@@ -468,6 +576,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,
@@ -475,13 +587,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, {
@@ -496,6 +612,7 @@ export async function stopMatchingListenerProcesses(
   }
   const failed = results.filter((result) => !result.stopped);
   return {
+    ok: true,
     matches,
     results,
     stoppedCount: results.filter((result) => result.stopped).length,