karajan-code 4.70.4 → 5.0.1

package/src/hu/lanes.js

@@ -0,0 +1,66 @@
+/**
+ * KJC-TSK-1313: which card each worktree lane works on. Read from git every time, never stored on
+ * the card, so a lane removed by hand never lingers on the board.
+ */
+import path from "node:path";
+
+/**
+ * The worktrees with a branch in `git worktree list --porcelain`. The first entry is the main
+ * checkout and is left out, as are detached worktrees. With `root`, only the lanes under it.
+ * @returns {{slug: string, branch: string, path: string}[]}
+ */
+export function parseLanes(porcelain, { root = null } = {}) {
+  const lanes = [];
+  let current = null;
+  let seen = 0;
+  for (const line of porcelain.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      current = seen++ === 0 ? null : { path: line.slice(9).trim() };
+    } else if (line.startsWith("branch ") && current) {
+      lanes.push({ slug: path.basename(current.path), branch: line.slice(7).trim().replace(/^refs\/heads\//, ""), path: current.path });
+    }
+  }
+  return root ? lanes.filter((l) => l.path.startsWith(root + path.sep)) : lanes;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+/**
+ * The lanes of each card: those whose branch carries the card id as a whole token (so HU-2 never
+ * claims HU-27). Cards without a lane have no entry.
+ * @returns {Map<string, {slug: string, branch: string, path: string}[]>}
+ */
+export function lanesByCard(lanes, cardIds) {
+  const byCard = new Map();
+  for (const id of new Set(cardIds)) {
+    const token = new RegExp(`(^|[^a-z0-9])${escapeRe(id)}($|[^a-z0-9])`, "i");
+    const hits = lanes.filter((l) => token.test(l.branch));
+    if (hits.length > 0) byCard.set(id, hits);
+  }
+  return byCard;
+}
+
+/**
+ * The cards a lane works on: those whose id or any of whose references (a tracker card, an
+ * issue) its branch names. `cards` are `{id, refs}`.
+ * @returns {string[]}
+ */
+/**
+ * KJC-TSK-1316: one PR per branch from `gh pr list --json number,url,state,headRefName`: an open
+ * one wins, else the newest (a merged lane is what KJC-TSK-1314 warns about).
+ * @returns {Map<string, {number: number, url: string, state: string}>}
+ */
+export function prsByBranch(prs) {
+  const byBranch = new Map();
+  const open = (p) => (p.state === "OPEN" ? 1 : 0);
+  for (const p of prs) {
+    const cur = byBranch.get(p.headRefName);
+    if (!cur || open(p) > open(cur) || (open(p) === open(cur) && p.number > cur.number)) {
+      byBranch.set(p.headRefName, { number: p.number, url: p.url, state: p.state });
+    }
+  }
+  return byBranch;
+}
+
+export const cardsOfLane = (lane, cards) =>
+  cards.filter((c) => lanesByCard([lane], [c.id, ...c.refs]).size > 0).map((c) => c.id);

package/src/hu/team-board-mirror.js

@@ -19,10 +19,11 @@ export async function writeTeamMirror(projectDir, rows, { repo }) {
   const plan = {
     version: 2, planId: MIRROR_PLAN_ID, name: "github", alias: "github", projectDir,
     task: `Shared HU Board: GitHub Issues of ${repo}`,
-    status: "ready", readonly: "github", createdAt: now,
+    status: "ready", readonly: "github", repo, createdAt: now,
     hus: rows.map((r) => ({
       id: r.short_id, short_id: r.short_id, title: r.title, status: r.status,
-      claimed_by: r.claimed_by ?? null, created_by: "github", external_ref: `${repo}#${r.number}`,
+      // KJC-BUG-0443: the tracker card it replicates too, so the gates find it by that reference.
+      claimed_by: r.claimed_by ?? null, created_by: "github", external_ref: [`${repo}#${r.number}`, r.ref].filter(Boolean).join(" · "),
       acceptance_criteria: [], acceptance_tests: [], createdAt: now, updatedAt: now,
     })),
   };

package/src/infrastructure/command-runner.js

@@ -8,7 +8,7 @@
  *
  * This adapter preserves the runCommand API exactly, so current consumers
  * can opt-in to DI without behavioural changes. A matching MockCommandRunner
- * lives in src/infrastructure/mocks.js and lets tests script outputs per
+ * lives in tests/support/infrastructure-mocks.js and lets tests script outputs per
  * invocation.
  *
  * @typedef {Object} CommandRunResult

package/src/infrastructure/file-system-service.js

@@ -8,7 +8,7 @@
  * This adapter preserves the exact native API shapes for the handful of
  * operations actually used in the codebase, so consumers can opt-in to DI
  * without rewriting call sites. A matching MockFileSystem lives in
- * src/infrastructure/mocks.js.
+ * tests/support/infrastructure-mocks.js.
  *
  * Scope for TSK-0316: intentionally minimal. Only the operations already used
  * by orchestrator + agents. Additional methods added on demand.

package/src/mcp/handlers/direct-handlers.js

@@ -1,6 +1,6 @@
 /**
- * Direct role handler logic (code, review, plan, audit, discover, triage, researcher, architect, impeccable).
- * Extracted from server-handlers.js for maintainability.
+ * Direct role handler logic (code, audit, discover). KJC-TSK-1318: review,
+ * plan, triage, researcher and architect left with the kj run pipeline.
  */
 
 import fs from "node:fs/promises";
@@ -8,12 +8,7 @@ import { resolveRole } from "../../config.js";
 import { createLogger } from "../../utils/logger.js";
 import { assertAgentsAvailable } from "../../agents/availability.js";
 import { createAgent } from "../../agents/index.js";
-import { buildPlannerPrompt } from "../../prompts/planner.js";
 import { buildCoderPrompt } from "../../prompts/coder.js";
-import { buildReviewerPrompt } from "../../prompts/reviewer.js";
-import { parseMaybeJsonString, agentAnswerText } from "../../review/parser.js";
-import { computeBaseRef, generateDiff } from "../../review/diff-generator.js";
-import { resolveReviewProfile } from "../../review/profiles.js";
 import { createRunLog } from "../../utils/run-log.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { sendTrackerLog } from "../progress.js";
@@ -66,165 +61,6 @@ function applySessionOverrides(a, roleKeys) {
   }
 }
 
-export async function handlePlanDirect(a, server, extra) {
-  // KJC-PCS-0048 PR 3b: same `specReviewMode: skip` → skipSpecReview
-  // mapping as kj_run. Default "auto" keeps the reviewer enabled.
-  if (a.specReviewMode === "skip") a.skipSpecReview = true;
-  const { normalizePlanArgs } = await import("../tool-arg-normalizers.js");
-  const options = normalizePlanArgs(a);
-  const config = await buildConfig(options, "plan");
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const plannerRole = resolveRole(config, "planner");
-  await assertAgentsAvailable([plannerRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  await ensureTaskFromFile(a, projectDir);
-  const runLog = createRunLog(projectDir);
-  const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
-    ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
-    : undefined;
-  const plannerTimeoutMs = Number(config?.session?.max_planner_minutes) > 0
-    ? Math.round(Number(config.session.max_planner_minutes) * 60 * 1000)
-    : undefined;
-  const silenceLabel = silenceTimeoutMs ? `${Math.round(silenceTimeoutMs / 1000)}s` : "disabled";
-  const runtimeLabel = plannerTimeoutMs ? `${Math.round(plannerTimeoutMs / 1000)}s` : "disabled";
-  runLog.logText(
-    `[kj_plan] started — provider=${plannerRole.provider}, max_silence=${silenceLabel}, max_runtime=${runtimeLabel}`
-  );
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-
-  // --- Phase 1: Researcher (codebase context) ---
-  let researchContext = null;
-  try {
-    const { ResearcherRole } = await import("../../roles/researcher-role.js");
-    const researcherRole = resolveRole(config, "researcher");
-    const researcherOnOutput = ({ stream, line }) => {
-      emitter.emit("progress", { type: "agent:output", stage: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
-    };
-    const researcherStall = createStallDetector({
-      onOutput: researcherOnOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
-    });
-
-    sendTrackerLog(server, "researcher", "running", researcherRole.provider);
-    runLog.logText(`[researcher] agent launched for plan context...`);
-    const researcher = new ResearcherRole({ config, logger, emitter });
-    await researcher.init({ task: a.task });
-    let researchOutput;
-    try {
-      researchOutput = await researcher.run({ task: a.task, onOutput: researcherStall.onOutput });
-    } finally {
-      researcherStall.stop();
-    }
-    if (researchOutput.ok) {
-      researchContext = researchOutput.result;
-      sendTrackerLog(server, "researcher", "done");
-      runLog.logText(`[researcher] completed — context available`);
-    } else {
-      sendTrackerLog(server, "researcher", "failed");
-      runLog.logText(`[researcher] failed: ${researchOutput.summary || "unknown"}`);
-    }
-  } catch (err) {
-    logger.warn(`Researcher phase skipped: ${err.message}`);
-  }
-
-  // --- Phase 2: Architect (solution design) ---
-  let architectContext = null;
-  try {
-    const { ArchitectRole } = await import("../../roles/architect-role.js");
-    const architectRole = resolveRole(config, "architect");
-    const architectOnOutput = ({ stream, line }) => {
-      emitter.emit("progress", { type: "agent:output", stage: "architect", message: line, detail: { stream, agent: architectRole.provider } });
-    };
-    const architectStall = createStallDetector({
-      onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
-    });
-
-    sendTrackerLog(server, "architect", "running", architectRole.provider);
-    runLog.logText(`[architect] agent launched for plan context...`);
-    const architect = new ArchitectRole({ config, logger, emitter });
-    await architect.init({ task: a.task });
-    let architectOutput;
-    try {
-      architectOutput = await architect.run({ task: a.task, researchContext, onOutput: architectStall.onOutput });
-    } finally {
-      architectStall.stop();
-    }
-    if (architectOutput.ok) {
-      architectContext = architectOutput.result;
-      sendTrackerLog(server, "architect", "done");
-      runLog.logText(`[architect] completed — context available`);
-    } else {
-      sendTrackerLog(server, "architect", "failed");
-      runLog.logText(`[architect] failed: ${architectOutput.summary || "unknown"}`);
-    }
-  } catch (err) {
-    logger.warn(`Architect phase skipped: ${err.message}`);
-  }
-
-  // --- Phase 3: Planner (with research + architecture context) ---
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "planner", message: line, detail: { stream, agent: plannerRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
-  });
-
-  const planner = createAgent(plannerRole.provider, config, logger);
-  const prompt = buildPlannerPrompt({ task: a.task, context: a.context, architectContext });
-  sendTrackerLog(server, "planner", "running", plannerRole.provider);
-  runLog.logText(`[planner] agent launched, waiting for response...`);
-  let result;
-  let plannerStats;
-  try {
-    result = await planner.runTask({
-      prompt,
-      role: "planner",
-      onOutput: stallDetector.onOutput,
-      silenceTimeoutMs,
-      timeoutMs: plannerTimeoutMs
-    });
-  } finally {
-    stallDetector.stop();
-    plannerStats = stallDetector.stats();
-    runLog.logText(
-      `[planner] finished — lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s`
-    );
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "planner", "failed");
-    const baseError = result.error || result.output || "Planner failed";
-    const statsSuffix = plannerStats
-      ? ` [lines=${plannerStats.lineCount}, bytes=${plannerStats.bytesReceived}, elapsed=${Math.round(plannerStats.elapsedMs / 1000)}s]`
-      : "";
-    throw new Error(`${baseError}${statsSuffix}`);
-  }
-
-  sendTrackerLog(server, "planner", "done");
-  const parsed = parseMaybeJsonString(result.output);
-
-  // --- Persist plan ---
-  let planId = null;
-  try {
-    const { savePlan } = await import("../../plan/plan-store.js");
-    planId = await savePlan(projectDir, {
-      task: a.task,
-      researchContext,
-      architectContext,
-      plan: parsed || result.output,
-      raw: result.output
-    });
-    runLog.logText(`[kj_plan] plan persisted — planId=${planId}`);
-  } catch (err) {
-    logger.warn(`Plan persistence failed (non-blocking): ${err.message}`);
-  }
-
-  return { ok: true, plan: parsed || result.output, raw: result.output, planId, researchContext, architectContext };
-}
-
 export async function handleCodeDirect(a, server, extra) {
   const config = await buildConfig(a, "code");
   await assertNotOnBaseBranch(config);
@@ -277,55 +113,6 @@ export async function handleCodeDirect(a, server, extra) {
   return { ok: true, output: result.output, exitCode: result.exitCode };
 }
 
-export async function handleReviewDirect(a, server, extra) {
-  const config = await buildConfig(a, "review");
-  await assertNotOnBaseBranch(config);
-  const logger = createLogger(config.output.log_level, "mcp");
-
-  const reviewerRole = resolveRole(config, "reviewer");
-  await assertAgentsAvailable([reviewerRole.provider]);
-
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  await ensureTaskFromFile(a, projectDir);
-  const runLog = createRunLog(projectDir);
-  runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
-  const emitter = buildDirectEmitter(server, runLog, extra);
-  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
-  const onOutput = ({ stream, line }) => {
-    emitter.emit("progress", { type: "agent:output", stage: "reviewer", message: line, detail: { stream, agent: reviewerRole.provider } });
-  };
-  const stallDetector = createStallDetector({
-    onOutput, emitter, eventBase, stage: "reviewer", provider: reviewerRole.provider
-  });
-
-  const reviewer = createAgent(reviewerRole.provider, config, logger);
-  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef: a.baseRef });
-  const diff = await generateDiff({ baseRef: resolvedBase });
-  const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
-
-  const prompt = await buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
-  sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
-  runLog.logText(`[reviewer] agent launched, waiting for response...`);
-  let result;
-  try {
-    result = await reviewer.reviewTask({ prompt, role: "reviewer", onOutput: stallDetector.onOutput });
-  } finally {
-    stallDetector.stop();
-    const stats = stallDetector.stats();
-    runLog.logText(`[reviewer] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
-    runLog.close();
-  }
-
-  if (!result.ok) {
-    sendTrackerLog(server, "reviewer", "failed");
-    throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
-  }
-
-  sendTrackerLog(server, "reviewer", "done");
-  const parsed = parseMaybeJsonString(agentAnswerText(result.output));
-  return { ok: true, review: parsed || result.output, raw: result.output };
-}
-
 export async function handleDiscoverDirect(a, server, extra) {
   // Build context from pgTask if provided
   let context = a.context || null;
@@ -350,34 +137,6 @@ export async function handleDiscoverDirect(a, server, extra) {
   });
 }
 
-export async function handleTriageDirect(a, server, extra) {
-  return runDirectRole({
-    roleName: "triage",
-    importRole: async () => {
-      const { TriageRole } = await import("../../roles/triage-role.js");
-      return { RoleClass: TriageRole };
-    },
-    initContext: { task: a.task },
-    runInput: { task: a.task },
-    args: a, server, extra,
-    resolveProjectDir, buildConfig, buildDirectEmitter
-  });
-}
-
-export async function handleResearcherDirect(a, server, extra) {
-  return runDirectRole({
-    roleName: "researcher",
-    importRole: async () => {
-      const { ResearcherRole } = await import("../../roles/researcher-role.js");
-      return { RoleClass: ResearcherRole };
-    },
-    initContext: { task: a.task },
-    runInput: { task: a.task },
-    args: a, server, extra,
-    resolveProjectDir, buildConfig, buildDirectEmitter
-  });
-}
-
 export async function handleAuditDirect(a, server, extra) {
   const task = a.task || "Analyze the full codebase";
   return runDirectRole({
@@ -394,20 +153,6 @@ export async function handleAuditDirect(a, server, extra) {
   });
 }
 
-export async function handleArchitectDirect(a, server, extra) {
-  return runDirectRole({
-    roleName: "architect",
-    importRole: async () => {
-      const { ArchitectRole } = await import("../../roles/architect-role.js");
-      return { RoleClass: ArchitectRole };
-    },
-    initContext: { task: a.task },
-    runInput: { task: a.task, researchContext: a.context || null },
-    args: a, server, extra,
-    resolveProjectDir, buildConfig, buildDirectEmitter
-  });
-}
-
 export async function handleCode(a, server, extra) {
   const missingTask = await requireTask(a, server);
   if (missingTask) return missingTask;
@@ -422,20 +167,6 @@ export async function handleCode(a, server, extra) {
   return handleCodeDirect(a, server, extra);
 }
 
-export async function handleReview(a, server, extra) {
-  const missingTask = await requireTask(a, server);
-  if (missingTask) return missingTask;
-  await runBootstrapGate(server, a);
-  return handleReviewDirect(a, server, extra);
-}
-
-export async function handlePlan(a, server, extra) {
-  const missingTask = await requireTask(a, server);
-  if (missingTask) return missingTask;
-  await runBootstrapGate(server, a);
-  return handlePlanDirect(a, server, extra);
-}
-
 export async function handleDiscover(a, server, extra) {
   const missingTask = await requireTask(a, server);
   if (missingTask) return missingTask;
@@ -447,27 +178,6 @@ export async function handleDiscover(a, server, extra) {
   return handleDiscoverDirect(a, server, extra);
 }
 
-export async function handleTriage(a, server, extra) {
-  const missingTask = await requireTask(a, server);
-  if (missingTask) return missingTask;
-  await runBootstrapGate(server, a);
-  return handleTriageDirect(a, server, extra);
-}
-
-export async function handleResearcher(a, server, extra) {
-  const missingTask = await requireTask(a, server);
-  if (missingTask) return missingTask;
-  await runBootstrapGate(server, a);
-  return handleResearcherDirect(a, server, extra);
-}
-
-export async function handleArchitect(a, server, extra) {
-  const missingTask = await requireTask(a, server);
-  if (missingTask) return missingTask;
-  await runBootstrapGate(server, a);
-  return handleArchitectDirect(a, server, extra);
-}
-
 export async function handleAudit(a, server, extra) {
   await runBootstrapGate(server, a);
   const result = await handleAuditDirect(a, server, extra);

package/src/mcp/handlers/hu-handlers.js

@@ -1,5 +1,5 @@
 /**
- * HU, Skills, and Suggest handler logic.
+ * HU and Suggest handler logic (skills moved to `atril mcp`, ADR 0021).
  * Extracted from server-handlers.js for maintainability.
  */
 
@@ -70,40 +70,6 @@ export async function handleHu(a, server) {
   }
 }
 
-export async function handleSkills(a) {
-  const action = a.action;
-  if (!action) return failPayload("Missing required field: action");
-
-  const { isOpenSkillsAvailable, installSkill, removeSkill, listSkills, readSkill } =
-    await import("../../skills/openskills-client.js");
-
-  const opts = { projectDir: a.projectDir || null };
-
-  switch (action) {
-    case "install": {
-      if (!a.source) return failPayload("Missing required field: source (required for install)");
-      const available = await isOpenSkillsAvailable();
-      if (!available) {
-        return failPayload("OpenSkills CLI is not available. Install it with: npm install -g openskills");
-      }
-      return installSkill(a.source, { ...opts, global: a.global || false });
-    }
-    case "remove": {
-      if (!a.name) return failPayload("Missing required field: name (required for remove)");
-      return removeSkill(a.name, opts);
-    }
-    case "list": {
-      return listSkills(opts);
-    }
-    case "read": {
-      if (!a.name) return failPayload("Missing required field: name (required for read)");
-      return readSkill(a.name, opts);
-    }
-    default:
-      return failPayload(`Unknown skills action: ${action}`);
-  }
-}
-
 export async function handleSuggest(a) {
   if (!a.suggestion) {
     return failPayload("Missing required field: suggestion");

package/src/mcp/handlers/management-handlers.js

@@ -1,11 +1,10 @@
 /**
- * Management handler logic (init, doctor, config, scan, report, roles, agents, preflight, status, board).
- * Extracted from server-handlers.js for maintainability.
+ * Management handler logic (init, doctor, config, scan, report, roles, agents, preflight, board, clean).
+ * KJC-TSK-1318: status and undo left with the kj run pipeline.
  */
 
 import { runKjCommand } from "../run-kj.js";
 import { loadConfig } from "../../config.js";
-import { readRunLog } from "../../utils/run-log.js";
 import { ackPreflight, getSessionOverrides } from "../preflight.js";
 import { ensureBootstrap } from "../../bootstrap.js";
 import {
@@ -14,8 +13,6 @@ import {
   responseText,
   buildConfig,
 } from "../shared-helpers.js";
-import { buildDashboardJson } from "../../utils/status-dashboard.js";
-import { loadMostRecentSession } from "../../session/store.js";
 import { escapeRegExp } from "../../utils/escape-regexp.js";
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
@@ -29,31 +26,6 @@ async function runBootstrapGate(server, a) {
   await ensureBootstrap(projectDir, config);
 }
 
-export async function handleStatus(a, server) {
-  const maxLines = a.lines || 50;
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const logResult = readRunLog(projectDir, maxLines);
-
-  // Enrich with dashboard data when possible
-  try {
-    const session = await loadMostRecentSession();
-    const stories = [];
-    if (session) {
-      try {
-        const { loadHuBatch } = await import("../../hu/store.js");
-        const batch = await loadHuBatch(session.id);
-        if (batch?.stories) stories.push(...batch.stories);
-      } catch { /* no HU batch for this session */ }
-    }
-
-    const dashboard = buildDashboardJson(session, logResult.lines || [], { stories });
-    return { ...logResult, dashboard };
-  } catch {
-    // Fallback: return raw log without dashboard
-    return logResult;
-  }
-}
-
 export async function handleAgents(a) {
   const action = a.action || "list";
   if (action === "set") {
@@ -190,18 +162,6 @@ export async function handleBoard(a) {
   }
 }
 
-export async function handleUndo(a, server) {
-  const projectDir = await resolveProjectDir(server, a.projectDir);
-  const origCwd = process.cwd();
-  try {
-    process.chdir(projectDir);
-    const { undoCommand } = await import("../../commands/undo.js");
-    return undoCommand({ hard: !!a.hard });
-  } finally {
-    process.chdir(origCwd);
-  }
-}
-
 /**
  * Garbage-collect stale Karajan state. Routed here (not through the
  * generic `runKjCommand`) because the user needs a structured result

package/src/mcp/handlers/rag-handler.js

@@ -10,6 +10,7 @@ import { indexProject } from "../../rag/indexer.js";
 import { ragExclude } from "../../rag/indexable.js";
 import { query } from "../../rag/retriever.js";
 import { pathNamedHits, withPathNamedHits } from "../../rag/path-hits.js";
+import { claimLease, indexLeasePath, releaseLease } from "../../rag/pid-lease.js";
 import { getKarajanHome } from "../../utils/paths.js";
 import { resolveProjectDir, buildConfig, responseText, failPayload } from "../shared-helpers.js";
 
@@ -56,7 +57,11 @@ export async function handleRagIndex(args, server) {
     const projectDir = await resolveProjectDir(server, args?.projectDir);
     const config = await buildConfig({ ...args, projectDir }, "rag-index");
     const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
+    // HU-2907: the long-lived host holds the machine lease for the walk and releases it in the finally.
+    const lease = indexLeasePath();
+    let claim;
     try {
+      claim = claimLease(lease, { projectDir, slug: projectSlug(projectDir) });
       const totals = await indexProject(projectDir, {
         db, embedder: makeGovernedEmbedder(config),
         karajanHome: getKarajanHome(), logger: silentLogger,
@@ -64,7 +69,10 @@ export async function handleRagIndex(args, server) {
         exclude: ragExclude(config), // KJC-TSK-0891
       });
       return responseText(totals);
-    } finally { db.close(); }
+    } finally {
+      if (claim?.claimed) releaseLease(lease);
+      db.close();
+    }
   } catch (err) {
     return failPayload(`kj_rag_index failed: ${err.message}`);
   }

package/src/mcp/server-handlers.js

@@ -20,32 +20,35 @@ export {
 } from "./shared-helpers.js";
 
 // ── Sub-module re-exports ────────────────────────────────────────────
-export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
-export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
-export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, handleClean, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
-export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
+export { handleCodeDirect, handleDiscoverDirect, handleAuditDirect, handleCode, handleDiscover, handleAudit } from "./handlers/direct-handlers.js";
+export { handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleClean, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleHu, handleSuggest } from "./handlers/hu-handlers.js";
 
 // ── Handler dispatch ─────────────────────────────────────────────────
 
 import { asObject, failPayload } from "./shared-helpers.js";
-import { handleRun, handleResume } from "./handlers/run-handler.js";
+import { handleCode, handleDiscover, handleAudit } from "./handlers/direct-handlers.js";
 import {
-  handleCode, handleReview, handlePlan, handleDiscover,
-  handleTriage, handleResearcher, handleArchitect, handleAudit
-} from "./handlers/direct-handlers.js";
-import {
-  handleStatus, handleAgents, handlePreflight, handleRoles,
+  handleAgents, handlePreflight, handleRoles,
   handleReport, handleInit, handleDoctor, handleConfig,
-  handleScan, handleBoard, handleUndo, handleClean
+  handleScan, handleBoard, handleClean
 } from "./handlers/management-handlers.js";
-import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
+import { retiredMessage } from "../cli/retired-commands.js";
+
+// KJC-TSK-1318: the tools of the kj run pipeline, retired in 5.0 with their
+// commands; a call answers with the same notice and starts nothing.
+const RETIRED_TOOLS = {
+  kj_run: "run", kj_resume: "resume", kj_plan: "plan generate", kj_status: "status", kj_undo: "undo",
+  kj_triage: "triage", kj_researcher: "researcher", kj_architect: "architect", kj_review: "review",
+};
+import { handleHu, handleSuggest } from "./handlers/hu-handlers.js";
 import { handleRagQuery, handleRagIndex } from "./handlers/rag-handler.js";
 import { withKarajanHome } from "../utils/paths.js";
 
 export async function handleToolCall(name, args, server, extra) {
+  if (Object.hasOwn(RETIRED_TOOLS, name)) return failPayload(retiredMessage(RETIRED_TOOLS[name]));
   const a = asObject(args);
   const handler = {
-    kj_status:      (a, server) => handleStatus(a, server),
     kj_init:        (a) => handleInit(a),
     kj_doctor:      (a) => handleDoctor(a),
     kj_agents:      (a) => handleAgents(a),
@@ -54,21 +57,12 @@ export async function handleToolCall(name, args, server, extra) {
     kj_scan:        (a, server) => handleScan(a, server),
     kj_roles:       (a) => handleRoles(a),
     kj_report:      (a) => handleReport(a),
-    kj_resume:      (a, server, extra) => handleResume(a, server, extra),
-    kj_run:         (a, server, extra) => handleRun(a, server, extra),
     kj_code:        (a, server, extra) => handleCode(a, server, extra),
-    kj_review:      (a, server, extra) => handleReview(a, server, extra),
-    kj_plan:        (a, server, extra) => handlePlan(a, server, extra),
     kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
-    kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
-    kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
-    kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
     kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
     kj_board:       (a) => handleBoard(a),
     kj_hu:          (a, server) => handleHu(a, server),
     kj_suggest:     (a) => handleSuggest(a),
-    kj_skills:      (a) => handleSkills(a),
-    kj_undo:        (a, server) => handleUndo(a, server),
     kj_clean:       (a) => handleClean(a),
     kj_rag_query:   (a, server) => handleRagQuery(a, server),
     kj_rag_index:   (a, server) => handleRagIndex(a, server),