@socketsecurity/lib 6.0.7 → 6.0.8

package/dist/ai/route.d.mts

@@ -0,0 +1,69 @@
+/**
+ * @file Availability-gated tier routing. `tier.mts` says which model+effort is
+ *   the "perfect" choice for a unit of work; this module turns that hint into a
+ *   concrete spawn target that ACTUALLY EXISTS on the machine. A tier resolves
+ *   to its preferred engine only when that engine's CLI is installed AND a
+ *   credential for it is resolvable; otherwise the resolver walks a
+ *   cross-engine equivalence ladder (Claude → Codex → an open-weight provider
+ *   via opencode) and returns the best available equivalent. Why gate on
+ *   existence: a fleet machine may have Claude but no Codex, or Codex but an
+ *   expired Claude key, or neither plus an opencode/synthetic seat. Hard-coding
+ *   `fable` then fails at spawn time; routing here degrades gracefully and
+ *   tells the caller WHY (the `reason`), so a skill can log "fell back to codex
+ *   gpt-5.5 (claude unavailable)" instead of crashing. Pure given an
+ *   availability/keyed context — no I/O — so callers fan out their `which` +
+ *   credential probes once and pass the result in. Pairs with `buildArgs` in
+ *   `spawn.mts`: a Fable candidate carries `effort: undefined` because Fable is
+ *   adaptive-thinking-only and the spawn layer omits `--effort` for it anyway.
+ */
+import type { CredentialProvider } from './credentials.mts';
+import type { AiAgentName, AiEffort } from './types.mts';
+import type { AiTier } from './tier.mts';
+/**
+ * A concrete, spawnable target: which CLI engine to run, the model id, the
+ * reasoning effort to pass (undefined when the model ignores effort, e.g.
+ * Fable), and the credential provider whose key gates it.
+ */
+export interface TierCandidate {
+    readonly effort: AiEffort | undefined;
+    readonly engine: AiAgentName;
+    readonly model: string;
+    readonly provider: CredentialProvider;
+}
+/**
+ * Why the resolver returned what it did. - `preferred` — the tier's
+ * first-choice engine was available + keyed. - `fellback` — the preferred
+ * engine was missing/unkeyed; an equivalent on another engine was used (`from`
+ * names the original tier).
+ */
+export type TierResolveReason = 'fellback' | 'preferred';
+export interface TierResolution {
+    readonly candidate: TierCandidate;
+    readonly reason: TierResolveReason;
+    readonly from?: AiTier | undefined;
+}
+/**
+ * The context a caller probes once and passes in: which engine CLIs exist, and
+ * which credential providers have a resolvable key. Both are sets so the
+ * resolver stays pure (no `which` / keychain I/O of its own).
+ */
+export interface RouteContext {
+    readonly available: ReadonlySet<AiAgentName>;
+    readonly keyed: ReadonlySet<CredentialProvider>;
+}
+export declare const TIER_CHAINS: Readonly<Record<AiTier, readonly TierCandidate[]>>;
+/**
+ * A candidate is usable when its engine CLI exists AND a credential for its
+ * provider is resolvable. Both gates matter: an installed Claude with an
+ * expired key is as unusable as a missing CLI.
+ */
+export declare function isCandidateUsable(candidate: TierCandidate, ctx: RouteContext): boolean;
+/**
+ * Resolve a tier to the best available concrete target. Prefers the tier's
+ * first-choice (Claude) candidate; if its engine is missing or unkeyed, walks
+ * the cross-engine equivalence ladder and returns the first usable equivalent,
+ * tagging the result `fellback` with the original tier in `from`. Returns
+ * `undefined` only when NOTHING in the chain is usable — the caller then skips
+ * the work or surfaces a "no AI engine available" message.
+ */
+export declare function resolveTier(tier: AiTier, ctx: RouteContext): TierResolution | undefined;

package/dist/ai/route.js

