@socketsecurity/lib 5.28.0 → 6.0.0

package/CHANGELOG.md

@@ -5,46 +5,75 @@ 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.0](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.0) - 2026-05-20
+
+Public-surface reshape. All top-level barrels are gone; import from named leaf subpaths instead. `@socketsecurity/lib/logger` and `@socketsecurity/lib/errors` stay as aliases.
+
+### Removed (breaking)
+
+- **All top-level barrel modules.** Replace with leaf subpaths — e.g. `fs` → `fs/safe`, `http-request` → `http-request/convenience`, `packages` → `packages/operations`, `versions` → `versions/compare`. Affects `fs`, `http-request`, `spinner`, `git`, `github`, `spawn`, `bin`, `primordials`, `objects`, `strings`, `promises`, `arrays`, `url`, `packages`, `cacache`, `signal-exit`, `compression`, `archives`, `globs`, `regexps`, `ssri`, `colors`, `ansi`, `crypto`, `abort`, `streams`, `links`, `shadow`, `ipc`, `ipc-cli`, `errors`, `words`, `tables`, `sorts`, `env`, `debug`, `versions`, `types`.
+- **`agent` removed.** Per-tool helpers under `eco/npm/<tool>/{exec,flags}` (`bun`, `npm`, `pnpm`, `vlt`, `yarnpkg/yarn`).
+- **`types/` removed.** Schema types under `eco/purl` and `eco/types`.
+- **Subdir renames.** `memoization/` → `memo/`, `performance/` → `perf/`, `suppress-warnings/` → `warnings/`, `cache-with-ttl/` → `ttl-cache/`, `process-lock/` → `process/`, `package-extensions/` → `pkg-ext/`, `temporary-executor/` → `process/transient` (`isRunningInTemporaryExecutor` → `isTransientProcess`).
+- **`SOCKET_LIB_USER_AGENT` + `SOCKET_LIB_URL` removed.** Use `getSocketCallerUserAgent()` from `http-request/user-agent` — see Added.
+
+### Changed (breaking)
+
+- **`versions` API renamed.** `compareVersions` → `compare`, `isEqual` → `eq` (+ new `neq`), `isLessThan(OrEqual)` → `lt`/`lte`, `isGreaterThan(OrEqual)` → `gt`/`gte`, `sortVersions` → `sort`, `sortVersionsDesc` → `rsort`. Runs through `node:smol-versions` when present, falls back to `semver`.
+- **`dlx/manifest` `ManifestEntry` → `DlxManifestEntry`** (disambiguates from `eco/types` `ManifestEntry`).
+- **`dlx/arborist getBaseArboristOptions`** second arg is now `{ quiet }` instead of positional `quiet: boolean`.
+- **Predicates renamed for scope clarity** — cwd/process-scoped predicates now carry the scope in the name.
+- **Default `User-Agent` header** now `socketsecurity-lib/<version> node/<node-version> <platform>/<arch>` (was `socketsecurity-lib/<version> (<url>)`).
+
+### Added
+
+- **`http-request/user-agent`** — `buildUserAgent({ name, version }, caller?)` for the canonical three-token UA, and `getSocketCallerUserAgent()` for the lib's own outbound requests. Set `SOCKET_CALLER_USER_AGENT` to append your own identifier to the lib UA (empty/whitespace is ignored).
+- **`packages/operations#pkgNameToSlug(name)`** — `@scope/name` → `scope-name`, plain names unchanged.
+- **`secrets/socket-api-token`** — `readSocketApiToken()` / `readSocketApiTokenSync()` resolve the Socket API token from keychain → `SOCKET_API_TOKEN` (canonical) → `SOCKET_API_KEY` (legacy). Pass `{ allowEnvOnly }` to skip keychain in headless contexts.
+- **`ai/discover` + `ai/spawn`** — locked-down spawn helpers for Claude / Codex / Gemini / OpenCode CLIs. Type-level enforcement of the four lockdown flags (`tools`, `allowedTools`, `disallowedTools`, `permissionMode: 'dontAsk'`). Retries HTTP 529 / "Overloaded" with 5 s / 15 s / 45 s backoff.
+- **`socket-lib check primordials --fix`** — applies suggested rewrites for `.socket-lib.json`-tracked drift.
+- **9 new primordial exports** (305 total) — Array.prototype: `ToLocaleString`, `ToString`. String.prototype: `IsWellFormed` (ES2024), `ToString`, `ToWellFormed` (ES2024), `ValueOf`. Number.prototype: `ToExponential`, `ToPrecision`, `ValueOf`. `StringPrototypeIsWellFormed` routes through `node:smol-primordial` on the smol Node binary — ASCII strings short-circuit to `true` without an O(n) lone-surrogate scan.
+
+### Fixed
+
+- **pnpm v9 `isDev` derivation.** Snapshot entries were stuck at `depType: 'prod'` because v9 dropped the per-snapshot `dev` marker. Now derived per-package across all importer blocks; ties go to prod, matching pnpm's resolver.
+- **yarn `dependenciesMeta` inversion.** A child's `optional: true` was flipping the parent's `isOptional`; flags now refer to the child as declared.
+- **pnpm v9 phantom PackageRef.** Block-shape importer entries emitted a parent ref with `version: ''` before the indented `version:` was consumed.
+- **pnpm v9 protocol filter.** `workspace:`, `file:`, and `link:` importer values are no longer surfaced as registry refs.
+- **npm v1 alias extraction.** Aliased installs (`"alias": { "version": "npm:<real>@<ver>" }`) now surface the real `{ name, version }`; the alias key is preserved on `_index`.
+- **npm v2/v3 workspace + alias name preference.** Path-keyed workspace entries and aliased installs honor the explicit `pkg.name` over the path-derived fallback.
+
+### Migration
+
+```diff
+- import { safeDelete, readJson } from '@socketsecurity/lib/fs'
++ import { safeDelete } from '@socketsecurity/lib/fs/safe'
++ import { readJson } from '@socketsecurity/lib/fs/read-json'
+
+- import { httpJson } from '@socketsecurity/lib/http-request'
++ import { httpJson } from '@socketsecurity/lib/http-request/convenience'
+
+- import { compareVersions, isLessThan, sortVersions } from '@socketsecurity/lib/versions'
+- compareVersions(a, b); isLessThan(a, b); sortVersions(arr)
++ import { compare, lt, sort } from '@socketsecurity/lib/versions/compare'
++ compare(a, b); lt(a, b); sort(arr)
+```
+
 ## [5.28.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.28.0) - 2026-05-06
 
 ### Added
 
