karajan-code 3.13.0 → 3.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/register-pipeline.js

@@ -101,6 +101,8 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
     .option("--no-sonarcloud")
     .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
+    .option("--step", "Pause after each iteration with a report and ask before continuing")
+    .option("--parallel <n>", "Concurrent HU lanes for plan runs (default: 1, sequential)")
     .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
     .option("--pg-project <projectId>", "Planning Game project ID")
     .option("--auto-simplify", "Auto-simplify pipeline for simple tasks (disable reviewer/tester)")

package/src/commands/init.js

@@ -371,6 +371,15 @@ async function runWizard(config, logger) {
     logger.info("Git automation:");
     await askGitAutomation(wizard, config, logger);
 
+    // Iteration gate (KJC-TSK-0628): opt-in step mode, default no.
+    config.session = config.session || {};
+    const stepMode = await wizard.confirm(
+      "Pause after each iteration with a report and ask before continuing (step mode)?",
+      false,
+    );
+    config.session.iteration_gate = stepMode;
+    logger.info(`  -> iteration_gate: ${stepMode}`);
+
     if (enableHuBoard) {
       logger.info("");
       logger.info("HU Board security:");

package/src/config/defaults.js

@@ -55,7 +55,10 @@ const DEFAULTS = {
   review_mode: "standard",
   max_iterations: 5,
   hu_max_iterations: 3,
-  max_budget_usd: null,
+  // Hard per-run spend ceiling, ON by default (KJC-TSK-0621): a stuck or
+  // runaway run must never drain a subscription quota unattended. Explicit
+  // null in the user's config opts out (no cap).
+  max_budget_usd: 5,
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",
@@ -173,6 +176,12 @@ const DEFAULTS = {
     role_overrides: {}
   },
   session: {
+    // Opt-in per-iteration supervision (KJC-TSK-0628): pause after each
+    // iteration with a report and ask continue / stop / instructions.
+    iteration_gate: false,
+    // Concurrent HU lanes per plan run (KJC-TSK-0626). 1 = sequential.
+    // Raising it multiplies token burn rate — the plan budget scales with it.
+    max_parallel_hus: 1,
     max_iteration_minutes: 30,
     max_total_minutes: 120,
     max_planner_minutes: 60,

package/src/config/overrides.js

@@ -55,6 +55,7 @@ const SCALAR_FLAGS = [
   ["maxIterationMinutes", (out, v) => { out.session.max_iteration_minutes = Number(v); }],
   ["maxTotalMinutes", (out, v) => { out.session.max_total_minutes = Number(v); }],
   ["checkpointInterval", (out, v) => { out.session.checkpoint_interval_minutes = Number(v); }],
+  ["parallel", (out, v) => { out.session.max_parallel_hus = Number(v); }],
   ["baseBranch", (out, v) => { out.base_branch = v; }],
   ["coderFallback", (out, v) => { out.coder_options.fallback_coder = v; }],
   ["reviewerFallback", (out, v) => { out.reviewer_options.fallback_reviewer = v; }],
@@ -147,6 +148,9 @@ function applyMiscOverrides(out, flags) {
   // The flag is still accepted to avoid breaking scripts; it now emits a
   // warning at run start and is otherwise ignored. See preflight-checks.js
   // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  // --step: per-iteration supervision gate (KJC-TSK-0628).
+  if (flags.step === true) out.session.iteration_gate = true;
+
   if (flags.noSonar || flags.sonar === false) {
     out._deprecated = out._deprecated || {};
     out._deprecated.noSonarFlag = true;
@@ -172,8 +176,14 @@ export function applyRunOverrides(config, flags) {
   out.git = out.git || {};
   out.development = out.development || {};
   out.sonarqube = out.sonarqube || {};
-  if (out.max_budget_usd === undefined || out.max_budget_usd === null) {
-    out.max_budget_usd = out.session.max_budget_usd ?? null;
+  // Precedence: explicit top-level value (including null = opt-out) wins;
+  // the legacy session.max_budget_usd location next; the shipped default
+  // (KJC-TSK-0621: 5) last. When top-level still carries the default, a
+  // session-level value — including an explicit null — takes over.
+  if (out.max_budget_usd === undefined) {
+    out.max_budget_usd = out.session.max_budget_usd !== undefined ? out.session.max_budget_usd : DEFAULTS.max_budget_usd;
+  } else if (out.max_budget_usd === DEFAULTS.max_budget_usd && out.session.max_budget_usd !== undefined) {
+    out.max_budget_usd = out.session.max_budget_usd;
   }
   out.budget = mergeDeep(DEFAULTS.budget, out.budget || {});
   out.roles = mergeDeep(DEFAULTS.roles, out.roles || {});

package/src/orchestrator/drivers/iteration-loop.js

@@ -27,6 +27,7 @@ import {
   setReviewerFeedback, resetRetryCount,
 } from "../../session/mutators.js";
 import { invokeSolomon } from "../solomon-escalation.js";
+import { buildIterationReport, handleIterationGate } from "../iteration-gate.js";
 import {
   handleCiEarlyPrOrPush, handleCiReviewDispatch,
 } from "../ci-integration.js";
@@ -251,6 +252,21 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       return iterResult.result;
     }
     if (iterResult.action === "retry") { i -= 1; }
+    else {
+      // Iteration gate (KJC-TSK-0628): opt-in pause with a report before the
+      // next iteration; free-text answers become directives for the coder.
+      const gate = await handleIterationGate({
+        enabled: ctx.config.session?.iteration_gate === true,
+        askQuestion, session: ctx.session, logger,
+        report: buildIterationReport({
+          i, maxIterations: ctx.config.max_iterations, stageResults: ctx.stageResults,
+          budgetTracker: ctx.budgetTracker, maxBudgetUsd: ctx.config.max_budget_usd,
+        }),
+      });
+      if (gate.action === "stop") {
+        return { approved: false, sessionId: ctx.session.id, reason: "user_stopped_at_gate", iteration: i };
+      }
+    }
   }
 
   // Solomon decides whether to extend iterations or stop
@@ -289,6 +305,20 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       const iterResult = await runSingleIteration(ctx);
       if (iterResult.action === "return") return iterResult.result;
       if (iterResult.action === "retry") { i -= 1; }
+      else {
+        // Same iteration gate on Solomon-extended iterations (KJC-TSK-0628).
+        const gate = await handleIterationGate({
+          enabled: ctx.config.session?.iteration_gate === true,
+          askQuestion, session: ctx.session, logger,
+          report: buildIterationReport({
+            i, maxIterations: ctx.config.max_iterations, stageResults: ctx.stageResults,
+            budgetTracker: ctx.budgetTracker, maxBudgetUsd: ctx.config.max_budget_usd,
+          }),
+        });
+        if (gate.action === "stop") {
+          return { approved: false, sessionId: ctx.session.id, reason: "user_stopped_at_gate", iteration: i };
+        }
+      }
     }
 
     // Extended iterations also exhausted — final Solomon call

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -14,6 +14,7 @@
  */
 
 import { generateDiff } from "../../../review/diff-generator.js";
+import { withLock } from "../../../utils/async-lock.js";
 import {
   runTddCheckStage, runSonarStage, runSonarCloudStage,
 } from "../../iteration-stages.js";
@@ -52,10 +53,12 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   // that one file.
   const sonarStageDisabledForTest = config?.testHarness?.disableSonarStage === true;
   if (!sonarStageDisabledForTest && session.resolved_policies?.sonar !== false) {
-    const sonarResult = await runSonarStage({
+    // Serialize across parallel HU lanes (KJC-TSK-0625): the SonarQube
+    // server scans one project key at a time. No-op on sequential runs.
+    const sonarResult = await withLock("sonar-scan", () => runSonarStage({
       config, logger, emitter, eventBase, session, trackBudget, iteration: i,
       repeatDetector, budgetSummary, sonarState, askQuestion, task, brainCtx
-    });
+    }));
     if (sonarResult.action === "stalled" || sonarResult.action === "pause") return { action: "return", result: sonarResult.result };
     if (sonarResult.action === "continue") return { action: "continue" };
     if (sonarResult.stageResult) {

package/src/orchestrator/flow-control.js

@@ -153,7 +153,11 @@ export async function checkBudgetExceeded({ budgetTracker, config, session, emit
 
   await markSessionStatus(session, "failed");
   const totalCost = budgetTracker.total().cost_usd;
-  const message = `Budget exceeded: $${totalCost.toFixed(2)} > $${budgetLimit.toFixed(2)}`;
+  const limit = Number(budgetLimit ?? config?.max_budget_usd);
+  const message =
+    `Budget exceeded: $${totalCost.toFixed(2)} > $${limit.toFixed(2)}. ` +
+    `Continue consciously with \`kj resume ${session.id}\`, or raise the cap ` +
+    `(max_budget_usd in .karajan/kj.config.yml; null removes it).`;
   emitProgress(
     emitter,
     makeEvent("session:end", { ...eventBase, iteration: i, stage: "budget" }, {

package/src/orchestrator/hu-scheduler.js

@@ -0,0 +1,114 @@
+/**
+ * hu-scheduler — pure scheduling for parallel HU execution (KJC-TSK-0623,
+ * épica KJC-PCS-0065). Decides WHICH HUs may run concurrently; it never
+ * launches anything. Two rules, both conservative by design:
+ *
+ *   1. Dependencies: every blocked_by id must be in completedIds.
+ *   2. Scope isolation: two HUs whose scopes touch the same path prefix are
+ *      never scheduled together — predictable merge conflicts cost more than
+ *      the parallelism they'd buy. An HU with NO scope has an unknown blast
+ *      radius, so it runs alone (exclusive with everything).
+ */
+
+/**
+ * Extract path-like tokens from a free-form scope. The planner writes scope
+ * as prose ("src/auth y tests/auth", "docs/*.md"); we keep anything that
+ * looks like a path or glob, normalized to its base directory.
+ */
+export function scopeTokens(scope) {
+  if (!scope || typeof scope !== "string") return [];
+  const matches = scope.match(/[\w.-]+(?:\/[\w*.{}-]+)+|[\w.-]+\/(?=\s|$|,)/g) || [];
+  return matches
+    .map((raw) => {
+      // Cut the token at its first glob segment: "src/**/*.js" → "src".
+      const segments = raw.replace(/\/+$/, "").split("/");
+      const firstGlob = segments.findIndex((s) => s.includes("*") || s.includes("{"));
+      return (firstGlob === -1 ? segments : segments.slice(0, firstGlob)).join("/");
+    })
+    .filter(Boolean);
+}
+
+/** True when two token lists share a path-prefix relationship. */
+function tokensOverlap(a, b) {
+  for (const ta of a) {
+    for (const tb of b) {
+      if (ta === tb || ta.startsWith(`${tb}/`) || tb.startsWith(`${ta}/`)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True when two HUs cannot run concurrently: either one has no parseable
+ * scope (unknown blast radius ⇒ exclusive) or their scopes overlap.
+ */
+export function husConflict(huA, huB) {
+  const a = scopeTokens(huA.scope);
+  const b = scopeTokens(huB.scope);
+  if (a.length === 0 || b.length === 0) return true;
+  return tokensOverlap(a, b);
+}
+
+/**
+ * Split one dependency-level group into conflict-free chunks of at most
+ * `maxParallel` HUs (KJC-TSK-0626). Every chunk runs concurrently; chunks
+ * run one after another. maxParallel 1 ⇒ singletons (fully sequential).
+ * Same conservative rules as husConflict: no parseable scope ⇒ runs alone.
+ *
+ * @param {Array<{id: string, scope?: string|null}>} stories - full story list
+ * @param {string[]} groupIds - ids of one dependency-level group, in order
+ * @param {number} maxParallel
+ * @returns {string[][]} chunks of ids
+ */
+export function partitionConflictFree(stories, groupIds, maxParallel = 1) {
+  if (maxParallel <= 1) return groupIds.map((id) => [id]);
+  const byId = new Map(stories.map((s) => [s.id, s]));
+  const chunks = [];
+  for (const id of groupIds) {
+    const story = byId.get(id) ?? { id };
+    const fit = chunks.find(
+      (chunk) => chunk.length < maxParallel && !chunk.some((otherId) => husConflict(story, byId.get(otherId) ?? { id: otherId })),
+    );
+    if (fit) fit.push(id);
+    else chunks.push([id]);
+  }
+  return chunks;
+}
+
+/**
+ * Select the next HUs to launch, order-preserving and greedy.
+ *
+ * @param {object} args
+ * @param {Array<{id: string, blocked_by?: string[], scope?: string|null}>} args.hus - candidates, in plan order
+ * @param {string[]} [args.completedIds] - HUs already done (dependency source)
+ * @param {Array<{id: string, scope?: string|null}>} [args.inFlight] - HUs currently running
+ * @param {number} [args.maxParallel] - total concurrency cap (in-flight included)
+ * @returns {{ selected: object[], blocked: Array<{id: string, reason: string}> }}
+ */
+export function selectRunnableHus({ hus = [], completedIds = [], inFlight = [], maxParallel = 1 } = {}) {
+  const done = new Set(completedIds);
+  const flying = new Set(inFlight.map((h) => h.id));
+  const slots = Math.max(0, maxParallel - inFlight.length);
+  const selected = [];
+  const blocked = [];
+
+  for (const hu of hus) {
+    if (flying.has(hu.id) || done.has(hu.id)) continue;
+    const missing = (hu.blocked_by || []).filter((dep) => !done.has(dep));
+    if (missing.length > 0) {
+      blocked.push({ id: hu.id, reason: `waiting for ${missing.join(", ")}` });
+      continue;
+    }
+    if (selected.length >= slots) {
+      blocked.push({ id: hu.id, reason: "no free slot" });
+      continue;
+    }
+    const rival = [...inFlight, ...selected].find((other) => husConflict(hu, other));
+    if (rival) {
+      blocked.push({ id: hu.id, reason: `scope conflicts with ${rival.id}` });
+      continue;
+    }
+    selected.push(hu);
+  }
+  return { selected, blocked };
+}

package/src/orchestrator/hu-sub-pipeline.js

@@ -7,6 +7,8 @@ import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/st
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
 import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
+import { partitionConflictFree } from "./hu-scheduler.js";
+import { createParallelLimiter, planBudgetUsd } from "./parallel-limiter.js";
 
 /**
  * Determine whether the HU reviewer result needs the sub-pipeline path.
@@ -459,15 +461,38 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
   // --- Group HUs into parallel batches ---
   const parallelBatches = findParallelGroups(certifiedStories, orderedIds);
 
-  for (const group of parallelBatches) {
+  // Governance (KJC-TSK-0626): the dependency groups above used to launch
+  // UNBOUNDED via Promise.all — a plan with N independent HUs ran N full
+  // pipelines at once, with no cap, no shared budget and no scope checks.
+  // Now each group is partitioned into conflict-free chunks of at most
+  // max_parallel_hus (default 1 = fully sequential, today's safe path) and
+  // a shared limiter gates every launch against the PLAN budget.
+  const maxParallel = Math.max(1, Number(config?.session?.max_parallel_hus ?? 1));
+  const limiter = createParallelLimiter({
+    maxParallel,
+    budgetTracker,
+    planBudgetUsd: planBudgetUsd({ maxBudgetUsd: config?.max_budget_usd, maxParallel }),
+  });
+  let stopReason = null;
+
+  outer: for (const group of parallelBatches) {
+    for (const chunk of partitionConflictFree(batch.stories, group, maxParallel)) {
     // Filter out HUs that were blocked by a failed dependency in a previous batch
-    const runnableIds = group.filter(id => {
+    const runnableIds = chunk.filter(id => {
       const story = batch.stories.find(s => s.id === id);
       return story && story.status !== HU_STATUS.BLOCKED;
     });
 
     if (runnableIds.length === 0) continue;
 
+    const blockReason = limiter.launchBlockReason();
+    if (blockReason) {
+      stopReason = blockReason;
+      allApproved = false;
+      logger.warn(`HU sub-pipeline stopped before launching ${runnableIds.join(", ")}: ${blockReason}`);
+      break outer;
+    }
+
     // Emit parallel batch start event
     emitProgress(emitter, makeEvent("hu:parallel-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
       message: `Starting parallel batch of ${runnableIds.length} HU(s): ${runnableIds.join(", ")}`,
@@ -511,14 +536,20 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
         }
       }
 
-      // Run all HUs in the batch concurrently
+      // Run all HUs in the batch concurrently, each holding a limiter slot
+      // (belt-and-braces: chunks are already ≤ maxParallel).
       const batchPromises = runnableIds.map(async (storyId) => {
-        return runSingleHu({
-          storyId, batch, batchSessionId, runIterationFn,
-          emitter, eventBase, logger, config, results,
-          worktreePath: worktrees.get(storyId),
-          onStatusChange, onOutcome, budgetTracker
-        });
+        await limiter.acquire();
+        try {
+          return await runSingleHu({
+            storyId, batch, batchSessionId, runIterationFn,
+            emitter, eventBase, logger, config, results,
+            worktreePath: worktrees.get(storyId),
+            onStatusChange, onOutcome, budgetTracker
+          });
+        } finally {
+          limiter.release();
+        }
       });
 
       const batchResults = await Promise.all(batchPromises);
@@ -554,7 +585,8 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
 
       await saveHuBatch(batchSessionId, batch);
     }
+    }
   }
 
-  return { approved: allApproved, results, blockedIds };
+  return { approved: allApproved, results, blockedIds, ...(stopReason ? { stopReason } : {}) };
 }

package/src/orchestrator/iteration-gate.js

@@ -0,0 +1,73 @@
+/**
+ * iteration-gate — opt-in per-iteration supervision (KJC-TSK-0628, épica
+ * KJC-PCS-0062). With `--step` (or session.iteration_gate in config) the
+ * pipeline pauses after EVERY iteration with a compact report — what
+ * happened, what the next iteration will do, spend vs cap — and asks the
+ * user: continue, stop, or continue WITH instructions. Free-text answers
+ * are appended to the reviewer feedback the coder reads next iteration
+ * (same channel Solomon's human guidance uses), never overwriting the
+ * reviewer's own must-fix list.
+ */
+
+import { markSessionStatus } from "../session/store.js";
+import { setReviewerFeedback } from "../session/mutators.js";
+
+const STOP_ANSWERS = new Set(["stop", "parar", "para", "no", "n", "4"]);
+const CONTINUE_ANSWERS = new Set(["", "s", "si", "sí", "y", "yes", "1", "continue", "continuar"]);
+
+/** Compact human report of the iteration that just finished. */
+export function buildIterationReport({ i, maxIterations, stageResults = {}, budgetTracker, maxBudgetUsd, reviewVerdict }) {
+  const lines = [`Iteration ${i}/${maxIterations} finished.`];
+  const stages = Object.keys(stageResults);
+  if (stages.length > 0) lines.push(`Stages so far: ${stages.join(", ")}`);
+
+  const review = reviewVerdict ?? stageResults.reviewer ?? null;
+  const mustFix = review?.must_fix ?? review?.issues ?? [];
+  if (review?.approved === true) {
+    lines.push("Reviewer: APPROVED");
+  } else if (mustFix.length > 0) {
+    const shown = mustFix.slice(0, 3).map((f) => `  • ${typeof f === "string" ? f : f.title || f.description || JSON.stringify(f)}`);
+    lines.push(`Reviewer: rejected with ${mustFix.length} must-fix:`, ...shown);
+    if (mustFix.length > 3) lines.push(`  … and ${mustFix.length - 3} more`);
+    lines.push(`Next iteration: the coder tackles those ${mustFix.length} must-fix.`);
+  } else {
+    lines.push("Next iteration: the coder retries against the pending feedback.");
+  }
+
+  const spent = budgetTracker?.total?.().cost_usd ?? 0;
+  const cap = maxBudgetUsd != null ? ` / cap $${Number(maxBudgetUsd).toFixed(2)}` : "";
+  lines.push(`Spend: $${spent.toFixed(2)}${cap}`);
+  return lines.join("\n");
+}
+
+/** Append a user directive without clobbering the reviewer's feedback. */
+export function appendUserDirective(session, text) {
+  const existing = session.last_reviewer_feedback || "";
+  const block = `## User directive (iteration gate)\n${text}`;
+  setReviewerFeedback(session, existing ? `${existing}\n\n${block}` : block);
+}
+
+/**
+ * Ask the user at the gate. Returns { action: "continue" | "stop",
+ * injected?: string }. Disabled gate, missing askQuestion (nobody to ask)
+ * or unattended autonomous runs pass straight through.
+ */
+export async function handleIterationGate({ enabled, askQuestion, session, logger, report }) {
+  if (!enabled || !askQuestion || askQuestion.unattended === true) return { action: "continue" };
+
+  const answer = await askQuestion(
+    `${report}\n\nContinue? [Enter = yes | "stop" = stop | anything else = instructions for the next iteration]`,
+  );
+  const trimmed = (answer || "").trim();
+  const lower = trimmed.toLowerCase();
+
+  if (STOP_ANSWERS.has(lower)) {
+    await markSessionStatus(session, "stopped");
+    return { action: "stop" };
+  }
+  if (CONTINUE_ANSWERS.has(lower)) return { action: "continue" };
+
+  appendUserDirective(session, trimmed);
+  logger?.info?.("Iteration gate: user directive injected for the next iteration.");
+  return { action: "continue", injected: trimmed };
+}

package/src/orchestrator/parallel-limiter.js

@@ -0,0 +1,74 @@
+/**
+ * parallel-limiter — shared concurrency coordinator for parallel HU
+ * execution (KJC-TSK-0624, épica KJC-PCS-0065). One instance per plan run,
+ * shared by every HU lane:
+ *
+ *   - Semaphore: at most maxParallel HUs hold a slot (acquire/release).
+ *   - Plan budget: the whole run shares ONE BudgetTracker; the launch gate
+ *     refuses new lanes once aggregated spend reaches the plan ceiling
+ *     (maxParallel × max_budget_usd — parallelism scales the cap, it never
+ *     multiplies it silently).
+ *   - Cooldown: when any lane hits a provider rate limit it calls
+ *     notifyCooldown(ms); NEW launches pause until it expires while lanes
+ *     already flying finish their work — parallel retry stampedes are the
+ *     fastest way to burn a quota.
+ */
+
+export function createParallelLimiter({ maxParallel = 1, budgetTracker = null, planBudgetUsd = null, now = Date.now } = {}) {
+  let inUse = 0;
+  let cooldownUntil = 0;
+  const waiters = [];
+
+  const overPlanBudget = () => {
+    if (planBudgetUsd == null || !budgetTracker) return false;
+    return (budgetTracker.total?.().cost_usd ?? 0) >= Number(planBudgetUsd);
+  };
+
+  const grantNext = () => {
+    while (waiters.length > 0 && inUse < maxParallel) {
+      inUse += 1;
+      waiters.shift()();
+    }
+  };
+
+  return {
+    /** Why a new lane may not launch right now; null = clear to go. */
+    launchBlockReason() {
+      if (overPlanBudget()) {
+        return `plan budget exhausted ($${(budgetTracker.total().cost_usd).toFixed(2)} ≥ $${Number(planBudgetUsd).toFixed(2)})`;
+      }
+      const waitMs = cooldownUntil - now();
+      if (waitMs > 0) return `provider cooldown for ${Math.ceil(waitMs / 1000)}s`;
+      return null;
+    },
+
+    /** Wait for a free slot. Resolves when this lane may run. */
+    acquire() {
+      if (inUse < maxParallel) {
+        inUse += 1;
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+
+    release() {
+      inUse = Math.max(0, inUse - 1);
+      grantNext();
+    },
+
+    /** A lane hit a rate limit: pause NEW launches until it expires. */
+    notifyCooldown(ms) {
+      cooldownUntil = Math.max(cooldownUntil, now() + Math.max(0, ms));
+    },
+
+    stats() {
+      return { inUse, waiting: waiters.length, maxParallel, cooldownUntil };
+    },
+  };
+}
+
+/** Plan-level ceiling: parallelism scales the per-run cap, explicitly. */
+export function planBudgetUsd({ maxBudgetUsd, maxParallel = 1 }) {
+  if (maxBudgetUsd == null) return null;
+  return Number(maxBudgetUsd) * Math.max(1, maxParallel);
+}

package/src/utils/async-lock.js

@@ -0,0 +1,31 @@
+/**
+ * async-lock — named in-process mutex (KJC-TSK-0625, épica KJC-PCS-0065).
+ * Parallel HU lanes run inside ONE kj process; shared single-instance
+ * resources (the SonarQube server scans one project key at a time) must
+ * serialize across lanes. `withLock` chains callers per name in FIFO
+ * order; sequential runs pay nothing (the chain is always settled).
+ */
+
+const locks = new Map(); // name -> { tail: Promise, holders: number }
+
+/** Run `fn` exclusively among every caller sharing `name`. */
+export async function withLock(name, fn) {
+  const entry = locks.get(name) ?? { tail: Promise.resolve(), holders: 0 };
+  entry.holders += 1;
+  locks.set(name, entry);
+
+  const previous = entry.tail;
+  let release;
+  entry.tail = new Promise((resolve) => {
+    release = resolve;
+  });
+
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    entry.holders -= 1;
+    if (entry.holders === 0) locks.delete(name);
+  }
+}

package/templates/kj.config.yml

@@ -114,5 +114,7 @@ output:
 session:
   max_iteration_minutes: 15
   max_total_minutes: 120
-  max_budget_usd: null
+  # Hard per-run spend ceiling (USD-equivalent). The run stops with a summary
+  # when exceeded; resume with `kj resume`. Set to null to remove the cap.
+  max_budget_usd: 5
   fail_fast_repeats: 2