headlesscode 1.0.2

package/src/budget/budget.ts

@@ -0,0 +1,221 @@
+/**
+ * Phase 6 — per-session cost/time/iteration budget enforcement.
+ *
+ * `BudgetTracker` is the pure, unit-testable core of the per-session budget
+ * guardrail (spec 6.3): it sits inside a `HeadlessSession` (or any caller
+ * that makes LLM calls) and trips a `BudgetExceededError` when ANY of these
+ * limits is crossed:
+ *
+ *   - `maxCostUsd`     — accumulated estimated USD cost (tokens × pricing);
+ *   - `maxDurationMs`  — wall-clock elapsed since the tracker was created;
+ *   - `maxIterations`  — number of LLM calls (ticks) performed.
+ *
+ * Enforcement points (see `check` / `tick` / `record`):
+ *   - `tick()` is called BEFORE each LLM call and re-checks elapsed time,
+ *     iteration count AND accumulated cost (a previous call's `record()` may
+ *     have pushed cost past the cap — the next `tick()` catches it before any
+ *     further spend);
+ *   - `record()` is called AFTER each LLM call with the provider's usage token
+ *     counts and accumulates cost (checking the cost cap again).
+ *
+ * Pure by construction: no fs, no network, no global state. Time is
+ * injectable (`now`), so duration tests use a fake clock; pricing is
+ * injectable so cost tests don't depend on the env pricing file.
+ *
+ * When a budget is NOT configured the tracker is simply never created — zero
+ * behavior change (the session default is `budget: null`).
+ */
+
+import { estimateCost, loadPricingTable, type PricingTable } from "./cost.js"
+
+/** Per-session budget (all limits optional — only the set ones are enforced). */
+export interface SessionBudget {
+	/** Max estimated USD spend for the session (accumulated across LLM calls). */
+	maxCostUsd?: number
+	/** Max wall-clock duration for the session, ms (checked before each call). */
+	maxDurationMs?: number
+	/** Max LLM-call iterations (a stricter cap than the loop's maxIterations). */
+	maxIterations?: number
+}
+
+export type BudgetLimitReason = "cost" | "duration" | "iterations"
+
+/** Thrown by `tick()`/`record()` when a budget limit trips. */
+export class BudgetExceededError extends Error {
+	readonly reason: BudgetLimitReason
+	readonly costUsd: number
+	readonly elapsedMs: number
+	readonly iterations: number
+
+	constructor(reason: BudgetLimitReason, costUsd: number, elapsedMs: number, iterations: number) {
+		super(`Budget exceeded: ${reason} (cost $${costUsd.toFixed(6)}, elapsed ${elapsedMs}ms, iterations ${iterations})`)
+		this.name = "BudgetExceededError"
+		this.reason = reason
+		this.costUsd = costUsd
+		this.elapsedMs = elapsedMs
+		this.iterations = iterations
+	}
+}
+
+export interface BudgetTrackerOptions {
+	/** Clock (default Date.now) — inject a fake for duration tests. */
+	now?: () => number
+	/** Pricing table (default: env-merged defaults) — inject for cost tests. */
+	pricing?: PricingTable
+	/**
+	 * When false, record() never accumulates cost (stays 0 forever) and
+	 * maxCostUsd checks never trip. Default true. Issue #144: a local-
+	 * backend session has no real dollar cost — computing and logging a
+	 * fabricated figure for it is noise at best, misleading at worst.
+	 */
+	trackCost?: boolean
+}
+
+/** Non-throwing snapshot of the budget state (surfaced on SessionResult). */
+export interface BudgetCheck {
+	ok: boolean
+	reason?: BudgetLimitReason
+	costUsd: number
+	elapsedMs: number
+	iterations: number
+}
+
+export class BudgetTracker {
+	private readonly budget: SessionBudget
+	private readonly now: () => number
+	private readonly pricing: PricingTable
+	private readonly trackCost: boolean
+	private readonly startedAt: number
+	private iterations = 0
+	private costUsd = 0
+	/** Cumulative ms spent paused (see pauseClock/resumeClock), excluded from elapsedMs. */
+	private blockedMs = 0
+	/** Set while paused (the `now()` value pauseClock() was called at); null when running. */
+	private blockStartedAt: number | null = null
+
+	constructor(budget: SessionBudget, options: BudgetTrackerOptions = {}) {
+		this.budget = budget
+		this.now = options.now ?? (() => Date.now())
+		this.pricing = options.pricing ?? loadPricingTable()
+		this.trackCost = options.trackCost ?? true
+		this.startedAt = this.now()
+	}
+
+	/**
+	 * Decision escalation (workstream 2): call before blocking on an external
+	 * answer (e.g. ask_followup_question waiting on `.harness.decision-answer`)
+	 * so the wait doesn't count against `maxDurationMs`. Idempotent — a second
+	 * call while already paused is a no-op.
+	 */
+	pauseClock(): void {
+		if (this.blockStartedAt === null) {
+			this.blockStartedAt = this.now()
+		}
+	}
+
+	/**
+	 * Resume the clock after a pause, folding the paused interval into
+	 * `blockedMs`. Idempotent — a call while not paused is a no-op.
+	 */
+	resumeClock(): void {
+		if (this.blockStartedAt !== null) {
+			this.blockedMs += Math.max(0, this.now() - this.blockStartedAt)
+			this.blockStartedAt = null
+		}
+	}
+
+	get elapsedMs(): number {
+		const raw = Math.max(0, this.now() - this.startedAt)
+		const inProgressBlock = this.blockStartedAt !== null ? Math.max(0, this.now() - this.blockStartedAt) : 0
+		return Math.max(0, raw - this.blockedMs - inProgressBlock)
+	}
+
+	get iterationCount(): number {
+		return this.iterations
+	}
+
+	get totalCostUsd(): number {
+		return this.costUsd
+	}
+
+	/**
+	 * Call BEFORE each LLM call. Increments the iteration counter and re-checks
+	 * duration, iterations and accumulated cost. Throws `BudgetExceededError`
+	 * when a limit is crossed.
+	 */
+	tick(): void {
+		this.iterations++
+		this.throwIfExceeded()
+	}
+
+	/**
+	 * Call AFTER each LLM call with the provider's usage token counts.
+	 * Accumulates the estimated cost and re-checks the cost cap. Throws
+	 * `BudgetExceededError` when the cost limit trips.
+	 */
+	record(input: { model: string; inputTokens?: number; outputTokens?: number; cachedTokens?: number }): void {
+		if (!this.trackCost) {
+			return
+		}
+		const cost = estimateCost({
+			model: input.model,
+			inputTokens: input.inputTokens ?? 0,
+			outputTokens: input.outputTokens ?? 0,
+			cachedTokens: input.cachedTokens ?? 0,
+			pricing: this.pricing,
+		})
+		this.costUsd += cost
+		this.throwIfExceeded()
+	}
+
+	/** Non-throwing snapshot: { ok, reason?, costUsd, elapsedMs, iterations }. */
+	check(): BudgetCheck {
+		const { reason } = this.exceededReason()
+		return {
+			ok: reason === undefined,
+			reason,
+			costUsd: this.costUsd,
+			elapsedMs: this.elapsedMs,
+			iterations: this.iterations,
+		}
+	}
+
+	private exceededReason(): { reason?: BudgetLimitReason } {
+		if (this.budget.maxDurationMs !== undefined && this.elapsedMs >= this.budget.maxDurationMs) {
+			return { reason: "duration" }
+		}
+		if (this.budget.maxIterations !== undefined && this.iterations > this.budget.maxIterations) {
+			return { reason: "iterations" }
+		}
+		if (this.budget.maxCostUsd !== undefined && this.costUsd >= this.budget.maxCostUsd) {
+			return { reason: "cost" }
+		}
+		return {}
+	}
+
+	private throwIfExceeded(): void {
+		const { reason } = this.exceededReason()
+		if (reason !== undefined) {
+			throw new BudgetExceededError(reason, this.costUsd, this.elapsedMs, this.iterations)
+		}
+	}
+}
+
+/**
+ * Build a `SessionBudget` from the harness env vars used by the CLI +
+ * run-worker.sh/run-qa.sh. Returns undefined when neither cost nor duration is
+ * set (budget OFF). Invalid values are ignored (validation lives in the CLI).
+ */
+export function sessionBudgetFromEnv(env: NodeJS.ProcessEnv = process.env): SessionBudget | undefined {
+	const costRaw = env.HEADLESSCODE_MAX_COST_USD
+	const durationRaw = env.HEADLESSCODE_MAX_DURATION_MS
+	const cost = costRaw !== undefined && costRaw !== "" ? Number(costRaw) : undefined
+	const duration = durationRaw !== undefined && durationRaw !== "" ? Number(durationRaw) : undefined
+	if ((cost !== undefined && Number.isFinite(cost) && cost > 0) || (duration !== undefined && Number.isFinite(duration) && duration > 0)) {
+		return {
+			...(cost !== undefined && Number.isFinite(cost) && cost > 0 ? { maxCostUsd: cost } : {}),
+			...(duration !== undefined && Number.isFinite(duration) && duration > 0 ? { maxDurationMs: duration } : {}),
+		}
+	}
+	return undefined
+}