-- **`compression` (new export)** — brotli + gzip helpers with three calling shapes (in-memory `Buffer`, file-to-file, raw streams) and a single `{ inPlace: true }` option for compress/decompress-in-place. 28 named exports total:
-  - In-memory: `compressBrotli`, `decompressBrotli`, `compressGzip`, `decompressGzip`
-  - File-to-file: `compressBrotliFile`, `decompressBrotliFile`, `compressGzipFile`, `decompressGzipFile` — each with three overloads (explicit dest, in-place, options object). The gzip in-place path follows `.tgz` → `.tar` convention so a round-trip is lossless
-  - Streams: `createBrotliCompressor`, `createBrotliDecompressor`, `createGzipCompressor`, `createGzipDecompressor`
-  - Detection: `isBrotliCompressed(buffer)` / `isGzipCompressed(buffer)` (magic-byte sniffing)
-  - Path classification: `hasBrotliExt(filePath)` / `hasGzipExt(filePath)` — case-insensitive `path.extname` match against `.br` / `.brotli` / `.gz` / `.gzip` / `.tgz`
-  - Helpers: `BROTLI_EXTS` / `GZIP_EXTS` `ReadonlySet<string>` constants; `stripExt(filePath, exts)` for trimming a recognized extension from a path; `resolveBrotliOptions` / `resolveGzipOptions` for translating `CompressOptions` into the underlying zlib option shapes
-  - `CompressOptions` / `CompressFileOptions` interfaces
-- **`socket-lib` CLI (new `bin` entry)** — fleet-wide static-analysis dispatcher invoked via `pnpm exec socket-lib <command>`. Initial subcommand: `check primordials` (alias `check prim`) — diffs every name destructured from `primordials` in scanned source against `@socketsecurity/lib`'s exposed primordials set, emitting unmapped or missing-from-lib findings. Reads sectional config from `.socket-lib.json` (with `.config/socket-lib.json` as a fallback) or a bare object for single-check setups. Flags: `--config / -c <path>` (defaults to `.socket-lib.json`, falls back to `.config/socket-lib.json`), `--explain`, `--json`, `--silent`, `--help`. Lifted from socket-btm's `scripts/check-primordials-coverage.mts` so the same drift gate now ships to every consumer.
-- **`dlx/package` `installRoot` option** — new `EnsurePackageInstallOptions` (and `DlxPackageOptions`) field overriding the install root passed to Arborist. Default remains `~/.socket/_dlx/<cacheKey>/`; when set, the value is used verbatim. Lets build pipelines colocate the install with their own gitignored outputs (e.g. ink-builder bundling ink via esbuild). Caller owns per-spec separation; see JSDoc for the full contract.
+- **`compression` (new)** — brotli + gzip helpers with in-memory `Buffer`, file-to-file (with `{ inPlace: true }`), and stream-creator shapes. Detection (`isBrotliCompressed` / `isGzipCompressed` magic-byte sniffing), extension classification (`hasBrotliExt` / `hasGzipExt`), `BROTLI_EXTS` / `GZIP_EXTS` constants, `stripExt(path, exts)`, and `CompressOptions` / `CompressFileOptions` types.
+- **`socket-lib` CLI** — `pnpm exec socket-lib <command>` dispatcher. First subcommand: `check primordials` (alias `check prim`) diffs source-destructured primordials against the lib's set. Reads `.socket-lib.json` (or `.config/socket-lib.json`). Flags: `--config`, `--explain`, `--json`, `--silent`, `--help`.
+- **`dlx/package` `installRoot`** option overrides the Arborist install root (default `~/.socket/_dlx/<cacheKey>/`). Useful for colocating installs with consumer-owned build outputs.
 
 ## [5.27.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.27.0) - 2026-05-04
 
 ### Added
 
