sentinelayer-cli 0.46.0 → 0.46.2

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.0",
+  "version": "0.46.2",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/agents/agent-id-path.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+
+// An agent id names exactly one entry directly under the directory that holds per-agent files:
+// <run>/agents/<id>.json for an audit run, <session>/agents/<id>.json for a session.
+//
+// The rule is the canonical agent id (canonicalAgentId in src/session/admission-auth.js:
+// lowercase letters, digits, '.', '_' and '-', never starting or ending with '-'), held to a
+// spelling that is also one portable file name:
+// - 1-64 characters, the bound admission already puts on the same ids;
+// - starts with a letter or digit, so it is never '.' or '..';
+// - does not end with '.': Windows drops it, so "abc." and "abc" would name the same file;
+// - is not a Windows device name (refused on every platform).
+// Every id in use fits: built-in audit agents and personas (security, code-quality,
+// ai-governance), ids from --agent (canonicalised before they get here), generated ids
+// (claude-a1b2, claude-3) and daemon ids (senti, scope-engine, audit-orchestrator).
+const AGENT_ID_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9_])?$/;
+// CON, PRN, AUX, NUL, COM1-9 and LPT1-9, with or without an extension.
+const RESERVED_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/;
+// Either separator, on every platform.
+const SEPARATOR = /[\\/]/;
+
+export const AGENT_ID_RULE =
+  "agent id must be 1-64 characters: lowercase letters, digits, '.', '_' or '-', starting with a letter or digit and ending with a letter, digit or '_'.";
+export const AGENT_ID_RESERVED_RULE = "agent id must not be a reserved device name.";
+export const AGENT_ID_ENTRY_RULE = "agent id must name one entry directly under its directory.";
+
+/** The rule `value` breaks, or "" when it is an agent id that can name a file. */
+export function agentIdProblem(value) {
+  const id = typeof value === "string" ? value : "";
+  if (!AGENT_ID_PATTERN.test(id)) return AGENT_ID_RULE;
+  if (RESERVED_DEVICE_NAME.test(id)) return AGENT_ID_RESERVED_RULE;
+  return "";
+}
+
+/**
+ * `<dir>/<agentId><suffix>`, refused unless the result is exactly one entry directly under
+ * `dir` and the id follows the agent id rule. The one-entry check runs first, on the id as
+ * given (no separator, and the resolved path is a direct child of `dir` with that exact name),
+ * so it holds by itself whatever the rule admits.
+ */
+export function resolveAgentIdPath(dir, agentId, suffix = "") {
+  const root = path.resolve(String(dir || "."));
+  const id = typeof agentId === "string" ? agentId : String(agentId ?? "");
+  if (!id) {
+    throw new Error("agentId is required.");
+  }
+  const entry = `${id}${suffix}`;
+  const target = path.resolve(root, entry);
+  if (SEPARATOR.test(entry) || path.dirname(target) !== root || path.basename(target) !== entry) {
+    throw new Error(AGENT_ID_ENTRY_RULE);
+  }
+  const problem = agentIdProblem(id);
+  if (problem) {
+    throw new Error(problem);
+  }
+  return target;
+}

package/src/agents/jules/tools/runtime-audit.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
 import { credentialedRequest, isAuthenticated } from "../../../auth/credential-destinations.js";
+import { urlPathSegment } from "../../../net/url-path.js";
 import { assertPermittedAuditTarget } from "./url-policy.js";
 import { buildScrubbedEnv } from "../../shared-tools/shell.js";
 
@@ -495,7 +496,7 @@ async function callScannerApi(url) {
   }
 
   // Poll for completion (max 90s)