@@ -0,0 +1,156 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_ai_tier = require('./tier.js');
+
+//#region src/ai/route.mts
+/**
+* @file Availability-gated tier routing. `tier.mts` says which model+effort is
+*   the "perfect" choice for a unit of work; this module turns that hint into a
+*   concrete spawn target that ACTUALLY EXISTS on the machine. A tier resolves
+*   to its preferred engine only when that engine's CLI is installed AND a
+*   credential for it is resolvable; otherwise the resolver walks a
+*   cross-engine equivalence ladder (Claude → Codex → an open-weight provider
+*   via opencode) and returns the best available equivalent. Why gate on
+*   existence: a fleet machine may have Claude but no Codex, or Codex but an
+*   expired Claude key, or neither plus an opencode/synthetic seat. Hard-coding
+*   `fable` then fails at spawn time; routing here degrades gracefully and
+*   tells the caller WHY (the `reason`), so a skill can log "fell back to codex
+*   gpt-5.5 (claude unavailable)" instead of crashing. Pure given an
+*   availability/keyed context — no I/O — so callers fan out their `which` +
+*   credential probes once and pass the result in. Pairs with `buildArgs` in
+*   `spawn.mts`: a Fable candidate carries `effort: undefined` because Fable is
+*   adaptive-thinking-only and the spawn layer omits `--effort` for it anyway.
+*/
+/**
+* Per-tier preference chain, most-preferred-first. The head is the "perfect"
+* Claude choice from `AI_TIER`; the tail is the cross-engine equivalent ladder
+* (Codex, then an open-weight provider reached through opencode). Effort is the
+* shared `AiEffort` vocab; `buildArgs` translates per engine (codex clamps
+* `max`→`xhigh`, Fable drops effort entirely).
+*
+* The Claude head reuses `AI_TIER` so a model-generation bump stays a single
+* edit there. Fable's head carries `effort: undefined` — it is adaptive-only.
+*/
+const FABLE = require_ai_tier.AI_TIER.fable;
+const OPUS = require_ai_tier.AI_TIER.opus;
+const SONNET = require_ai_tier.AI_TIER.sonnet;
+const HAIKU = require_ai_tier.AI_TIER.haiku;
+const TIER_CHAINS = {
+	__proto__: null,
+	fable: [
+		{
+			effort: void 0,
+			engine: "claude",
+			model: FABLE.model,
+			provider: "anthropic"
+		},
+		{
+			effort: "xhigh",
+			engine: "codex",
+			model: "gpt-5.5",
+			provider: "openai"
+		},
+		{
+			effort: "xhigh",
+			engine: "opencode",
+			model: "fireworks-ai/accounts/fireworks/models/glm-5p1",
+			provider: "fireworks"
+		}
+	],
+	opus: [
+		{
+			effort: OPUS.effort,
+			engine: "claude",
+			model: OPUS.model,
+			provider: "anthropic"
+		},
+		{
+			effort: "high",
+			engine: "codex",
+			model: "gpt-5.5",
+			provider: "openai"
+		},
+		{
+			effort: "high",
+			engine: "opencode",
+			model: "fireworks-ai/accounts/fireworks/models/glm-5p1",
+			provider: "fireworks"
+		}
+	],
+	sonnet: [
+		{
+			effort: SONNET.effort,
+			engine: "claude",
+			model: SONNET.model,
+			provider: "anthropic"
+		},
+		{
+			effort: "medium",
+			engine: "codex",
+			model: "gpt-5.5",
+			provider: "openai"
+		},
+		{
+			effort: "medium",
+			engine: "opencode",
+			model: "synthetic/hf:moonshotai/Kimi-K2.5",
+			provider: "synthetic"
+		}
+	],
+	haiku: [
+		{
+			effort: HAIKU.effort,
+			engine: "claude",
+			model: HAIKU.model,
+			provider: "anthropic"
+		},
+		{
+			effort: "low",
+			engine: "codex",
+			model: "gpt-5.5",
+			provider: "openai"
+		},
+		{
+			effort: "low",
+			engine: "opencode",
+			model: "synthetic/hf:moonshotai/Kimi-K2.5",
+			provider: "synthetic"
+		}
+	]
+};
+/**
+* A candidate is usable when its engine CLI exists AND a credential for its
+* provider is resolvable. Both gates matter: an installed Claude with an
+* expired key is as unusable as a missing CLI.
+*/
+function isCandidateUsable(candidate, ctx) {
+	return ctx.available.has(candidate.engine) && ctx.keyed.has(candidate.provider);
+}
+/**
+* Resolve a tier to the best available concrete target. Prefers the tier's
+* first-choice (Claude) candidate; if its engine is missing or unkeyed, walks
+* the cross-engine equivalence ladder and returns the first usable equivalent,
+* tagging the result `fellback` with the original tier in `from`. Returns
+* `undefined` only when NOTHING in the chain is usable — the caller then skips
+* the work or surfaces a "no AI engine available" message.
+*/
+function resolveTier(tier, ctx) {
+	const chain = TIER_CHAINS[tier] ?? TIER_CHAINS.sonnet;
+	for (let i = 0, { length } = chain; i < length; i += 1) {
+		const candidate = chain[i];
+		if (isCandidateUsable(candidate, ctx)) return i === 0 ? {
+			candidate,
+			reason: "preferred"
+		} : {
+			candidate,
+			from: tier,
+			reason: "fellback"
+		};
+	}
+}
+
+//#endregion
+exports.TIER_CHAINS = TIER_CHAINS;
+exports.isCandidateUsable = isCandidateUsable;
+exports.resolveTier = resolveTier;