package/src/budget/concurrency.ts

@@ -0,0 +1,126 @@
+/**
+ * Phase 6 — global concurrency guardrail (spec 6.3): a hard cap on how many
+ * harness sessions may run at once, enforced BEFORE anything is spawned.
+ *
+ * Two layers, both in this module:
+ *
+ *  1. `ConcurrencyLimiter` — an in-process counting semaphore. We deliberately
+ *     chose FAIL-FAST over queueing for headless spawners: a queued spawner
+ *     has nowhere to hold "waiting" work unless it is the watcher (which
+ *     already has a durable pending mechanism), and a silently queued
+ *     orchestrate run is worse than a loud abort. The watcher's "defer with
+ *     durable pending state" is the queue — implemented in the watcher, not
+ *     the limiter.
+ *
+ *  2. `activeSessionCount(...)` — a CROSS-PROCESS view of how many sessions
+ *     are currently running, derived from the durable state files:
+ *       - `.orchestrator-state.json` groups with status `spawned` | `running`;
+ *       - `.watcher-state.json` entries with status `spawned` (in-flight
+ *         write-ahead spawns).
+ *     Each process (orchestrate, watcher, a cron watcher, a manual run) reads
+ *     these files before spawning, so the cap holds even when several
+ *     processes run concurrently against the same repo — the in-process
+ *     limiter covers the window INSIDE one process (e.g. a sweep spawning
+ *     several batches back-to-back), the state files cover the window ACROSS
+ *     processes.
+ */
+
+import * as path from "node:path"
+
+import { loadStateSync, type OrchestratorState } from "../orchestrator/state.js"
+import { loadWatcherStateSync, type WatcherState } from "../watcher/state.js"
+
+/** Default global cap: HEADLESSCODE_MAX_CONCURRENT_SESSIONS or 3. */
+export const DEFAULT_MAX_CONCURRENT_SESSIONS = 3
+
+/**
+ * In-process counting semaphore with fail-fast acquisition. The cap counts
+ * SESSIONS (one worktree group = one harness session), not worktrees.
+ */
+export class ConcurrencyLimiter {
+	readonly maxSessions: number
+	private active = 0
+
+	constructor(maxSessions: number) {
+		if (!Number.isInteger(maxSessions) || maxSessions <= 0) {
+			throw new Error(`ConcurrencyLimiter: maxSessions must be a positive integer (got ${maxSessions})`)
+		}
+		this.maxSessions = maxSessions
+	}
+
+	/**
+	 * Try to reserve a slot. Fail-fast: returns { ok: false, reason } instead
+	 * of queueing — a caller that cannot spawn right now must either defer
+	 * (watcher → durable pending) or abort loudly (orchestrate), never wait
+	 * silently. (Decision documented in docs/phase6-cloud.md.)
+	 */
+	acquire(): { ok: boolean; reason?: string } {
+		if (this.active >= this.maxSessions) {
+			return {
+				ok: false,
+				reason: `concurrency cap reached: ${this.maxSessions} active session(s) (HEADLESSCODE_MAX_CONCURRENT_SESSIONS)`,
+			}
+		}
+		this.active++
+		return { ok: true }
+	}
+
+	/** Release a slot previously reserved with acquire(). Never goes below 0. */
+	release(): void {
+		this.active = Math.max(0, this.active - 1)
+	}
+
+	/** Current number of reserved (active) slots in this process. */
+	current(): number {
+		return this.active
+	}
+}
+
+/** Parsed env cap: HEADLESSCODE_MAX_CONCURRENT_SESSIONS (default 3). */
+export function maxConcurrentSessionsFromEnv(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env.HEADLESSCODE_MAX_CONCURRENT_SESSIONS
+	if (raw === undefined || raw === "") {
+		return DEFAULT_MAX_CONCURRENT_SESSIONS
+	}
+	const n = Number(raw)
+	return Number.isInteger(n) && n > 0 ? n : DEFAULT_MAX_CONCURRENT_SESSIONS
+}
+
+/**
+ * Cross-process active-session count: orchestrator groups in `spawned`/
+ * `running` + watcher entries in `spawned` (write-ahead, spawn in flight).
+ * Pass either state as null/undefined when that pipeline isn't in use.
+ */
+export function activeSessionCount(
+	orchState?: OrchestratorState | null,
+	watcherState?: WatcherState | null,
+): number {
+	let count = 0
+	if (orchState) {
+		for (const group of orchState.groups) {
+			if (group.status === "spawned" || group.status === "running") {
+				count++
+			}
+		}
+	}
+	if (watcherState) {
+		for (const entry of Object.values(watcherState.processed)) {
+			if (entry.status === "spawned") {
+				count++
+			}
+		}
+	}
+	return count
+}
+
+/**
+ * Convenience: load BOTH durable state files for a repo root and return the
+ * combined active count. Missing files are tolerated (fresh default state).
+ * Paths follow the repo conventions: `<repoRoot>/.worktrees/`.
+ */
+export function activeSessionCountForRepo(repoRoot: string): number {
+	const worktrees = path.join(path.resolve(repoRoot), ".worktrees")
+	const orchState = loadStateSync(path.join(worktrees, ".orchestrator-state.json"))
+	const watcherState = loadWatcherStateSync(path.join(worktrees, ".watcher-state.json"))
+	return activeSessionCount(orchState, watcherState)
+}

