@kal-elsam/kairo-runtime 0.15.0 → 0.17.0

package/src/global/runtime/execution-worktree-orchestrator.js

@@ -0,0 +1,194 @@
+import { createRunId } from "./run-types.js";
+import { startRun as startRunDefault } from "./run-manager.js";
+import {
+  beginRoleRun as beginRoleRunDefault,
+  completeRoleRun as completeRoleRunDefault,
+  markInterrupted,
+  markReadyForReview as markReadyForReviewDefault
+} from "./execution-worktree-manager.js";
+import { readWorktreeState } from "./execution-worktree-store.js";
+import { WORKTREE_STATES } from "./execution-worktree-types.js";
+import { readTaskRecord } from "../architect/architect-store.js";
+import { readSkillCatalog } from "../intelligence/skill-catalog.js";
+import { matchSkills } from "../intelligence/execution-router.js";
+
+/**
+ * Strict order — never parallel, never reordered. Debugger's real work
+ * only makes sense against Builder's own real commit, and Tester's only
+ * against both.
+ */
+const ROLE_CHAIN = Object.freeze(["Builder", "Debugger", "Tester"]);
+
+const ROLE_INSTRUCTIONS = Object.freeze({
+  Builder:
+    "You are acting as the Builder role in this execution worktree. Implement the following "
+    + "approved plan directly in the current working tree. Only edit real files — Kairo itself "
+    + "owns every real commit; never run `git add` or `git commit` yourself.",
+  Debugger:
+    "You are acting as the Debugger role in this execution worktree. The Builder role's real "
+    + "implementation of the following approved plan is already committed in the current working "
+    + "tree. Review it for real bugs, edge cases, or deviations from the plan, and fix what you "
+    + "find. Only edit real files — Kairo itself owns every real commit; never run `git add` or "
+    + "`git commit` yourself.",
+  Tester:
+    "You are acting as the Tester role in this execution worktree. The Builder and Debugger "
+    + "roles' real work on the following approved plan is already committed in the current "
+    + "working tree. Write and run real tests that validate this implementation against the plan. "
+    + "Only edit real files — Kairo itself owns every real commit; never run `git add` or `git "
+    + "commit` yourself."
+});
+
+/**
+ * Appends the real, project-local skills (docs/skills, .claude/skills, etc
+ * — see skill-catalog.js) whose own real description actually overlaps
+ * this plan's text — the exact same word-overlap matcher execution-
+ * router.js already uses for ASK-mode routing, never a new heuristic.
+ * Only the real name + real file path are ever included; the skill's own
+ * content is never duplicated into the prompt — the role's real agent run
+ * has real filesystem access inside this same worktree and can read the
+ * real SKILL.md itself if it decides the match is relevant. An empty
+ * catalog or zero matches changes nothing: the plan text is untouched.
+ */
+function buildRoleTask(role, planMarkdown, skills = []) {
+  const matches = matchSkills(planMarkdown, skills);
+  const skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
+  const skillLines = matches
+    .map((match) => skillsByName.get(match.name))
+    .filter(Boolean)
+    .map((skill) => `- ${skill.name} (${skill.path}): ${skill.description}`);
+
+  const skillsSection = skillLines.length > 0
+    ? `\n\n## Relevant project skills\nThese real project skills may apply — read the file at its own path if useful, never assume its content:\n${skillLines.join("\n")}`
+    : "";
+
+  return `${ROLE_INSTRUCTIONS[role]}\n\n${planMarkdown}${skillsSection}`;
+}
+
+/**
+ * Automatically chains Builder -> Debugger -> Tester inside one already-
+ * created execution worktree — the real point of everything increments
+ * 1-4 built: isolation (worktree), a trustworthy per-role transaction
+ * (beginRoleRun/completeRoleRun), and a governed budget
+ * (assertProviderNotExhausted, already wired into startRun itself) all
+ * had to exist BEFORE this was safe to automate.
+ *
+ * Only ever drives a freshly-created worktree (real status PENDING, no
+ * role has run yet) — this is a strict, from-scratch chain, not a
+ * resumable one; a worktree that already progressed manually should keep
+ * being driven manually via beginRoleRun/completeRoleRun/
+ * markReadyForReview directly.
+ *
+ * Per role, in strict order: beginRoleRun, a real startRun pointed at the
+ * worktree's own treePath (the same governed budget gate from
+ * usage-manager.js already runs inside startRun itself — no separate
+ * check needed here), then completeRoleRun once the real run reaches a
+ * terminal state. The task text sent to each role's real agent run wraps
+ * the same real, approved plan.md with a role-specific framing — the
+ * plan itself is never split or rewritten, only presented differently.
+ *
+ * Any real failure — the run itself failing, completeRoleRun rejecting a
+ * bad diff, or the run never even starting (a budget/preflight/adapter
+ * failure before any real process existed) — stops the chain immediately
+ * at that role. A never-started run has no run for completeRoleRun's own
+ * checks to find, so this function marks the worktree INTERRUPTED itself
+ * in that one case; every other real failure is already handled by
+ * completeRoleRun's own existing logic. The next role is never attempted
+ * once one fails.
+ *
+ * Only once all three roles complete does this call markReadyForReview
+ * automatically — the one, explicit boundary automation stops at. Preview
+ * and apply remain entirely manual, exactly as designed in increment 3:
+ * a reviewed, confirmed `git merge --ff-only` is never automatic.
+ * @param {object} args
+ * @param {string} args.worktreeId
+ * @param {string} args.homeDir
+ * @param {string} args.agentId - the default execution-adapters/index.js provider for every role
+ * @param {Partial<Record<"Builder"|"Debugger"|"Tester", string>>} [args.roleAgents] - per-role provider override
+ * @param {string|null} [args.model]
+ * @param {object|null} [args.profile] - the resolveProfile() shape ({profile, sources}), passed straight through to startRun
+ * @param {string} [args.cliVersion]
+ * @param {string[]} [args.permissions]
+ * @param {boolean} [args.captureTranscript]
+ * @param {Function} [args.spawnImpl] - forwarded to every real startRun call, see run-manager.js's own
+ * @param {Function} [args.resolveAdapterImpl] - forwarded to every real startRun call, see run-manager.js's own
+ */
+export async function runOrchestratedChain({
+  worktreeId,
+  homeDir,
+  agentId,
+  roleAgents = {},
+  model = null,
+  profile = null,
+  cliVersion,
+  permissions = [],
+  captureTranscript = false,
+  spawnImpl,
+  resolveAdapterImpl,
+  startRunImpl = startRunDefault,
+  beginRoleRunImpl = beginRoleRunDefault,
+  completeRoleRunImpl = completeRoleRunDefault,
+  markReadyForReviewImpl = markReadyForReviewDefault
+}) {
+  const initial = await readWorktreeState(homeDir, worktreeId);
+  if (!initial) throw new Error(`Execution worktree "${worktreeId}" not found.`);
+  if (initial.status !== WORKTREE_STATES.PENDING) {
+    throw new Error(
+      `Execution worktree "${worktreeId}" is ${initial.status}; runOrchestratedChain only drives a `
+      + "freshly-created worktree from PENDING — a worktree already in progress must be driven manually."
+    );
+  }
+
+  const record = await readTaskRecord(initial.projectRoot, initial.taskId);
+  if (!record?.planMarkdown) {
+    throw new Error(`Execution worktree "${worktreeId}" has no real approved plan text to orchestrate roles from.`);
+  }
+
+  // Read once, from the worktree's own real checkout — exactly what each
+  // role's real agent run will itself see, not the main project's
+  // possibly-different working tree.
+  const skills = await readSkillCatalog(initial.treePath);
+
+  const completedRoles = [];
+
+  for (const role of ROLE_CHAIN) {
+    const runId = createRunId();
+    await beginRoleRunImpl({ worktreeId, role, runId, homeDir });
+
+    try {
+      const { completion } = await startRunImpl({
+        homeDir,
+        runId,
+        agentId: roleAgents[role] ?? agentId,
+        task: buildRoleTask(role, record.planMarkdown, skills),
+        cwd: initial.treePath,
+        model,
+        permissions,
+        captureTranscript,
+        cliVersion,
+        profile,
+        wait: true,
+        ...(spawnImpl ? { spawnImpl } : {}),
+        ...(resolveAdapterImpl ? { resolveAdapterImpl } : {})
+      });
+      await completion;
+    } catch (error) {
+      const worktreeNow = (await readWorktreeState(homeDir, worktreeId)) ?? initial;
+      await markInterrupted(
+        homeDir, worktreeNow,
+        `Role "${role}" run "${runId}" could not be started: ${error.message ?? String(error)}`
+      );
+      throw new Error(`Orchestrated chain stopped at role "${role}": ${error.message ?? String(error)}`);
+    }
+
+    try {
+      await completeRoleRunImpl({ worktreeId, role, runId, homeDir });
+    } catch (error) {
+      throw new Error(`Orchestrated chain stopped at role "${role}": ${error.message ?? String(error)}`);
+    }
+
+    completedRoles.push(role);
+  }
+
+  const ready = await markReadyForReviewImpl({ worktreeId, homeDir });
+  return { worktree: ready, completedRoles };
+}