package/dist/ai/spawn.d.mts

@@ -22,7 +22,15 @@ export declare function backoffFor(attempt: number): number;
  * 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 buildArgs(agent: AiAgentName, options: SpawnAiAgentOptions): string[];
+/**
+ * Fable and Mythos run adaptive thinking only — thinking is always on and there
+ * is no manual thinking-budget knob. The effort dial does not apply the way it
+ * does on Opus, so the spawn layer drops `--effort` for these models rather
+ * than passing a level they should ignore. Matches both alias and full-id
+ * shapes (`fable`, `claude-fable-5`, `mythos`, `claude-mythos-5`).
+ */
+export declare function isAdaptiveOnlyModel(model: string): boolean;
 export declare function isOverloaded(stdout: string, stderr: string): boolean;
 export declare function pickAgent(requested: AiAgentName | undefined, cwd: string): Promise<AiAgentName>;
 /**
@@ -46,4 +54,4 @@ export declare function pickAgent(requested: AiAgentName | undefined, cwd: strin
  *   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>;
+export declare function spawnAiAgent(options: SpawnAiAgentOptions): Promise<AgentSpawnResult>;

package/dist/ai/spawn.js

@@ -2,12 +2,12 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_error = require('../primordials/error.js');
-const require_primordials_date = require('../primordials/date.js');
 const require_primordials_object = require('../primordials/object.js');
+const require_primordials_date = require('../primordials/date.js');
 const require_errors_message = require('../errors/message.js');
-const require_ai_discover = require('./discover.js');
 const require_process_spawn_errors = require('../process/spawn/errors.js');
 const require_process_spawn_child = require('../process/spawn/child.js');
+const require_ai_discover = require('./discover.js');
 const require_primordials_promise = require('../primordials/promise.js');
 
 //#region src/ai/spawn.mts
@@ -38,63 +38,81 @@ function backoffFor(attempt) {
 * Update sites (when an agent changes its flag surface): 1. The relevant case
 * below. 2. The agent's docs link (cited inline).
 */
