sentinelayer-cli 0.46.4 → 0.48.0

package/src/audit/persona-loop.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 
 import { createMultiProviderApiClient } from "../ai/client.js";
 import { serializeProxyError } from "../ai/proxy.js";
@@ -376,6 +377,7 @@ export function createIsolatedPersonaContext({
   runId = "",
   rootPath = ".",
   artifactDir = "",
+  outputFs,
   provider = null,
   budget = {},
   onEvent = null,
@@ -384,6 +386,7 @@ export function createIsolatedPersonaContext({
   isolation = DEFAULT_ISOLATION_MODE,
   eventContext = null,
 } = {}) {
+  if (artifactDir) requireOutputFileSystem(outputFs);
   const normalizedAgent = normalizeAuditPersona(agent || {});
   const resolvedRootPath = path.resolve(String(rootPath || "."));
   const resolvedRunId =
@@ -399,6 +402,7 @@ export function createIsolatedPersonaContext({
     budget: loopBudget,
     runId: resolvedRunId,
     artifactDir,
+    outputFs,
     onEvent,
   });
   const emitter = (event, payload = {}) => {
@@ -701,6 +705,7 @@ async function runSinglePersonaAgenticLoop({
   sharedContext = null,
   hybridContext = null,
   artifactDir = "",
+  outputFs,
   provider = null,
   budget = {},
   maxTurns = null,
@@ -722,6 +727,7 @@ async function runSinglePersonaAgenticLoop({
     runId: requestedRunId,
     rootPath: resolvedRootPath,
     artifactDir,
+    outputFs,
     provider,
     budget,
     onEvent,
@@ -1053,6 +1059,7 @@ function summarizeSwarmStatus(results = []) {
 }
 
 export async function runPersonaAgenticLoop(options = {}) {
+  if (options.artifactDir) requireOutputFileSystem(options.outputFs);
   const {
     agent,
     rootPath,

package/src/audit/replay.js

@@ -1,4 +1,4 @@
-import fsp from "node:fs/promises";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 import path from "node:path";
 
 function normalizeString(value) {
@@ -87,15 +87,17 @@ export function compareAuditReports(baseReport = {}, candidateReport = {}) {
 }
 
 export async function writeAuditComparisonArtifact({
+  outputFs,
   baseReport = {},
   candidateReport = {},
   outputDirectory = "",
 } = {}) {
+  requireOutputFileSystem(outputFs);
   const resolvedOutputDirectory = path.resolve(String(outputDirectory || "."));
   const comparison = compareAuditReports(baseReport, candidateReport);
   const fileName = `AUDIT_COMPARISON_${comparison.baseRunId}_vs_${comparison.candidateRunId}.json`;
   const outputPath = path.join(resolvedOutputDirectory, fileName);
-  await fsp.writeFile(outputPath, `${JSON.stringify(comparison, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(outputPath, `${JSON.stringify(comparison, null, 2)}\n`, "utf-8");
   return {
     comparison,
     outputPath,

package/src/auth/gate.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 import { resolveActiveAuthSession } from "./service.js";
+import { readStoredSessionMetadata } from "./session-store.js";
 import { resolveAgentAdmissionTarget } from "../session/admission-auth.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { isAuthenticated } from "./credential-destinations.js";
@@ -16,6 +17,8 @@ import { isAuthenticated } from "./credential-destinations.js";
  * - auth login, auth status, auth --help
  * - --help, --version, -h, -v
  * - config (read-only config inspection)
+ * - skills install/list (local packaged files only)
+ * - judge check (validates a local verdict file; sends nothing)
  *
  * All other commands require a valid session.
  * If not authenticated, prints instructions and exits.
@@ -30,7 +33,7 @@ const AUTH_BYPASS_COMMANDS = new Set([
   "-v",
 ]);
 
-// Commands that work without auth (read-only, no API calls)
+// Commands that work without auth (local only, no API calls)
 const NO_AUTH_REQUIRED = new Set([
   "config",    // local config inspection
 ]);
@@ -330,6 +333,25 @@ function isAuthenticatedSessionValid(session) {
   return true;
 }
 
+/**
+ * A help request a newcomer can make before signing in (`sl session --help`, `sl session say --help`): the help flag
+ * is the LAST argument and every argument before it is a plain word (command, subcommand, positional). Then no option
+ * can take "--help" as its value (`--message-file --help` stays gated), so Commander prints help and runs nothing.
+ * The caller applies it only to Commander-dispatched commands. Tokens are judged exactly as Commander will see them,
+ * never trimmed: `" --help"` is message text to Commander, so it must not skip the gate either.
+ *
+ * @param {string[]} args - CLI arguments (after normalization)
+ * @returns {boolean}
+ */
+export function isHelpOnlyInvocation(args = []) {
+  const list = Array.isArray(args) ? args : [];
+  const last = list[list.length - 1];
+  if (last !== "--help" && last !== "-h") {
+    return false;
+  }
+  return list.slice(0, -1).every((arg) => typeof arg === "string" && arg !== "" && !arg.startsWith("-"));
+}
+
 /**
  * Check if the current command requires authentication.
  * Returns true if auth is required but user is not logged in.
@@ -348,6 +370,16 @@ export async function checkAuthGate(args) {
     return { authenticated: true, session: null, bypassReason: "no_auth_required", failureReason: null };
   }
 
+  // These two commands only inspect/copy packaged files. Future skills subcommands stay gated.
+  if (args[0] === "skills" && (args[1] === "install" || args[1] === "list")) {
+    return { authenticated: true, session: null, bypassReason: "local_skills", failureReason: null };
+  }
+
+  // Validating a verdict file is local; `judge verdict` sends, so it stays gated.
+  if (args[0] === "judge" && args[1] === "check") {
+    return { authenticated: true, session: null, bypassReason: "local_judge_check", failureReason: null };
+  }
+
   if (isSessionNoAuthCommand(args)) {
     return { authenticated: true, session: null, bypassReason: "session_no_auth_required", failureReason: null };
   }
@@ -378,7 +410,9 @@ export async function checkAuthGate(args) {
         resolveError = "session_invalid";
       }
     } else {
-      resolveError = "no_session";
+      // A keyring/decryption failure leaves the metadata intact. That is not
+      // absence, and recommending logout would destroy recoverable sign-in.
+      resolveError = (await readStoredSessionMetadata()) ? "session_token_missing" : "no_session";
     }
   } catch (error) {
     resolveError = error instanceof Error ? `session_read_error: ${error.message}` : "session_read_error";
@@ -405,15 +439,19 @@ export function printAuthRequired(failureReason = null) {
   if (reason === "session_expired") {
     console.error("  Your stored session has expired. Log in again:");
   } else if (reason === "session_token_missing") {
-    console.error("  Your session metadata is present but the token is missing");
-    console.error("  (likely a keyring read failure or mismatched storage).");
+    console.error("  Your session metadata is present but its credential cannot be read.");
+    console.error("  Check the current user/home, keyring, encryption key and file permissions.");
+    console.error("  Your stored credentials were not cleared; repair storage before signing in again.");
     console.error("");
-    console.error("  " + pc.yellow("Fix:") + " log out to clear the stale metadata, then log in:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    process.exitCode = 1;
+    return;
   } else if (reason && reason.startsWith("session_read_error")) {
     console.error("  Session read failed: " + pc.yellow(reason.replace(/^session_read_error:\s*/, "")));
-    console.error("  Log out and back in to reset local state:");
-    console.error("    " + pc.cyan("sentinelayer-cli auth logout"));
+    console.error("  Check the current user/home and credential-file permissions.");
+    console.error("  Your stored credentials were not cleared; do not log out to repair a read error.");
+    console.error("");
+    process.exitCode = 1;
+    return;
   } else {
     console.error("  Log in to SentinelLayer to use CLI commands:");
   }

package/src/auth/service.js

@@ -7,6 +7,7 @@ import open from "open";
 import { loadConfig } from "../config/service.js";
 import { scopedAdmissionAuth } from "./admission-scope.js";
 import {
+  CredentialDestinationRefused,
   DEFAULT_API_URL,
   assertTrustedApiUrl,
   credentialFor,
@@ -453,6 +454,7 @@ async function rotateStoredApiTokenIfNeeded({
       tokenPrefix: issued.token_prefix || null,
       tokenExpiresAt: issued.expires_at || null,
       user: session.user,
+      aidenid: session.aidenid,
     },
     { homeDir }
   );
@@ -490,7 +492,8 @@ async function rotateStoredApiTokenIfNeeded({
  *   tokenTtlDays?: number,
  *   ide?: string,
  *   cliVersion?: string,
- *   homeDir?: string
+ *   homeDir?: string,
+ *   onAuthorize?: (details: { authorizeUrl: string, browserOpened: boolean }) => void | Promise<void>
  * }} [options]
  * @returns {Promise<{
  *   apiUrl: string,
@@ -521,6 +524,7 @@ export async function loginAndPersistSession({
   ide = DEFAULT_IDE_NAME,
   cliVersion = "",
   homeDir,
+  onAuthorize = () => {},
 } = {}) {
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
   // The token this flow issues is the user's, so the API that issues it must be the configured
@@ -548,6 +552,10 @@ export async function loginAndPersistSession({
     }
   }
 
+  // Headless hosts must receive the URL before approval polling can complete.
+  // The command renders this on stderr in JSON mode, keeping stdout parseable.
+  await onAuthorize({ authorizeUrl, browserOpened });
+
   const approval = await pollCliAuthSession({
     apiUrl,
     sessionId: String(session.session_id || "").trim(),
@@ -768,7 +776,8 @@ export async function resolveActiveAuthSession({
  *   homeDir?: string
  * }} [options]
  * @returns {Promise<{
- *   authenticated: boolean,
+ *   authenticated: boolean | null,
+ *   validation: "none" | "not_checked" | "verified" | "rejected" | "unavailable" | "storage_unavailable",
  *   apiUrl: string,
  *   source: string | null,
  *   storage: string | null,
@@ -805,20 +814,25 @@ export async function getAuthStatus({
   });
 
   if (!session) {
+    // Encrypted metadata can survive a missing/unreadable key or keyring.
+    // Distinguish recoverable storage from actual absence without creating a
+    // replacement key, validating remotely, or claiming authentication.
+    const stored = await readStoredSessionMetadata({ homeDir });
     return {
-      authenticated: false,
+      authenticated: stored ? null : false,
+      validation: stored ? "storage_unavailable" : "none",
       apiUrl: await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir }),
-      source: null,
-      storage: null,
-      user: null,
-      aidenid: null,
+      source: stored ? "storage_unknown" : null,
+      storage: stored?.storage || null,
+      user: stored ? normalizeUser(stored.user || {}) : null,
+      aidenid: stored?.aidenid || null,
       remoteUser: null,
       remoteError: null,
       rotated: false,
-      tokenExpiresAt: null,
-      tokenPrefix: null,
-      tokenId: null,
-      filePath: null,
+      tokenExpiresAt: stored?.tokenExpiresAt || null,
+      tokenPrefix: stored?.tokenPrefix || null,
+      tokenId: stored?.tokenId || null,
+      filePath: stored?.filePath || null,
     };
   }
 
@@ -829,12 +843,12 @@ export async function getAuthStatus({
       remoteUser = normalizeUser(await fetchCurrentUser({ apiUrl: session.apiUrl, credential: session.credential }));
     } catch (error) {
       remoteError =
-        error instanceof SentinelayerApiError
+        error instanceof SentinelayerApiError || error instanceof CredentialDestinationRefused
           ? {
               code: error.code,
               message: error.message,
-              status: error.status,
-              requestId: error.requestId,
+              status: error instanceof CredentialDestinationRefused ? 403 : error.status,
+              requestId: error.requestId || null,
             }
           : {
               code: "UNKNOWN",
@@ -845,8 +859,13 @@ export async function getAuthStatus({
     }
   }
 
+  const validationUnavailable = remoteError && (
+    [408, 425, 429, 499].includes(remoteError.status) || remoteError.status >= 500
+  );
   return {
-    authenticated: !remoteError,
+    // Unknown remote health is neither a successful validation nor a logout.
+    authenticated: validationUnavailable ? null : !remoteError,
+    validation: validationUnavailable ? "unavailable" : remoteError ? "rejected" : checkRemote ? "verified" : "not_checked",
     apiUrl: session.apiUrl,
     source: session.source,
     storage: session.storage,

package/src/auth/session-store.js

@@ -19,6 +19,19 @@ const SESSION_WARNING_ALLOWED_FIELDS = new Set([
 ]);
 const emittedSessionWarningKeys = new Set();
 let keytarClientOverrideForTests;
+let sessionOperationTail = Promise.resolve();
+
+// A store operation spans metadata, keyring and file publication/cleanup. Reads
+// can migrate plaintext too. Keep that transaction in order within this module;
+// serializing only rename would still permit stale migrations and logout races.
+// One queue also covers path aliases and keyring accounts shared across homes.
+// Other processes still rely on the existing key publication and bounded retries.
+function runSessionOperation(operation) {
+  const result = sessionOperationTail.then(operation);
+  // A failed operation must not poison the queue or retain returned credentials.
+  sessionOperationTail = result.then(() => undefined, () => undefined);
+  return result;
+}
 
 function nowIso() {
   return new Date().toISOString();
@@ -135,60 +148,68 @@ function resolveLegacyCredentialsKeyPath({ homeDir } = {}) {
   return path.join(resolvedHome, ".sentinelayer", "credentials.key");
 }
 
-async function loadOrCreateFileKey({ homeDir } = {}) {
-  const keyPath = resolveCredentialsKeyPath({ homeDir });
-  const legacyKeyPath = resolveLegacyCredentialsKeyPath({ homeDir });
-  try {
-    const raw = await fsp.readFile(keyPath, "utf-8");
-    const key = Buffer.from(String(raw || "").trim(), "base64");
-    if (key.length === 32) {
-      return key;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+async function readFileKeyAt(keyPath) {
+  // Exclusive-create fallback filesystems may expose a partially written key.
+  // Retry that bounded race, but never replace an invalid or unreadable key.
+  for (let attempt = 0; ; attempt += 1) {
+    let raw;
+    try {
+      raw = await fsp.readFile(keyPath, "utf-8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
       throw error;
     }
-  }
-
-  try {
-    const legacyRaw = await fsp.readFile(legacyKeyPath, "utf-8");
-    const legacyKey = Buffer.from(String(legacyRaw || "").trim(), "base64");
-    if (legacyKey.length === 32) {
-      await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-      await fsp.writeFile(keyPath, legacyKey.toString("base64"), { encoding: "utf-8", mode: 0o600 });
-      try {
-        await fsp.chmod(keyPath, 0o600);
-      } catch {
-        // Windows does not reliably support POSIX chmod semantics.
-      }
-      let verified = false;
-      try {
-        const verifyRaw = await fsp.readFile(keyPath, "utf-8");
-        const verifyKey = Buffer.from(String(verifyRaw || "").trim(), "base64");
-        verified = verifyKey.length === 32 && verifyKey.equals(legacyKey);
-      } catch {
-        verified = false;
-      }
-      if (verified) {
-        await fsp.rm(legacyKeyPath, { force: true });
-      }
-      return legacyKey;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
+    const encoded = String(raw || "").trim();
+    const key = Buffer.from(encoded, "base64");
+    if (key.length === 32 && key.toString("base64") === encoded) return key;
+    if (attempt >= 5) {
+      const error = new Error("Stored credential encryption key is invalid; it was not replaced.");
+      error.code = "CREDENTIALS_KEY_INVALID";
       throw error;
     }
+    await delayMilliseconds(20);
   }
+}
 
-  const key = crypto.randomBytes(32);
+async function readFileKey({ homeDir } = {}) {
+  return (await readFileKeyAt(resolveCredentialsKeyPath({ homeDir }))) ||
+    (await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir })));
+}
+
+async function loadOrCreateFileKey({ homeDir } = {}) {
+  const keyPath = resolveCredentialsKeyPath({ homeDir });
+  const existing = await readFileKeyAt(keyPath);
+  if (existing) return existing;
+  const legacyKey = await readFileKeyAt(resolveLegacyCredentialsKeyPath({ homeDir }));
+  const key = legacyKey || crypto.randomBytes(32);
+  const encoded = key.toString("base64");
   await fsp.mkdir(path.dirname(keyPath), { recursive: true, mode: 0o700 });
-  await fsp.writeFile(keyPath, key.toString("base64"), { encoding: "utf-8", mode: 0o600 });
+  const tmpPath = `${keyPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
   try {
-    await fsp.chmod(keyPath, 0o600);
-  } catch {
-    // Windows does not reliably support POSIX chmod semantics.
+    await fsp.writeFile(tmpPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+    await syncFile(tmpPath);
+    try {
+      // Publish complete bytes once. Every concurrent writer then uses the winner.
+      await fsp.link(tmpPath, keyPath);
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        if (!["ENOTSUP", "ENOSYS", "EXDEV", "EPERM"].includes(error?.code)) throw error;
+        try {
+          await fsp.writeFile(keyPath, encoded, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+        } catch (fallbackError) {
+          if (fallbackError?.code !== "EEXIST") throw fallbackError;
+        }
+      }
+    }
+    const persisted = await readFileKeyAt(keyPath);
+    if (!persisted) throw new Error("Credential encryption key could not be persisted.");
+    await syncFile(keyPath);
+    await syncDirectory(path.dirname(keyPath));
+    // Keep the legacy key: deleting it can race a read-only legacy reader.
+    return persisted;
+  } finally {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
   }
-  return key;
 }
 
 function encryptToken(token, key) {
@@ -540,7 +561,11 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
     return null;
   }
   try {
-    const key = await loadOrCreateFileKey({ homeDir });
+    const key = await readFileKey({ homeDir });
+    if (!key) {
+      emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", { reason: "key_missing", source: "file-encrypted" });
+      return null;
+    }
     const token = decryptToken(
       {
         tokenEncrypted: metadata.tokenEncrypted,
@@ -550,7 +575,13 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
       key
     );
     return token || null;
-  } catch {
+  } catch (error) {
+    emitSessionWarning("FILE_CREDENTIAL_UNAVAILABLE", {
+      reason: error?.code === "EACCES" || error?.code === "EPERM"
+        ? "key_unreadable"
+        : error?.code === "CREDENTIALS_KEY_INVALID" ? "key_invalid" : "decryption_failed",
+      source: "file-encrypted",
+    });
     return null;
   }
 }
@@ -582,6 +613,11 @@ async function tryDecryptFileToken({ metadata, homeDir }) {
  * }>}
  */
 export async function readStoredSession({ homeDir } = {}) {
+  const options = { homeDir: resolveHomeDir(homeDir) };
+  return runSessionOperation(() => readStoredSessionUnlocked(options));
+}
+
+async function readStoredSessionUnlocked({ homeDir } = {}) {
   const { filePath, metadata } = await readMetadata({ homeDir });
   if (!metadata) {
     return null;
@@ -693,6 +729,11 @@ export async function readStoredSession({ homeDir } = {}) {
  * }>}
  */
 export async function readStoredSessionMetadata({ homeDir } = {}) {
+  const options = { homeDir: resolveHomeDir(homeDir) };
+  return runSessionOperation(() => readStoredSessionMetadataUnlocked(options));
+}
+
+async function readStoredSessionMetadataUnlocked({ homeDir } = {}) {
   const { filePath, metadata } = await readMetadata({ homeDir });
   if (!metadata) {
     return null;
@@ -722,6 +763,7 @@ export async function readStoredSessionMetadata({ homeDir } = {}) {
  *   tokenPrefix?: string | null,
  *   tokenExpiresAt?: string | null,
  *   user?: Record<string, unknown>
+ *   aidenid?: Record<string, unknown> | null
  * }} [session]
  * @param {{ homeDir?: string }} [options]
  * @returns {Promise<{
@@ -754,8 +796,18 @@ export async function writeStoredSession(
     tokenPrefix = null,
     tokenExpiresAt = null,
     user = {},
+    aidenid = null,
   } = {},
   { homeDir } = {}
+) {
+  const session = { apiUrl, token, tokenId, tokenPrefix, tokenExpiresAt, user, aidenid };
+  const options = { homeDir: resolveHomeDir(homeDir) };
+  return runSessionOperation(() => writeStoredSessionUnlocked(session, options));
+}
+
+async function writeStoredSessionUnlocked(
+  { apiUrl, token, tokenId, tokenPrefix, tokenExpiresAt, user, aidenid },
+  { homeDir }
 ) {
   const normalizedApiUrl = String(apiUrl || "").trim();
   const normalizedToken = String(token || "").trim();
@@ -778,6 +830,7 @@ export async function writeStoredSession(
     tokenPrefix,
     tokenExpiresAt,
     user: normalizeUser(user),
+    aidenid,
     createdAt: existingMetadata?.createdAt || updatedAt,
     updatedAt,
   });
@@ -817,6 +870,11 @@ export async function writeStoredSession(
  * @returns {Promise<{ filePath: string, hadSession: boolean }>}
  */
 export async function clearStoredSession({ homeDir } = {}) {
+  const options = { homeDir: resolveHomeDir(homeDir) };
+  return runSessionOperation(() => clearStoredSessionUnlocked(options));
+}
+
+async function clearStoredSessionUnlocked({ homeDir } = {}) {
   const { filePath, metadata } = await readMetadata({ homeDir });
   if (metadata && metadata.storage === "keyring") {
     const keytar = await loadKeytarClient({ allowImplicit: true });

package/src/board/evidence-resolvers.js

@@ -30,7 +30,7 @@
  * refused with an Error, which the gate reports as cannot-verify.
  */
 
-import { ghCommitSha, ghRefSegment, ghRepoSlug } from "../net/gh-api-path.js";
+import { ghCheckRunsApiPath, ghCompareApiPath, ghRepoSlug } from "../net/gh-api-path.js";
 
 /** Shape a resolver must return. Anything else is treated as indeterminate. */
 const YES = true;
@@ -74,8 +74,7 @@ export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
   }
 
   async function shaOnBranch({ repo, sha, branch }) {
-    const basehead = `${ghRefSegment(branch, { label: "branch" })}...${ghCommitSha(sha)}`;
-    const res = await run(["api", `repos/${ghRepoSlug(repo)}/compare/${basehead}`, "--jq", ".status"]);
+    const res = await run(["api", ghCompareApiPath({ repo, branch, sha }), "--jq", ".status"]);
     if (!res || !res.ok) return UNKNOWN;
     const status = String(res.stdout ?? "").trim();
     // GitHub's compare status, base=branch head=sha:
@@ -87,7 +86,7 @@ export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
   }
 
   async function checkConclusive({ repo, ref, check }) {
-    const res = await run(["api", `repos/${ghRepoSlug(repo)}/commits/${ghRefSegment(ref)}/check-runs`, "--jq", ".check_runs"]);
+    const res = await run(["api", ghCheckRunsApiPath({ repo, ref }), "--jq", ".check_runs"]);
     if (!res || !res.ok) return UNKNOWN;
     const runs = parseJson(res.stdout);
     if (!Array.isArray(runs)) return UNKNOWN;

package/src/cli.js

@@ -5,6 +5,16 @@ import { CLI_VERSION, runLegacyCliWithErrorHandling } from "./legacy-cli.js";
 import { restrictProgramLookupToPath } from "./program-lookup.js";
 
 const COMMAND_REGISTRARS = {
+  skills: {
+    loader: () => import("./commands/skills.js"),
+    exportName: "registerSkillsCommand",
+    needsLegacy: false,
+  },
+  judge: {
+    loader: () => import("./commands/judge.js"),
+    exportName: "registerJudgeCommand",
+    needsLegacy: false,
+  },
   init: {
     loader: () => import("./commands/init.js"),
     exportName: "registerInitCommand",
@@ -262,9 +272,11 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
   // Normalize slash commands (/omargate → omargate, /audit → audit, etc.)
   const normalizedArgs = normalizeSlashArgs(rawArgs);
 
-  // Auth gate — require login for all commands except auth/help/version/config
-  const { checkAuthGate, printAuthRequired } = await import("./auth/gate.js");
-  const authResult = await checkAuthGate(normalizedArgs);
+  // Auth gate — require login for all commands except auth/help/version/config. Help for a Commander command prints
+  // without login too: Commander prints it and runs nothing (a newcomer reads `sl session --help` first).
+  const { checkAuthGate, isHelpOnlyInvocation, printAuthRequired } = await import("./auth/gate.js");
+  const helpOnly = !shouldBypassCommander(normalizedArgs) && isHelpOnlyInvocation(normalizedArgs);
+  const authResult = helpOnly ? { authenticated: true } : await checkAuthGate(normalizedArgs);
   if (!authResult.authenticated) {
     printAuthRequired(authResult.failureReason);
     return;
@@ -272,6 +284,14 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
 
   if (shouldBypassCommander(normalizedArgs)) {
     await runLegacyCliWithErrorHandling(normalizedArgs);
+    if (["--help", "-h", "help"].includes(normalizedArgs[0])) {
+      console.log("\nAgent Skills:");
+      console.log("  sl skills install [names...] [--dir <path>] [--force] [--json]  Install bundled Senti skills (all, or the named ones)");
+      console.log("  sl skills list [--dir <path>] [--json]  Show bundled and installed versions/hashes");
+      console.log("\nJudge Loop:");
+      console.log("  sl judge check --file <verdict.json> [--json]  Validate a verdict offline and preview the message");
+      console.log("  sl judge verdict <sessionId> --agent <id> --file <verdict.json>  Send the verdict to the coder");
+    }
     return;
   }