@socketsecurity/lib 6.0.7 → 6.0.9

package/dist/ai/route.d.mts

@@ -0,0 +1,82 @@
+/**
+ * @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. - `fell-over` — the preferred
+ * engine was missing/unkeyed; an equivalent on another engine was used
+ * (`requestedTier` names the tier originally asked for). Matches the
+ * `fellOver` vocabulary `spawnTierWithFallback` (spawn.mts) reports.
+ */
+export type TierResolveReason = 'fell-over' | 'preferred';
+export interface TierResolution {
+    readonly candidate: TierCandidate;
+    readonly reason: TierResolveReason;
+    readonly requestedTier?: 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 `fell-over` with the original tier in `requestedTier`.
+ * 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;
+/**
+ * The ORDERED list of usable candidates for a tier — the runtime-fallback
+ * sequence. `resolveTier` returns only the single best pick (good when you
+ * trust it will work); this returns every usable candidate in preference order
+ * so a caller can advance to the next when one fails AT RUNTIME — e.g. the
+ * preferred model is installed + keyed (so it passes `isCandidateUsable`) yet
+ * its CLI reports it offline at spawn ("Claude Fable 5 is currently
+ * unavailable"). The static check can't predict an outage; only the spawn
+ * result can, so the caller walks this list until a spawn returns without the
+ * `unavailable` flag. Empty when nothing in the chain is usable.
+ */
+export declare function usableTierCandidates(tier: AiTier, ctx: RouteContext): TierCandidate[];

package/dist/ai/route.js

@@ -0,0 +1,171 @@
+"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 `fell-over` with the original tier in `requestedTier`.
+* 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,
+			requestedTier: tier,
+			reason: "fell-over"
+		};
+	}
+}
+/**
+* The ORDERED list of usable candidates for a tier — the runtime-fallback
+* sequence. `resolveTier` returns only the single best pick (good when you
+* trust it will work); this returns every usable candidate in preference order
+* so a caller can advance to the next when one fails AT RUNTIME — e.g. the
+* preferred model is installed + keyed (so it passes `isCandidateUsable`) yet
+* its CLI reports it offline at spawn ("Claude Fable 5 is currently
+* unavailable"). The static check can't predict an outage; only the spawn
+* result can, so the caller walks this list until a spawn returns without the
+* `unavailable` flag. Empty when nothing in the chain is usable.
+*/
+function usableTierCandidates(tier, ctx) {
+	return (TIER_CHAINS[tier] ?? TIER_CHAINS.sonnet).filter((c) => isCandidateUsable(c, ctx));
+}
+
+//#endregion
+exports.TIER_CHAINS = TIER_CHAINS;
+exports.isCandidateUsable = isCandidateUsable;
+exports.resolveTier = resolveTier;
+exports.usableTierCandidates = usableTierCandidates;

package/dist/ai/spawn.d.mts

@@ -11,6 +11,8 @@
  *   SDK installs. Retry: 3 attempts on overload (HTTP 529 / "Overloaded"), exp.
  *   backoff (5s / 15s / 45s). Each retry is a fresh subprocess.
  */
+import type { RouteContext, TierCandidate } from './route.mts';
+import type { AiTier } from './tier.mts';
 import type { AgentSpawnResult, AiAgentName, SpawnAiAgentOptions } from './types.mts';
 export declare function backoffFor(attempt: number): number;
 /**
@@ -22,7 +24,16 @@ 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 isModelUnavailable(stdout: string, stderr: string): boolean;
 export declare function isOverloaded(stdout: string, stderr: string): boolean;
 export declare function pickAgent(requested: AiAgentName | undefined, cwd: string): Promise<AiAgentName>;
 /**
@@ -46,4 +57,33 @@ 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>;
+/**
+ * Result of a tier spawn that may have fallen over one or more offline models.
+ * `result` is the spawn that actually ran (the first whose model was not
+ * `unavailable`, or the last attempt if every candidate was down). `candidate`
+ * is the engine/model that produced it. `fellOver` lists the candidates that
+ * reported their model offline before this one — empty on a first-try success.
+ */
+export interface TierSpawnResult {
+    readonly candidate: TierCandidate;
+    readonly fellOver: readonly TierCandidate[];
+    readonly result: AgentSpawnResult;
+}
+/**
+ * Spawn a tier's work, automatically FALLING OVER to the next agent when a
+ * model is offline. Walks the tier's usable candidates (Claude → Codex →
+ * open-weight) in order; if a spawn comes back with `unavailable` (the model is
+ * down or gated — e.g. "Claude Fable 5 is currently unavailable"), it advances
+ * to the next candidate instead of failing. This is the runtime complement to
+ * `route.mts`'s static availability check: that check can't predict an outage,
+ * so the live spawn result drives the fallback.
+ *
+ * Returns the first non-`unavailable` spawn (success OR a genuine work failure
+ * on a model that WAS reachable — a real failure shouldn't silently retry on a
+ * weaker model). If every candidate is offline, returns the last attempt with
+ * its `unavailable` flag set, so the caller can report "all models down".
+ * Throws only when the tier has no usable candidate at all (nothing installed +
+ * keyed) — same contract as `resolveTier` returning undefined.
+ */
+export declare function spawnTierWithFallback(tier: AiTier, ctx: RouteContext, options: Omit<SpawnAiAgentOptions, 'agent' | 'effort' | 'model'>): Promise<TierSpawnResult>;