-function buildArgs(agent, opts) {
-	const allAllowed = [...opts.tools, ...opts.allow ?? []];
+function buildArgs(agent, options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const allAllowed = [...options.tools, ...options.allow ?? []];
 	switch (agent) {
 		case "claude": {
 			const args = [
 				"--print",
 				"--no-session-persistence",
 				"--permission-mode",
-				opts.permissionMode,
+				options.permissionMode,
 				"--add-dir",
-				opts.cwd
+				options.cwd
 			];
-			for (const dir of opts.addDirs ?? []) args.push("--add-dir", dir);
-			if (opts.model) args.push("--model", opts.model);
-			if (opts.effort) args.push("--effort", opts.effort);
+			for (const dir of options.addDirs ?? []) args.push("--add-dir", dir);
+			if (options.model) args.push("--model", options.model);
+			if (options.effort && !isAdaptiveOnlyModel(options.model ?? "")) args.push("--effort", options.effort);
 			if (allAllowed.length > 0) args.push("--allowedTools", ...allAllowed);
-			if (opts.disallow.length > 0) args.push("--disallowedTools", ...opts.disallow);
-			if (opts.extraArgs) args.push(...opts.extraArgs);
+			if (options.disallow.length > 0) args.push("--disallowedTools", ...options.disallow);
+			if (options.extraArgs) args.push(...options.extraArgs);
 			return args;
 		}
 		case "codex": {
 			const args = ["--print"];
-			if (opts.permissionMode === "plan") args.push("--read-only");
-			if (opts.model) args.push("--model", opts.model);
+			if (options.permissionMode === "plan") args.push("--read-only");
+			if (options.model) args.push("--model", options.model);
+			if (options.effort) {
+				const codexEffort = options.effort === "max" ? "xhigh" : options.effort;
+				args.push("-c", `model_reasoning_effort=${codexEffort}`);
+			}
 			if (allAllowed.length > 0) args.push("--tools", allAllowed.join(","));
-			if (opts.disallow.length > 0) args.push("--disallow-tools", opts.disallow.join(","));
-			args.push("--cwd", opts.cwd);
-			if (opts.extraArgs) args.push(...opts.extraArgs);
+			if (options.disallow.length > 0) args.push("--disallow-tools", options.disallow.join(","));
+			args.push("--cwd", options.cwd);
+			if (options.extraArgs) args.push(...options.extraArgs);
 			return args;
 		}
 		case "gemini": {
 			const args = [
 				"--no-interactive",
 				"--workspace",
-				opts.cwd
+				options.cwd
 			];
-			if (opts.model) args.push("--model", opts.model);
+			if (options.model) args.push("--model", options.model);
 			if (allAllowed.length > 0) args.push("--allowed-tools", allAllowed.join(","));
-			if (opts.disallow.length > 0) args.push("--denied-tools", opts.disallow.join(","));
-			if (opts.permissionMode === "plan") args.push("--read-only");
-			if (opts.extraArgs) args.push(...opts.extraArgs);
+			if (options.disallow.length > 0) args.push("--denied-tools", options.disallow.join(","));
+			if (options.permissionMode === "plan") args.push("--read-only");
+			if (options.extraArgs) args.push(...options.extraArgs);
 			return args;
 		}
 		case "opencode": {
 			const args = [
 				"--print",
 				"--cwd",
-				opts.cwd
+				options.cwd
 			];
-			if (opts.model) args.push("--model", opts.model);
+			if (options.model) args.push("--model", options.model);
 			if (allAllowed.length > 0) args.push("--tools", allAllowed.join(","));
-			if (opts.disallow.length > 0) args.push("--no-tools", opts.disallow.join(","));
-			if (opts.extraArgs) args.push(...opts.extraArgs);
+			if (options.disallow.length > 0) args.push("--no-tools", options.disallow.join(","));
+			if (options.extraArgs) args.push(...options.extraArgs);
 			return args;
 		}
 	}
 }
+/**
+* Fable and Mythos run adaptive thinking only — thinking is always on and there
+* is no manual thinking-budget knob. The effort dial does not apply the way it
+* does on Opus, so the spawn layer drops `--effort` for these models rather
+* than passing a level they should ignore. Matches both alias and full-id
+* shapes (`fable`, `claude-fable-5`, `mythos`, `claude-mythos-5`).
+*/
+function isAdaptiveOnlyModel(model) {
+	return /\b(?:fable|mythos)\b/i.test(model) || /claude-(?:fable|mythos)/i.test(model);
+}
 function isOverloaded(stdout, stderr) {
 	const re = /API Error: 529|Overloaded/i;
 	return re.test(stdout) || re.test(stderr);
@@ -134,9 +152,13 @@ async function pickAgent(requested, cwd) {
 *   Throws when the requested agent isn't on PATH (or, when no agent
 *   is requested, when none of the known agents are on PATH).
 */
-async function spawnAiAgent(opts) {
-	const agent = await pickAgent(opts.agent, opts.cwd);
-	const args = buildArgs(agent, opts);
+async function spawnAiAgent(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
+	const agent = await pickAgent(options.agent, options.cwd);
+	const args = buildArgs(agent, options);
 	let stdout = "";
 	let stderr = "";
 	let exitCode = 0;
@@ -149,12 +171,12 @@ async function spawnAiAgent(opts) {
 		exitCode = 0;
 		try {
 			const child = require_process_spawn_child.spawn(agent, args, {
-				cwd: opts.cwd,
+				cwd: options.cwd,
 				stdio: "pipe",
 				stdioString: true,
-				timeout: opts.timeoutMs
+				timeout: options.timeoutMs
 			});
-			child.stdin?.end(opts.prompt);
+			child.stdin?.end(options.prompt);
 			const result = await child;
 			stdout = String(result.stdout ?? "");
 			stderr = String(result.stderr ?? "");
@@ -176,6 +198,7 @@ async function spawnAiAgent(opts) {
 		attempts,
 		durationMs: require_primordials_date.DateNow() - start,
 		exitCode,
+		overloaded: isOverloaded(stdout, stderr),
 		stderr,
 		stdout
 	};
@@ -184,6 +207,7 @@ async function spawnAiAgent(opts) {
 //#endregion
 exports.backoffFor = backoffFor;
 exports.buildArgs = buildArgs;
+exports.isAdaptiveOnlyModel = isAdaptiveOnlyModel;
 exports.isOverloaded = isOverloaded;
 exports.pickAgent = pickAgent;
 exports.spawnAiAgent = spawnAiAgent;

package/dist/ai/subagent-status.d.mts

@@ -0,0 +1,48 @@
+/**
+ * @file The terminal-status contract a delegated subagent returns to its
+ *   orchestrator. Subagent-driven development depends on a SMALL, fixed status
+ *   vocabulary so the orchestrator can route deterministically instead of
+ *   parsing free-form prose: a subagent that "sort of finished but has a worry"
+ *   must be distinguishable from one that is genuinely blocked, because they
+ *   escalate differently. The four states and their escalation paths are the
+ *   contract; `escalationFor` is the single place that maps a state to what the
+ *   orchestrator does next. Encoding it as a typed union + map (rather than a
+ *   doc convention) is the code-is-law surface: a stray status string fails the
+ *   guard, and `agent-delegation.md` is checked against this union so the prose
+ *   can't drift from the code.
+ */
+/**
+ * A subagent's terminal status.
+ *
+ * - `done` — work complete, no reservations; the orchestrator advances.
+ * - `done-with-concerns` — work complete but the subagent flagged a risk or
+ *   follow-up the orchestrator should surface before advancing.
+ * - `needs-context` — the subagent lacks information it cannot obtain itself; the
+ *   orchestrator supplies it and re-dispatches (a fresh attempt, not the same
+ *   model retrying blind).
+ * - `blocked` — the work cannot proceed without a decision or action only the
+ *   user can provide; the orchestrator escalates to the user and stops.
+ */
+export type SubagentStatus = 'blocked' | 'done' | 'done-with-concerns' | 'needs-context';
+/**
+ * What the orchestrator does for each terminal status. `advance` continues to
+ * the next unit of work; `surface` advances but raises the concern first;
+ * `redispatch` re-runs the unit with the missing context added; `escalate`
+ * stops and hands the decision to the user.
+ */
+export type SubagentEscalation = 'advance' | 'escalate' | 'redispatch' | 'surface';
+/**
+ * The canonical status set, sorted, for callers that need to enumerate or
+ * validate against the full vocabulary (the doc-parity check reads this).
+ */
+export declare const SUBAGENT_STATUSES: readonly SubagentStatus[];
+/**
+ * Map a terminal status to the orchestrator action it requires. A status
+ * outside the vocabulary is itself a contract violation, so this throws rather
+ * than guessing — never force a retry on an unrecognized state.
+ */
+export declare function escalationFor(status: SubagentStatus): SubagentEscalation;
+/**
+ * True when `value` names a status in the contract.
+ */
+export declare function isSubagentStatus(value: string): value is SubagentStatus;

package/dist/ai/subagent-status.js

@@ -0,0 +1,57 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+
+//#region src/ai/subagent-status.mts
+/**
+* @file The terminal-status contract a delegated subagent returns to its
+*   orchestrator. Subagent-driven development depends on a SMALL, fixed status
+*   vocabulary so the orchestrator can route deterministically instead of
+*   parsing free-form prose: a subagent that "sort of finished but has a worry"
+*   must be distinguishable from one that is genuinely blocked, because they
+*   escalate differently. The four states and their escalation paths are the
+*   contract; `escalationFor` is the single place that maps a state to what the
+*   orchestrator does next. Encoding it as a typed union + map (rather than a
+*   doc convention) is the code-is-law surface: a stray status string fails the
+*   guard, and `agent-delegation.md` is checked against this union so the prose
+*   can't drift from the code.
+*/
+const ESCALATION = {
+	__proto__: null,
+	blocked: "escalate",
+	done: "advance",
+	"done-with-concerns": "surface",
+	"needs-context": "redispatch"
+};
+/**
+* The canonical status set, sorted, for callers that need to enumerate or
+* validate against the full vocabulary (the doc-parity check reads this).
+*/
+const SUBAGENT_STATUSES = [
+	"blocked",
+	"done",
+	"done-with-concerns",
+	"needs-context"
+];
+/**
+* Map a terminal status to the orchestrator action it requires. A status
+* outside the vocabulary is itself a contract violation, so this throws rather
+* than guessing — never force a retry on an unrecognized state.
+*/
+function escalationFor(status) {
+	const action = ESCALATION[status];
+	if (!action) throw new require_primordials_error.ErrorCtor(`escalationFor: unknown subagent status "${status}". Expected one of: ${SUBAGENT_STATUSES.join(", ")}. Return a status from the SubagentStatus contract.`);
+	return action;
+}
+/**
+* True when `value` names a status in the contract.
+*/
+function isSubagentStatus(value) {
+	return SUBAGENT_STATUSES.includes(value);
+}
+
+//#endregion
+exports.SUBAGENT_STATUSES = SUBAGENT_STATUSES;
+exports.escalationFor = escalationFor;
+exports.isSubagentStatus = isSubagentStatus;

package/dist/ai/tier.d.mts

@@ -0,0 +1,60 @@
+/**
+ * @file Canonical model + reasoning-effort ladder for AI orchestrators. The
+ *   fleet's AI-fix / AI-codify orchestrators pick a capability TIER per unit of
+ *   work (a lint rule, a hook, a doc edit) and resolve it to a concrete `{
+ *   model, effort }` pair. Before this module each orchestrator redefined the
+ *   same three-row table, so a model-generation bump (Sonnet 4.6 → 5.0, Opus
+ *   4.8 → 4.9) meant editing N files and risked drift. Import `AI_TIER` /
+ *   `tierToSpawn` here instead; a generation roll is then a single edit. The
+ *   mapping encodes the CLAUDE.md token-spend rule ("match model AND effort to
+ *   the job"): a cheap model left on the session's default effort still burns
+ *   reasoning a mechanical task never needs, and a premium model on low effort
+ *   under-thinks a hard one — so effort is pinned ALONGSIDE the model per
+ *   tier.
+ */
+import type { AiEffort } from './types.mts';
+/**
+ * The capability tiers, least → most capable. Orchestrators classify each unit
+ * of work into one of these (a regex-shaped rewrite → `haiku`; a caller-chain
+ * rewrite → `sonnet`; a module split / new-enforcer authoring → `opus`).
+ * `fable` is the apex escalation tier — reserve it for the hardest cases (a
+ * stuck compiler / native problem, planning + decomposition of a large task),
+ * never a first reach, and prefer to ask before selecting it. It is the most
+ * expensive model on the board (~2× opus, ~10× haiku output), so an
+ * orchestrator should pick the LEAST-capable tier that does the job and
+ * escalate to `fable` only after cheaper tiers fail.
+ */
+export type AiTier = 'fable' | 'haiku' | 'opus' | 'sonnet';
+/**
+ * Resolved spawn parameters for a tier — spread alongside an `AI_PROFILE` into
+ * a `spawnAiAgent` call (`{ ...AI_PROFILE.verify, ...tierToSpawn('opus'),
+ * prompt, cwd }`).
+ */
+export interface TierSpawn {
+    readonly effort: AiEffort;
+    readonly model: string;
+}
+/**
+ * Canonical tier → { model, effort }. The single source of truth for which
+ * Claude model + effort each tier runs. Bump here on a model generation roll;
+ * every orchestrator that imports this picks it up.
+ *
+ * - `haiku` / low — deterministic, regex-shaped rewrites (identifier rename,
+ *   null→undefined, single-token substitution).
+ * - `sonnet` / medium — control-flow / caller-chain reasoning (fetch→httpJson,
+ *   sync→async), a check script, a doc edit.
+ * - `opus` / high — real authoring / refactoring (module split, a brand-new hook
+ *   or lint rule with its test).
+ * - `fable` / xhigh — apex escalation only: a stuck compiler / native problem
+ *   after cheaper tiers fail, or planning + decomposition of a large task whose
+ *   chunks then run on cheaper tiers. Most expensive model on the board; never
+ *   a default.
+ */
+export declare const AI_TIER: Readonly<Record<AiTier, TierSpawn>>;
+/**
+ * Resolve a tier label to its `{ model, effort }` spawn pair. A convenience
+ * over indexing `AI_TIER` directly; returns the `sonnet` row for an unknown
+ * label so a caller that hands in a stray string degrades to the safe default
+ * rather than producing `undefined` model/effort.
+ */
+export declare function tierToSpawn(tier: AiTier): TierSpawn;

package/dist/ai/tier.js

@@ -0,0 +1,53 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/ai/tier.mts
+/**
+* Canonical tier → { model, effort }. The single source of truth for which
+* Claude model + effort each tier runs. Bump here on a model generation roll;
+* every orchestrator that imports this picks it up.
+*
+* - `haiku` / low — deterministic, regex-shaped rewrites (identifier rename,
+*   null→undefined, single-token substitution).
+* - `sonnet` / medium — control-flow / caller-chain reasoning (fetch→httpJson,
+*   sync→async), a check script, a doc edit.
+* - `opus` / high — real authoring / refactoring (module split, a brand-new hook
+*   or lint rule with its test).
+* - `fable` / xhigh — apex escalation only: a stuck compiler / native problem
+*   after cheaper tiers fail, or planning + decomposition of a large task whose
+*   chunks then run on cheaper tiers. Most expensive model on the board; never
+*   a default.
+*/
+const AI_TIER = {
+	__proto__: null,
+	fable: {
+		effort: "xhigh",
+		model: "claude-fable-5"
+	},
+	haiku: {
+		effort: "low",
+		model: "claude-haiku-4-5"
+	},
+	opus: {
+		effort: "high",
+		model: "claude-opus-4-8"
+	},
+	sonnet: {
+		effort: "medium",
+		model: "claude-sonnet-4-6"
+	}
+};
+/**
+* Resolve a tier label to its `{ model, effort }` spawn pair. A convenience
+* over indexing `AI_TIER` directly; returns the `sonnet` row for an unknown
+* label so a caller that hands in a stray string degrades to the safe default
+* rather than producing `undefined` model/effort.
+*/
+function tierToSpawn(tier) {
+	return AI_TIER[tier] ?? AI_TIER.sonnet;
+}
+
+//#endregion
+exports.AI_TIER = AI_TIER;
+exports.tierToSpawn = tierToSpawn;

package/dist/ai/types.d.mts

@@ -26,8 +26,14 @@ export type AiAgentName = 'claude' | 'codex' | 'gemini' | 'opencode';
  */
 export type PermissionMode = 'acceptEdits' | 'dontAsk' | 'plan';
 /**
- * Reasoning-effort level for the agent session. Maps to the claude CLI
- * `--effort <level>` flag (claude-specific; other agents ignore it). Pair a
+ * Reasoning-effort level for the agent session. Two agents consume it, each via
+ * its own flag — `buildArgs` translates per-agent:
+ *
+ * - Claude: `--effort <level>`, accepts low/medium/high/xhigh/max.
+ * - Codex: `-c model_reasoning_effort=<level>`, accepts minimal/low/medium/high/
+ *   xhigh (no `max` — `buildArgs` clamps `max` → `xhigh`, codex's ceiling).
+ *
+ * Gemini / opencode have no reasoning-effort flag, so they ignore it. Pair a
  * cheap model with low effort for mechanical work and reserve high/max for
  * tasks that genuinely need deeper reasoning.
  */
@@ -41,6 +47,13 @@ export interface AgentSpawnResult {
     readonly attempts: number;
     readonly durationMs: number;
     readonly exitCode: number;
+    /**
+     * True when the spawn failed because the API stayed overloaded (HTTP 529 /
+     * "Overloaded") through every retry. Lets a caller distinguish "back off and
+     * retry later" from "the work genuinely failed" — both surface as a non-zero
+     * `exitCode`, so this is the only way to tell them apart.
+     */
+    readonly overloaded: boolean;
     readonly stderr: string;
     readonly stdout: string;
 }