-- **45 new `primordials` exports** rounding out the surface to 296 total:
-  - `BigIntCtor`
-  - Math: 24 methods (Acos, Atan2, Hypot, Pow, etc.) + 8 constants (E, PI, SQRT2, etc.); `MathF16round` typed `| undefined` for ES2025
-  - Number constants: `EPSILON`, `MAX_SAFE_INTEGER`, `MAX_VALUE`, `MIN_SAFE_INTEGER`, `MIN_VALUE`, `NEGATIVE_INFINITY`, `POSITIVE_INFINITY`
-  - Symbol: 10 well-knowns (`HasInstance`, `KeyFor`, `Match`, `Species`, etc.); `SymbolAsyncDispose` / `SymbolDispose` typed `| undefined` for ES2024; prototype helpers (`Description`, `ToString`, `ValueOf`)
-  - Function: `FunctionPrototypeToString`
-  - Array (ES2023 Change Array By Copy): `ArrayPrototypeToSpliced`, `ArrayPrototypeWith`
-  - Globals: `InfinityValue`, `NaNValue`, `globalThisRef`
-  - Object (annex B): `ObjectPrototype{Define,Lookup}{Getter,Setter}`
-  - Error (V8 stack-trace API, `| undefined`): `ErrorCaptureStackTrace`, `ErrorPrepareStackTrace`, `ErrorStackTraceLimit` (function-shaped, reads live value)
-
-- **`smol/*` (new exports)** — feature-detect + lazy-loaders for socket-btm's smol Node binary:
-  - `smol/detect` — `isSmol()`: memoized boolean, mirrors `isSeaBinary()`
-  - `smol/util` — `getSmolUtil()`: native `uncurryThis` / `applyBind` (~2x faster), or `undefined`
-  - `smol/primordial` — `getSmolPrimordial()`: V8 Fast API typed `Math.*` / `Number.is*` (~30-50% faster on hot loops), or `undefined`
-  - `primordials` transparently routes through these on smol; **zero call-site changes**, identical behavior on stock Node, smol, browsers, Deno, Bun
-
-- **`node/*` (new exports)** — per-builtin lazy-loaders for `node:*` modules. Each is `/*@__NO_SIDE_EFFECTS__*/`-marked so bundlers tree-shake the `require()` when unused:
-  - `node/fs` (`getNodeFs`), `node/path` (`getNodePath`), `node/crypto` (`getNodeCrypto`), `node/http` (`getNodeHttp`), `node/https` (`getNodeHttps`), `node/os` (`getNodeOs`), `node/util` (`getNodeUtil`), `node/url` (`getNodeUrl`), `node/events` (`getNodeEvents`)
-  - `node/child-process` (`getNodeChildProcess`), `node/async-hooks` (`getNodeAsyncHooks`), `node/fs-promises` (`getNodeFsPromises`), `node/timers-promises` (`getNodeTimersPromises`)
-  - Replaces ~30 ad-hoc copies of the same lazy-loader boilerplate previously scattered across `http-request.ts`, `spawn.ts`, `fs.ts`, `crypto.ts`, etc.
+- **45 new `primordials` exports** (296 total) — `BigIntCtor`; 24 `Math.*` methods + 8 constants (`MathF16round` typed `| undefined` for ES2025); 7 `Number` constants; 10 `Symbol` well-knowns + 3 prototype helpers (`SymbolAsyncDispose` / `SymbolDispose` typed `| undefined`); `FunctionPrototypeToString`; ES2023 array-copy (`ArrayPrototypeToSpliced`, `ArrayPrototypeWith`); `InfinityValue` / `NaNValue` / `globalThisRef`; `ObjectPrototype{Define,Lookup}{Getter,Setter}`; V8 stack-trace API.
+- **`smol/*`** — feature-detect for socket-btm's smol Node binary. `smol/detect` (`isSmol()`), `smol/util` (`getSmolUtil()` — native `uncurryThis` / `applyBind`), `smol/primordial` (`getSmolPrimordial()` — V8 Fast API typed `Math.*` / `Number.is*`). `primordials` routes through these on smol transparently; no call-site changes.
+- **`node/*`** — per-builtin lazy-loaders, side-effect-free for tree-shaking: `node/fs`, `node/path`, `node/crypto`, `node/http`, `node/https`, `node/os`, `node/util`, `node/url`, `node/events`, `node/child-process`, `node/async-hooks`, `node/fs-promises`, `node/timers-promises`.
 
 ## [5.26.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.1) - 2026-05-01
 