package/src/budget/cost.ts

@@ -0,0 +1,309 @@
+/**
+ * Phase 6 — model pricing + LLM cost estimation (the numeric heart of the
+ * per-session cost budget).
+ *
+ * The harness pays OpenRouter per token (input + output). To enforce a
+ * per-session cost cap without post-hoc reconciliation we estimate the USD
+ * cost of every LLM call from the `usage` object the provider returns
+ * (prompt/completion tokens) × the model's price.
+ *
+ * Pricing table: USD per 1M tokens, keyed by model id. Defaults cover the
+ * models this project actually uses (DeepSeek family via OpenRouter) plus one
+ * general model as a sanity reference. The table is overridable:
+ *
+ *   - in-code: pass a `PricingTable` to `estimateCost` / `accumulateCost` /
+ *     `BudgetTracker` (the constructor option);
+ *   - via env: `HEADLESSCODE_PRICING_JSON` = path to a JSON file of the same
+ *     shape (`{ "<model>": { "input": <per1M USD>, "output": <per1M USD> } }`),
+ *     deep-merged over the defaults (per-model override; unlisted models keep
+ *     the built-in price).
+ *
+ * Unknown models fall back to a CONSERVATIVE general rate (`FALLBACK_MODEL_PRICE`)
+ * rather than $0 — a runaway session on a model we don't have a price for must
+ * still be capped, not silently free.
+ *
+ * Prices below are the list rates as of the 2026-08 baseline; they are input
+ * to a GUARDRAIL (cap enforcement), so being slightly stale is safe (the cap
+ * direction — "did we cross the budget" — is what matters).
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+/** USD per 1M tokens for one model. */
+export interface ModelPrice {
+	/** Price per 1M INPUT (prompt) tokens, USD. */
+	input: number
+	/** Price per 1M OUTPUT (completion) tokens, USD. */
+	output: number
+	/**
+	 * Price per 1M CACHED input tokens, USD (a provider-side prompt-cache hit —
+	 * see LlmResponse.usage.cachedTokens). Optional and deliberately NOT
+	 * defaulted to a discounted guess: when absent, cached tokens are priced
+	 * at the full `input` rate, i.e. zero behavior change from before cache
+	 * accounting existed. Only set this once you've confirmed the model's
+	 * real cache-hit rate (e.g. from OpenRouter/provider docs) — this is a
+	 * cost GUARDRAIL, so a wrong optimistic discount could let real spend
+	 * exceed a configured cap.
+	 */
+	cacheRead?: number
+}
+
+/** Model id → price. */
+export type PricingTable = Record<string, ModelPrice>
+
+/**
+ * Default pricing table (OpenRouter list rates, USD per 1M tokens).
+ *
+ * - `deepseek/deepseek-v4-flash-0731` — the harness default (Phase 1/2/5
+ *   workers; see `DEFAULT_MODEL` in src/llm/openrouter.ts). Priced the same
+ *   as the prior default, `deepseek/deepseek-v4-flash` (kept below for
+ *   override compat) — same model line, dated point-release id. The rate is
+ *   the OFFICIAL DeepSeek provider's own rate specifically (verified
+ *   against OpenRouter's own
+ *   `/api/v1/models/deepseek/deepseek-v4-flash/endpoints` on 2026-08-01,
+ *   cross-checked against OpenRouter's own pricing UI). This price is only
+ *   actually correct because `src/llm/openrouter.ts` pins routing to this
+ *   exact provider (`provider: { order: ["deepseek"], allow_fallbacks:
+ *   false }`) for deepseek/* models — OTHER routed endpoints behind the
+ *   same model id (DeepInfra, Baidu, Mancer, ...) have meaningfully
+ *   different prices, especially for cache reads, so this number would be
+ *   wrong/unverifiable without that pin. If the pin is ever removed, this
+ *   price must be revisited, not left as a stale guess.
+ *   Missing entirely from this table before was the actual root cause of a
+ *   real incident: sessions silently fell through to `FALLBACK_MODEL_PRICE`
+ *   (7x+ this model's real input rate), producing wildly inflated internal
+ *   cost estimates and at least one false-positive budget abort. A second,
+ *   smaller error (`cacheRead` off by 10x — $0.028 instead of the real
+ *   $0.0028/1M) was caught and fixed the same day.
+ * - `deepseek/deepseek-v4-flash` — the previous default, kept priced so an
+ *   explicit override to the un-dated id still estimates correctly.
+ * - `deepseek/deepseek-chat` — the legacy default, still priced so an
+ *   explicit `OPENROUTER_MODEL=deepseek/deepseek-chat` override accounts
+ *   correctly.
+ * - `deepseek/deepseek-reasoner` — the reasoning variant used for review/QA.
+ * - `anthropic/claude-3.5-sonnet` — a general-purpose reference model.
+ * - `qwen/qwen3-embedding-4b` / `qwen/qwen3-embedding-8b` — the codebase-index
+ *   embedding models (src/codesearch/embedder.ts; 8b is the default since
+ *   the central-store round, 4b kept priced so a legacy index/override still
+ *   estimates correctly). Embedding responses carry no completion tokens
+ *   (output is always 0). The rates are CONSERVATIVE input-only estimates:
+ *   $0.15/1M for 4b was observed live on OpenRouter's Google embedding
+ *   endpoint (2026-08-01), and 8b is estimated at $0.30/1M (2x the 4b rate,
+ *   parameter-scaled) because embedding models are absent from OpenRouter's
+ *   /api/v1/models listing so neither list price is API-verifiable (see
+ *   src/codesearch/embedder.ts's header). Pricing a guardrail means
+ *   fail-closed: estimate rather than $0, so an index build on a large repo
+ *   still counts against a cost cap.
+ */
+export const DEFAULT_PRICING_TABLE: PricingTable = {
+ "deepseek/deepseek-chat": { input: 0.27, output: 1.1 },
+ "deepseek/deepseek-reasoner": { input: 0.55, output: 2.19 },
+ "deepseek/deepseek-v4-flash-0731": { input: 0.14, output: 0.28, cacheRead: 0.0028 },
+ "deepseek/deepseek-v4-flash": { input: 0.14, output: 0.28, cacheRead: 0.0028 },
+ "anthropic/claude-3.5-sonnet": { input: 3.0, output: 15.0 },
+ "qwen/qwen3-embedding-4b": { input: 0.15, output: 0.15 },
+ "qwen/qwen3-embedding-8b": { input: 0.3, output: 0.3 },
+ // Cloud vision captioning (src/vision/describe.ts). Live OpenRouter list
+ // rates pulled 2026-08-02 for image-input models; the 12b is the default
+ // (cheapest candidate that wasn't materially worse than the quality anchor
+ // in the image-support evaluation — see plans/image-support.md), and the
+ // 27b is priced too so an override to the quality anchor still estimates
+ // accurately instead of falling through to FALLBACK_MODEL_PRICE. Both were
+ // verified live against the API during the evaluation.
+ "google/gemma-3-12b-it": { input: 0.05, output: 0.15 },
+ "google/gemma-3-27b-it": { input: 0.08, output: 0.45 },
+}
+
+/**
+ * Conservative fallback for models missing from the table (USD per 1M).
+ * Deliberately a mid-range general rate, NOT $0 — unknown models must still
+ * count against the budget (fail-closed: over-estimate slightly rather than
+ * underestimate, so a cost cap is never bypassed by an unlisted model id).
+ */
+export const FALLBACK_MODEL_PRICE: ModelPrice = { input: 2.0, output: 8.0 }
+
+/** One endpoint entry of OpenRouter's `/api/v1/models/<id>/endpoints` response. */
+export interface EndpointPricingEntry {
+	/** Provider slug as OpenRouter reports it (e.g. "DeepSeek", "DeepInfra"). */
+	provider_name?: unknown
+	/** Per-token prices as STRINGS, USD per token (verified live 2026-08-04). */
+	pricing?: {
+		prompt?: unknown
+		completion?: unknown
+		input_cache_read?: unknown
+	}
+}
+
+/** Parse a per-token USD string like "0.00000014" into per-1M-token USD. */
+function perTokenToPerMillion(value: unknown): number | undefined {
+	if (typeof value !== "string" && typeof value !== "number") {
+		return undefined
+	}
+	const n = typeof value === "string" ? Number(value) : value
+	if (!Number.isFinite(n) || n < 0) {
+		return undefined
+	}
+	return n * 1_000_000
+}
+
+/**
+ * Parse live endpoint pricing into a `ModelPrice` (USD per 1M tokens).
+ *
+ * Selection rules, mirroring how the request actually routes:
+ * - When `providerPreference` is given (e.g. "DeepSeek" for the deepseek/*
+ *   chat pin), the FIRST endpoint whose provider_name matches (case-
+ *   insensitive) is used verbatim — that is the price actually charged.
+ * - Otherwise the MAX of each field across all endpoints that expose it is
+ *   used. This is a deliberate fail-closed choice: for auto-routed models the
+ *   harness cannot know which endpoint served a call, and this table is a
+ *   GUARDRAIL (the codebase's FALLBACK_MODEL_PRICE rationale) — over-
+ *   estimating is safe, under-estimating lets a cap be bypassed.
+ *
+ * Returns undefined when no endpoint exposes usable pricing.
+ */
+export function parseEndpointPricing(
+	endpoints: EndpointPricingEntry[],
+	providerPreference?: string,
+): ModelPrice | undefined {
+	let price: ModelPrice | undefined
+	for (const ep of endpoints) {
+		const pricing = ep?.pricing
+		if (!pricing || typeof pricing !== "object") {
+			continue
+		}
+		const parsed: ModelPrice = {
+			input: perTokenToPerMillion(pricing.prompt) ?? 0,
+			output: perTokenToPerMillion(pricing.completion) ?? 0,
+		}
+		if (parsed.input === 0 && parsed.output === 0) {
+			continue
+		}
+		const cacheRead = perTokenToPerMillion(pricing.input_cache_read)
+		if (cacheRead !== undefined) {
+			parsed.cacheRead = cacheRead
+		}
+		// Provider-preference match wins outright (first match — a match
+		// returns immediately, so reaching the end without returning means no
+		// usable match existed).
+		if (providerPreference) {
+			const name = typeof ep?.provider_name === "string" ? ep.provider_name : ""
+			if (name.toLowerCase() === providerPreference.toLowerCase()) {
+				return parsed
+			}
+		}
+		// Otherwise keep the conservative per-field max.
+		price = {
+			input: Math.max(price?.input ?? 0, parsed.input),
+			output: Math.max(price?.output ?? 0, parsed.output),
+			...(cacheRead !== undefined
+				? { cacheRead: Math.max(price?.cacheRead ?? 0, cacheRead) }
+				: price?.cacheRead !== undefined
+					? { cacheRead: price.cacheRead }
+					: {}),
+		}
+	}
+	// A preference was requested but no endpoint matched it — return nothing
+	// so the caller falls back to the hardcoded table (for deepseek/* that
+	// table IS the official endpoint's rate; using some other host's numbers
+	// for a pinned model would be wrong).
+	if (providerPreference) {
+		return undefined
+	}
+	return price
+}
+
+/** Merge a live-resolved price into a pricing table under a model id. */
+export function mergeLivePrice(table: PricingTable, model: string, price: ModelPrice): PricingTable {
+	return { ...table, [model]: price }
+}
+
+/**
+ * Load the effective pricing table: defaults deep-merged with overrides from
+ * `HEADLESSCODE_PRICING_JSON` (when set). A missing/unreadable/malformed file
+ * throws — a broken pricing override must fail loudly, never silently weaken
+ * a cost cap.
+ */
+export function loadPricingTable(
+	env: NodeJS.ProcessEnv = process.env,
+	base: PricingTable = DEFAULT_PRICING_TABLE,
+): PricingTable {
+	const pricingPath = env.HEADLESSCODE_PRICING_JSON
+	if (!pricingPath) {
+		return base
+	}
+	const file = path.resolve(pricingPath)
+	let raw: string
+	try {
+		raw = fs.readFileSync(file, "utf-8")
+	} catch (err) {
+		throw new Error(
+			`HEADLESSCODE_PRICING_JSON: cannot read pricing file '${file}': ${err instanceof Error ? err.message : String(err)}`,
+		)
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch (err) {
+		throw new Error(
+			`HEADLESSCODE_PRICING_JSON: invalid JSON in '${file}': ${err instanceof Error ? err.message : String(err)}`,
+		)
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`HEADLESSCODE_PRICING_JSON: '${file}' must be a JSON object of {model: {input, output}}`)
+	}
+	const overrides: PricingTable = {}
+	for (const [model, value] of Object.entries(parsed)) {
+		const v = value as { input?: unknown; output?: unknown }
+		if (typeof v.input === "number" && Number.isFinite(v.input) && v.input >= 0 && typeof v.output === "number" && Number.isFinite(v.output) && v.output >= 0) {
+			overrides[model] = { input: v.input, output: v.output }
+		}
+	}
+	return { ...base, ...overrides }
+}
+
+/** Resolve the price for a model (fallback when unlisted). */
+export function priceFor(model: string, pricing: PricingTable = DEFAULT_PRICING_TABLE): ModelPrice {
+	return pricing[model] ?? FALLBACK_MODEL_PRICE
+}
+
+export interface CostInput {
+	model: string
+	inputTokens?: number
+	outputTokens?: number
+	/**
+	 * Prompt tokens served from the provider's cache (a SUBSET of
+	 * inputTokens, not additional — see LlmResponse.usage.cachedTokens).
+	 * Priced at price.cacheRead when set, else at the full input rate.
+	 */
+	cachedTokens?: number
+	/** Explicit pricing table (default: env-merged defaults). */
+	pricing?: PricingTable
+}
+
+/**
+ * Estimate the USD cost of one LLM call from its usage token counts.
+ *   cost = (inputTokens - cachedTokens) × price.input / 1e6
+ *         + cachedTokens × (price.cacheRead ?? price.input) / 1e6
+ *         + outputTokens × price.output / 1e6
+ * `cachedTokens` is clamped to `inputTokens` (a provider reporting more
+ * cached than total prompt tokens would otherwise produce a negative
+ * "uncached" count).
+ */
+export function estimateCost(input: CostInput): number {
+	const { model, inputTokens = 0, outputTokens = 0 } = input
+	const table = input.pricing ?? loadPricingTable()
+	const price = priceFor(model, table)
+	const cachedTokens = Math.min(Math.max(input.cachedTokens ?? 0, 0), inputTokens)
+	const uncachedTokens = inputTokens - cachedTokens
+	const cacheRate = price.cacheRead ?? price.input
+	return (uncachedTokens * price.input + cachedTokens * cacheRate + outputTokens * price.output) / 1_000_000
+}
+
+/** Sum the estimated cost across multiple calls (runs) — the session total. */
+export function accumulateCost(
+	runs: Array<{ model: string; inputTokens?: number; outputTokens?: number; cachedTokens?: number }>,
+	pricing?: PricingTable,
+): number {
+	return runs.reduce((sum, run) => sum + estimateCost({ ...run, pricing }), 0)
+}

package/src/budget/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Phase 6 — guardrails (spec 6.3): per-session cost/time/iteration budgets and
+ * the global concurrent-session cap. See docs/phase6-cloud.md.
+ */
+
+export * from "./cost.js"
+export * from "./budget.js"
+export * from "./concurrency.js"