@socketsecurity/lib 6.0.9 → 6.0.10

package/dist/ai/profiles.d.mts

@@ -11,11 +11,10 @@
  *     WebSearch. No Edit, no Write, no Bash. Static-analysis skills
  *     (scanning-quality, scanning-security).
  *   - `AI_PROFILE.edit` — in-place edits only. Read + Edit + Grep + Glob. NO
- *     Write (can't create files), NO MultiEdit, NO Bash. Lint autofix /
- *     codemods constrained to existing files.
- *   - `AI_PROFILE.create` — edit AND create files. Adds MultiEdit + Write on top
- *     of `.edit`. Still no Bash. Codegen, adding a test, refactors that split
- *     modules.
+ *     Write (can't create files), NO Bash. Lint autofix / codemods constrained
+ *     to existing files.
+ *   - `AI_PROFILE.create` — edit AND create files. Adds Write on top of `.edit`.
+ *     Still no Bash. Codegen, adding a test, refactors that split modules.
  *   - `AI_PROFILE.verify` — `.create` plus a READ-ONLY Bash allowlist (node /
  *     pnpm test+run / git status·diff·log). Lets an agent author files AND run
  *     the verifier (its own tests, a check script) — but it CANNOT mutate the
@@ -66,13 +65,13 @@ export declare const BASH_ALLOW: {
 export declare const AI_PROFILE: {
     readonly read: {
         readonly allow: readonly [];
-        readonly disallow: readonly ["Agent", "Bash", "Edit", "MultiEdit", "Write"];
+        readonly disallow: readonly ["Agent", "Bash", "Edit", "Write"];
         readonly permissionMode: 'dontAsk';
         readonly tools: readonly ["Glob", "Grep", "Read", "WebFetch", "WebSearch"];
     };
     readonly edit: {
         readonly allow: readonly [];
-        readonly disallow: readonly ["Agent", "Bash", "MultiEdit", "WebFetch", "WebSearch", "Write"];
+        readonly disallow: readonly ["Agent", "Bash", "WebFetch", "WebSearch", "Write"];
         readonly permissionMode: 'acceptEdits';
         readonly tools: readonly ["Edit", "Glob", "Grep", "Read"];
     };
@@ -80,18 +79,18 @@ export declare const AI_PROFILE: {
         readonly allow: readonly [];
         readonly disallow: readonly ["Agent", "Bash", "WebFetch", "WebSearch"];
         readonly permissionMode: 'acceptEdits';
-        readonly tools: readonly ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"];
+        readonly tools: readonly ["Edit", "Glob", "Grep", "Read", "Write"];
     };
     readonly verify: {
         readonly allow: readonly ["Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(node:*)", "Bash(pnpm run:*)", "Bash(pnpm test:*)"];
         readonly disallow: readonly ["Agent", "WebFetch", "WebSearch"];
         readonly permissionMode: 'acceptEdits';
-        readonly tools: readonly ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"];
+        readonly tools: readonly ["Bash", "Edit", "Glob", "Grep", "Read", "Write"];
     };
     readonly full: {
         readonly allow: readonly ["Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(node:*)", "Bash(pnpm run:*)", "Bash(pnpm test:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(pnpm exec:*)"];
         readonly disallow: readonly ["Agent", "WebFetch", "WebSearch"];
         readonly permissionMode: 'acceptEdits';
-        readonly tools: readonly ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"];
+        readonly tools: readonly ["Bash", "Edit", "Glob", "Grep", "Read", "Write"];
     };
 };

package/dist/ai/profiles.js

@@ -44,7 +44,6 @@ const AI_PROFILE = {
 			"Agent",
 			"Bash",
 			"Edit",
-			"MultiEdit",
 			"Write"
 		],
 		permissionMode: "dontAsk",
@@ -61,7 +60,6 @@ const AI_PROFILE = {
 		disallow: [
 			"Agent",
 			"Bash",
-			"MultiEdit",
 			"WebFetch",
 			"WebSearch",
 			"Write"
@@ -87,7 +85,6 @@ const AI_PROFILE = {
 			"Edit",
 			"Glob",
 			"Grep",
-			"MultiEdit",
 			"Read",
 			"Write"
 		]
@@ -105,7 +102,6 @@ const AI_PROFILE = {
 			"Edit",
 			"Glob",
 			"Grep",
-			"MultiEdit",
 			"Read",
 			"Write"
 		]
@@ -127,7 +123,6 @@ const AI_PROFILE = {
 			"Edit",
 			"Glob",
 			"Grep",
-			"MultiEdit",
 			"Read",
 			"Write"
 		]

package/dist/ai/role.d.mts

@@ -0,0 +1,58 @@
+/**
+ * @file Declarative ROLE → (tier, profile) orchestration for AI call-outs. A
+ *   caller names the ROLE its spawn plays — discovery, execution, planning,
+ *   review, verification — and gets the fleet-policy (model, effort) pair via
+ *   `AI_TIER` plus the matching permission `AI_PROFILE`, instead of hardcoding
+ *   a model string and hand-pairing a profile at every site.
+ *   The policy encodes fleet doctrine (see docs/agents.md/fleet/{token-spend,
+ *   delegating-execution,fable-fallback}.md): Fable is the planning/review
+ *   brain; execution + verification run on the sonnet floor to save tokens
+ *   (mechanical execution drops to haiku); Opus is reserved for
+ *   security-sensitive planning/review — never Fable there.
+ *   Everything downstream is reuse: `spawnForRole` delegates to
+ *   `spawnTierWithFallback`, so the model/effort table (`AI_TIER`), the
+ *   availability-gated cross-engine fallback (`route.mts`), and the
+ *   Fable-adaptive-only effort omission (`spawn.mts`) stay the single source.
+ *   Model + effort can never be mismatched or omitted here — the tier supplies
+ *   both, and the profile supplies tools/permission, so a caller cannot drift
+ *   them apart.
+ */
+import { AI_PROFILE } from './profiles.mts';
+import type { RouteContext } from './route.mts';
+import type { TierSpawnResult } from './spawn.mts';
+import type { AiTier } from './tier.mts';
+import type { SpawnAiAgentOptions } from './types.mts';
+export type AiRole = 'discovery' | 'execution' | 'planning' | 'review' | 'verification';
+export type RoleSensitivity = 'benign' | 'security';
+export interface RoleTierLevers {
+    readonly mechanical?: boolean | undefined;
+    readonly sensitivity?: RoleSensitivity | undefined;
+}
+export interface RolePolicy {
+    readonly tier: AiTier;
+    readonly securityTier?: AiTier | undefined;
+    readonly profile: keyof typeof AI_PROFILE;
+}
+/**
+ * The role → policy table. The one place a role's tier + permission profile
+ * live; consumers derive, never re-encode.
+ */
+export declare const ROLE_POLICY: Readonly<Record<AiRole, RolePolicy>>;
+/**
+ * Resolve the tier a role runs at, applying the two levers: `security`
+ * sensitivity escalates to the role's `securityTier` (planning/review → opus),
+ * and `mechanical` execution drops to the haiku floor. Pure — no I/O.
+ */
+export declare function resolveRoleTier(role: AiRole, options?: RoleTierLevers | undefined): AiTier;
+export interface SpawnForRoleOptions extends Omit<SpawnAiAgentOptions, 'agent' | 'allow' | 'disallow' | 'effort' | 'model' | 'permissionMode' | 'tools'> {
+    readonly sensitivity?: RoleSensitivity | undefined;
+    readonly mechanical?: boolean | undefined;
+}
+/**
+ * Spawn an AI call-out by the ROLE it plays. Resolves role → tier (via
+ * `resolveRoleTier`) and role → permission profile (via `AI_PROFILE`), then
+ * delegates to `spawnTierWithFallback` so model/effort/fallback/Fable handling
+ * stay in the canonical tier layer. The caller supplies only prompt/cwd/etc —
+ * never a model, effort, or profile.
+ */
+export declare function spawnForRole(role: AiRole, ctx: RouteContext, options: SpawnForRoleOptions): Promise<TierSpawnResult>;

package/dist/ai/role.js

@@ -0,0 +1,96 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_ai_spawn = require('./spawn.js');
+const require_ai_profiles = require('./profiles.js');
+
+//#region src/ai/role.mts
+/**
+* @file Declarative ROLE → (tier, profile) orchestration for AI call-outs. A
+*   caller names the ROLE its spawn plays — discovery, execution, planning,
+*   review, verification — and gets the fleet-policy (model, effort) pair via
+*   `AI_TIER` plus the matching permission `AI_PROFILE`, instead of hardcoding
+*   a model string and hand-pairing a profile at every site.
+*   The policy encodes fleet doctrine (see docs/agents.md/fleet/{token-spend,
+*   delegating-execution,fable-fallback}.md): Fable is the planning/review
+*   brain; execution + verification run on the sonnet floor to save tokens
+*   (mechanical execution drops to haiku); Opus is reserved for
+*   security-sensitive planning/review — never Fable there.
+*   Everything downstream is reuse: `spawnForRole` delegates to
+*   `spawnTierWithFallback`, so the model/effort table (`AI_TIER`), the
+*   availability-gated cross-engine fallback (`route.mts`), and the
+*   Fable-adaptive-only effort omission (`spawn.mts`) stay the single source.
+*   Model + effort can never be mismatched or omitted here — the tier supplies
+*   both, and the profile supplies tools/permission, so a caller cannot drift
+*   them apart.
+*/
+/**
+* The role → policy table. The one place a role's tier + permission profile
+* live; consumers derive, never re-encode.
+*/
+const ROLE_POLICY = {
+	discovery: {
+		profile: "read",
+		tier: "sonnet"
+	},
+	execution: {
+		profile: "verify",
+		tier: "sonnet"
+	},
+	planning: {
+		profile: "read",
+		securityTier: "opus",
+		tier: "fable"
+	},
+	review: {
+		profile: "read",
+		securityTier: "opus",
+		tier: "fable"
+	},
+	verification: {
+		profile: "verify",
+		tier: "sonnet"
+	}
+};
+/**
+* Resolve the tier a role runs at, applying the two levers: `security`
+* sensitivity escalates to the role's `securityTier` (planning/review → opus),
+* and `mechanical` execution drops to the haiku floor. Pure — no I/O.
+*/
+function resolveRoleTier(role, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const policy = ROLE_POLICY[role];
+	if (opts.mechanical && role === "execution") return "haiku";
+	if (opts.sensitivity === "security" && policy.securityTier !== void 0) return policy.securityTier;
+	return policy.tier;
+}
+/**
+* Spawn an AI call-out by the ROLE it plays. Resolves role → tier (via
+* `resolveRoleTier`) and role → permission profile (via `AI_PROFILE`), then
+* delegates to `spawnTierWithFallback` so model/effort/fallback/Fable handling
+* stay in the canonical tier layer. The caller supplies only prompt/cwd/etc —
+* never a model, effort, or profile.
+*/
+function spawnForRole(role, ctx, options) {
+	const { mechanical, sensitivity, ...rest } = {
+		__proto__: null,
+		...options
+	};
+	const tier = resolveRoleTier(role, {
+		mechanical,
+		sensitivity
+	});
+	const profile = require_ai_profiles.AI_PROFILE[ROLE_POLICY[role].profile];
+	return require_ai_spawn.spawnTierWithFallback(tier, ctx, {
+		...profile,
+		...rest
+	});
+}
+
+//#endregion
+exports.ROLE_POLICY = ROLE_POLICY;
+exports.resolveRoleTier = resolveRoleTier;
+exports.spawnForRole = spawnForRole;

package/dist/ai/route-heuristic.d.mts

@@ -0,0 +1,177 @@
+/**
+ * @file Billing-aware routing heuristic — a PURE policy layer over `route.mts`.
+ *   `route.mts` answers "which cross-engine candidates for this tier are
+ *   installed + keyed, in static preference order"; this module answers "given
+ *   how each provider is BILLED (a subscription seat vs a flat-rate plan vs
+ *   metered dollars), how much budget headroom remains, and whether we're in
+ *   local dev or a locked-down CI — REORDER those candidates so the cheapest
+ *   ration that still meets the tier's quality bar runs first." It is pure (no
+ *   I/O): a caller fans out the billing / headroom probes once (the discovery
+ *   layer) and passes a `BillingContext` in, exactly as `route.mts` takes a
+ *   probed `RouteContext`. The candidates within a tier chain are cross-engine
+ *   EQUIVALENTS at that capability level, so reordering them by cost is safe —
+ *   the tier already fixed the quality bar. NO per-user constants live here.
+ *   Every dollar limit, plan tier, member count, and promo window is DATA on
+ *   the passed-in context; this file is formula + ordering only, so the same
+ *   policy serves a metered org with a big budget, a free-promo subscription
+ *   seat, a shared team pool, or a member with no credentials at all. Even
+ *   "which model is suspended" is not encoded here — that is the
+ *   route/availability layer's concern. Two design choices keep it a "sweet
+ *   spot" rather than a blunt cost-sort: high-value tiers (opus/fable) stay
+ *   QUALITY-FIRST (the Claude head leads) and only DEMOTE an account under
+ *   budget pressure, while commodity tiers (haiku/sonnet) in local dev PROMOTE
+ *   the cheapest equivalent to preserve the metered budget for work that needs
+ *   it; and CI keeps the locked static order so a headless run never reorders
+ *   away from its single available provider.
+ */
+import type { CredentialProvider } from './credentials.mts';
+import type { RouteContext, TierCandidate } from './route.mts';
+import type { AiTier } from './tier.mts';
+/**
+ * How a provider's credential is billed, which decides what the marginal token
+ * actually costs:
+ *
+ * - `flat-rate` — a fixed monthly plan with a usage window (e.g. N requests per
+ *   5h). Marginal cost is $0 while the window has room.
+ * - `metered` — pay per token against a (usually large, readable) monthly spend
+ *   limit. Marginal cost is real dollars.
+ * - `subscription` — a seat (Claude Max, ChatGPT Pro) with an opaque weekly
+ *   quota. Marginal cost is $0 until the quota is hit, then it stops.
+ */
+export type BillingKind = 'flat-rate' | 'metered' | 'subscription';
+/**
+ * Where routing is running. `local` dev has the full discovered provider set
+ * and may chase the cheapest equivalent; `ci` is locked to the secrets actually
+ * present (often a single provider) under the four-flag lockdown, so the policy
+ * keeps the static order and never reorders away from the one available lane.
+ */
+export type RoutingEnv = 'ci' | 'local';
+/**
+ * The shape of a unit of work, mapped to a capability tier by
+ * `taskClassToTier`. Orthogonal to billing: the class fixes the quality bar,
+ * billing decides which equivalent at that bar is cheapest.
+ */
+export type TaskClass = 'agentic' | 'code' | 'grunt' | 'plan';
+/**
+ * Remaining-headroom signal for one account, as read by the discovery layer
+ * from the provider's live API (metered: spend ÷ limit; flat-rate: window used
+ * ÷ window limit). `fraction` is remaining headroom in [0, 1] (1 = full, 0 =
+ * none), or `undefined` when no signal is available — a subscription seat with
+ * no programmatic quota read, which the policy then treats reactively.
+ * `exhausted` is the hard stop: a cap was hit or a 429 was observed, so the
+ * account should fall to the back of the order regardless of `fraction`.
+ */
+export interface BillingHeadroom {
+    readonly exhausted: boolean;
+    readonly fraction: number | undefined;
+}
+/**
+ * One provider's billing situation for the credential that will actually be
+ * used (the resolver yields one token per provider, so one account per provider
+ * is the routing-relevant view). Multi-account-per-provider accounting belongs
+ * to the budget layer, not the candidate order.
+ */
+export interface BillingAccount {
+    readonly headroom?: BillingHeadroom | undefined;
+    readonly kind: BillingKind;
+    readonly prefer?: number | undefined;
+    readonly provider: CredentialProvider;
+}
+/**
+ * The per-provider billing view a caller probes once and passes in — the
+ * billing analog of `RouteContext`. Keyed by provider; a provider absent from
+ * the map has no known billing signal and is left in static order.
+ */
+export type BillingContext = Readonly<Partial<Record<CredentialProvider, BillingAccount>>>;
+/**
+ * Canonical task-class → tier. The class fixes the capability bar; the tier
+ * chain then offers cross-engine equivalents at that bar for billing to
+ * reorder.
+ *
+ * - `grunt` → `haiku` — classify / summarize / single-token rewrites.
+ * - `code` → `sonnet` — control-flow / caller-chain edits, feature work.
+ * - `agentic` → `opus` — long tool-use loops, high-value autonomous work.
+ * - `plan` → `opus` — decomposition / architecture (escalate to `fable` only
+ *   explicitly, never by default — and only when it is not suspended).
+ */
+export declare const TASK_CLASS_TIER: Readonly<Record<TaskClass, AiTier>>;
+/**
+ * Marginal-cost rank by billing kind, cheapest ration first (lower =
+ * preferred). Used only for commodity tiers in local dev — high-value tiers
+ * stay quality-first. Flat-rate and subscription are both $0-until-cap;
+ * flat-rate leads because its window resets fast (hours) vs a subscription's
+ * weekly cap.
+ */
+export declare const COST_RANK: Readonly<Record<BillingKind, number>>;
+/**
+ * Default per-task-class budget weights for `allocateBudget`. Reserves more of
+ * a member's share for high-value work (plan/agentic) than for bulk
+ * (grunt/code). Overridable per call — these are sane defaults, not per-user
+ * values.
+ */
+export declare const DEFAULT_TASK_CLASS_WEIGHTS: Readonly<Record<TaskClass, number>>;
+/**
+ * Headroom fraction at or below which a metered/flat-rate account is demoted
+ * (predictive backoff before the hard cap). A config knob with a sane default;
+ * callers override per `orderCandidates` call.
+ */
+export declare const DEFAULT_DEMOTE_THRESHOLD = 0.2;
+/**
+ * Per-task-class dollar caps. A generic allocation, not a per-user table —
+ * computed from a total + member count + weights, all of which are inputs.
+ */
+export type BudgetAllocation = Readonly<Record<TaskClass, number>>;
+export interface BudgetAllocationOptions {
+    readonly totalUsd: number;
+    readonly members?: number | undefined;
+    readonly weights?: Readonly<Partial<Record<TaskClass, number>>> | undefined;
+}
+/**
+ * Turn a total budget into reasonable per-member, per-task-class caps by a
+ * generic formula: split the total evenly across members, then distribute each
+ * member's share across task classes proportional to their weights. The numbers
+ * in are private; the formula is generic and committed. A non-positive total or
+ * member count degrades to zero caps rather than throwing.
+ */
+export declare function allocateBudget(options: BudgetAllocationOptions): BudgetAllocation;
+export interface CandidateScoreOptions {
+    readonly account: BillingAccount | undefined;
+    readonly demoteThreshold: number;
+    readonly promoteCheap: boolean;
+}
+/**
+ * Score one candidate for ordering (lower sorts earlier). A candidate with no
+ * known billing account scores neutral so it keeps its static position. The
+ * bands: a hard-exhausted account sinks to the back; a near-cap account is
+ * demoted; cost rank nudges commodity tiers toward the cheapest ration; an
+ * operator `prefer` nudge pulls a provider earlier. Pure.
+ */
+export declare function candidateScore(options: CandidateScoreOptions): number;
+export interface OrderCandidatesOptions {
+    readonly billing: BillingContext;
+    readonly demoteThreshold?: number | undefined;
+    readonly env?: RoutingEnv | undefined;
+    readonly route: RouteContext;
+    readonly tier: AiTier;
+}
+/**
+ * Reorder a tier's usable candidates by the billing policy, returning the
+ * runtime-fallback sequence (most-preferred first). Wraps
+ * `usableTierCandidates` — it never mutates the static `TIER_CHAINS`. The sort
+ * is stable on the original preference index, so candidates that score equal
+ * keep their static order (the Claude head stays first among equals).
+ *
+ * - In `ci`, or on a high-value tier (opus/fable), cost rank does NOT apply: the
+ *   static quality-first order holds and only budget demotion / exhaustion
+ *   reorders it.
+ * - In `local` on a commodity tier (haiku/sonnet), the cheapest billing kind is
+ *   promoted ahead of a pricier equivalent, preserving the metered budget for
+ *   the work that needs it.
+ */
+export declare function orderCandidates(options: OrderCandidatesOptions): TierCandidate[];
+/**
+ * Resolve a task class to its capability tier, defaulting to `sonnet` for an
+ * unknown label so a stray string degrades safely rather than yielding
+ * `undefined`.
+ */
+export declare function taskClassToTier(taskClass: TaskClass): AiTier;

package/dist/ai/route-heuristic.js

@@ -0,0 +1,194 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_ai_route = require('./route.js');
+
+//#region src/ai/route-heuristic.mts
+/**
+* @file Billing-aware routing heuristic — a PURE policy layer over `route.mts`.
+*   `route.mts` answers "which cross-engine candidates for this tier are
+*   installed + keyed, in static preference order"; this module answers "given
+*   how each provider is BILLED (a subscription seat vs a flat-rate plan vs
+*   metered dollars), how much budget headroom remains, and whether we're in
+*   local dev or a locked-down CI — REORDER those candidates so the cheapest
+*   ration that still meets the tier's quality bar runs first." It is pure (no
+*   I/O): a caller fans out the billing / headroom probes once (the discovery
+*   layer) and passes a `BillingContext` in, exactly as `route.mts` takes a
+*   probed `RouteContext`. The candidates within a tier chain are cross-engine
+*   EQUIVALENTS at that capability level, so reordering them by cost is safe —
+*   the tier already fixed the quality bar. NO per-user constants live here.
+*   Every dollar limit, plan tier, member count, and promo window is DATA on
+*   the passed-in context; this file is formula + ordering only, so the same
+*   policy serves a metered org with a big budget, a free-promo subscription
+*   seat, a shared team pool, or a member with no credentials at all. Even
+*   "which model is suspended" is not encoded here — that is the
+*   route/availability layer's concern. Two design choices keep it a "sweet
+*   spot" rather than a blunt cost-sort: high-value tiers (opus/fable) stay
+*   QUALITY-FIRST (the Claude head leads) and only DEMOTE an account under
+*   budget pressure, while commodity tiers (haiku/sonnet) in local dev PROMOTE
+*   the cheapest equivalent to preserve the metered budget for work that needs
+*   it; and CI keeps the locked static order so a headless run never reorders
+*   away from its single available provider.
+*/
+/**
+* Canonical task-class → tier. The class fixes the capability bar; the tier
+* chain then offers cross-engine equivalents at that bar for billing to
+* reorder.
+*
+* - `grunt` → `haiku` — classify / summarize / single-token rewrites.
+* - `code` → `sonnet` — control-flow / caller-chain edits, feature work.
+* - `agentic` → `opus` — long tool-use loops, high-value autonomous work.
+* - `plan` → `opus` — decomposition / architecture (escalate to `fable` only
+*   explicitly, never by default — and only when it is not suspended).
+*/
+const TASK_CLASS_TIER = {
+	__proto__: null,
+	agentic: "opus",
+	code: "sonnet",
+	grunt: "haiku",
+	plan: "opus"
+};
+/**
+* Marginal-cost rank by billing kind, cheapest ration first (lower =
+* preferred). Used only for commodity tiers in local dev — high-value tiers
+* stay quality-first. Flat-rate and subscription are both $0-until-cap;
+* flat-rate leads because its window resets fast (hours) vs a subscription's
+* weekly cap.
+*/
+const COST_RANK = {
+	__proto__: null,
+	"flat-rate": 0,
+	metered: 2,
+	subscription: 1
+};
+/**
+* Default per-task-class budget weights for `allocateBudget`. Reserves more of
+* a member's share for high-value work (plan/agentic) than for bulk
+* (grunt/code). Overridable per call — these are sane defaults, not per-user
+* values.
+*/
+const DEFAULT_TASK_CLASS_WEIGHTS = {
+	__proto__: null,
+	agentic: 3,
+	code: 2,
+	grunt: 1,
+	plan: 4
+};
+/**
+* Headroom fraction at or below which a metered/flat-rate account is demoted
+* (predictive backoff before the hard cap). A config knob with a sane default;
+* callers override per `orderCandidates` call.
+*/
+const DEFAULT_DEMOTE_THRESHOLD = .2;
+const BULK_TIERS = /* @__PURE__ */ new Set(["haiku", "sonnet"]);
+const SCORE_NEAR_CAP = 100;
+const SCORE_EXHAUSTED = 1e4;
+const TASK_CLASSES = [
+	"agentic",
+	"code",
+	"grunt",
+	"plan"
+];
+/**
+* Turn a total budget into reasonable per-member, per-task-class caps by a
+* generic formula: split the total evenly across members, then distribute each
+* member's share across task classes proportional to their weights. The numbers
+* in are private; the formula is generic and committed. A non-positive total or
+* member count degrades to zero caps rather than throwing.
+*/
+function allocateBudget(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const members = opts.members && opts.members > 0 ? opts.members : 1;
+	const perMember = (opts.totalUsd > 0 ? opts.totalUsd : 0) / members;
+	const weights = {
+		__proto__: null,
+		...DEFAULT_TASK_CLASS_WEIGHTS,
+		...opts.weights
+	};
+	let totalWeight = 0;
+	for (let i = 0, { length } = TASK_CLASSES; i < length; i += 1) totalWeight += weights[TASK_CLASSES[i]] ?? 0;
+	const divisor = totalWeight > 0 ? totalWeight : 1;
+	const out = { __proto__: null };
+	for (let i = 0, { length } = TASK_CLASSES; i < length; i += 1) {
+		const taskClass = TASK_CLASSES[i];
+		out[taskClass] = perMember * (weights[taskClass] ?? 0) / divisor;
+	}
+	return out;
+}
+/**
+* Score one candidate for ordering (lower sorts earlier). A candidate with no
+* known billing account scores neutral so it keeps its static position. The
+* bands: a hard-exhausted account sinks to the back; a near-cap account is
+* demoted; cost rank nudges commodity tiers toward the cheapest ration; an
+* operator `prefer` nudge pulls a provider earlier. Pure.
+*/
+function candidateScore(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const { account } = opts;
+	if (!account) return 0;
+	let score = 0;
+	const { headroom } = account;
+	if (headroom?.exhausted) score += SCORE_EXHAUSTED;
+	else if (typeof headroom?.fraction === "number" && headroom.fraction <= opts.demoteThreshold) score += SCORE_NEAR_CAP;
+	if (opts.promoteCheap) score += COST_RANK[account.kind] ?? 0;
+	if (typeof account.prefer === "number") score -= account.prefer;
+	return score;
+}
+/**
+* Reorder a tier's usable candidates by the billing policy, returning the
+* runtime-fallback sequence (most-preferred first). Wraps
+* `usableTierCandidates` — it never mutates the static `TIER_CHAINS`. The sort
+* is stable on the original preference index, so candidates that score equal
+* keep their static order (the Claude head stays first among equals).
+*
+* - In `ci`, or on a high-value tier (opus/fable), cost rank does NOT apply: the
+*   static quality-first order holds and only budget demotion / exhaustion
+*   reorders it.
+* - In `local` on a commodity tier (haiku/sonnet), the cheapest billing kind is
+*   promoted ahead of a pricier equivalent, preserving the metered budget for
+*   the work that needs it.
+*/
+function orderCandidates(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const env = opts.env ?? "local";
+	const demoteThreshold = opts.demoteThreshold ?? .2;
+	const promoteCheap = env === "local" && BULK_TIERS.has(opts.tier);
+	const scored = require_ai_route.usableTierCandidates(opts.tier, opts.route).map((candidate, index) => ({
+		candidate,
+		index,
+		score: candidateScore({
+			account: opts.billing[candidate.provider],
+			demoteThreshold,
+			promoteCheap
+		})
+	}));
+	scored.sort((a, b) => a.score - b.score || a.index - b.index);
+	return scored.map((entry) => entry.candidate);
+}
+/**
+* Resolve a task class to its capability tier, defaulting to `sonnet` for an
+* unknown label so a stray string degrades safely rather than yielding
+* `undefined`.
+*/
+function taskClassToTier(taskClass) {
+	return TASK_CLASS_TIER[taskClass] ?? "sonnet";
+}
+
+//#endregion
+exports.COST_RANK = COST_RANK;
+exports.DEFAULT_DEMOTE_THRESHOLD = DEFAULT_DEMOTE_THRESHOLD;
+exports.DEFAULT_TASK_CLASS_WEIGHTS = DEFAULT_TASK_CLASS_WEIGHTS;
+exports.TASK_CLASS_TIER = TASK_CLASS_TIER;
+exports.allocateBudget = allocateBudget;
+exports.candidateScore = candidateScore;
+exports.orderCandidates = orderCandidates;
+exports.taskClassToTier = taskClassToTier;

package/dist/ai/route.d.mts

@@ -6,15 +6,16 @@
  *   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.
+ *   existence: a Socket dev 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';