severally-mcp 2.3.1 → 2.4.2

package/src/policy.mjs

@@ -7,7 +7,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { parseJsonc } from './jsonc.mjs';
 import { findCommand } from './platform.mjs';
-import { buildConsultants, CLI_IDS, normalizeName } from './consultants.mjs';
+import { buildConsultants, isObject, normalizeName } from './consultants.mjs';
+
+/** @typedef {import('./consultants.mjs').Consultant} Consultant */
+/** @typedef {import('./consultants.mjs').CliId} CliId */
 
 // One file, read once at start, so an operator configures a machine in a
 // single place instead of editing each client's MCP registration. Precedence
@@ -17,12 +20,14 @@ import { buildConsultants, CLI_IDS, normalizeName } from './consultants.mjs';
 const CONFIG_HOME = process.env.SEVERALLY_HOME || path.join(os.homedir(), '.severally');
 // .jsonc first, for operators whose editor treats comments in a .json file as
 // an error; both are read the same way, comments and all.
-const CONFIG_PATH = process.env.SEVERALLY_CONFIG
-  || [path.join(CONFIG_HOME, 'config.jsonc'), path.join(CONFIG_HOME, 'config.json')]
-    .find((p) => fs.existsSync(p))
-  || path.join(CONFIG_HOME, 'config.json');
+const CONFIG_PATH =
+  process.env.SEVERALLY_CONFIG ||
+  [path.join(CONFIG_HOME, 'config.jsonc'), path.join(CONFIG_HOME, 'config.json')].find((p) => fs.existsSync(p)) ||
+  path.join(CONFIG_HOME, 'config.json');
 
+/** @type {string | null} */
 let configError = null;