package/src/global/runtime/execution-worktree-store.js

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { harnessHomePaths, worktreePaths } from "../paths.js";
+import { writeAtomicJson } from "./write-atomic-json.js";
+
+const writeLocks = new Map();
+
+export function getWorktreesDir(homeDir) {
+  return harnessHomePaths(homeDir).worktreesDir;
+}
+
+/** Creates the initial, real PENDING record — exclusive so two concurrent creations can never collide on the same worktreeId. */
+export async function createWorktreeRecord(homeDir, metadata) {
+  const { worktreeDir, statePath } = worktreePaths(homeDir, metadata.worktreeId);
+  await mkdir(worktreeDir, { recursive: true });
+  await writeAtomicJson(statePath, metadata, { createExclusive: true });
+  return metadata;
+}
+
+export async function readWorktreeState(homeDir, worktreeId) {
+  const { statePath } = worktreePaths(homeDir, worktreeId);
+  if (!existsSync(statePath)) return null;
+
+  try {
+    return JSON.parse(await readFile(statePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid execution worktree state at ${statePath}: ${error.message}`);
+  }
+}
+
+/** Read-modify-write is serialized per worktreeId — same real race protection run-store.js's writeRunState already relies on. */
+export async function writeWorktreeState(homeDir, metadata) {
+  const key = metadata.worktreeId;
+  const previous = writeLocks.get(key) ?? Promise.resolve();
+  const next = previous.then(async () => {
+    const { worktreeDir, statePath } = worktreePaths(homeDir, metadata.worktreeId);
+    await mkdir(worktreeDir, { recursive: true });
+    await writeAtomicJson(statePath, metadata);
+    return metadata;
+  });
+  writeLocks.set(key, next.catch(() => {}));
+  return next;
+}
+
+/** Append-only, one real checkpoint per line — mirrors run-store.js's own appendRunEvent for events.jsonl. */
+export async function appendCheckpoint(homeDir, worktreeId, checkpoint) {
+  const { worktreeDir, checkpointsPath } = worktreePaths(homeDir, worktreeId);
+  await mkdir(worktreeDir, { recursive: true });
+  await appendFile(checkpointsPath, `${JSON.stringify(checkpoint)}\n`, "utf8");
+  return checkpoint;
+}
+
+export async function readCheckpoints(homeDir, worktreeId) {
+  const { checkpointsPath } = worktreePaths(homeDir, worktreeId);
+  if (!existsSync(checkpointsPath)) return [];
+
+  const content = await readFile(checkpointsPath, "utf8");
+  return content
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        return { parseError: true, line: index + 1, message: error.message };
+      }
+    });
+}
+
+export async function listWorktreeRecords(homeDir) {
+  const worktreesDir = getWorktreesDir(homeDir);
+  if (!existsSync(worktreesDir)) return [];
+
+  const entries = await readdir(worktreesDir, { withFileTypes: true });
+  const worktrees = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const state = await readWorktreeState(homeDir, entry.name);
+    if (state) worktrees.push(state);
+  }
+  worktrees.sort((left, right) => String(right.createdAt).localeCompare(String(left.createdAt)));
+  return worktrees;
+}

package/src/global/runtime/execution-worktree-types.js

@@ -0,0 +1,45 @@
+export const EXECUTION_WORKTREE_SCHEMA = "kairo.execution-worktree/v1";
+
+// pending: registered, git worktree add not yet confirmed.
+// active: at least one role has a real run in progress inside the worktree.
+// ready_for_review: all roles finished; a real preview/merge is possible.
+// applying: a confirmed merge is in flight against the real project.
+// applied / discarded: terminal, successful/abandoned outcomes.
+// interrupted: Kairo restarted mid-operation — see recovery, never guessed.
+export const WORKTREE_STATES = Object.freeze({
+  PENDING: "pending",
+  ACTIVE: "active",
+  READY_FOR_REVIEW: "ready_for_review",
+  APPLYING: "applying",
+  APPLIED: "applied",
+  DISCARDED: "discarded",
+  INTERRUPTED: "interrupted"
+});
+
+export const ACTIVE_WORKTREE_STATES = new Set([
+  WORKTREE_STATES.PENDING,
+  WORKTREE_STATES.ACTIVE,
+  WORKTREE_STATES.READY_FOR_REVIEW,
+  WORKTREE_STATES.APPLYING
+]);
+
+export function isActiveWorktreeState(state) {
+  return ACTIVE_WORKTREE_STATES.has(state);
+}
+
+export const TERMINAL_WORKTREE_STATES = new Set([
+  WORKTREE_STATES.APPLIED,
+  WORKTREE_STATES.DISCARDED,
+  WORKTREE_STATES.INTERRUPTED
+]);
+
+export function isTerminalWorktreeState(state) {
+  return TERMINAL_WORKTREE_STATES.has(state);
+}
+
+/** Same shape as run-types.js's own createRunId — an opaque, sortable-enough, collision-resistant local id, never a real git ref name. */
+export function createWorktreeId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `wt_${timestamp}_${random}`;
+}

package/src/global/runtime/run-events.js

@@ -131,6 +131,44 @@ export function applyEventToMetadata(metadata, event) {
   return next;
 }
 
+/**
+ * Best-effort real human-readable text out of a real "run.transcript"
+ * event's own `data` — the shape varies by adapter (Codex/Claude each pass
+ * their own CLI's raw JSON event through mostly as-is, see each adapter's
+ * own parseEventLine), so this tries the common real shapes in order
+ * (flat string, `text`, `content` as a string or an Anthropic-style
+ * content-block array, a nested `message`, `result`) and only ever falls
+ * back to a raw JSON dump when none of those match — it never silently
+ * drops a real event's content just because its exact shape wasn't
+ * anticipated.
+ * @param {unknown} data
+ * @returns {string}
+ */
+export function formatTranscriptEventText(data) {
+  if (data == null) return "";
+  if (typeof data === "string") return data;
+  if (typeof data !== "object") return String(data);
+  if (typeof data.text === "string") return data.text;
+  if (typeof data.content === "string") return data.content;
+  if (Array.isArray(data.content)) {
+    const text = data.content
+      .filter((block) => block && typeof block === "object" && typeof block.text === "string")
+      .map((block) => block.text)
+      .join("");
+    if (text) return text;
+  }
+  if (data.message && typeof data.message === "object") {
+    const nested = formatTranscriptEventText(data.message);
+    if (nested) return nested;
+  }
+  if (typeof data.result === "string") return data.result;
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return String(data);
+  }
+}
+
 export function transitionRunState(metadata, nextState, { exitCode = null, error = null } = {}) {
   const now = new Date().toISOString();
   return {

package/src/global/runtime/run-manager.js

@@ -11,6 +11,7 @@ import {
   writeRunState
 } from "./run-store.js";
 import { resolveExecutionAdapter } from "./execution-adapters/index.js";
+import { assertProviderNotExhausted } from "./usage-manager.js";
 import { resolveProfileAgents } from "../profile.js";
 import { resolveRuntimeOptions } from "./run-profile.js";
 import { authorizeRunPermissions } from "./run-permissions.js";
@@ -100,10 +101,12 @@ async function prepareRun({
   captureTranscript = false,
   cliVersion,
   profile = null,
-  strategy = "direct"
+  strategy = "direct",
+  runId: requestedRunId = null,
+  resolveAdapterImpl = resolveExecutionAdapter
 }) {
   const normalizedStrategy = assertOrchestratedAgent(agentId, strategy);
-  const adapter = resolveExecutionAdapter(agentId);
+  const adapter = resolveAdapterImpl(agentId);
   const availability = adapter.availability({ cwd });
 
   if (!availability.available) {
@@ -117,6 +120,14 @@ async function prepareRun({
     );
   }
 
+  await adapter.preflight({ cwd });
+  // The one real, enforced budget gate this increment adds — refuses only
+  // a provider whose real, cumulative consumption already reached its own
+  // configured budget (usage-manager.js). No configured
+  // profile.providerTokenBudgets.<agentId> means no gate: this never
+  // blocks a provider nobody set a budget for.
+  await assertProviderNotExhausted({ homeDir, provider: agentId, profile: profile?.profile ?? null });
+
   const authorized = authorizeRunPermissions({
     permissions,
     agentId,
@@ -129,7 +140,7 @@ async function prepareRun({
     await assertManagedMinionExtension(homeDir);
   }
 
-  const runId = createRunId();
+  const runId = requestedRunId ?? createRunId();
   const lineage = createRootRunLineage(runId);
   const metadata = createRunMetadata({
     runId,
@@ -197,7 +208,9 @@ export async function startRun({
   timeoutMs = null,
   wait = true,
   spawnImpl = spawn,
-  forkDetachedSupervisorImpl = forkDetachedSupervisor
+  forkDetachedSupervisorImpl = forkDetachedSupervisor,
+  runId: requestedRunId = null,
+  resolveAdapterImpl = resolveExecutionAdapter
 }) {
   const { runId, metadata } = await prepareRun({
     homeDir,
@@ -212,7 +225,9 @@ export async function startRun({
     captureTranscript,
     cliVersion,
     profile,
-    strategy: normalizeRunStrategy(strategy)
+    strategy: normalizeRunStrategy(strategy),
+    runId: requestedRunId,
+    resolveAdapterImpl
   });
 
   if (!wait) {
@@ -274,7 +289,8 @@ export async function startRun({
     timeoutMs,
     spawnImpl,
     cancelledRuns,
-    activeProcesses
+    activeProcesses,
+    resolveAdapterImpl
   });
 
   return {

package/src/global/runtime/run-supervisor.js

@@ -14,6 +14,7 @@ import {
   writeRunState
 } from "./run-store.js";
 import { resolveExecutionAdapter } from "./execution-adapters/index.js";
+import { recordProviderUsage } from "./usage-manager.js";
 import { consumeRunHandoff } from "./run-handoff.js";
 import { isRunCancelRequested } from "./run-cancel-signal.js";
 import { readSupervisorLock, touchSupervisorLock, writeSupervisorLock } from "./run-supervisor-lock.js";
@@ -72,10 +73,11 @@ export async function supervisePreparedRun({
   timeoutMs = null,
   spawnImpl = spawn,
   cancelledRuns = null,
-  activeProcesses = null
+  activeProcesses = null,
+  resolveAdapterImpl = resolveExecutionAdapter
 }) {
   const handoff = await consumeRunHandoff(homeDir, runId);
-  const adapter = resolveExecutionAdapter(handoff.agentId);
+  const adapter = resolveAdapterImpl(handoff.agentId);
   let metadata = await readRunState(homeDir, runId);
 
   if (!metadata) {
@@ -85,16 +87,6 @@ export async function supervisePreparedRun({
   const captureTranscript = handoff.captureTranscript === true;
   const strategy = normalizeRunStrategy(handoff.strategy ?? metadata.strategy ?? "direct");
   const extensionPath = resolveOrchestratedExtensionPath(homeDir, strategy);
-  const launch = adapter.buildLaunch({
-    task: handoff.task,
-    cwd: handoff.cwd,
-    model: handoff.model,
-    permissions: handoff.permissions ?? [],
-    profile: handoff.profile ?? null,
-    strategy,
-    extensionPath
-  });
-
   metadata = {
     ...metadata,
     state: RUN_STATES.RUNNING,
@@ -109,6 +101,26 @@ export async function supervisePreparedRun({
     lastHeartbeat: new Date().toISOString()
   });
 
+  try {
+    await adapter.preflight({ cwd: handoff.cwd });
+  } catch (error) {
+    metadata = transitionRunState(metadata, RUN_STATES.FAILED, { error: error.message });
+    await writeRunState(homeDir, metadata);
+    await appendRunEvent(homeDir, createRunEvent({
+      runId, type: "run.failed", data: { error: error.message }
+    }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
+    throw error;
+  }
+  const launch = adapter.buildLaunch({
+    task: handoff.task,
+    cwd: handoff.cwd,
+    model: handoff.model,
+    permissions: handoff.permissions ?? [],
+    profile: handoff.profile ?? null,
+    strategy,
+    extensionPath
+  });
+
   const child = spawnImpl(launch.command, launch.args, {
     cwd: launch.cwd,
     env: buildOrchestratedRuntimeEnv({
@@ -169,6 +181,13 @@ export async function supervisePreparedRun({
           captureTranscript: true
         }),
         runId,
+        // createRunEvent defaults source to "kairo" — the real event this
+        // is mirrored from already carries the real adapter id (see
+        // normalizeAdapterEvent's own `source: adapterId`), so this must
+        // be explicitly propagated, or every provider's transcript would
+        // collapse to a generic "kairo" label with no way to tell whether
+        // a given line came from Codex, Claude, or another real provider.
+        source: event.source ?? adapter.id,
         timestamp: event.timestamp
       });
     }
@@ -301,6 +320,16 @@ export async function supervisePreparedRun({
             type: failed ? "run.failed" : "run.completed",
             data: { exitCode }
           }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
+          // Recorded exactly once, here, at the real terminal state — never
+          // on intermediate streamed usage events, which would double-count
+          // as they arrive. A run whose adapter never reported real usage
+          // (tokenUsage.total stays null) records nothing.
+          await recordProviderUsage(homeDir, adapter.id, {
+            input: metadata.tokenUsage?.input,
+            output: metadata.tokenUsage?.output,
+            total: metadata.tokenUsage?.total,
+            cost: metadata.cost
+          });
           if (!failed && strategy === RUN_STRATEGIES.ORCHESTRATED) {
             await finalizeOrchState(runId, { homeDir, recovered: false });
           }

package/src/global/runtime/usage-manager.js

@@ -0,0 +1,96 @@
+import { classifyUsageTier, createProviderUsageRecord, isProviderExhausted } from "./usage-types.js";
+import { readProviderUsage, writeProviderUsage } from "./usage-store.js";
+
+/**
+ * Records one real run's own usage onto a provider's real, cumulative
+ * total — called exactly once per real run, at the moment it reaches a
+ * terminal state (run-supervisor.js), never on intermediate streamed
+ * usage events (which would double-count as they arrive). A run with no
+ * real usage data at all (tokens null — the adapter never reported any,
+ * or the process never really started) records nothing: there is no
+ * real consumption to attribute, and bumping runCount for it would be
+ * noise, not evidence.
+ * @param {string} homeDir
+ * @param {string} provider - a real execution-adapters/index.js id
+ * @param {{input?: number|null, output?: number|null, total?: number|null, cost?: number|null}} usage
+ */
+export async function recordProviderUsage(homeDir, provider, usage = {}) {
+  const total = Number.isFinite(usage.total) ? usage.total : null;
+  if (total == null) return null;
+
+  const current = (await readProviderUsage(homeDir, provider)) ?? createProviderUsageRecord(provider);
+  const input = Number.isFinite(usage.input) ? usage.input : 0;
+  const output = Number.isFinite(usage.output) ? usage.output : 0;
+  const cost = Number.isFinite(usage.cost) ? usage.cost : 0;
+
+  const next = {
+    ...current,
+    totalInputTokens: current.totalInputTokens + input,
+    totalOutputTokens: current.totalOutputTokens + output,
+    totalTokens: current.totalTokens + total,
+    totalCost: current.totalCost + cost,
+    runCount: current.runCount + 1,
+    updatedAt: new Date().toISOString()
+  };
+
+  await writeProviderUsage(homeDir, provider, next);
+  return next;
+}
+
+function resolveProviderBudget(profile, provider) {
+  const perProvider = profile?.providerTokenBudgets;
+  if (perProvider && typeof perProvider === "object" && Number.isFinite(perProvider[provider])) {
+    return perProvider[provider];
+  }
+  return null;
+}
+
+/**
+ * The real, current classification for one provider — real cumulative
+ * consumption (readProviderUsage) against the real configured budget for
+ * that provider (profile.providerTokenBudgets), never a single run's own
+ * usage. No configured budget for this provider means no real consumption
+ * record is even required to answer HEALTHY.
+ * @param {object} args
+ * @param {string} args.homeDir
+ * @param {string} args.provider
+ * @param {object} [args.profile] - a resolved profile object (profile.js's own `profile` field)
+ */
+export async function getProviderUsageState({ homeDir, provider, profile = null }) {
+  const budgetTokens = resolveProviderBudget(profile, provider);
+  const record = (await readProviderUsage(homeDir, provider)) ?? createProviderUsageRecord(provider);
+  const tier = classifyUsageTier(record.totalTokens, budgetTokens);
+
+  return {
+    provider,
+    budgetTokens,
+    consumedTokens: record.totalTokens,
+    consumedCost: record.totalCost,
+    runCount: record.runCount,
+    tier
+  };
+}
+
+/**
+ * The real, single enforcement point this increment adds — called from
+ * run-manager.js's prepareRun, right after adapter.preflight and before a
+ * new run is ever created. Refuses only a provider whose real cumulative
+ * consumption has reached its own configured budget; every other tier
+ * (HEALTHY through CRITICAL) is informational only in this increment —
+ * there is no automatic model-chaining yet for a softer tier to throttle.
+ * @param {object} args
+ * @param {string} args.homeDir
+ * @param {string} args.provider
+ * @param {object} [args.profile]
+ */
+export async function assertProviderNotExhausted({ homeDir, provider, profile = null }) {
+  const state = await getProviderUsageState({ homeDir, provider, profile });
+  if (isProviderExhausted(state.tier)) {
+    throw new Error(
+      `Provider "${provider}" has exhausted its configured token budget `
+      + `(${state.consumedTokens}/${state.budgetTokens} tokens). Raise providerTokenBudgets.${provider} `
+      + "in the profile, or wait for the budget to be reset, before starting a new run."
+    );
+  }
+  return state;
+}