karajan-code 3.14.0 → 3.15.0

package/README.md

@@ -383,6 +383,16 @@ Each AI role is executed by the agent you choose:
 >
 > Full per-stage reference: [Pipeline roles](https://karajan-code.web.app/docs/handbook/pipeline-roles/) (handbook).
 
+## Step mode and parallel lanes (v3.14+)
+
+Two ways to control how a plan executes:
+
+**`kj run --step`** — supervise the orchestra iteration by iteration. After every iteration the pipeline pauses with a compact report (what happened, the reviewer's must-fix list, what the next iteration will do, spend vs cap) and asks: press Enter to continue, type `stop` to halt (resumable with `kj resume`), or **type instructions** — free text is injected into the feedback the coder reads next iteration, without clobbering the reviewer's own findings. Also offered as a question in the `kj init` wizard (`session.iteration_gate`).
+
+**`kj run --plan <id> --parallel <n>`** — run a plan's independent HUs concurrently, each in its own **git worktree** under `.kj/worktrees/<huId>` on branch `kj-hu-<huId>`. The scheduler walks the `blocked_by` graph and only pairs HUs with disjoint `scope` paths (scopeless HUs run alone); the whole lane — coder, acceptance tests, diffs, sonar, final commit — runs inside its worktree while the main working tree stays parked. Governance is built in: default is `1` (fully sequential), a plan-level budget ceiling (`n × max_budget_usd`) stops the batch loudly when exhausted, and SonarQube serializes across lanes. Each fresh worktree is bootstrapped automatically (submodules + `npm ci`, or your `session.worktree_setup` command) and receives `KJ_LANE_SLOT` / `KJ_PORT_OFFSET` env vars so services started by tests don't collide on ports.
+
+Full guide: [`docs/parallel-hus.md`](docs/parallel-hus.md).
+
 ## 5 AI agents supported
 
 | Agent | CLI | Install |

package/package.json

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

package/packages/hu-board/src/routes/api.js

@@ -76,7 +76,9 @@ router.get('/version', (_req, res) => {
  */
 router.get('/standby', async (_req, res) => {
   try {
-    const { listPendingStandby } = await import('../../../../src/brain/standby-store.js');
+    // KJC-TSK-0632: resolve from karajan-core directly — the CLI's
+    // src/brain/standby-store.js is just a re-export shim of this.
+    const { listPendingStandby } = await import('karajan-core/standby-store');
     const sessions = listPendingStandby();
     res.set('Cache-Control', 'no-store');
     res.json({ sessions });
@@ -1362,8 +1364,10 @@ router.post('/rag/query', async (req, res) => {
   }
   try {
     const { openVecStore, countChunks } = await import('karajan-core/vec-store');
-    const { makeEmbedder } = await import('../../../../src/rag/embedders/factory.js');
-    const { query } = await import('../../../../src/rag/retriever.js');
+    // KJC-TSK-0632: resolved from karajan-core — the board carries zero
+    // relative imports into the CLI src tree (see no-cli-imports test).
+    const { makeEmbedder } = await import('karajan-core/rag/embedders/factory');
+    const { query } = await import('karajan-core/rag/retriever');
     const db = openVecStore({ dim: 768 });
     try {
       if (countChunks(db) === 0) return res.json({ hits: [], empty: true, topK, scope });

package/scripts/verify-pack.mjs

@@ -166,7 +166,11 @@ try {
     console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
     // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
     // scripts by default) — expected here, so don't treat the exit as failure.
-    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store")], {
+    // minimum-release-age=0: modern pnpm quarantines freshly published
+    // versions (supply-chain protection), so right after publishing
+    // karajan-core it silently resolves an OLD one and this smoke fails on
+    // missing subpaths. The gate verifies packaging, not release-age policy.
+    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store"), "--config.minimum-release-age=0"], {
       encoding: "utf8",
       env: childEnv,
       cwd: pnpmTmp,

package/src/agents/claude-agent.js

@@ -300,7 +300,10 @@ export function createStreamJsonFilter(onOutput) {
  */
 function cleanExecaOpts(extra = {}) {
   const { CLAUDECODE: _CLAUDECODE, ...env } = process.env;
-  return { env, stdin: "ignore", ...extra };
+  // PAR-H (KJC-TSK-0631): extra.env ADDS to the inherited env (lane slot
+  // vars) instead of replacing it wholesale.
+  const { env: extraEnv, ...rest } = extra;
+  return { env: extraEnv ? { ...env, ...extraEnv } : env, stdin: "ignore", ...rest };
 }
 
 /**
@@ -370,7 +373,8 @@ export class ClaudeAgent extends BaseAgent {
       const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
         onOutput: streamFilter,
         silenceTimeoutMs: task.silenceTimeoutMs,
-        timeout: task.timeoutMs
+        timeout: task.timeoutMs,
+        env: task.env
       }));
       const raw = pickOutput(res);
       const output = extractTextFromStreamJson(raw);
@@ -380,7 +384,7 @@ export class ClaudeAgent extends BaseAgent {
 
     // Without streaming, use json output to get structured response via stderr
     args.push("--output-format", "json");
-    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts());
+    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({ env: task.env }));
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
     const usage = extractUsageFromStreamJson(raw);
@@ -393,7 +397,8 @@ export class ClaudeAgent extends BaseAgent {
     const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
-      timeout: task.timeoutMs
+      timeout: task.timeoutMs,
+      env: task.env
     }));
     const raw = pickOutput(res);
     const usage = extractUsageFromStreamJson(raw);

package/src/agents/model-registry.js

@@ -108,6 +108,29 @@ registerModelAlias("gemini", "gemini-2.5-pro");
 registerModel("aider", { provider: "aider", pricing: { input_per_million: 3, output_per_million: 15 } });
 registerModel("opencode", { provider: "opencode", pricing: { input_per_million: 0, output_per_million: 0 } });
 
+/**
+ * Moonshot Kimi Family (KJC-TSK-0633) — consumed through OpenCode as an
+ * OpenAI-compatible provider (docs/providers-via-opencode.md).
+ * Pricing: https://platform.moonshot.ai/docs/pricing — verify before
+ * trusting for billing decisions; ids/prices move fast.
+ */
+registerModel("kimi-k2", { provider: "moonshot", pricing: { input_per_million: 0.6, output_per_million: 2.5 } });
+registerModel("kimi-k2-thinking", { provider: "moonshot", pricing: { input_per_million: 0.6, output_per_million: 2.5 } });
+registerModelAlias("kimi", "kimi-k2");
+// Prefixed ids as the documented opencode.json snippet produces them.
+registerModelAlias("kimi/kimi-k2", "kimi-k2");
+registerModelAlias("kimi/kimi-k2-thinking", "kimi-k2-thinking");
+
+/**
+ * DeepSeek Family (KJC-TSK-0633) — same OpenCode route.
+ * Pricing: https://api-docs.deepseek.com/quick_start/pricing
+ */
+registerModel("deepseek-chat", { provider: "deepseek", pricing: { input_per_million: 0.28, output_per_million: 0.42 } });
+registerModel("deepseek-reasoner", { provider: "deepseek", pricing: { input_per_million: 0.28, output_per_million: 0.42 } });
+registerModelAlias("deepseek", "deepseek-chat");
+registerModelAlias("deepseek/deepseek-chat", "deepseek-chat");
+registerModelAlias("deepseek/deepseek-reasoner", "deepseek-reasoner");
+
 // Common CLI Aliases (with provider overrides)
 registerModelAlias("aider/claude-3-7-sonnet", "claude-sonnet-4.6", { provider: "aider" });
 registerModelAlias("aider/gpt-4o", "gpt-5.4-standard", { provider: "aider" });

package/src/config/defaults.js

@@ -182,6 +182,10 @@ const DEFAULTS = {
     // 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,
+    // Command run inside each fresh lane worktree before the coder starts
+    // (KJC-TSK-0630). null = auto-detect: `npm ci` when package-lock.json
+    // exists, nothing otherwise. Submodules are always initialized first.
+    worktree_setup: null,
     max_iteration_minutes: 30,
     max_total_minutes: 120,
     max_planner_minutes: 60,

package/src/git/hu-automation.js

@@ -113,11 +113,11 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
  * @param {object} params.logger
  * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null}>}
  */
-export async function finalizeHuCommit({ story, branchName, config, logger }) {
+export async function finalizeHuCommit({ story, branchName, config, logger, cwd = null }) {
   const result = { committed: false, pushed: false, prUrl: null };
   if (!branchName) return result;
 
-  const changed = await hasChanges();
+  const changed = await hasChanges(cwd);
   if (!changed) {
     logger.info(`HU ${story.id}: no changes to commit`);
     return result;
@@ -126,7 +126,7 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
   const title = story.title || story.id;
   const commitMsg = `feat(${story.id}): ${title}`;
   if (config.git?.auto_commit) {
-    const commitRes = await commitAll(commitMsg);
+    const commitRes = await commitAll(commitMsg, cwd);
     if (commitRes) {
       result.committed = true;
       logger.info(`HU ${story.id}: committed on '${branchName}'`);
@@ -135,7 +135,7 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
 
   if (config.git?.auto_push && result.committed) {
     try {
-      await pushBranch(branchName);
+      await pushBranch(branchName, cwd);
       result.pushed = true;
       logger.info(`HU ${story.id}: pushed '${branchName}'`);
     } catch (err) {
@@ -157,7 +157,8 @@ export async function finalizeHuCommit({ story, branchName, config, logger }) {
         baseBranch: config.base_branch || "main",
         branch: branchName,
         title: commitMsg,
-        body: prBody
+        body: prBody,
+        cwd
       });
       result.prUrl = url;
       logger.info(`HU ${story.id}: PR created ${url}`);

package/src/hu/acceptance-runner.js

@@ -12,11 +12,15 @@ import { runCommand } from "../utils/process.js";
  * @param {number} [timeoutMs=30000] - Timeout per test
  * @returns {Promise<{cmd: string, passed: boolean, output: string, exitCode: number}>}
  */
-async function runSingleTest(cmd, cwd, timeoutMs = 30000) {
+async function runSingleTest(cmd, cwd, timeoutMs = 30000, env = null) {
   try {
     const result = await runCommand("bash", ["-c", cmd], {
       timeout: timeoutMs,
-      cwd
+      cwd,
+      // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET) so
+      // tests that start services can offset their ports. execa merges
+      // this on top of process.env.
+      ...(env ? { env } : {})
     });
     const output = (result.stdout || "") + (result.stderr || "");
     return {
@@ -51,7 +55,7 @@ async function runSingleTest(cmd, cwd, timeoutMs = 30000) {
  * @param {string} cwd - Working directory
  * @returns {Promise<{allPassed: boolean, results: object[], summary: string, diagnostics: string|null, pending: number}>}
  */
-export async function runAcceptanceTests(tests, cwd) {
+export async function runAcceptanceTests(tests, cwd, { env = null } = {}) {
   if (!tests || tests.length === 0) {
     return { allPassed: false, results: [], summary: "No acceptance tests defined", diagnostics: null, pending: 0 };
   }
@@ -86,7 +90,7 @@ export async function runAcceptanceTests(tests, cwd) {
       });
       continue;
     }
-    const result = await runSingleTest(cmd, cwd);
+    const result = await runSingleTest(cmd, cwd, 30000, env);
     results.push({ ...result, type: "shell" });
   }
 

package/src/hu/worktree-bootstrap.js

@@ -0,0 +1,59 @@
+/**
+ * PAR-G (KJC-TSK-0630): make a freshly created lane worktree operative.
+ *
+ * `git worktree add` produces a clean checkout: no node_modules, no
+ * initialized submodules — and a container/bind-mounted process cannot
+ * init them itself because the worktree's real .git lives in the parent
+ * repo (gotcha reported by Jorge del Casar's worktree-docker-envs skill).
+ * Without this step, --parallel lanes die on the first `npm test` in any
+ * real project.
+ *
+ * Best-effort by contract: a failed or slow bootstrap warns and the lane
+ * continues — the acceptance tests deliver the real verdict.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+const STEP_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * @param {object} params
+ * @param {string} params.worktreePath  Absolute path of the lane worktree.
+ * @param {string|null} [params.setupCommand]  session.worktree_setup — wins over auto-detect.
+ * @param {object|null} [params.logger]
+ * @param {number} [params.timeoutMs]
+ * @param {Function} [params.run]  Injectable runner (tests).
+ * @returns {Promise<{ok: boolean, steps: string[], warnings: string[]}>}
+ */
+export async function bootstrapWorktree({ worktreePath, setupCommand = null, logger = null, timeoutMs = STEP_TIMEOUT_MS, run = runCommand }) {
+  const warnings = [];
+  const steps = [];
+
+  if (existsSync(join(worktreePath, ".gitmodules"))) {
+    steps.push({ name: "submodules", cmd: "git", args: ["submodule", "update", "--init", "--recursive"] });
+  }
+
+  const explicit = typeof setupCommand === "string" && setupCommand.trim() ? setupCommand.trim() : null;
+  if (explicit) {
+    steps.push({ name: "setup", cmd: "sh", args: ["-c", explicit] });
+  } else if (existsSync(join(worktreePath, "package-lock.json"))) {
+    steps.push({ name: "deps", cmd: "npm", args: ["ci", "--no-audit", "--no-fund"] });
+  }
+
+  for (const step of steps) {
+    try {
+      const res = await run(step.cmd, step.args, { cwd: worktreePath, timeout: timeoutMs });
+      if (res.exitCode !== 0) {
+        warnings.push(`${step.name} failed (exit ${res.exitCode}): ${String(res.stderr || res.stdout || "").slice(0, 200)}`);
+      } else {
+        logger?.info?.(`worktree bootstrap: ${step.name} ok`);
+      }
+    } catch (err) {
+      warnings.push(`${step.name} threw: ${err.message}`);
+    }
+  }
+
+  for (const w of warnings) logger?.warn?.(`worktree bootstrap: ${w} — lane continues`);
+  return { ok: warnings.length === 0, steps: steps.map((s) => s.name), warnings };
+}

package/src/orchestrator/drivers/iteration-phases/guards.js

@@ -28,7 +28,7 @@ export async function runGuardStages({ config, logger, emitter, eventBase, sessi
   let diff;
   try {
     const baseRef = await computeBaseRef({ baseBranch });
-    diff = await generateDiff({ baseRef });
+    diff = await generateDiff({ baseRef, projectDir: config?.projectDir || null });
   } catch {
     logger.warn("Guards: could not generate diff, skipping");
     return { action: "ok" };

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

@@ -77,7 +77,7 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   }
 
   if (pipelineFlags?.impeccableEnabled) {
-    const diff = await generateDiff({ baseRef: session.session_start_sha });
+    const diff = await generateDiff({ baseRef: session.session_start_sha, projectDir: config?.projectDir || null });
     const impeccableMode = pipelineFlags?.impeccableMode || "audit";
     const impeccableResult = await runImpeccableStage({
       config, logger, emitter, eventBase, session, coderRole, trackBudget,

package/src/orchestrator/drivers/run-hu-batch.js

@@ -55,7 +55,6 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   }));
 
   // Per-HU pipeline: focused max_iterations, fresh Brain state, own git branch.
-  const originalMaxIterations = ctx.config.max_iterations;
   const huMaxIterations = ctx.config.hu_max_iterations ?? 3;
   const huBranches = new Map();
   const { prepareHuBranch, finalizeHuCommit } = await import("../../git/hu-automation.js");
@@ -83,15 +82,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
 
   const subPipelineResult = await runHuSubPipeline({
     huReviewerResult: ctx.stageResults.huReviewer,
-    runIterationFn: async (huTask, story) => {
-      ctx.config.max_iterations = huMaxIterations;
-      if (ctx.brainCtx?.enabled) {
-        ctx.brainCtx.extensionCount = 0;
-        const { createBrainContext } = await import("../brain-coordinator.js");
-        const fresh = createBrainContext({ enabled: true });
-        ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
-        ctx.brainCtx.verificationTracker = fresh.verificationTracker;
-      }
+    runIterationFn: async (huTask, story, laneOpts = {}) => {
       // Apply per-HU policies based on task_type (infra skips reviewer/sonar/tdd).
       // KJC-TSK-0400: `effectiveTaskType` mira primero story.task_type y, si
       // no es válido, infiere del prefijo del title ([SPIKE], [DOC]…). Así
@@ -103,15 +94,56 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         logger.info(`HU ${story.id}: task_type inferido del title → ${resolvedTaskType} (era ${story.task_type || "null"})`);
       }
       const huPolicies = applyPolicies({ taskType: resolvedTaskType, policies: ctx.config.policies });
-      const savedFlags = { ...ctx.pipelineFlags };
-      if (!huPolicies.reviewer) ctx.pipelineFlags.reviewerEnabled = false;
-      if (!huPolicies.tdd) ctx.config.development = { ...ctx.config.development, methodology: "standard", require_test_changes: false };
-      if (!huPolicies.sonar) ctx.config.sonarqube = { ...ctx.config.sonarqube, enabled: false };
-      if (!huPolicies.testsRequired) ctx.pipelineFlags.testerEnabled = false;
       logger.info(`HU ${story.id} (${resolvedTaskType}): policies → reviewer=${huPolicies.reviewer}, tdd=${huPolicies.tdd}, sonar=${huPolicies.sonar}, tests=${huPolicies.testsRequired}`);
 
-      const branchName = await prepareHuBranch({ story, huBranches, config: ctx.config, logger });
-      const projectDir = ctx.config.projectDir || process.cwd();
+      // PAR-E2 PR2 (KJC-TSK-0629): every per-HU adjustment lands on LANE
+      // copies. ctx.config/pipelineFlags/session/brainCtx are shared by all
+      // lanes, so concurrent lanes must never mutate them. This also fixes a
+      // latent leak: max_iterations was mutated on ctx.config and only the
+      // fallback path restored it — the acceptance path returned early and
+      // left it clamped to hu_max_iterations for the rest of the run.
+      const worktreePath = laneOpts?.worktreePath || null;
+      const projectDir = worktreePath || ctx.config.projectDir || process.cwd();
+      // PAR-H (KJC-TSK-0631): the lane's slot travels as env vars so any
+      // service the coder or the acceptance tests start can offset its
+      // ports (offset = slot × 100; the project applies its own base).
+      const laneEnv = Number.isInteger(laneOpts?.laneSlot)
+        ? { KJ_LANE_SLOT: String(laneOpts.laneSlot), KJ_PORT_OFFSET: String(laneOpts.laneSlot * 100) }
+        : null;
+      const laneConfig = { ...ctx.config, projectDir, max_iterations: huMaxIterations, lane_env: laneEnv };
+      if (!huPolicies.tdd) laneConfig.development = { ...laneConfig.development, methodology: "standard", require_test_changes: false };
+      if (!huPolicies.sonar) laneConfig.sonarqube = { ...laneConfig.sonarqube, enabled: false };
+      const laneFlags = { ...ctx.pipelineFlags };
+      if (!huPolicies.reviewer) laneFlags.reviewerEnabled = false;
+      if (!huPolicies.testsRequired) laneFlags.testerEnabled = false;
+      // Worktree lanes clone the session so reviewer feedback never leaks
+      // across concurrent HUs. Disk saves still share the session id (last
+      // writer wins) — journal noise at most; in-memory isolation is what
+      // guards correctness.
+      const laneSession = worktreePath ? { ...ctx.session } : ctx.session;
+      let laneBrain = ctx.brainCtx;
+      if (ctx.brainCtx?.enabled) {
+        const { createBrainContext } = await import("../brain-coordinator.js");
+        const fresh = createBrainContext({ enabled: true });
+        if (worktreePath) {
+          laneBrain = { ...ctx.brainCtx, extensionCount: 0, feedbackQueue: fresh.feedbackQueue, verificationTracker: fresh.verificationTracker };
+        } else {
+          ctx.brainCtx.extensionCount = 0;
+          ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
+          ctx.brainCtx.verificationTracker = fresh.verificationTracker;
+        }
+      }
+      let lanePlannedTask = ctx.plannedTask;
+
+      // A worktree lane skips the main-tree checkout: `git worktree add -b`
+      // already left the worktree checked out on kj-hu-<id>.
+      let branchName;
+      if (worktreePath) {
+        branchName = `kj-hu-${story.id}`;
+        huBranches.set(story.id, branchName);
+      } else {
+        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger });
+      }
 
       // KJC-TSK-0408 step 2: snapshot del workspace ANTES de invocar al
       // coder. Si el usuario hace Undo después, restaura este SHA. El
@@ -142,11 +174,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         // iterations against an irreparable test (the 2026-04-29 bug).
         const failureTracker = createFailureTracker();
 
-        for (let attempt = 1; attempt <= ctx.config.max_iterations; attempt++) {
-          logger.info(`HU ${story.id}: coder iteration ${attempt}/${ctx.config.max_iterations}`);
+        for (let attempt = 1; attempt <= laneConfig.max_iterations; attempt++) {
+          logger.info(`HU ${story.id}: coder iteration ${attempt}/${laneConfig.max_iterations}`);
           emitProgress(emitter, makeEvent("iteration:start", { ...ctx.eventBase, stage: "iteration" }, {
-            message: `Iteration ${attempt}/${ctx.config.max_iterations}`,
-            detail: { iteration: attempt, maxIterations: ctx.config.max_iterations }
+            message: `Iteration ${attempt}/${laneConfig.max_iterations}`,
+            detail: { iteration: attempt, maxIterations: laneConfig.max_iterations }
           }));
 
           // Coder runs with the HU task + any diagnostic feedback from previous attempt.
@@ -155,9 +187,9 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           // not only after the first failed run.
           const coderResult = await runCoderStage({
             coderRoleInstance: ctx.coderRoleInstance, coderRole: ctx.coderRole,
-            config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-            session: ctx.session, plannedTask: ctx.plannedTask,
-            trackBudget: ctx.trackBudget, iteration: attempt, brainCtx: ctx.brainCtx,
+            config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+            session: laneSession, plannedTask: lanePlannedTask,
+            trackBudget: ctx.trackBudget, iteration: attempt, brainCtx: laneBrain,
             acceptanceTests: story.acceptance_tests,
             // PR F (v2.7.5): plan-aware coder context. ADRs are
             // shared across the plan, the rest are scoped to this
@@ -173,11 +205,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           }
 
           // Sonar quality gate (sw task_type only, when policies say sonar=true)
-          if (huPolicies.sonar && ctx.config.sonarqube?.enabled) {
+          if (huPolicies.sonar && laneConfig.sonarqube?.enabled) {
             try {
               const sonarResult = await runSonarStage({
-                config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-                session: ctx.session, trackBudget: ctx.trackBudget, iteration: attempt,
+                config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+                session: laneSession, trackBudget: ctx.trackBudget, iteration: attempt,
                 // sonarState is required: runSonarStage reads/writes
                 // .issuesInitial / .issuesFinal on it. Forgetting this
                 // surfaces as `Cannot read properties of undefined
@@ -188,11 +220,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
                 sonarState: ctx.sonarState,
                 repeatDetector: ctx.repeatDetector,
                 budgetSummary: ctx.budgetSummary,
-                askQuestion, brainCtx: ctx.brainCtx
+                askQuestion, brainCtx: laneBrain
               });
               if (sonarResult?.action === "continue") {
                 // Sonar failed — add to feedback for next coder attempt
-                ctx.plannedTask = `${huTask}\n\n--- SONAR FAILURE ---\n${ctx.session.last_reviewer_feedback}`;
+                lanePlannedTask = `${huTask}\n\n--- SONAR FAILURE ---\n${laneSession.last_reviewer_feedback}`;
                 continue;
               }
             } catch (err) {
@@ -207,7 +239,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             detail: { huId: story.id, testCount: story.acceptance_tests.length }
           }));
 
-          const testResult = await runAcceptanceTests(story.acceptance_tests, projectDir);
+          const testResult = await runAcceptanceTests(story.acceptance_tests, projectDir, { env: laneEnv });
           emitProgress(emitter, makeEvent("hu:acceptance-end", { ...ctx.eventBase, stage: "acceptance" }, {
             status: testResult.allPassed ? "ok" : "fail",
             message: testResult.summary,
@@ -225,8 +257,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             );
             if (pendingGherkinTests.length === 0) {
               logger.info(`HU ${story.id}: all shell acceptance tests PASSED, no Gherkin to translate — approved`);
-              await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-              return { approved: true, sessionId: ctx.session.id, reason: "acceptance_tests_passed" };
+              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
             }
 
             // Shell tests passed; Gherkin needs translation. Invoke the
@@ -236,16 +268,16 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             const { runTesterStage } = await import("../post-loop-stages.js");
             const shellResults = testResult.results.filter((r) => r.type !== "gherkin");
             const testerOutcome = await runTesterStage({
-              config: ctx.config, logger, emitter, eventBase: ctx.eventBase,
-              session: ctx.session, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
+              config: laneConfig, logger, emitter, eventBase: ctx.eventBase,
+              session: laneSession, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
               iteration: attempt, task: huTask, diff: null, askQuestion,
               pendingGherkinTests, shellTestResults: shellResults,
             });
             const testerStage = testerOutcome?.stageResult;
             if (testerOutcome?.action !== "continue" && testerStage?.verdict === "pass") {
               logger.info(`HU ${story.id}: tester translated Gherkin and verdict=pass — approved`);
-              await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-              return { approved: true, sessionId: ctx.session.id, reason: "acceptance_tests_passed" };
+              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
             }
 
             // Tester rejected (translated tests failed or coverage
@@ -259,8 +291,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
               "Fix the implementation so every scenario passes. Do NOT soften the scenarios.",
             ].filter(Boolean).join("\n");
             logger.warn(`HU ${story.id}: tester verdict=fail after Gherkin translation — sending back to coder`);
-            setReviewerFeedback(ctx.session, diagnostic);
-            ctx.plannedTask = `${huTask}\n\n--- GHERKIN TRANSLATION FAILURES ---\n${diagnostic}`;
+            setReviewerFeedback(laneSession, diagnostic);
+            lanePlannedTask = `${huTask}\n\n--- GHERKIN TRANSLATION FAILURES ---\n${diagnostic}`;
             continue;
           }
 
@@ -314,7 +346,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
 
           if (repairEscalate) {
             logger.warn(`HU ${story.id}: Repairer escalated — ${repairEscalate}`);
-            return { approved: false, sessionId: ctx.session.id, reason: "repair_escalated" };
+            return { approved: false, sessionId: laneSession.id, reason: "repair_escalated" };
           }
           if (repairedAny) {
             // Tests were rewritten — restart iteration with the fixed
@@ -328,26 +360,24 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
           // No repair happened — normal coder feedback path.
           const diagnostic = buildDiagnosticPrompt(failed);
           logger.warn(`HU ${story.id}: ${failed.length} acceptance test(s) FAILED — sending diagnostic to coder`);
-          setReviewerFeedback(ctx.session, diagnostic);
-          ctx.plannedTask = `${huTask}\n\n--- ACCEPTANCE TEST FAILURES ---\n${diagnostic}`;
+          setReviewerFeedback(laneSession, diagnostic);
+          lanePlannedTask = `${huTask}\n\n--- ACCEPTANCE TEST FAILURES ---\n${diagnostic}`;
         }
 
         // All iterations exhausted
         logger.warn(`HU ${story.id}: max iterations reached with acceptance tests still failing`);
-        return { approved: false, sessionId: ctx.session.id, reason: "acceptance_tests_failed" };
+        return { approved: false, sessionId: laneSession.id, reason: "acceptance_tests_failed" };
       }
 
-      // Fallback: no acceptance_tests → standard pipeline (reviewer/tester)
-      try {
-        const result = await runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger });
-        if (result?.approved) {
-          await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
-        }
-        return result;
-      } finally {
-        ctx.config.max_iterations = originalMaxIterations;
-        Object.assign(ctx.pipelineFlags, savedFlags);
+      // Fallback: no acceptance_tests → standard pipeline (reviewer/tester).
+      // The loop reads everything through ctx.* — handing it a lane view
+      // keeps the shared ctx untouched (no more mutate-and-restore dance).
+      const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask };
+      const result = await runIterationLoop(laneCtx, { task: huTask, askQuestion, emitter, logger });
+      if (result?.approved) {
+        await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
       }
+      return result;
     },
     emitter,
     eventBase: ctx.eventBase,

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

@@ -6,7 +6,11 @@ import { topologicalSort } from "../hu/graph.js";
 import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
+import { join } from "node:path";
+import { acquireSlot, releaseSlot } from "karajan-core/slot-registry";
+import { getKarajanHome } from "karajan-core/paths";
 import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
+import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
 import { partitionConflictFree } from "./hu-scheduler.js";
 import { createParallelLimiter, planBudgetUsd } from "./parallel-limiter.js";
 
@@ -200,7 +204,7 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
  * @param {object} params
  * @returns {Promise<{huId: string, approved: boolean, result?: object, error?: string, blockedDependents?: string[]}>}
  */
-async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
+async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, laneSlot = null, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
   // PR1 (live HU status): every saveHuBatch should also notify the
   // plan JSON so the board reflects state in real time. Defined as a
   // local helper so we don't repeat the try/null-check boilerplate.
@@ -285,7 +289,9 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
   }));
 
   try {
-    const iterResult = await runIterationFn(huTask, story);
+    // PAR-E2 (KJC-TSK-0629): lanes handed a worktree must aim every git and
+    // filesystem touchpoint at it — laneOpts carries that path to the runner.
+    const iterResult = await runIterationFn(huTask, story, { worktreePath: worktreePath || null, laneSlot });
     const approved = Boolean(iterResult?.approved);
 
     // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---
@@ -525,12 +531,27 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
       // Multiple HUs: create worktrees, run in parallel
       const projectDir = config?.projectDir || process.cwd();
       const worktrees = new Map();
+      // PAR-H (KJC-TSK-0631): every lane gets a stable numeric slot so
+      // services it starts can offset their ports (KJ_LANE_SLOT /
+      // KJ_PORT_OFFSET reach the coder and the acceptance tests).
+      const slotRegistryPath = join(getKarajanHome(), "worktree-slots.json");
+      const laneSlots = new Map();
 
       // Create worktrees for each HU in the batch
       for (const id of runnableIds) {
         try {
           const wtPath = await createWorktree(projectDir, id);
           worktrees.set(id, wtPath);
+          // PAR-G (KJC-TSK-0630): a fresh worktree has no node_modules and
+          // no initialized submodules — make the lane operative before the
+          // coder lands. Best-effort: warnings never block the lane.
+          await bootstrapWorktree({ worktreePath: wtPath, setupCommand: config?.session?.worktree_setup || null, logger });
+          try {
+            const { slot } = await acquireSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${id}` });
+            laneSlots.set(id, slot);
+          } catch (err) {
+            logger.warn(`Failed to acquire lane slot for HU ${id}: ${err.message} — lane runs without port offset`);
+          }
         } catch (err) {
           logger.warn(`Failed to create worktree for HU ${id}: ${err.message} — will run sequentially`);
         }
@@ -545,6 +566,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
             storyId, batch, batchSessionId, runIterationFn,
             emitter, eventBase, logger, config, results,
             worktreePath: worktrees.get(storyId),
+            laneSlot: laneSlots.get(storyId) ?? null,
             onStatusChange, onOutcome, budgetTracker
           });
         } finally {
@@ -560,6 +582,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
         if (res.approved && worktrees.has(res.huId)) {
           try {
             await mergeWorktree(projectDir, res.huId);
+            await releaseSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${res.huId}` }).catch(() => {});
           } catch (err) {
             logger.warn(`Failed to merge worktree for HU ${res.huId}: ${err.message}`);
           }
@@ -579,6 +602,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
           // Clean up failed worktree
           if (worktrees.has(res.huId)) {
             try { await removeWorktree(projectDir, res.huId); } catch { /* ignore */ }
+            await releaseSlot({ registryPath: slotRegistryPath, id: `${projectDir}::${res.huId}` }).catch(() => {});
           }
         }
       }