@socketsecurity/lib 6.0.6 → 6.0.8

package/CHANGELOG.md

@@ -5,11 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.8](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.8) - 2026-06-11
+
+### Added
+
+- **`shell/parse`: `detectShellHazards`.** Checks a shell command string for two tricks that hide which program actually runs, so a tool that allows or denies commands by name isn't fooled. First, Zsh `=name` expansion: `=curl evil.com` runs `/usr/bin/curl`, but the command's first word reads as `=curl`, not `curl`. Second, process substitution `<(…)` / `>(…)` / `=(…)`: the command inside the parentheses runs, yet its name never appears as a command word. Returns `{ equalsExpansion, processSubstitution }`, the facts only; the caller decides whether to block.
+- **`url` — `assertSafeHttpUrl`.** SSRF guard for a URL the server did not author (an OAuth issuer, a metadata-advertised introspection endpoint, a webhook target): parses the value, rejects non-`http(s)` schemes, and refuses hosts in loopback / private / link-local ranges (cloud metadata, redis, internal services). Returns the parsed `URL`; throws otherwise. `allowLocalhost` permits `localhost` / `127.0.0.1` / `::1` for local-stack dev; `label` names the subject in the thrown message.
+- **`git/tracked` — tracked-status and submodule-membership probes.** `isTracked(path)` reports whether git tracks an exact path. `getSubmodulePaths()` lists a repo's submodule mount points read from `.gitmodules`, so it covers submodules that are declared but not yet initialized. `isInSubmodule(path)` and the pure `pathIsUnderSubmodule(path, subs)` report whether a path lives inside one. `isUntrackedNonSubmodulePath(path)` composes them into the safe-to-touch condition for cleanup tooling: true only when git does not track the path and it is not inside a submodule (any check error resolves to false).
+- **`primordials/process` — accessors for the `process` global.** `processCwd`, `processPlatform`, `processEnv`, `processArgv`, `processArch`, `processExecPath`, `processPid`, `processVersion`, `processStdout`, `processStderr`, `processEmitWarning`, and `processNextTick`. Each reads through the `process` object captured when the module loads, so reassigning the global cannot redirect it, while still calling the method at access time so test spies keep working.
+- **`ai` — model-selection tiers, balancing, and provider routing.** The model-selection ladder gains a verification tier for check-style passes and a top-capability tier for the hardest work. Requests load-balance across a provider's backends so they spread instead of pinning one. A shared multi-agent backend registry centralizes routing, and a provider-credential resolver reads from environment variables and falls back to the OS keychain.
+
+### Changed
+
+- **`http-request` browser entry — `fetch/browser`.** The browser build of `httpJson` / `httpText` now resolves through `http-request/fetch/browser` (was `http-request/browser-fetch`), and the package's `browser` field maps Node-only builtins to their browser stubs. Bundlers targeting the browser pick the right entry automatically.
+- **Node-builtin accessors are browser-bundler friendly.** The internal Node-builtin accessor layer requires builtins by their bare name so a browser bundler's builtin replacement (the package `browser` field, a consumer's bundler fallback config) resolves them; the `node:`-prefixed form bypasses that replacement in some bundlers. No public API change.
+- **Caller-supplied `options` are prototype-pollution hardened.** Functions that take an `options` argument normalize it before reading, so an object with a tampered prototype cannot leak inherited properties into the library's behavior.
+
+### Fixed
+
+- **`ai` — codex reasoning effort.** Setting `effort` on a `spawnAiAgent` call now reaches the codex backend (emitted as codex's reasoning-effort config), where it was previously accepted but silently ignored for every agent except claude. The claude-only `max` level maps to codex's `xhigh` ceiling.
+
+## [6.0.7](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.7) - 2026-06-03
+
+### Added
+
+- **`external-tools/python` — zero-host-dependency Python.** `resolvePython` (PATH → python-build-standalone download), `downloadPipPackage` (bundle-safe `pip install --target`), `resolvePipPackagePin` (hash-pinned closure), and the `dlxPipInstall` / `dlxPipPin` one-call wrappers. Removes the unused `external-tools/uv`.
+- **`constants/platform` — `getOs`, `getLibc`, `getTarget`.** OS, libc (`glibc`/`musl`/`undefined`), and the pnpm `pack-app` host token `<os>-<arch>[-<libc>]`.
+- **`http-request` decompresses `gzip` / `br` response bodies.** Buffered requests advertise `Accept-Encoding: gzip, br` and now decode the body by its `Content-Encoding` before resolving. 6.0.6 sent the header but never decompressed, so a compressed response reached callers as raw deflated bytes. Streamed requests (`stream: true`, e.g. `httpDownload`) skip the header so piped-to-disk payloads stay raw and checksum cleanly. Callers can override with `'identity'`.
+- **`crypto/hash` blob content-address helpers.** `blobHashOf(bytes)` returns Socket's content-addressed blob hash (`Q` + base64url(sha256)), and `verifyBlobHash(hash, bytes)` throws when bytes don't hash to the expected address. Both build on the fast one-shot `hash()`; the `S` file-stream discriminator verifies against the same digest body. Lets blob consumers (the SDK, MCP server) verify integrity against one canonical implementation instead of re-deriving the scheme.
+- **`integrity` — unified checksum/integrity surface.** `checksumToIntegrity(hex, algorithm?)` and `integrityToChecksum(sri)` convert between the two named hash flavors and are idempotent on the destination format (pass an SRI to `checksumToIntegrity`, get it back unchanged). `isIntegrity(s)` and `isChecksum(s)` are the predicates. `parseIntegrity(s)` returns `{ algorithm, body }` for the SRI structure. Replaces the `src/ssri/` directory (`hexToSsri`, `ssriToHex`, `isValidHex`, `isValidSsri`, `parseSsri`) — SSRI is just another name for Subresource Integrity, so the duplication confused readers. `isIntegrity` now accepts the full W3C SRI set (`sha256` / `sha384` / `sha512`) — the previous predicate hardcoded `sha512` only, which mismatched the contract `external-tools/manifest.ts` already promised and rejected the fleet's `sha256-<base64>` integrity strings.
+- **`process/spawn/kill-tree` — cross-platform process-tree termination.** `killProcessTree(target, { detached?, signal? })` walks and signals the whole descendant tree of a `pid` or `ChildProcess`: POSIX uses `process.kill(-pid, signal)` against the detached child's process group; Windows shells out to `taskkill /T /F /pid <pid>`. `isProcessAlive(pid)` probes liveness with `process.kill(pid, 0)`. Both helpers are best-effort and never throw — `ESRCH` (process gone) or `EPERM` (not ours) returns `false` so cleanup kills can't mask the caller's control flow.
+
+### Changed
+
+- **dlx + pin API renamed (breaking).** `downloadPackage` → `downloadNpmPackage`, `generatePackagePin` → `resolveNpmPackagePin`, the `package` option → `spec`. `downloadNpmPackage` gains an optional `hash` for tarball integrity.
+- **`packages/operations` split by concern (breaking).** The grab-bag `@socketsecurity/lib/packages/operations` export is gone; its members move to focused subpaths: `readPackageJson`/`readPackageJsonSync` → `packages/read`, the fetcher + GitHub tarball resolver → `packages/fetch`, `extractPackage`/`packPackage` → `packages/tarball`, the dependency-metadata override lookup → `packages/metadata-extensions`, and the name/spec helpers → `packages/specs`. `findUpPackageJson` now lives at `packages/find` (the `packages/find-up` subpath is removed). The `fs/find-up` subpath is renamed `fs/find`, and `fs/path-cache` is renamed `fs/allowed-dirs-cache` (it caches the safe-delete allowed-directories set, not arbitrary paths).
+
+### Fixed
+
+- **Python downloads now work on Windows and Alpine.** python-build-standalone resolution previously returned no asset on `win32` and musl hosts; both now resolve.
+- **`debug` — namespace `SOCKET_DEBUG` values enable debug output.** `envAsBoolean(getSocketDebug())` returned false for `SOCKET_DEBUG=*` or `SOCKET_DEBUG=socket:foo` — those aren't boolean literals, so debug output was silently suppressed for the common namespace-selection shape. The new `isSocketDebugEnabled()` helper treats any non-empty value other than `0`/`false`/`no` (case-insensitive) as enabled.
+- **`external-tools/skillspector` pipx detection on Windows.** The PATH-tier resolver normalizes the resolved binary path with `normalizePath` and matches a forward-slash-only `pipx/venvs/` pattern, instead of `path.normalize` plus a dual-separator regex. On Windows the old form left backslashes in the path and missed pipx-installed binaries, tagging them `source: 'path'` rather than `source: 'pipx'`.
+
+### Removed
+
+- **`@socketsecurity/lib/ssri/{convert,parse,validate}` package exports.** Folded into `@socketsecurity/lib/integrity` (see Added). No fleet consumers were using the `ssri` subpath imports — verified by grep across socket-\* fleet repos.
+
 ## [6.0.6](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.6) - 2026-06-01
 
 ### Added
 
-- **`http-request` now negotiates and decompresses `gzip` / `br` response bodies.** Buffered requests advertise `Accept-Encoding: gzip, br` and transparently decompress responses by `Content-Encoding`. Node's HTTP client does neither, so a compressed Socket API response previously reached callers as raw deflated bytes. Streamed requests (`stream: true`, e.g. `httpDownload`) intentionally skip the `Accept-Encoding` header so piped-to-disk payloads stay raw and checksum cleanly. Callers can override (e.g. `'identity'`).
 - **`http-request/headers` — `basicAuthHeader(token)`.** Builds the Socket API Basic-auth shape (token-as-username, empty password) so call sites stop hand-rolling `Basic ${base64(token + ':')}`.
 - **`http-request` retry instrumentation.** Adds `Retry-Attempt`, `Retry-Max`, and `Retry-After` request headers on retried attempts so server-side logs can correlate a retry chain.
 - **`prim` CLI bin.** `prim` is now published as a `bin` entry (`dist/bin/prim.cjs`); installs from `@socketsecurity/lib` make `npx prim` work. Also new in this release: `prim --diff` for unified line-diffs in dry-run mode, multi-hop cycle detection in `validateRewrites`, and a two-phase apply with cross-batch validation.

package/README.md

@@ -39,7 +39,7 @@ import { httpJson } from '@socketsecurity/lib/http-request'
 import { safeDelete } from '@socketsecurity/lib/fs'
 ```
 
-Start with the [API Index](./docs/api-index.md) — every subpath export with a one-line description.
+Start with the [API reference](./docs/api.md) — every subpath export with a one-line description.
 
 ## Development
 

package/dist/ai/agent-context.d.mts

@@ -0,0 +1,103 @@
+/**
+ * @file Agent-awareness for hooks + scripts: WHICH agent is running right now,
+ *   and WHERE that agent keeps its config / memory on the current platform. Two
+ *   distinct questions, two functions:
+ *
+ *   - `detectAgent()` — who is invoking this process? Read from the environment
+ *     the running agent injects, NOT from any stdin payload (a Claude Code hook
+ *     gets `{tool_name,…}` on stdin but no agent id; Codex/OpenCode use
+ *     entirely different invocation contracts). The cross-agent signal is
+ *     `AI_AGENT` (Claude Code sets `AI_AGENT=claude-code_<ver>_agent`);
+ *     tool-specific flags (`CLAUDECODE`, `CODEX_*`, `OPENCODE`) are the
+ *     fallback. Returns `undefined` when nothing identifies an agent (a plain
+ *     shell / CI).
+ *   - `agentPaths()` — given an agent, the config + memory directories it uses on
+ *     THIS OS. Built on the cross-platform `getHome()` (HOME → USERPROFILE) and
+ *     XDG helpers so a Windows path differs from mac/linux correctly. This is
+ *     the runtime complement to `discoverAiAgents()` (which agents are
+ *     INSTALLED on PATH); this answers which one is DRIVING + where it lives.
+ *     Memory caveat baked into the data: only Claude Code maintains an
+ *     agent-written memory store (`~/.claude/projects/<slug>/memory/`). Codex +
+ *     OpenCode have NO self-written memory — their only persistent context is
+ *     the human-authored AGENTS.md. So `agentPaths(...).memoryDir` is defined
+ *     only for `claude`; for the others it is `undefined` (there is no memory
+ *     dir to point at), and the shared cross-tool memory surface is the
+ *     committed AGENTS.md (which the fleet symlinks to CLAUDE.md).
+ */
+import type { AiAgentName } from './types.mts';
+/**
+ * The detected running agent + the raw version token from `AI_AGENT`, when
+ * present. `agent` is the normalized `AiAgentName`; `raw` is the full env value
+ * (e.g. `claude-code_2-1-169_agent`) for callers that want the version.
+ */
+export interface DetectedAgent {
+    readonly agent: AiAgentName;
+    readonly raw: string | undefined;
+}
+export declare function agentFromAiAgentEnv(value: string): AiAgentName | undefined;
+/**
+ * The config + memory directories an agent uses on the current platform.
+ *
+ * `configDir` is where the agent keeps global config / instructions.
+ * `memoryDir` is the agent-written persistent-memory store — defined ONLY for
+ * `claude` (Codex/OpenCode have no self-written memory; their durable context
+ * is the human-authored AGENTS.md). For non-claude agents `memoryDir` is
+ * `undefined`.
+ *
+ * All paths derive from `getHome()` (HOME → USERPROFILE, cross-platform) so the
+ * Windows location differs from mac/linux correctly. Returns `undefined` when
+ * the home dir can't be resolved.
+ */
+export interface AgentPaths {
+    readonly agent: AiAgentName;
+    readonly configDir: string;
+    readonly memoryDir: string | undefined;
+}
+/**
+ * Resolve an agent's config (and, for Claude, memory) directories on this OS.
+ *
+ * Per-agent / per-platform (verified against each tool's docs; flagged where a
+ * platform path is best-effort):
+ *
+ * - **claude**: `~/.claude` on every OS. Memory:
+ *   `~/.claude/projects/<cwd-slug>/memory/` (slug = cwd with `/`→`-`). Pass
+ *   `options.cwd` to compute the memory dir for a specific project.
+ * - **codex**: `$CODEX_HOME` if set, else `~/.codex` (all OSes, incl. Windows
+ *   `%USERPROFILE%\.codex` — Codex uses a dotdir, not %APPDATA%). No memory.
+ * - **opencode**: XDG — `$XDG_CONFIG_HOME/opencode` else `~/.config/opencode` on
+ *   mac/linux; on Windows `%APPDATA%\opencode` (best-effort: OpenCode's docs
+ *   don't pin the Windows user-config path; APPDATA is the conventional
+ *   fallback and is overridable via `$XDG_CONFIG_HOME`). No memory.
+ * - **gemini**: `~/.gemini` (all OSes). No memory.
+ *
+ * @returns The resolved paths, or `undefined` if the home dir is unresolvable.
+ */
+export declare function agentPaths(agent: AiAgentName, options?: {
+    cwd?: string | undefined;
+} | undefined): AgentPaths | undefined;
+/**
+ * Detect which AI agent is invoking the current process, from the environment.
+ *
+ * Resolution order:
+ *
+ * 1. `AI_AGENT` — the cross-agent signal (Claude Code sets it). Its leading token
+ *    names the family.
+ * 2. Tool-specific flags as a fallback: `CLAUDECODE=1` / `CLAUDE_CODE_*` → claude;
+ *    `CODEX_*` → codex; `OPENCODE` → opencode.
+ *
+ * Returns `undefined` when no agent signal is present (a plain shell, CI, a
+ * non-agent subprocess) — callers should treat that as "agent-agnostic", not an
+ * error.
+ *
+ * Note: a hook receives NO agent id in its stdin payload; this env read is the
+ * only reliable signal. Different agents also invoke hooks differently (Claude:
+ * stdin JSON; Codex: its own hooks; OpenCode: plugin callbacks), so a
+ * `.claude/hooks/` script is fundamentally Claude-invoked — `detectAgent()` is
+ * most useful for scripts/skills that want to branch on the active agent, or
+ * when an agent delegates to another.
+ *
+ * @example
+ *   const detected = detectAgent()
+ *   if (detected?.agent === 'claude') { ... }
+ */
+export declare function detectAgent(): DetectedAgent | undefined;

package/dist/ai/agent-context.js

@@ -0,0 +1,157 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_constants_platform = require('../constants/platform.js');
+const require_env_rewire = require('../env/rewire.js');
+const require_env_home = require('../env/home.js');
+const require_env_xdg = require('../env/xdg.js');
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+
+//#region src/ai/agent-context.mts
+/**
+* @file Agent-awareness for hooks + scripts: WHICH agent is running right now,
+*   and WHERE that agent keeps its config / memory on the current platform. Two
+*   distinct questions, two functions:
+*
+*   - `detectAgent()` — who is invoking this process? Read from the environment
+*     the running agent injects, NOT from any stdin payload (a Claude Code hook
+*     gets `{tool_name,…}` on stdin but no agent id; Codex/OpenCode use
+*     entirely different invocation contracts). The cross-agent signal is
+*     `AI_AGENT` (Claude Code sets `AI_AGENT=claude-code_<ver>_agent`);
+*     tool-specific flags (`CLAUDECODE`, `CODEX_*`, `OPENCODE`) are the
+*     fallback. Returns `undefined` when nothing identifies an agent (a plain
+*     shell / CI).
+*   - `agentPaths()` — given an agent, the config + memory directories it uses on
+*     THIS OS. Built on the cross-platform `getHome()` (HOME → USERPROFILE) and
+*     XDG helpers so a Windows path differs from mac/linux correctly. This is
+*     the runtime complement to `discoverAiAgents()` (which agents are
+*     INSTALLED on PATH); this answers which one is DRIVING + where it lives.
+*     Memory caveat baked into the data: only Claude Code maintains an
+*     agent-written memory store (`~/.claude/projects/<slug>/memory/`). Codex +
+*     OpenCode have NO self-written memory — their only persistent context is
+*     the human-authored AGENTS.md. So `agentPaths(...).memoryDir` is defined
+*     only for `claude`; for the others it is `undefined` (there is no memory
+*     dir to point at), and the shared cross-tool memory surface is the
+*     committed AGENTS.md (which the fleet symlinks to CLAUDE.md).
+*/
+function agentFromAiAgentEnv(value) {
+	const lower = value.toLowerCase();
+	if (lower.startsWith("claude")) return "claude";
+	if (lower.startsWith("codex")) return "codex";
+	if (lower.startsWith("opencode")) return "opencode";
+	if (lower.startsWith("gemini")) return "gemini";
+}
+/**
+* Resolve an agent's config (and, for Claude, memory) directories on this OS.
+*
+* Per-agent / per-platform (verified against each tool's docs; flagged where a
+* platform path is best-effort):
+*
+* - **claude**: `~/.claude` on every OS. Memory:
+*   `~/.claude/projects/<cwd-slug>/memory/` (slug = cwd with `/`→`-`). Pass
+*   `options.cwd` to compute the memory dir for a specific project.
+* - **codex**: `$CODEX_HOME` if set, else `~/.codex` (all OSes, incl. Windows
+*   `%USERPROFILE%\.codex` — Codex uses a dotdir, not %APPDATA%). No memory.
+* - **opencode**: XDG — `$XDG_CONFIG_HOME/opencode` else `~/.config/opencode` on
+*   mac/linux; on Windows `%APPDATA%\opencode` (best-effort: OpenCode's docs
+*   don't pin the Windows user-config path; APPDATA is the conventional
+*   fallback and is overridable via `$XDG_CONFIG_HOME`). No memory.
+* - **gemini**: `~/.gemini` (all OSes). No memory.
+*
+* @returns The resolved paths, or `undefined` if the home dir is unresolvable.
+*/
+function agentPaths(agent, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const home = require_env_home.getHome();
+	if (!home) return;
+	switch (agent) {
+		case "claude": {
+			const configDir = node_path.default.join(home, ".claude");
+			const cwd = opts.cwd;
+			return {
+				agent,
+				configDir,
+				memoryDir: cwd ? node_path.default.join(configDir, "projects", cwd.replace(/[/\\]/g, "-"), "memory") : void 0
+			};
+		}
+		case "codex": return {
+			agent,
+			configDir: require_env_rewire.getEnvValue("CODEX_HOME") || node_path.default.join(home, ".codex"),
+			memoryDir: void 0
+		};
+		case "opencode": {
+			const xdg = require_env_xdg.getXdgConfigHome();
+			let base;
+			if (xdg) base = xdg;
+			else if (require_constants_platform.WIN32) base = require_env_rewire.getEnvValue("APPDATA") || node_path.default.join(home, ".config");
+			else base = node_path.default.join(home, ".config");
+			return {
+				agent,
+				configDir: node_path.default.join(base, "opencode"),
+				memoryDir: void 0
+			};
+		}
+		case "gemini": return {
+			agent,
+			configDir: node_path.default.join(home, ".gemini"),
+			memoryDir: void 0
+		};
+	}
+}
+/**
+* Detect which AI agent is invoking the current process, from the environment.
+*
+* Resolution order:
+*
+* 1. `AI_AGENT` — the cross-agent signal (Claude Code sets it). Its leading token
+*    names the family.
+* 2. Tool-specific flags as a fallback: `CLAUDECODE=1` / `CLAUDE_CODE_*` → claude;
+*    `CODEX_*` → codex; `OPENCODE` → opencode.
+*
+* Returns `undefined` when no agent signal is present (a plain shell, CI, a
+* non-agent subprocess) — callers should treat that as "agent-agnostic", not an
+* error.
+*
+* Note: a hook receives NO agent id in its stdin payload; this env read is the
+* only reliable signal. Different agents also invoke hooks differently (Claude:
+* stdin JSON; Codex: its own hooks; OpenCode: plugin callbacks), so a
+* `.claude/hooks/` script is fundamentally Claude-invoked — `detectAgent()` is
+* most useful for scripts/skills that want to branch on the active agent, or
+* when an agent delegates to another.
+*
+* @example
+*   const detected = detectAgent()
+*   if (detected?.agent === 'claude') { ... }
+*/
+function detectAgent() {
+	const aiAgent = require_env_rewire.getEnvValue("AI_AGENT");
+	if (aiAgent) {
+		const agent = agentFromAiAgentEnv(aiAgent);
+		if (agent) return {
+			agent,
+			raw: aiAgent
+		};
+	}
+	if (require_env_rewire.getEnvValue("CLAUDECODE") || require_env_rewire.getEnvValue("CLAUDE_CODE_ENTRYPOINT")) return {
+		agent: "claude",
+		raw: aiAgent
+	};
+	if (require_env_rewire.getEnvValue("OPENCODE")) return {
+		agent: "opencode",
+		raw: aiAgent
+	};
+	if (require_env_rewire.getEnvValue("CODEX_SANDBOX") || require_env_rewire.getEnvValue("CODEX_HOME")) return {
+		agent: "codex",
+		raw: aiAgent
+	};
+}
+
+//#endregion
+exports.agentFromAiAgentEnv = agentFromAiAgentEnv;
+exports.agentPaths = agentPaths;
+exports.detectAgent = detectAgent;

package/dist/ai/backends.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @file Multi-agent CLI backend registry + role routing. The fleet's review /
+ *   scan / fix skills delegate work to whichever agent CLIs are installed
+ *   (`codex`, `claude`, `kimi`, `opencode`), falling back through a per-role
+ *   preference order and skipping a pass when nothing usable is present. Before
+ *   this module each skill copied the same registry + detection block inline
+ *   (the canonical copy lived in
+ *   `.claude/skills/fleet/reviewing-code/run.mts`); the shared policy doc
+ *   (`_shared/multi-agent-backends.md`) flagged the extraction. Import
+ *   `BACKENDS` / `detectAvailableBackends` / `resolveBackendForRole` here
+ *   instead so a new backend or a routing-policy change is a single edit. The
+ *   registry is prompt-agnostic: it owns WHICH CLI runs and HOW its argv is
+ *   built ({ argv, outMode }), not WHAT to ask. A skill keeps its own role
+ *   table (prompts + per-role `preferenceOrder` + timeouts) and passes the
+ *   order into `resolveBackendForRole`. Detection uses `which` (cross-platform)
+ *   rather than `command -v` under `shell: true`, which mangles on Windows. The
+ *   resolver is pure — it returns a structured result (chosen backend + why)
+ *   and never logs, so the caller decides how to surface a fallback or a skip.
+ *   `opencode` is hybrid (it dispatches to whatever provider its own config
+ *   selects, e.g. Fireworks / Synthetic), so it is NEVER auto-picked from a
+ *   preference order — only when a caller names it explicitly — to keep model
+ *   attribution accurate.
+ */
+/**
+ * A CLI backend the fleet can delegate a pass to.
+ */
+export type BackendName = 'claude' | 'codex' | 'kimi' | 'opencode';
+/**
+ * How a backend's process emits its result.
+ */
+export type BackendOutMode = 'file' | 'stdout';
+export interface BackendRun {
+    readonly argv: readonly string[];
+    readonly outMode: BackendOutMode;
+}
+export interface BackendDescriptor {
+    readonly bin: string;
+    readonly hybrid: boolean;
+    readonly name: BackendName;
+    readonly run: (promptFile: string, outFile: string) => BackendRun;
+}
+export declare const BACKENDS: Readonly<Record<BackendName, BackendDescriptor>>;
+/**
+ * The set of backends whose CLI is installed. Fans the `which` lookups out
+ * concurrently rather than awaiting one at a time.
+ */
+export declare function detectAvailableBackends(): Promise<ReadonlySet<BackendName>>;
+/**
+ * True when `value` names a known backend.
+ */
+export declare function isBackendName(value: string): value is BackendName;
+/**
+ * True when the named CLI resolves on PATH (cross-platform via `which`).
+ */
+export declare function isCommandAvailable(bin: string): Promise<boolean>;
+export type BackendResolution = {
+    readonly backend: BackendName;
+    readonly reason: 'override';
+} | {
+    readonly backend: BackendName;
+    readonly reason: 'preference';
+} | {
+    readonly backend: BackendName;
+    readonly reason: 'preference';
+    readonly overrideMissing: BackendName;
+} | {
+    readonly backend: undefined;
+    readonly reason: 'unavailable';
+};
+export interface ResolveBackendOptions {
+    readonly preferenceOrder: readonly BackendName[];
+    readonly available: ReadonlySet<BackendName>;
+    readonly override?: BackendName | undefined;
+}
+/**
+ * Resolve which backend runs a pass, encoding the fleet detection policy
+ * (`_shared/multi-agent-backends.md`): an installed explicit override wins;
+ * else the first installed non-hybrid entry in the preference order; else
+ * nothing (skip the pass). Pure — returns the decision + why, never logs. An
+ * override that isn't installed is reported via `overrideMissing` so the caller
+ * can warn.
+ */
+export declare function resolveBackendForRole(options: ResolveBackendOptions): BackendResolution;

package/dist/ai/backends.js

@@ -0,0 +1,173 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_bin_which = require('../bin/which.js');
+const require_ai_spawn = require('./spawn.js');
+
+//#region src/ai/backends.mts
+/**
+* @file Multi-agent CLI backend registry + role routing. The fleet's review /
+*   scan / fix skills delegate work to whichever agent CLIs are installed
+*   (`codex`, `claude`, `kimi`, `opencode`), falling back through a per-role
+*   preference order and skipping a pass when nothing usable is present. Before
+*   this module each skill copied the same registry + detection block inline
+*   (the canonical copy lived in
+*   `.claude/skills/fleet/reviewing-code/run.mts`); the shared policy doc
+*   (`_shared/multi-agent-backends.md`) flagged the extraction. Import
+*   `BACKENDS` / `detectAvailableBackends` / `resolveBackendForRole` here
+*   instead so a new backend or a routing-policy change is a single edit. The
+*   registry is prompt-agnostic: it owns WHICH CLI runs and HOW its argv is
+*   built ({ argv, outMode }), not WHAT to ask. A skill keeps its own role
+*   table (prompts + per-role `preferenceOrder` + timeouts) and passes the
+*   order into `resolveBackendForRole`. Detection uses `which` (cross-platform)
+*   rather than `command -v` under `shell: true`, which mangles on Windows. The
+*   resolver is pure — it returns a structured result (chosen backend + why)
+*   and never logs, so the caller decides how to surface a fallback or a skip.
+*   `opencode` is hybrid (it dispatches to whatever provider its own config
+*   selects, e.g. Fireworks / Synthetic), so it is NEVER auto-picked from a
+*   preference order — only when a caller names it explicitly — to keep model
+*   attribution accurate.
+*/
+const BACKENDS = {
+	__proto__: null,
+	claude: {
+		bin: "claude",
+		hybrid: false,
+		name: "claude",
+		run(_promptFile, _outFile) {
+			const model = process.env["CLAUDE_MODEL"] ?? "opus";
+			const effort = process.env["CLAUDE_EFFORT"] ?? "high";
+			return {
+				argv: [
+					"--print",
+					"--model",
+					model,
+					...require_ai_spawn.isAdaptiveOnlyModel(model) ? [] : ["--effort", effort],
+					"--no-session-persistence",
+					"--permission-mode",
+					"dontAsk"
+				],
+				outMode: "stdout"
+			};
+		}
+	},
+	codex: {
+		bin: "codex",
+		hybrid: false,
+		name: "codex",
+		run(_promptFile, outFile) {
+			return {
+				argv: [
+					"exec",
+					"--model",
+					process.env["CODEX_MODEL"] ?? "gpt-5.5",
+					"-c",
+					`model_reasoning_effort=${process.env["CODEX_REASONING"] ?? "xhigh"}`,
+					"--full-auto",
+					"--ephemeral",
+					"-o",
+					outFile,
+					"-"
+				],
+				outMode: "file"
+			};
+		}
+	},
+	kimi: {
+		bin: "kimi",
+		hybrid: false,
+		name: "kimi",
+		run(_promptFile, _outFile) {
+			return {
+				argv: [
+					"chat",
+					"--model",
+					process.env["KIMI_MODEL"] ?? "kimi-latest",
+					"--no-stream"
+				],
+				outMode: "stdout"
+			};
+		}
+	},
+	opencode: {
+		bin: "opencode",
+		hybrid: true,
+		name: "opencode",
+		run(_promptFile, _outFile) {
+			const model = process.env["OPENCODE_MODEL"];
+			return {
+				argv: model ? [
+					"run",
+					"--model",
+					model
+				] : ["run"],
+				outMode: "stdout"
+			};
+		}
+	}
+};
+/**
+* The set of backends whose CLI is installed. Fans the `which` lookups out
+* concurrently rather than awaiting one at a time.
+*/
+async function detectAvailableBackends() {
+	const names = Object.keys(BACKENDS);
+	const results = await Promise.all(names.map(async (name) => ({
+		available: await isCommandAvailable(BACKENDS[name].bin),
+		name
+	})));
+	return new Set(results.filter((r) => r.available).map((r) => r.name));
+}
+/**
+* True when `value` names a known backend.
+*/
+function isBackendName(value) {
+	return value in BACKENDS;
+}
+/**
+* True when the named CLI resolves on PATH (cross-platform via `which`).
+*/
+async function isCommandAvailable(bin) {
+	return await require_bin_which.which(bin) !== null;
+}
+/**
+* Resolve which backend runs a pass, encoding the fleet detection policy
+* (`_shared/multi-agent-backends.md`): an installed explicit override wins;
+* else the first installed non-hybrid entry in the preference order; else
+* nothing (skip the pass). Pure — returns the decision + why, never logs. An
+* override that isn't installed is reported via `overrideMissing` so the caller
+* can warn.
+*/
+function resolveBackendForRole(options) {
+	const { available, override, preferenceOrder } = {
+		__proto__: null,
+		...options
+	};
+	if (override && available.has(override)) return {
+		backend: override,
+		reason: "override"
+	};
+	for (let i = 0, { length } = preferenceOrder; i < length; i += 1) {
+		const candidate = preferenceOrder[i];
+		if (BACKENDS[candidate]?.hybrid) continue;
+		if (available.has(candidate)) return override ? {
+			backend: candidate,
+			overrideMissing: override,
+			reason: "preference"
+		} : {
+			backend: candidate,
+			reason: "preference"
+		};
+	}
+	return {
+		backend: void 0,
+		reason: "unavailable"
+	};
+}
+
+//#endregion
+exports.BACKENDS = BACKENDS;
+exports.detectAvailableBackends = detectAvailableBackends;
+exports.isBackendName = isBackendName;
+exports.isCommandAvailable = isCommandAvailable;
+exports.resolveBackendForRole = resolveBackendForRole;

package/dist/ai/credentials.d.mts

@@ -0,0 +1,49 @@
+/**
+ * @file Layered provider-credential resolver for AI backends. One call site,
+ *   dev and CI: a provider token resolves from an explicit override, then the
+ *   provider's env var, then the OS keychain — mirroring the
+ *   `readSocketApiToken` env → keychain precedence
+ *   (`secrets/socket-api-token.ts`). Why a single resolver: `ai/http.mts` read
+ *   `process.env[tokenEnv]` inline, so every consumer hard-coded the env-only
+ *   path and none could reach the keychain. Routing skills also need a uniform
+ *   way to ask "do I have a credential for provider X?" without knowing its
+ *   env-var name. This centralizes the provider → { tokenEnv, keychainService }
+ *   map (the HTTP providers reuse `AI_HTTP_PROVIDERS` so the env var isn't
+ *   duplicated) and the precedence. CI vs dev: pass `allowEnvOnly: true` (the
+ *   resolver's existing escape) in headless contexts so a missing token returns
+ *   `undefined` immediately instead of triggering a keychain auth prompt. CI
+ *   sets the token as a GH-secret env var (e.g. `ANTHROPIC_API_KEY`); the same
+ *   `resolveProviderCredential` call reads it there with no keychain. proteus
+ *   hook-point: the forthcoming biometric credential daemon
+ *   (`.claude/plans/proteus-credential-broker.md`) slots in as a layer between
+ *   the env check and the keychain read inside `resolve()`'s implementation —
+ *   call sites here do not change when it lands (resolver decision #4 in that
+ *   plan). This module is the stable seam.
+ */
+/**
+ * A provider whose credential this module can resolve: the HTTP providers
+ * (fireworks, synthetic) plus the CLI/first-party providers (anthropic, openai,
+ * xai) for CI env + keychain.
+ */
+export type CredentialProvider = 'anthropic' | 'fireworks' | 'openai' | 'synthetic' | 'xai';
+export interface ProviderCredentialSpec {
+    readonly tokenEnv: string;
+    readonly keychainService: string;
+}
+export declare const PROVIDER_CREDENTIALS: Readonly<Record<CredentialProvider, ProviderCredentialSpec>>;
+/**
+ * True when `value` names a provider with a resolvable credential.
+ */
+export declare function isCredentialProvider(value: string): value is CredentialProvider;
+export interface ResolveProviderCredentialOptions {
+    readonly provider: CredentialProvider;
+    readonly explicit?: string | undefined;
+    readonly allowEnvOnly?: boolean | undefined;
+}
+/**
+ * Resolve a provider's bearer token: explicit override → env var → keychain →
+ * undefined. The token never appears inline or in logs — callers pass the
+ * result straight to an `Authorization` header. Returns `undefined` when no
+ * source has it (the caller decides whether that's fatal).
+ */
+export declare function resolveProviderCredential(options: ResolveProviderCredentialOptions): Promise<string | undefined>;