@@ -78,12 +107,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- `globs` `getGlobMatcher` — narrow the `path.matchesGlob` fast-path that an earlier draft introduced. `path.matchesGlob` doesn't honor the picomatch defaults (`dot: true`, `nocase: true`) that callers expect, so taking the fast-path under those defaults silently changed observable behavior — including breaking the case-insensitive default everywhere a single-pattern matcher was used. The fast-path now activates only when the caller has explicitly opted out of both defaults (`nocase: false` AND `dot: false`), signaling "I want strict, case-sensitive, no-dotfile-match" — exactly what `path.matchesGlob` provides
-- `globs` `glob` / `globSync` — normalize results to forward slashes via `paths/normalize.normalizePath` regardless of which backend (`node:fs.glob` or `fast-glob`) was used. Restores fast-glob's forward-slash contract on Windows, where `node:fs.glob` returns native-OS separators
-- `globs` `glob` / `globSync` / `globStreamLicenses` — strip a trailing `/` from `ignore` patterns before passing them to fast-glob. The gitignore convention of writing directory entries as `dist/` was silently dropped at the deep-filter level (fast-glob walked the entire subtree before discarding results), which on a large `dist/` could push memory past the limit. fast-glob v3.3.3 and the unreleased v4 both have the bug; tracked at [mrmlnc/fast-glob#437](https://github.com/mrmlnc/fast-glob/issues/437). Same workaround as [SocketDev/socket-cli#1288](https://github.com/SocketDev/socket-cli/pull/1288).
-- `releases/github-api` `getLatestRelease` and `getReleaseAssetUrl` transparently fall back to GraphQL when GitHub REST returns 200 + empty body (search-degraded incident shape)
-- `github` `resolveRefToSha` and `fetchGhsaDetails` get the same GraphQL fallback for the same incident shape
-- All fallbacks only fire on the empty-body signature; real 404s, rate-limits, and 5xx still propagate
+- `globs` `getGlobMatcher` — `path.matchesGlob` fast-path only activates when the caller opts out of both picomatch defaults (`nocase: false` AND `dot: false`); previously took the fast-path under default options and silently broke case-insensitive matching.
+- `globs` `glob` / `globSync` — results normalized to forward slashes on Windows regardless of backend (`node:fs.glob` returns native-OS separators).
+- `globs` `glob` / `globSync` / `globStreamLicenses` — trailing `/` stripped from `ignore` patterns before passing to fast-glob (gitignore-style `dist/` was silently dropped at the deep-filter level). Workaround for [mrmlnc/fast-glob#437](https://github.com/mrmlnc/fast-glob/issues/437).
+- GitHub helpers (`releases/github-api`, `github/resolveRefToSha`, `fetchGhsaDetails`) fall back to GraphQL on the "search-degraded" 200 OK + empty body shape. Real 404s / rate-limits / 5xx still propagate.
 
 ## [5.26.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.0) - 2026-04-27
 

package/README.md

@@ -2,7 +2,7 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)
 
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)