+/** @type {unknown} the parsed config file, before validation */
 const CONFIG = (() => {
   try {
     return parseJsonc(fs.readFileSync(CONFIG_PATH, 'utf8'));
@@ -30,7 +35,8 @@ const CONFIG = (() => {
     // A missing file is the normal case. A malformed one is not: silently
     // ignoring it would run the machine on defaults the operator thinks they
     // overrode, so it is surfaced on stderr when the server starts.
-    if (err.code !== 'ENOENT') configError = `${CONFIG_PATH}: ${err.message}`;
+    const code = err instanceof Error && 'code' in err ? err.code : undefined;
+    if (code !== 'ENOENT') configError = `${CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`;
     return {};
   }
 })();
@@ -50,7 +56,10 @@ if (!configError && ![undefined, '', 'on', 'off'].includes(process.env.SEVERALLY
 const FROM = configError ? buildConsultants({}) : BUILT;
 const LOCAL = configError ? [] : BUILT.problems.filter((p) => !BUILT.global.includes(p));
 
-/** What is wrong with the config file as a whole, or null. Reported at startup; while set, nothing can be started. */
+/**
+ * What is wrong with the config file as a whole, or null. Reported at startup; while set, nothing can be started.
+ * @returns {string | null}
+ */
 export function configProblem() {
   return configError;
 }
@@ -65,31 +74,66 @@ export function brokenConsultantNames() {
   return configError ? [] : Object.keys(BUILT.broken);
 }
 
-/** Why the consultant of this name is out of use because of a config mistake, or null. */
+/**
+ * Why the consultant of this name is out of use because of a config mistake, or null.
+ * @param {string} name
+ */
 export function brokenConsultant(name) {
   const p = !configError && Object.hasOwn(BUILT.broken, name) ? BUILT.broken[name] : null;
   return p ? `the config file has a mistake in it: ${p.join('; ')}` : null;
 }
 
-const usable = configError ? {} : CONFIG;
+/**
+ * One CLI's section of the config file. `args`, `env` and `provider` are read
+ * only after buildConsultants has checked them (a section with a mistake is
+ * replaced by a disabled one in cfgCli), so they have the types given here.
+ * @typedef {object} CliSection
+ * @property {unknown} [enabled]
+ * @property {unknown} [note]
+ * @property {unknown} [bin]
+ * @property {string[]} [args]
+ * @property {Record<string, string>} [env]
+ * @property {Record<string, Record<string, unknown>>} [provider]
+ */
+
+/** @type {Record<string, unknown>} */
+const usable = configError || !isObject(CONFIG) ? {} : CONFIG;
 // A CLI whose own section has a mistake is off, whatever else the section says.
+/**
+ * @param {string} id
+ * @returns {CliSection}
+ */
 const cfgCli = (id) => {
-  if (Object.hasOwn(BUILT.brokenClis, id) && !configError) {
-    return { enabled: false, note: `turned off: the config file has a mistake in clis.${id}: ${BUILT.brokenClis[id].join('; ')}` };
+  const broken = Object.hasOwn(BUILT.brokenClis, id) ? BUILT.brokenClis[id] : undefined;
+  if (broken && !configError) {
+    return {
+      enabled: false,
+      note: `turned off: the config file has a mistake in clis.${id}: ${broken.join('; ')}`,
+    };
   }
-  return usable.clis && typeof usable.clis === 'object' ? usable.clis[id] ?? {} : {};
+  const def = isObject(usable.clis) ? usable.clis[id] : undefined;
+  // A section reaches here only when buildConsultants found no mistake in it.
+  return isObject(def) ? /** @type {CliSection} */ (def) : {};
 };
-const cfgServer = usable.server && typeof usable.server === 'object' ? usable.server : {};
+const cfgServer = isObject(usable.server) ? usable.server : {};
 
 /**
  * Is this command runnable here? Absolute/relative paths are checked as given.
  * Exported so the config generator can report what a machine has without
  * going through POLICY, which already reflects any config file it found.
+ * @param {string} command
  */
 export function isInstalled(command) {
   return findCommand(command) !== null;
 }
 
+/**
+ * @param {string} name
+ * @param {number | null} dflt
+ * @param {number} min
+ * @param {number} max
+ * @returns {number | null}
+ */
 const num = (name, dflt, min, max) => {
   const raw = process.env[name];
   if (raw === undefined || raw === '') return dflt;
@@ -102,6 +146,14 @@ const num = (name, dflt, min, max) => {
 // the same range whichever one supplied it. Codex and OpenCode do not pass the
 // user's shell environment to an MCP server, so for them the file is the only
 // place an operator can reach without editing the client's registration.
+/**
+ * @param {string} name
+ * @param {unknown} fromCfg
+ * @param {number} dflt
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 const limit = (name, fromCfg, dflt, min, max) => {
   const fromEnv = num(name, null, min, max);
   if (fromEnv !== null) return fromEnv;
@@ -109,6 +161,11 @@ const limit = (name, fromCfg, dflt, min, max) => {
   return dflt;
 };
 
+/**
+ * @param {string} name
+ * @param {string} dflt
+ * @returns {string}
+ */
 const str = (name, dflt) => {
   const raw = process.env[name];
   return raw === undefined || raw === '' ? dflt : raw;
@@ -117,23 +174,43 @@ const str = (name, dflt) => {
 // The CLI a lead runs in, by any everyday name. Only `caller` uses this:
 // which consultant a name reaches is consultants.mjs's resolveConsultant.
 // Object.create(null) so 'constructor' is an unknown name, not a function.
-export const CALLER_ALIASES = Object.freeze(Object.assign(Object.create(null), {
-  codex: 'codex', gpt: 'codex', chatgpt: 'codex', openai: 'codex',
-  'claude-code': 'claude-code', claude: 'claude-code', anthropic: 'claude-code',
-  antigravity: 'antigravity', agy: 'antigravity', gemini: 'antigravity', google: 'antigravity',
-  opencode: 'opencode', glm: 'opencode',
-}));
+/** @type {Readonly<Record<string, CliId>>} */
+export const CALLER_ALIASES = Object.freeze(
+  Object.assign(Object.create(null), {
+    codex: 'codex',
+    gpt: 'codex',
+    chatgpt: 'codex',
+    openai: 'codex',
+    'claude-code': 'claude-code',
+    claude: 'claude-code',
+    anthropic: 'claude-code',
+    antigravity: 'antigravity',
+    agy: 'antigravity',
+    gemini: 'antigravity',
+    google: 'antigravity',
+    opencode: 'opencode',
+    glm: 'opencode',
+  }),
+);
 
 export const CALLER_INPUTS = Object.freeze(Object.keys(CALLER_ALIASES));
 
-/** The CLI id for any accepted spelling of a caller, or null. */
+/**
+ * The CLI id for any accepted spelling of a caller, or null.
+ * @param {unknown} raw
+ * @returns {CliId | null}
+ */
 export function resolveCaller(raw) {
   const key = normalizeName(raw);
-  return typeof key === 'string' && Object.hasOwn(CALLER_ALIASES, key) ? CALLER_ALIASES[key] : null;
+  return typeof key === 'string' ? (CALLER_ALIASES[key] ?? null) : null;
 }
 
 // Which CLI is hosting this server. Used only to annotate a consultation that
 // goes to the caller's own vendor; it never affects permissions or limits.
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {CliId | null}
+ */
 export function detectCaller(env = process.env) {
   if (env.CLAUDECODE === '1' || env.CLAUDE_CODE_ENTRYPOINT) return 'claude-code';
   if (env.CODEX_HOME || env.CODEX_SANDBOX || env.CODEX_SANDBOX_NETWORK_DISABLED) return 'codex';
@@ -153,12 +230,15 @@ export const VERDICTS = ['unverified', 'confirmed', 'not_applicable', 'unverifia
 // The consultant's own one-word bottom line. Also what the lead may predict
 // before asking -- the same vocabulary, so a prediction and an answer can be
 // read side by side without anyone translating between two scales.
-export const STANCES = ['proceed', 'do_not_proceed', 'alternative', 'undetermined'];
+export const STANCES = /** @type {const} */ (['proceed', 'do_not_proceed', 'alternative', 'undetermined']);
 
 /**
  * A leading ~ is a shell courtesy, not a path: nothing expands it here, so
  * "~/.local/bin/claudex" would simply not exist and the consultant would drop
  * out of the available list without saying why. Expand it where a path is read.
+ * @template T
+ * @param {T} value
+ * @returns {T | string}
  */
 function expandHome(value) {
   if (typeof value !== 'string') return value;
@@ -167,6 +247,12 @@ function expandHome(value) {
 }
 
 // env > config file > built-in default, for a CLI's bin.
+/**
+ * @param {string} id
+ * @param {string} envName
+ * @param {string} dflt
+ * @returns {string}
+ */
 const binFor = (id, envName, dflt) => {
   const fromEnv = process.env[envName];
   if (fromEnv !== undefined && fromEnv !== '') return expandHome(fromEnv);
@@ -177,11 +263,16 @@ const binFor = (id, envName, dflt) => {
 // Why a consultant is off, in the operator's words: "quota exhausted until
 // 15:00" is more use to a lead than a bare refusal, and it is the reason a CLI
 // that IS installed gets excluded.
+/** @param {string} id */
 const disabledNote = (id) => {
   const n = cfgCli(id).note;
   return typeof n === 'string' && n.trim() !== '' ? n.trim() : null;
 };
 
+/**
+ * @param {string} id
+ * @param {string} cli
+ */
 const isEnabled = (id, cli) => {
   const flag = cfgCli(id).enabled;
   if (typeof flag === 'boolean') return flag;
@@ -196,7 +287,14 @@ const OPENCODE_BIN = binFor('opencode', 'SEVERALLY_OPENCODE_BIN', 'opencode');
 // Operator-only extras for the child process (config: args, env). Config-only,
 // never from a request, and validated at launch (jobs.mjs) where the isolation
 // flags and variables they must not undo are known.
-const extras = (id) => ({ extraArgs: cfgCli(id).args ?? [], extraEnv: cfgCli(id).env ?? {} });
+/**
+ * @param {string} id
+ * @returns {{ extraArgs: string[], extraEnv: Record<string, string> }}
+ */
+const extras = (id) => ({
+  extraArgs: cfgCli(id).args ?? [],
+  extraEnv: cfgCli(id).env ?? {},
+});
 
 export const POLICY = Object.freeze({
   home: str('SEVERALLY_HOME', path.join(os.homedir(), '.severally')),
@@ -205,18 +303,34 @@ export const POLICY = Object.freeze({
   // a consultant's business.
   clis: Object.freeze({
     codex: Object.freeze({
-      cli: CODEX_BIN, available: isEnabled('codex', CODEX_BIN), note: disabledNote('codex'), label: 'Codex CLI', ...extras('codex'),
+      cli: CODEX_BIN,
+      available: isEnabled('codex', CODEX_BIN),
+      note: disabledNote('codex'),
+      label: 'Codex CLI',
+      ...extras('codex'),
     }),
     'claude-code': Object.freeze({
-      cli: CLAUDE_BIN, available: isEnabled('claude-code', CLAUDE_BIN), note: disabledNote('claude-code'), label: 'Claude Code CLI', ...extras('claude-code'),
+      cli: CLAUDE_BIN,
+      available: isEnabled('claude-code', CLAUDE_BIN),
+      note: disabledNote('claude-code'),
+      label: 'Claude Code CLI',
+      ...extras('claude-code'),
     }),
     // Where the real Antigravity credentials live is credentialsHome() below,
     // not a field here: the sandbox reads it per job (see timeoutMs()).
     antigravity: Object.freeze({
-      cli: AGY_BIN, available: isEnabled('antigravity', AGY_BIN), note: disabledNote('antigravity'), label: 'Antigravity CLI', ...extras('antigravity'),
+      cli: AGY_BIN,
+      available: isEnabled('antigravity', AGY_BIN),
+      note: disabledNote('antigravity'),
+      label: 'Antigravity CLI',
+      ...extras('antigravity'),
     }),
     opencode: Object.freeze({
-      cli: OPENCODE_BIN, available: isEnabled('opencode', OPENCODE_BIN), note: disabledNote('opencode'), label: 'OpenCode CLI', ...extras('opencode'),
+      cli: OPENCODE_BIN,
+      available: isEnabled('opencode', OPENCODE_BIN),
+      note: disabledNote('opencode'),
+      label: 'OpenCode CLI',
+      ...extras('opencode'),
       // opencode.json `provider` definitions copied into the sandbox config:
       // the only way to reach a provider the sandbox's empty HOME would not
       // know, such as a local OpenAI-compatible server.
@@ -286,6 +400,8 @@ export const POLICY = Object.freeze({
   }),
 });
 
+/** @typedef {typeof POLICY} Policy */
+
 /**
  * Wall-clock budget for one consultation of this consultant. Read at job
  * start (not frozen into the module) so an operator restart is not needed to
@@ -293,6 +409,7 @@ export const POLICY = Object.freeze({
  * same time: a long Gemini answer should not force the same patience on every
  * other consultant. The two hour ceiling stays -- past that the answer is a
  * different request, not a slower one.
+ * @param {Consultant | null} [consultant]
  */
 export function timeoutMs(consultant) {
   return consultant?.timeoutMs ?? limit('SEVERALLY_TIMEOUT_MS', cfgServer.timeout_ms, 1_800_000, 1_000, 7_200_000);
@@ -338,22 +455,61 @@ export function opencodeCredentialsHome() {
 // and never copied by expose_paths; Codex's read-only sandbox cannot express
 // path rules, which the boundary record says.
 export const PROTECTED_HOME_PATHS = Object.freeze([
-  '.ssh', '.gnupg', '.aws', '.azure', '.kube', '.docker', '.config/gcloud', '.config/gh', '.config/hub',
-  '.netrc', '.npmrc', '.pypirc', '.git-credentials', '.cargo/credentials', '.cargo/credentials.toml',
-  '.terraform.d', '.vault-token', 'Library/Keychains',
-  '.codex', '.claude', '.claude.json', '.gemini', '.config/opencode', '.local/share/opencode',
+  '.ssh',
+  '.gnupg',
+  '.aws',
+  '.azure',
+  '.kube',
+  '.docker',
+  '.config/gcloud',
+  '.config/gh',
+  '.config/hub',
+  '.netrc',
+  '.npmrc',
+  '.pypirc',
+  '.git-credentials',
+  '.cargo/credentials',
+  '.cargo/credentials.toml',
+  '.terraform.d',
+  '.vault-token',
+  'Library/Keychains',
+  '.codex',
+  '.claude',
+  '.claude.json',
+  '.gemini',
+  '.config/opencode',
+  '.local/share/opencode',
 ]);
 // Under POLICY.home, wherever the operator moved it.
-const PROTECTED_SEVERALLY_PATHS = Object.freeze(['history', 'backups', 'config.json', 'config.jsonc', 'homes',
+const PROTECTED_SEVERALLY_PATHS = Object.freeze([
+  'history',
+  'backups',
+  'config.json',
+  'config.jsonc',
+  'homes',
   // Where homes lived before 1.7: one left by an interrupted run can still hold an auth.json copy.
-  'jobs/*/home']);
+  'jobs/*/home',
+]);
 // File names protected wherever they are.
 export const PROTECTED_FILE_NAMES = Object.freeze([
-  '.env', '.env.*', '.npmrc', '.netrc', '.pypirc', '.git-credentials', 'id_rsa', 'id_ed25519', 'id_ecdsa', 'id_dsa',
+  '.env',
+  '.env.*',
+  '.npmrc',
+  '.netrc',
+  '.pypirc',
+  '.git-credentials',
+  'id_rsa',
+  'id_ed25519',
+  'id_ecdsa',
+  'id_dsa',
 ]);
 
-/** Absolute protected roots, with forward slashes; `*` stands for one path segment. */
+/**
+ * Absolute protected roots, with forward slashes; `*` stands for one path segment.
+ * @returns {string[]}
+ */
 export function protectedRoots() {
+  /** @param {string} p */
   const fwd = (p) => p.replaceAll('\\', '/');
   return [
     ...PROTECTED_HOME_PATHS.map((rel) => fwd(path.join(os.homedir(), rel))),
@@ -361,26 +517,38 @@ export function protectedRoots() {
   ];
 }
 
+/** @param {string} s */
 const escapeRe = (s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
 // Case-insensitive where the default file system is: Windows and macOS.
 export const PATHS_CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin';
-/** Regex sources: one per protected root, matching it and anything under it. */
+/**
+ * Regex sources: one per protected root, matching it and anything under it.
+ * @param {string[]} [extraRoots]
+ */
 export function protectedRootPatterns(extraRoots = []) {
-  return [...protectedRoots(), ...extraRoots.map((r) => r.replaceAll('\\', '/'))]
-    .map((r) => `^${escapeRe(r.replace(/\/+$/, '')).replaceAll('*', '[^/]+')}(/|$)`);
+  return [...protectedRoots(), ...extraRoots.map((r) => r.replaceAll('\\', '/'))].map(
+    (r) => `^${escapeRe(r.replace(/\/+$/, '')).replaceAll('*', '[^/]+')}(/|$)`,
+  );
 }
 /** Regex sources for PROTECTED_FILE_NAMES, matched against a base name. */
 export function protectedNamePatterns() {
   return PROTECTED_FILE_NAMES.map((n) => `^${escapeRe(n).replaceAll('*', '.*')}$`);
 }
 
-/** Whether an absolute path, or the file it links to, is protected. */
+/**
+ * Whether an absolute path, or the file it links to, is protected.
+ * @param {string} abs
+ */
 export function isProtectedPath(abs) {
   const flags = PATHS_CASE_INSENSITIVE ? 'i' : '';
   const roots = protectedRootPatterns().map((p) => new RegExp(p, flags));
   const names = protectedNamePatterns().map((p) => new RegExp(p, flags));
   let real = abs;
-  try { real = fs.realpathSync.native(abs); } catch { /* missing: check the name as given */ }
+  try {
+    real = fs.realpathSync.native(abs);
+  } catch {
+    /* missing: check the name as given */
+  }
   return [abs, real].some((p) => {
     const fwd = p.replaceAll('\\', '/');
     return roots.some((re) => re.test(fwd)) || names.some((re) => re.test(path.basename(fwd)));
@@ -389,12 +557,31 @@ export function isProtectedPath(abs) {
 
 export const artifactKinds = ['code', 'log', 'doc', 'data', 'diff', 'spec', 'test-output', 'config'];
 
-/** The consultant with this exact name, or undefined. */
+/**
+ * The consultant with this exact name, or undefined.
+ * @param {string} name
+ */
 export function consultantByName(name) {
   return POLICY.consultants.find((c) => c.name === name);
 }
 
-/** Can this consultant run here: turned on itself, and its CLI usable. */
+/**
+ * The consultant with this exact name, for a caller that holds a name it got
+ * from a consultant already (a started job's target). Throws when there is
+ * none; use consultantByName when the name may be unknown.
+ * @param {string} name
+ * @returns {Consultant}
+ */
+export function consultantNamed(name) {
+  const c = consultantByName(name);
+  if (!c) throw new Error(`no consultant named "${name}"`);
+  return c;
+}
+
+/**
+ * Can this consultant run here: turned on itself, and its CLI usable.
+ * @param {Consultant} c
+ */
 export function consultantAvailable(c) {
   return c.enabled && POLICY.clis[c.cli].available;
 }
@@ -402,6 +589,8 @@ export function consultantAvailable(c) {
 /**
  * Why this consultant cannot be reached, or null when it can. The operator's
  * own note wins: "installed but rate-limited" is a case only they can state.
+ * @param {Consultant | null | undefined} c
+ * @returns {string | null}
  */
 export function unavailableReason(c) {
   if (!c || consultantAvailable(c)) return null;
@@ -419,6 +608,7 @@ export function availableConsultants() {
 
 export function limitsSummary() {
   const list = availableConsultants();
+  /** @param {(c: Consultant) => unknown} f */
   const by = (f) => Object.fromEntries(list.map((c) => [c.name, f(c)]));
   return {
     available_targets: list.map((c) => c.name),
@@ -434,16 +624,19 @@ export function limitsSummary() {
     max_concurrent_jobs: POLICY.maxConcurrent,
     max_wait_ms: POLICY.maxWaitMs,
     input_char_budget: POLICY.input.totalCharsMax,
-    // Stated so it is true of all three consultants. Reading is allowed for
-    // every one of them -- what keeps a consultation brief-only is that the
-    // child starts in an empty working directory and is never told where the
-    // repository is, not that it cannot read. Codex is additionally sandboxed
-    // read-only rather than execution-free, so do not advertise "no execution".
+    // Stated so it is true of all four CLIs. Reading is allowed for every one
+    // of them -- what keeps a consultation brief-only is that the child starts
+    // in an empty working directory and is never told where the repository
+    // is, not that it cannot read. Only Claude Code drops its whole-disk read
+    // when files are exposed (claude-code.mjs). Codex is additionally
+    // sandboxed read-only rather than execution-free, so do not advertise
+    // "no execution".
     consultant_permissions:
-      'web search/browse and reading local files allowed, but the consultant starts in an empty working ' +
-      'directory and is not told where your repository is -- unless context.expose_paths names files or ' +
-      'directories, which are copied read-only into that working directory and are then the only part of ' +
-      'your repository it has; file edits, network access, MCP tools and further consultations denied; the ' +
-      'Codex consultant additionally has a read-only shell',
+      'web search/browse and reading local files allowed; the consultant starts in an empty working ' +
+      'directory and is not told where your repository is. context.expose_paths copies the files or ' +
+      'directories it names read-only into that working directory, but that is not a read boundary: apart ' +
+      'from the protected credential paths, Codex, Antigravity and OpenCode can read any file your account ' +
+      'can, and so can Claude Code when nothing is exposed; file edits, network access, MCP tools and ' +
+      'further consultations denied; the Codex consultant additionally has a read-only shell',
   };
 }

package/src/redact.mjs

@@ -1,65 +1,107 @@
 // Credential scrubbing. Applied on the way out (brief sent to the consultant),
 // on the way in (consultant output), and to everything persisted to disk.
 
-const CODE_WORDS = new Set(['true', 'false', 'null', 'none', 'undefined', 'string', 'str', 'number', 'boolean', 'bool', 'int', 'bytes']);
+const CODE_WORDS = new Set([
+  'true',
+  'false',
+  'null',
+  'none',
+  'undefined',
+  'string',
+  'str',
+  'number',
+  'boolean',
+  'bool',
+  'int',
+  'bytes',
+]);
 
 // A password-type value that is code, not a secret: a flag or a type, a
 // variable reference (${X}, $X, process.env.X, os.environ[...]), and -- unless
 // it is a long value under a full PASSWORD/PASSWD name, which stays masked
 // whatever it looks like -- a dotted name, a call or a borrow (&str).
+/**
+ * @param {string} name
+ * @param {string} value
+ */
 function looksLikeCode(name, value) {
-  if (CODE_WORDS.has(value.toLowerCase()) || value.startsWith('${') || /^\$[A-Z_][A-Z0-9_]*$/.test(value)
-    || /^(?:process\.env\.|os\.environ\b)/.test(value)) return true;
-  if (value.length >= 8 && /^PASSW(?:OR)?D$/i.test(name.split('_').at(-1))) return false;
+  if (
+    CODE_WORDS.has(value.toLowerCase()) ||
+    value.startsWith('${') ||
+    /^\$[A-Z_][A-Z0-9_]*$/.test(value) ||
+    /^(?:process\.env\.|os\.environ\b)/.test(value)
+  )
+    return true;
+  if (value.length >= 8 && /^PASSW(?:OR)?D$/i.test(name.split('_').at(-1) ?? '')) return false;
   return /^[A-Za-z_][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(value) || /^[A-Za-z_][\w$.]*\(/.test(value) || value.startsWith('&');
 }
 
+// A replacement is a string or a function of the match.
+/** @type {Array<[RegExp, string | ((...groups: string[]) => string)]>} */
 const PATTERNS = [
   // Provider API keys
-  [/\bsk-ant-[A-Za-z0-9_\-]{12,}/g, '[REDACTED:anthropic-key]'],
-  [/\bsk-proj-[A-Za-z0-9_\-]{12,}/g, '[REDACTED:openai-key]'],
-  [/\bsk-[A-Za-z0-9_\-]{20,}/g, '[REDACTED:api-key]'],
+  [/\bsk-ant-[A-Za-z0-9_-]{12,}/g, '[REDACTED:anthropic-key]'],
+  [/\bsk-proj-[A-Za-z0-9_-]{12,}/g, '[REDACTED:openai-key]'],
+  [/\bsk-[A-Za-z0-9_-]{20,}/g, '[REDACTED:api-key]'],
   [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, '[REDACTED:github-token]'],
   [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, '[REDACTED:github-token]'],
   [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, '[REDACTED:slack-token]'],
   [/https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+\/B[A-Za-z0-9]+\/[A-Za-z0-9]+/g, '[REDACTED:slack-webhook]'],
   [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED:aws-access-key-id]'],
   [/\bASIA[0-9A-Z]{16}\b/g, '[REDACTED:aws-access-key-id]'],
-  [/\bAIza[0-9A-Za-z_\-]{30,}/g, '[REDACTED:google-api-key]'],
+  [/\bAIza[0-9A-Za-z_-]{30,}/g, '[REDACTED:google-api-key]'],
   // Stripe secret and restricted keys (pk_ is public, left alone), npm, GitLab, Hugging Face
   [/\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}/g, '[REDACTED:stripe-key]'],
   [/\bnpm_[A-Za-z0-9]{30,}/g, '[REDACTED:npm-token]'],
-  [/\bglpat-[A-Za-z0-9_\-]{20,}/g, '[REDACTED:gitlab-token]'],
+  [/\bglpat-[A-Za-z0-9_-]{20,}/g, '[REDACTED:gitlab-token]'],
   [/\bhf_[A-Za-z0-9]{30,}/g, '[REDACTED:huggingface-token]'],
   // JWT / OAuth access tokens (3 base64url segments)
-  [/\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}/g, '[REDACTED:jwt]'],
-  [/\bBearer\s+[A-Za-z0-9._\-]{20,}/gi, 'Bearer [REDACTED:token]'],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[REDACTED:jwt]'],
+  [/\bBearer\s+[A-Za-z0-9._-]{20,}/gi, 'Bearer [REDACTED:token]'],
   // PEM private keys
   [/-----BEGIN[^-]{0,40}PRIVATE KEY-----[\s\S]*?-----END[^-]{0,40}PRIVATE KEY-----/g, '[REDACTED:private-key]'],
   // The password in a URL's userinfo, also with an empty user (redis://:pass@host)
   [/(:\/\/[^\s:/@]*:)[^\s@/]+(@)/g, '$1[REDACTED]$2'],
   // KEY=value / "token": "value" style assignments
-  [/\b((?:[A-Za-z0-9_]*_)?(?:API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY|ACCESS_TOKEN|REFRESH_TOKEN|ID_TOKEN|SECRET_KEY|CLIENT_SECRET|AUTH_TOKEN|CREDENTIALS|ACCOUNTKEY|SHAREDACCESSKEY|SECRET|TOKEN))(["']?\s*[:=]\s*["']?)([^\s"',;)]{8,})/gi,
-    (_m, k, sep, _v) => `${k}${sep}[REDACTED]`],
+  [
+    /\b((?:[A-Za-z0-9_]*_)?(?:API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY|ACCESS_TOKEN|REFRESH_TOKEN|ID_TOKEN|SECRET_KEY|CLIENT_SECRET|AUTH_TOKEN|CREDENTIALS|ACCOUNTKEY|SHAREDACCESSKEY|SECRET|TOKEN))(["']?\s*[:=]\s*["']?)([^\s"',;)]{8,})/gi,
+    (_m, k, sep, _v) => `${k}${sep}[REDACTED]`,
+  ],
   // Password-type names, with values from 4 characters; PASS and PWD too (PWD
   // only after `_` or a letter: bare PWD is the working directory). What reads
   // as code rather than a password is left alone (looksLikeCode).
-  [/\b((?:[A-Za-z0-9_]*_)?(?:PASSWORD|PASSWD|PASS|(?<=[A-Za-z_])PWD))(["']?\s*[:=]\s*["']?)([^\s"',;)]{4,})/gi,
-    (m, k, sep, v) => (looksLikeCode(k, v) ? m : `${k}${sep}[REDACTED]`)],
+  [
+    /\b((?:[A-Za-z0-9_]*_)?(?:PASSWORD|PASSWD|PASS|(?<=[A-Za-z_])PWD))(["']?\s*[:=]\s*["']?)([^\s"',;)]{4,})/gi,
+    (m, k, sep, v) => (looksLikeCode(k, v) ? m : `${k}${sep}[REDACTED]`),
+  ],
   // Any environment variable named *_KEY. Upper case only: in code, primary_key,
   // sort_key and idempotency_key name things, not secrets.
   [/\b([A-Z0-9_]+_KEY)(\s*=\s*["']?)([^\s"',;)]{8,})/g, (_m, k, sep, _v) => `${k}${sep}[REDACTED]`],
 ];
 
+/**
+ * Any JSON-like value in, the same shape out with its strings scrubbed.
+ * @template T
+ * @overload
+ * @param {T} value
+ * @returns {T}
+ */
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
 export function redact(value) {
   if (value === null || value === undefined) return value;
   if (typeof value === 'string') {
+    /** @type {string} */
     let out = value;
-    for (const [re, rep] of PATTERNS) out = out.replace(re, rep);
+    // The same call either way: replace() has one overload for a string and one for a function.
+    for (const [re, rep] of PATTERNS) out = typeof rep === 'string' ? out.replace(re, rep) : out.replace(re, rep);
     return out;
   }
   if (Array.isArray(value)) return value.map(redact);
   if (typeof value === 'object') {
+    /** @type {Record<string, unknown>} */
     const out = {};
     for (const [k, v] of Object.entries(value)) out[k] = redact(v);
     return out;
@@ -67,6 +109,7 @@ export function redact(value) {
   return value;
 }
 
+/** @param {unknown} text */
 export function containsSecret(text) {
   if (typeof text !== 'string') return false;
   return redact(text) !== text;