package/dist/ai/spawn.js

@@ -2,13 +2,14 @@
 /* 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');
+const require_ai_route = require('./route.js');
 
 //#region src/ai/spawn.mts
 /**
@@ -38,63 +39,120 @@ 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);
+}
+const MODEL_UNAVAILABLE_PHRASES = [
+	"access denied",
+	"currently unavailable",
+	"forbidden",
+	"have access",
+	"is unavailable",
+	"isn’t available",
+	"isn't available",
+	"may not exist",
+	"no access to",
+	"no such model",
+	"not authorized",
+	"not authorised",
+	"not available",
+	"permission denied",
+	"permission_denied",
+	"temporarily unavailable",
+	"unauthorized",
+	"unauthorised"
+];
+const MODEL_EXISTENCE_PHRASES = [
+	"does not exist",
+	"doesn't exist",
+	"no such",
+	"not exist",
+	"not found",
+	"unavailable",
+	"unknown",
+	"unreachable"
+];
+function isModelUnavailable(stdout, stderr) {
+	const text = `${stdout}\n${stderr}`.toLowerCase();
+	for (let i = 0, { length } = MODEL_UNAVAILABLE_PHRASES; i < length; i += 1) if (text.includes(MODEL_UNAVAILABLE_PHRASES[i])) return true;
+	if (/\bmodel[_-]?not[_-]?found\b/i.test(text) || /\bapi error:\s*(?:403|404)\b/i.test(text)) return true;
+	if (text.includes("model")) {
+		for (let i = 0, { length } = MODEL_EXISTENCE_PHRASES; i < length; i += 1) if (text.includes(MODEL_EXISTENCE_PHRASES[i])) return true;
+	}
+	return false;
+}
 function isOverloaded(stdout, stderr) {
 	const re = /API Error: 529|Overloaded/i;
 	return re.test(stdout) || re.test(stderr);
@@ -134,9 +192,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 +211,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,14 +238,65 @@ async function spawnAiAgent(opts) {
 		attempts,
 		durationMs: require_primordials_date.DateNow() - start,
 		exitCode,
+		overloaded: isOverloaded(stdout, stderr),
 		stderr,
-		stdout
+		stdout,
+		unavailable: isModelUnavailable(stdout, stderr)
+	};
+}
+/**
+* Spawn a tier's work, automatically FALLING OVER to the next agent when a
+* model is offline. Walks the tier's usable candidates (Claude → Codex →
+* open-weight) in order; if a spawn comes back with `unavailable` (the model is
+* down or gated — e.g. "Claude Fable 5 is currently unavailable"), it advances
+* to the next candidate instead of failing. This is the runtime complement to
+* `route.mts`'s static availability check: that check can't predict an outage,
+* so the live spawn result drives the fallback.
+*
+* Returns the first non-`unavailable` spawn (success OR a genuine work failure
+* on a model that WAS reachable — a real failure shouldn't silently retry on a
+* weaker model). If every candidate is offline, returns the last attempt with
+* its `unavailable` flag set, so the caller can report "all models down".
+* Throws only when the tier has no usable candidate at all (nothing installed +
+* keyed) — same contract as `resolveTier` returning undefined.
+*/
+async function spawnTierWithFallback(tier, ctx, options) {
+	const candidates = require_ai_route.usableTierCandidates(tier, ctx);
+	if (candidates.length === 0) throw new require_primordials_error.ErrorCtor(`spawnTierWithFallback: no usable agent for tier "${tier}". No candidate engine is both installed and keyed (checked: ${candidates.length}). Install/authenticate one of the tier's engines, or pick a different tier.`);
+	const fellOver = [];
+	let last;
+	for (let i = 0, { length } = candidates; i < length; i += 1) {
+		const candidate = candidates[i];
+		const result = await spawnAiAgent({
+			...options,
+			agent: candidate.engine,
+			effort: candidate.effort,
+			model: candidate.model
+		});
+		last = {
+			candidate,
+			result
+		};
+		if (!result.unavailable) return {
+			candidate,
+			fellOver,
+			result
+		};
+		fellOver.push(candidate);
+	}
+	return {
+		candidate: last.candidate,
+		fellOver: fellOver.slice(0, -1),
+		result: last.result
 	};
 }
 
 //#endregion
 exports.backoffFor = backoffFor;
 exports.buildArgs = buildArgs;
+exports.isAdaptiveOnlyModel = isAdaptiveOnlyModel;
+exports.isModelUnavailable = isModelUnavailable;
 exports.isOverloaded = isOverloaded;
 exports.pickAgent = pickAgent;
-exports.spawnAiAgent = spawnAiAgent;
+exports.spawnAiAgent = spawnAiAgent;
+exports.spawnTierWithFallback = spawnTierWithFallback;

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;