-  const pollUrl = apiUrl + "/api/v1/scan/url/" + scanId;
+  const pollUrl = `${apiUrl}/api/v1/scan/url/${urlPathSegment(scanId, { label: "scanId" })}`;
   for (let attempt = 0; attempt < 30; attempt++) {
     await new Promise(r => setTimeout(r, 3000));
     try {

package/src/ai/aidenid.js

@@ -1,6 +1,7 @@
 import process from "node:process";
 import { authLoginHint } from "../ui/command-hints.js";
 import { isAuthenticated } from "../auth/credential-destinations.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 export const DEFAULT_AIDENID_API_URL = "https://api.aidenid.com";
 
@@ -439,7 +440,7 @@ export async function revokeIdentity({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedIdentityId)}/revoke`,
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedIdentityId, { label: "identityId" })}/revoke`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -482,7 +483,7 @@ export async function listIdentityEvents({
   const requestHeaders = buildReadHeaders({ apiKey, orgId, projectId });
 
   const endpoint = new URL(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedIdentityId)}/events`
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedIdentityId, { label: "identityId" })}/events`
   );
   endpoint.searchParams.set("limit", String(normalizedLimit));
   if (normalizedCursor) {
@@ -530,7 +531,7 @@ export async function getLatestIdentityExtraction({
   const requestHeaders = buildReadHeaders({ apiKey, orgId, projectId });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedIdentityId)}/latest-extraction`,
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedIdentityId, { label: "identityId" })}/latest-extraction`,
     {
       method: "GET",
       headers: requestHeaders,
@@ -595,7 +596,7 @@ export async function createChildIdentity({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedParentIdentityId)}/children`,
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedParentIdentityId, { label: "identityId" })}/children`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -635,7 +636,7 @@ export async function getIdentityLineage({
   const requestHeaders = buildReadHeaders({ apiKey, orgId, projectId });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedIdentityId)}/lineage`,
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedIdentityId, { label: "identityId" })}/lineage`,
     {
       method: "GET",
       headers: requestHeaders,
@@ -686,7 +687,7 @@ export async function revokeIdentityChildren({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/identities/${encodeURIComponent(normalizedIdentityId)}/revoke-children`,
+    `${normalizedApiUrl}/v1/identities/${urlPathSegment(normalizedIdentityId, { label: "identityId" })}/revoke-children`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -781,7 +782,7 @@ export async function verifyDomain({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/domains/${encodeURIComponent(normalizedDomainId)}/verify`,
+    `${normalizedApiUrl}/v1/domains/${urlPathSegment(normalizedDomainId, { label: "domainId" })}/verify`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -828,7 +829,7 @@ export async function freezeDomain({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/domains/${encodeURIComponent(normalizedDomainId)}/freeze`,
+    `${normalizedApiUrl}/v1/domains/${urlPathSegment(normalizedDomainId, { label: "domainId" })}/freeze`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -917,7 +918,7 @@ export async function verifyTarget({
   });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/targets/${encodeURIComponent(normalizedTargetId)}/verify`,
+    `${normalizedApiUrl}/v1/targets/${urlPathSegment(normalizedTargetId, { label: "targetId" })}/verify`,
     {
       method: "POST",
       headers: requestHeaders,
@@ -957,7 +958,7 @@ export async function getTarget({
   const requestHeaders = buildReadHeaders({ apiKey, orgId, projectId });
 
   const response = await fetchImpl(
-    `${normalizedApiUrl}/v1/targets/${encodeURIComponent(normalizedTargetId)}`,
+    `${normalizedApiUrl}/v1/targets/${urlPathSegment(normalizedTargetId, { label: "targetId" })}`,
     {
       method: "GET",
       headers: requestHeaders,

package/src/ai/client.js

@@ -1,4 +1,5 @@
 import { invokeViaProxy, DEFAULT_PROXY_MODEL } from "./proxy.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 const PROVIDER_ENV_KEYS = Object.freeze({
   openai: "OPENAI_API_KEY",
@@ -248,7 +249,7 @@ function buildProviderRequest({ provider, apiKey, model, prompt, stream }) {
 
   const method = stream ? "streamGenerateContent" : "generateContent";
   return {
-    url: `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:${method}`,
+    url: `https://generativelanguage.googleapis.com/v1beta/models/${urlPathSegment(model, { label: "model" })}:${method}`,
     headers: {
       "Content-Type": "application/json",
       "x-goog-api-key": apiKey,

package/src/audit/orchestrator.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { resolveAgentIdPath } from "../agents/agent-id-path.js";
 import { userCredential } from "../auth/credential-destinations.js";
 import { resolveOutputRoot } from "../config/service.js";
 import { createAgentEvent } from "../events/schema.js";
@@ -396,6 +397,11 @@ export async function runAuditOrchestrator({
   const startedAt = Date.now();
   const runDirectory = path.join(outputRoot, "audits", runId);
   const agentsDirectory = path.join(runDirectory, "agents");
+  // Each agent's file is resolved before anything is written: an id that is not one file
+  // directly under the agents directory stops the run here.
+  const agentPaths = new Map(
+    agents.map((agent) => [agent, resolveAgentIdPath(agentsDirectory, agent.id, ".json")])
+  );
   await fsp.mkdir(agentsDirectory, { recursive: true });
   const blackboard = createBlackboard({
     runId,
@@ -754,7 +760,7 @@ export async function runAuditOrchestrator({
       note: `${agent.id} persona finding`,
       confidence,
     });
-    const agentPath = path.join(agentsDirectory, `${agent.id}.json`);
+    const agentPath = agentPaths.get(agent);
     await fsp.writeFile(agentPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
     emitAuditLifecycleEvent(
       onEvent,

package/src/audit/registry.js

@@ -1,6 +1,8 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { agentIdProblem } from "../agents/agent-id-path.js";
+
 export const DEFAULT_AUDIT_AGENT_TOOLS = Object.freeze([
   "FileRead",
   "Grep",
@@ -246,11 +248,17 @@ function mergeRegistry(builtinAgents = [], overrideAgents = []) {
   for (const builtin of builtinAgents) {
     byId.set(builtin.id, { ...builtin });
   }
-  for (const override of overrideAgents) {
+  for (const [index, override] of overrideAgents.entries()) {
     const normalized = normalizeAgentRecord(override);
     if (!normalized.id) {
       continue;
     }
+    // An agent id names the agent's file in every audit run, so the whole registry is refused
+    // before anything is written when one id cannot.
+    const problem = agentIdProblem(normalized.id);
+    if (problem) {
+      throw new Error(`Invalid audit registry file: agents[${index}].id ${JSON.stringify(normalized.id)}: ${problem}`);
+    }
     const existing = byId.get(normalized.id) || {};
     if (!Object.prototype.hasOwnProperty.call(override, "tools")) {
       normalized.tools = Array.isArray(existing.tools) && existing.tools.length > 0

package/src/auth/credential-destinations.js

@@ -20,9 +20,10 @@
 // (src/auth/admission-scope.js) and is never re-bound to the pocket gateway.
 //
 // credentialedRequest(credential, url, init, { fetchImpl }) is the one way to send a credential.
-// It refuses a URL on any other origin, sets the Authorization header itself, and never follows
-// a redirect. An injected transport (fetchImpl) is what it calls once those checks pass. A bare
-// token from an injected auth resolver (tests) is bound to the configured API by credentialFor.
+// It takes the URL as a string, refuses one on any other origin or one whose path is not plain
+// segments, sets the Authorization header itself, and never follows a redirect. An injected
+// transport (fetchImpl) is what it calls once those checks pass. A bare token from an injected
+// auth resolver (tests) is bound to the configured API by credentialFor.
 // tests/unit.credential-census.test.mjs fails on any other place in src/ that builds an
 // Authorization header, reads a raw token, or writes a trust-source variable into process.env.
 
@@ -53,6 +54,45 @@ export class CredentialDestinationRefused extends Error {
   }
 }
 
+/**
+ * A URL on the credential's own origin whose path is not plain segments: a segment that is, or
+ * decodes to, "." or "..", that decodes to something containing "/" or "\", or that does not
+ * decode. Nothing is sent.
+ */
+export class CredentialPathRefused extends CredentialDestinationRefused {
+  constructor(origin) {
+    super(origin);
+    this.message =
+      "Refusing to send your SentinelLayer credential to a URL whose path is not plain segments: " +
+      "each identifier in a URL path must be one segment.";
+    this.name = "CredentialPathRefused";
+    this.code = "CREDENTIAL_PATH_REFUSED";
+  }
+}
+
+/** One raw path segment, decoded once: refused when it is "." or "..", holds "/" or "\", or does not decode. */
+function isUnsafePathSegment(segment) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    return true;
+  }
+  return decoded === "." || decoded === ".." || /[/\\]/.test(decoded);
+}
+
+/**
+ * Whether the raw URL string has a path segment that is not plain, read the way the URL parser
+ * reads an http(s) URL, before it normalizes anything: tabs and newlines dropped, leading and
+ * trailing C0 controls and spaces trimmed, the path after the scheme and authority up to "?" or
+ * "#", and "\" a separator like "/". Each segment is then decoded once (isUnsafePathSegment).
+ */
+function hasUnsafePathSegment(target) {
+  const text = target.replace(/[\t\n\r]/g, "").replace(/^[\u0000-\u0020]+|[\u0000-\u0020]+$/g, "");
+  const afterAuthority = text.replace(/^[a-z][a-z0-9+.-]*:[/\\]*[^/\\?#]*/i, "");
+  return afterAuthority.split(/[?#]/, 1)[0].split(/[/\\]/).some(isUnsafePathSegment);
+}
+
 function originOf(value) {
   try {
     const parsed = new URL(String(value || "").trim());
@@ -161,11 +201,17 @@ export async function assertTrustedApiUrl(url, { context, env, homeDir } = {}) {
   if (origin !== trust.apiOrigin) throw new CredentialDestinationRefused(origin, [trust.apiOrigin]);
 }
 
-/** Refuse sending `credential` anywhere but its own origin. `target` is the exact URL string sent. */
+/**
+ * Refuse sending `credential` anywhere but its own origin, or to a path that is not plain
+ * segments. `target` is the exact URL string sent; a URL object is refused, because its path has
+ * already been normalized and the string that was built can no longer be checked.
+ */
 export function assertCredentialDestination(credential, target) {
   if (!isCredential(credential)) throw new TypeError("A credential from src/auth/credential-destinations.js is required.");
+  if (typeof target !== "string") throw new TypeError("A credentialed request takes its URL as a string, not a URL object.");
   const origin = originOf(target);
-  if (origin !== credential.origin) throw new CredentialDestinationRefused(origin || String(target), [credential.origin]);
+  if (origin !== credential.origin) throw new CredentialDestinationRefused(origin || target, [credential.origin]);
+  if (hasUnsafePathSegment(target)) throw new CredentialPathRefused(origin);
 }
 
 /**
@@ -174,9 +220,9 @@ export function assertCredentialDestination(credential, target) {
  */
 export function checkedTransport(requestImpl) {
   return async (url, options, ...rest) => {
-    const target = String(url); // checked and passed on as the same string
-    if (options?.credential) assertCredentialDestination(options.credential, target);
-    return requestImpl(target, options, ...rest);
+    if (!options?.credential) return requestImpl(String(url), options, ...rest);
+    assertCredentialDestination(options.credential, url); // a string, checked and passed on as is
+    return requestImpl(url, options, ...rest);
   };
 }
 
@@ -188,13 +234,11 @@ function headersWithout(headers, name) {
 /**
  * Send a request carrying `credential`: only to the credential's own origin, with the
  * Authorization header set here, and without following redirects. `fetchImpl` is the transport
- * it calls once those checks pass. The URL is turned into a string once, and that string is both
- * checked and sent.
+ * it calls once those checks pass. The URL is a string, and that string is both checked and sent.
  */
 export async function credentialedRequest(credential, url, init = {}, { fetchImpl = globalThis.fetch } = {}) {
-  const target = String(url);
-  assertCredentialDestination(credential, target);
-  return fetchImpl(target, {
+  assertCredentialDestination(credential, url);
+  return fetchImpl(url, {
     ...init,
     headers: { ...headersWithout(init.headers, "authorization"), Authorization: `Bearer ${tokens.get(credential)}` },
     redirect: "error",

package/src/auth/http.js

@@ -448,6 +448,10 @@ export async function requestJson(
   if (credential && !isCredential(credential)) {
     throw new TypeError("requestJson: credential must come from src/auth/credential-destinations.js.");
   }
+  // Checked here, before any retry or breaker accounting: credentialedRequest takes a URL string.
+  if (credential && typeof url !== "string") {
+    throw new TypeError("requestJson: a credentialed request takes its URL as a string, not a URL object.");
+  }
   // Without a credential, nothing here attaches one: a caller-built Authorization header is refused.
   if (Object.keys(headers || {}).some((name) => /^(?:proxy-)?authorization$/i.test(name))) {
     throw new TypeError("requestJson: send a credential with { credential }, not an Authorization header.");

package/src/auth/service.js

@@ -22,6 +22,7 @@ import {
   writeStoredSession,
 } from "./session-store.js";
 import { authLoginHint } from "../ui/command-hints.js";
+import { urlPathSegment } from "../net/url-path.js";
 
 /** Default maximum wall-clock wait for browser-based CLI auth approval (ms). */
 export const DEFAULT_AUTH_TIMEOUT_MS = 10 * 60 * 1000;
@@ -414,7 +415,7 @@ async function revokeApiToken({ apiUrl, credential, tokenId }) {
   if (!normalizedTokenId) {
     return false;
   }
-  await requestJsonMutation(buildApiPath(apiUrl, `/api/v1/auth/api-tokens/${encodeURIComponent(normalizedTokenId)}`), {
+  await requestJsonMutation(buildApiPath(apiUrl, `/api/v1/auth/api-tokens/${urlPathSegment(normalizedTokenId, { label: "tokenId" })}`), {
     method: "DELETE",
     operationName: "revoke-token",
     credential,
@@ -1055,7 +1056,7 @@ export async function listRuntimeRunEvents({
     ? `?after_event_id=${encodeURIComponent(String(afterEventId))}`
     : "";
   return requestJson(
-    buildApiPath(apiUrl, `/api/v1/runtime/runs/${encodeURIComponent(String(runId || ""))}/events/list${query}`),
+    buildApiPath(apiUrl, `/api/v1/runtime/runs/${urlPathSegment(runId, { label: "runId" })}/events/list${query}`),
     {
       method: "GET",
       credential,
@@ -1099,7 +1100,7 @@ export async function getRuntimeRunStatus({
   runId,
 } = {}) {
   return requestJson(
-    buildApiPath(apiUrl, `/api/v1/runtime/runs/${encodeURIComponent(String(runId || ""))}/status`),
+    buildApiPath(apiUrl, `/api/v1/runtime/runs/${urlPathSegment(runId, { label: "runId" })}/status`),
     {
       method: "GET",
       credential,

package/src/board/evidence-resolvers.js

@@ -24,13 +24,21 @@
  *
  * Every lookup is INJECTED (`run`), so each branch above -- including every failure
  * branch -- is reachable in a test without a network.
+ *
+ * The repo, PR number, sha, branch and ref come from the ticket file. Each is checked for
+ * its role before `run` is called (src/net/gh-api-path.js); a value that does not fit is
+ * refused with an Error, which the gate reports as cannot-verify.
  */
 
+import { ghCommitSha, ghRefSegment, ghRepoSlug } from "../net/gh-api-path.js";
+
 /** Shape a resolver must return. Anything else is treated as indeterminate. */
 const YES = true;
 const NO = false;
 const UNKNOWN = null;
 
+const PR_NUMBER = /^[1-9][0-9]{0,9}$/;
+
 function parseJson(stdout) {
   try {
     return JSON.parse(String(stdout ?? ""));
@@ -52,7 +60,10 @@ export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
   if (typeof run !== "function") throw new TypeError("a run() is required");
 
   async function prMerged({ repo, number }) {
-    const res = await run(["pr", "view", String(number), "--repo", repo, "--json", "state,mergedAt"]);
+    const slug = ghRepoSlug(repo);
+    const pr = String(number);
+    if (!PR_NUMBER.test(pr)) throw new Error("number must be a pull request number.");
+    const res = await run(["pr", "view", pr, "--repo", slug, "--json", "state,mergedAt"]);
     if (!res || !res.ok) return UNKNOWN; // unreachable, missing, or unauthorised
     const data = parseJson(res.stdout);
     if (!data || typeof data.state !== "string") return UNKNOWN;
@@ -63,7 +74,8 @@ export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
   }
 
   async function shaOnBranch({ repo, sha, branch }) {
-    const res = await run(["api", `repos/${repo}/compare/${branch}...${sha}`, "--jq", ".status"]);
+    const basehead = `${ghRefSegment(branch, { label: "branch" })}...${ghCommitSha(sha)}`;
+    const res = await run(["api", `repos/${ghRepoSlug(repo)}/compare/${basehead}`, "--jq", ".status"]);
     if (!res || !res.ok) return UNKNOWN;
     const status = String(res.stdout ?? "").trim();
     // GitHub's compare status, base=branch head=sha:
@@ -75,7 +87,7 @@ export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
   }
 
   async function checkConclusive({ repo, ref, check }) {
-    const res = await run(["api", `repos/${repo}/commits/${ref}/check-runs`, "--jq", ".check_runs"]);
+    const res = await run(["api", `repos/${ghRepoSlug(repo)}/commits/${ghRefSegment(ref)}/check-runs`, "--jq", ".check_runs"]);
     if (!res || !res.ok) return UNKNOWN;
     const runs = parseJson(res.stdout);
     if (!Array.isArray(runs)) return UNKNOWN;

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/ai/identity-lifecycle.js

@@ -38,6 +38,7 @@ import {
   stableTimestampForFile,
   writeArtifact,
 } from "./shared.js";
+import { urlPathSegment } from "../../net/url-path.js";
 
 function maskEmailForDisplay(value) {
   const email = String(value || "").trim();
@@ -471,7 +472,7 @@ identity
         credentialsMissing: resolvedCredentials.missing,
         trackedIdentity,
         curlPreview: [
-          `curl -X POST ${apiUrl}/v1/identities/${encodeURIComponent(identityId)}/revoke \\`,
+          `curl -X POST ${apiUrl}/v1/identities/${urlPathSegment(identityId, { label: "identityId" })}/revoke \\`,
           `  -H \"Authorization: Bearer $AIDENID_API_KEY\" \\`,
           `  -H \"X-Org-Id: $AIDENID_ORG_ID\" \\`,
           `  -H \"X-Project-Id: $AIDENID_PROJECT_ID\" \\`,
@@ -638,7 +639,7 @@ identity
         credentialsMissing: resolvedCredentials.missing,
         parentIdentityTracked: Boolean(parentIdentity),
         curlPreview: [
-          `curl -X POST ${apiUrl}/v1/identities/${encodeURIComponent(parentIdentityId)}/children \\`,
+          `curl -X POST ${apiUrl}/v1/identities/${urlPathSegment(parentIdentityId, { label: "identityId" })}/children \\`,
           `  -H \"Authorization: Bearer $AIDENID_API_KEY\" \\`,
           `  -H \"X-Org-Id: $AIDENID_ORG_ID\" \\`,
           `  -H \"X-Project-Id: $AIDENID_PROJECT_ID\" \\`,
@@ -884,7 +885,7 @@ identity
         credentialsMissing: resolvedCredentials.missing,
         parentIdentityTracked: Boolean(trackedIdentity),
         curlPreview: [
-          `curl -X POST ${apiUrl}/v1/identities/${encodeURIComponent(identityId)}/revoke-children \\`,
+          `curl -X POST ${apiUrl}/v1/identities/${urlPathSegment(identityId, { label: "identityId" })}/revoke-children \\`,
           `  -H \"Authorization: Bearer $AIDENID_API_KEY\" \\`,
           `  -H \"X-Org-Id: $AIDENID_ORG_ID\" \\`,
           `  -H \"X-Project-Id: $AIDENID_PROJECT_ID\" \\`,

package/src/commands/chat.js

@@ -13,6 +13,7 @@ import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-us
 import { resolveOutputRoot } from "../config/service.js";
 import { estimateModelCost } from "../cost/tracker.js";
 import { estimateTokens } from "../cost/tokenizer.js";
+import { normalizeSessionId } from "../session/paths.js";
 
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
@@ -81,7 +82,9 @@ export function registerChatCommand(program) {
         outputDirOverride: options.outputDir,
         env: process.env,
       });
-      const sessionId = String(options.sessionId || "").trim() || createSessionId();
+      // An explicit id names the transcript file under chat/sessions/, so it is held to the session-id rule.
+      const requestedSessionId = String(options.sessionId || "").trim();
+      const sessionId = requestedSessionId ? normalizeSessionId(requestedSessionId) : createSessionId();
       const transcriptPath = path.join(outputRoot, "chat", "sessions", `${sessionId}.jsonl`);
 
       const provider = resolveProvider({