package/dist/abort/signal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Abort signal utilities — composite signal construction from multiple
+ *   sources and timeout-driven signal creation.
+ */
+/**
+ * Create a composite AbortSignal from multiple signals.
+ *
+ * @example
+ *   ;```typescript
+ *   const ac1 = new AbortController()
+ *   const ac2 = new AbortController()
+ *   const signal = createCompositeAbortSignal(ac1.signal, ac2.signal)
+ *   ```
+ */
+export declare function createCompositeAbortSignal(...signals: Array<AbortSignal | null | undefined>): AbortSignal;
+/**
+ * Create an AbortSignal that triggers after a timeout.
+ *
+ * @example
+ *   ;```typescript
+ *   const signal = createTimeoutSignal(5000) // aborts after 5 seconds
+ *   fetch('https://example.com', { signal })
+ *   ```
+ *
+ * @throws {TypeError} If `ms` is not a number, is NaN, is not finite, or is not
+ *   positive.
+ */
+export declare function createTimeoutSignal(ms: number): AbortSignal;

package/dist/{abort.js → abort/signal.js}

@@ -18,13 +18,15 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var abort_exports = {};
-__export(abort_exports, {
+var signal_exports = {};
+__export(signal_exports, {
   createCompositeAbortSignal: () => createCompositeAbortSignal,
   createTimeoutSignal: () => createTimeoutSignal
 });
-module.exports = __toCommonJS(abort_exports);
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(signal_exports);
+var import_error = require("../primordials/error");
+var import_math = require("../primordials/math");
+var import_number = require("../primordials/number");
 function createCompositeAbortSignal(...signals) {
   const validSignals = signals.filter((s) => s != null);
   if (validSignals.length === 0) {
@@ -44,16 +46,16 @@ function createCompositeAbortSignal(...signals) {
   return controller.signal;
 }
 function createTimeoutSignal(ms) {
-  if (typeof ms !== "number" || (0, import_primordials.NumberIsNaN)(ms)) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a number");
+  if (typeof ms !== "number" || (0, import_number.NumberIsNaN)(ms)) {
+    throw new import_error.TypeErrorCtor("timeout must be a number");
   }
-  if (!(0, import_primordials.NumberIsFinite)(ms)) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a finite number");
+  if (!(0, import_number.NumberIsFinite)(ms)) {
+    throw new import_error.TypeErrorCtor("timeout must be a finite number");
   }
   if (ms <= 0) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a positive number");
+    throw new import_error.TypeErrorCtor("timeout must be a positive number");
   }
-  return AbortSignal.timeout((0, import_primordials.MathCeil)(ms));
+  return AbortSignal.timeout((0, import_math.MathCeil)(ms));
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/ai/discover.d.mts

@@ -0,0 +1,50 @@
+/**
+ * @file Detect which AI agent CLIs are installed on PATH. Strategy:
+ *   which()-based lookup with a two-tier cache:
+ *
+ *   1. In-process Map — survives until the Node process exits.
+ *   2. On-disk JSON at `<repo>/.cache/agent-discovery.json`, TTL 1h — survives
+ *      across subprocess invocations (per-file ai-lint-fix batches) without
+ *      re-running which(). Cache invalidation: stale on-disk cache is detected
+ *      by mtime comparison; missing or expired → fresh which() pass + rewrite.
+ *      Why two tiers: hooks and skills spawn dozens of short-lived Node
+ *      processes per session. In-process alone misses the cross-process
+ *      speedup; on-disk alone hits the filesystem on every call. The
+ *      combination keeps repeated lookups under a millisecond after the
+ *      cold-start cost.
+ */
+import type { DiscoveredAgents } from './types.mts';
+export declare function cachePathFor(repoRoot: string): string;
+/**
+ * Discover which AI agent CLIs are installed.
+ *
+ * @param options.repoRoot - Where to read/write the on-disk cache. Defaults to
+ *   process.cwd(). Skill runners typically pass the target repo's root.
+ * @param options.refresh - When true, bypass both caches and re-run which().
+ *   Useful after `npm i -g <agent>` mid-session.
+ *
+ *   Returns a map of agent → absolute binary path. Agents that aren't installed
+ *   are absent from the map (not present-with-undefined), so callers can use
+ *   `'claude' in agents` for the existence check.
+ */
+export declare function discoverAiAgents(options?: {
+    readonly refresh?: boolean;
+    readonly repoRoot?: string;
+}): Promise<DiscoveredAgents>;
+export declare function discoverFresh(): DiscoveredAgents;
+/**
+ * Synchronous in-process lookup. Skips disk cache + which(). Returns undefined
+ * if discoverAiAgents() hasn't been called yet in this process, OR returns the
+ * most recent discovery result.
+ *
+ * Useful in fast paths where the caller has already populated the cache and
+ * just wants to read it back.
+ */
+export declare function getDiscoveredAiAgents(): DiscoveredAgents | undefined;
+export declare function readDiskCache(cachePath: string): DiscoveredAgents | undefined;
+/**
+ * Reset the in-process cache. Tests use this; production callers shouldn't need
+ * it (use `refresh: true` on discoverAiAgents()).
+ */
+export declare function resetAiAgentDiscoveryCache(): void;
+export declare function writeDiskCache(cachePath: string, agents: DiscoveredAgents): Promise<void>;

package/dist/ai/discover.js

@@ -0,0 +1,128 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var discover_exports = {};
+__export(discover_exports, {
+  cachePathFor: () => cachePathFor,
+  discoverAiAgents: () => discoverAiAgents,
+  discoverFresh: () => discoverFresh,
+  getDiscoveredAiAgents: () => getDiscoveredAiAgents,
+  readDiskCache: () => readDiskCache,
+  resetAiAgentDiscoveryCache: () => resetAiAgentDiscoveryCache,
+  writeDiskCache: () => writeDiskCache
+});
+module.exports = __toCommonJS(discover_exports);
+var import_node_fs = require("node:fs");
+var import_promises = require("node:fs/promises");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_which = require("../bin/which");
+var import_message = require("../errors/message");
+var import_logger = require("../logger/logger");
+var import_json = require("../primordials/json");
+const logger = (0, import_logger.getDefaultLogger)();
+const KNOWN_AGENTS = [
+  "claude",
+  "codex",
+  "gemini",
+  "opencode"
+];
+const CACHE_TTL_MS = 60 * 60 * 1e3;
+let inProcessCache;
+function cachePathFor(repoRoot) {
+  return import_node_path.default.join(repoRoot, ".cache", "agent-discovery.json");
+}
+async function discoverAiAgents(options = {}) {
+  const { refresh = false, repoRoot = process.cwd() } = options;
+  if (!refresh && inProcessCache) {
+    return inProcessCache;
+  }
+  const cachePath = cachePathFor(repoRoot);
+  if (!refresh) {
+    const fromDisk = readDiskCache(cachePath);
+    if (fromDisk) {
+      inProcessCache = fromDisk;
+      return fromDisk;
+    }
+  }
+  const fresh = discoverFresh();
+  inProcessCache = fresh;
+  await writeDiskCache(cachePath, fresh);
+  return fresh;
+}
+function discoverFresh() {
+  const out = {};
+  for (const name of KNOWN_AGENTS) {
+    const found = (0, import_which.whichSync)(name);
+    if (typeof found === "string" && found) {
+      out[name] = found;
+    }
+  }
+  return out;
+}
+function getDiscoveredAiAgents() {
+  return inProcessCache;
+}
+function readDiskCache(cachePath) {
+  if (!(0, import_node_fs.existsSync)(cachePath)) {
+    return void 0;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(cachePath, "utf8");
+    const parsed = (0, import_json.JSONParse)(raw);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.writtenAt !== "number" || Date.now() - parsed.writtenAt > CACHE_TTL_MS) {
+      return void 0;
+    }
+    return parsed.agents;
+  } catch {
+    return void 0;
+  }
+}
+function resetAiAgentDiscoveryCache() {
+  inProcessCache = void 0;
+}
+async function writeDiskCache(cachePath, agents) {
+  try {
+    await (0, import_promises.mkdir)(import_node_path.default.dirname(cachePath), { recursive: true });
+    const payload = { agents, writtenAt: Date.now() };
+    (0, import_node_fs.writeFileSync)(cachePath, (0, import_json.JSONStringify)(payload, void 0, 2) + "\n");
+  } catch (e) {
+    logger.error(`discoverAiAgents: cache write failed (${(0, import_message.errorMessage)(e)})`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cachePathFor,
+  discoverAiAgents,
+  discoverFresh,
+  getDiscoveredAiAgents,
+  readDiskCache,
+  resetAiAgentDiscoveryCache,
+  writeDiskCache
+});

package/dist/ai/profiles.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @file Pre-built lockdown profiles for spawnAiAgent. Per CLAUDE.md
+ *   "Programmatic Claude calls" rule: every spawn must set tools / disallow /
+ *   permissionMode (and the helper always sets --no-session-persistence +
+ *   --add-dir cwd). These profiles are canonical safe defaults that callers
+ *   spread + override per call. Choose by capability:
+ *
+ *   - `READ_ONLY_PROFILE` — research / scanning. Read + Grep + Glob
+ *   - WebFetch + WebSearch. No Edit, no Write, no Bash. Use for static analysis
+ *     skills (scanning-quality, scanning-security).
+ *   - `EDIT_ONLY_PROFILE` — fix-mode. Read + Edit + Grep + Glob. Bash explicitly
+ *     denied. Use for skills that mutate source files but don't run arbitrary
+ *     shell (ai-lint-fix, refactor passes).
+ *   - `FULL_FIX_PROFILE` — fix-mode WITH Bash. Read + Edit + Write + Grep + Glob
+ *   - Bash (allowlisted to git/pnpm/node by default). Use for skills that need to
+ *     commit, run tests, install deps. No `WIDE_OPEN_PROFILE` exists by design
+ *     — letting an agent run arbitrary tools is the lockdown rule's exact
+ *     failure mode.
+ */
+import type { PermissionMode } from './types.mts';
+interface Profile {
+    readonly allow: readonly string[];
+    readonly disallow: readonly string[];
+    readonly permissionMode: PermissionMode;
+    readonly tools: readonly string[];
+}
+/**
+ * Read-only research / scanning. No mutation.
+ */
+export declare const READ_ONLY_PROFILE: Profile;
+/**
+ * Edit-mode without Bash. Mutates source but can't run shell.
+ */
+export declare const EDIT_ONLY_PROFILE: Profile;
+/**
+ * Fix-mode with Bash, allowlisted to git / pnpm / node.
+ */
+export declare const FULL_FIX_PROFILE: Profile;
+export {};

package/dist/ai/profiles.js

@@ -0,0 +1,61 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var profiles_exports = {};
+__export(profiles_exports, {
+  EDIT_ONLY_PROFILE: () => EDIT_ONLY_PROFILE,
+  FULL_FIX_PROFILE: () => FULL_FIX_PROFILE,
+  READ_ONLY_PROFILE: () => READ_ONLY_PROFILE
+});
+module.exports = __toCommonJS(profiles_exports);
+const READ_ONLY_PROFILE = {
+  allow: [],
+  disallow: ["Bash", "Edit", "MultiEdit", "Write"],
+  permissionMode: "dontAsk",
+  tools: ["Glob", "Grep", "Read", "WebFetch", "WebSearch"]
+};
+const EDIT_ONLY_PROFILE = {
+  allow: [],
+  disallow: ["Bash", "WebFetch", "WebSearch"],
+  permissionMode: "acceptEdits",
+  tools: ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+};
+const FULL_FIX_PROFILE = {
+  allow: [
+    "Bash(git status:*)",
+    "Bash(git diff:*)",
+    "Bash(git log:*)",
+    "Bash(git add:*)",
+    "Bash(git commit:*)",
+    "Bash(node:*)",
+    "Bash(pnpm exec:*)",
+    "Bash(pnpm run:*)",
+    "Bash(pnpm test:*)"
+  ],
+  disallow: ["WebFetch", "WebSearch"],
+  permissionMode: "acceptEdits",
+  tools: ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EDIT_ONLY_PROFILE,
+  FULL_FIX_PROFILE,
+  READ_ONLY_PROFILE
+});

package/dist/ai/spawn.d.mts

@@ -0,0 +1,49 @@
+/**
+ * @file Locked-down spawn for AI agent CLIs (Claude / Codex / Gemini /
+ *   OpenCode). Per the CLAUDE.md "Programmatic Claude calls" rule: every
+ *   headless invocation MUST set the four lockdown flags (tools / disallow /
+ *   permissionMode / no-session-persistence). The helper enforces this at the
+ *   type level (`SpawnAiAgentOptions` requires the relevant fields) AND at the
+ *   spawn site (per-agent flag translator). Why CLI subprocess instead of an
+ *   SDK call: the fleet's contract matches what the local user sees when
+ *   invoking the CLI — same auth config, same model availability, same tool
+ *   permissions. SDK calls would diverge on auth handling and force per-agent
+ *   SDK installs. Retry: 3 attempts on overload (HTTP 529 / "Overloaded"), exp.
+ *   backoff (5s / 15s / 45s). Each retry is a fresh subprocess.
+ */
+import type { AgentSpawnResult, AiAgentName, SpawnAiAgentOptions } from './types.mts';
+export declare function backoffFor(attempt: number): number;
+/**
+ * Build CLI arg list for a given agent. The flag names differ across agents but
+ * the conceptual surface is the same: "here are the allowed tools, here are the
+ * denied tools, here is the permission mode, do not persist a session." This
+ * translator is the single source of truth for how each agent's flags map.
+ *
+ * Update sites (when an agent changes its flag surface): 1. The relevant case
+ * below. 2. The agent's docs link (cited inline).
+ */
+export declare function buildArgs(agent: AiAgentName, opts: SpawnAiAgentOptions): string[];
+export declare function isOverloaded(stdout: string, stderr: string): boolean;
+export declare function pickAgent(requested: AiAgentName | undefined, cwd: string): Promise<AiAgentName>;
+/**
+ * Spawn an AI agent CLI subprocess with the locked-down flag set.
+ *
+ * @example
+ *   ```ts
+ *   import { EDIT_ONLY_PROFILE } from '@socketsecurity/lib/ai/profiles'
+ *   import { spawnAiAgent } from '@socketsecurity/lib/ai/spawn'
+ *
+ *   const result = await spawnAiAgent({
+ *   ...EDIT_ONLY_PROFILE,
+ *   prompt: 'Fix the lint findings in src/foo.ts',
+ *   cwd: process.cwd(),
+ *   model: 'claude-sonnet-4-6',
+ *   timeoutMs: 5 * 60 * 1000,
+ *   })
+ *   if (result.exitCode !== 0) { ... }
+ *   ```
+ *
+ *   Throws when the requested agent isn't on PATH (or, when no agent
+ *   is requested, when none of the known agents are on PATH).
+ */
+export declare function spawnAiAgent(opts: SpawnAiAgentOptions): Promise<AgentSpawnResult>;