karajan-code 1.9.3 → 1.9.5

package/README.md

@@ -420,6 +420,18 @@ After `npm install -g karajan-code`, the MCP server is auto-registered in Claude
 | `kj_review` | Run reviewer-only mode |
 | `kj_plan` | Generate implementation plan with heartbeat/stall telemetry and clearer diagnostics |
 
+### MCP restart after version updates
+
+If you update Karajan Code (for example `npm install -g karajan-code` to a new version) while your MCP host session is still open, the current `karajan-mcp` process may exit and the host can show `Transport closed`.
+
+This is expected behavior: the MCP server detects a version mismatch and exits so the host can spawn a fresh process with the new code.
+
+Quick recovery:
+
+1. Restart your MCP host session (Claude/Codex/new terminal session).
+2. Verify the server is listed (`codex mcp list` or your host equivalent).
+3. Run a lightweight check (`kj_config`) before continuing with larger runs.
+
 ### Recommended Companion MCPs
 
 Karajan Code works great on its own, but combining it with these MCP servers gives your AI agent a complete development environment:

package/package.json

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

package/src/agents/claude-agent.js

@@ -70,6 +70,19 @@ function createStreamJsonFilter(onOutput) {
   };
 }
 
+/**
+ * Build a clean environment for Claude subprocess.
+ * Claude Code 2.x sets CLAUDECODE=1 to detect nesting. When Karajan's MCP
+ * server runs inside Claude Code and spawns `claude -p`, the child inherits
+ * this variable and refuses to start. Stripping it allows the subprocess to
+ * run normally — it is a separate, non-interactive invocation, not a true
+ * nested session.
+ */
+function cleanEnv() {
+  const { CLAUDECODE, ...rest } = process.env;
+  return rest;
+}
+
 export class ClaudeAgent extends BaseAgent {
   async runTask(task) {
     const role = task.role || "coder";
@@ -77,11 +90,14 @@ export class ClaudeAgent extends BaseAgent {
     const model = this.getRoleModel(role);
     if (model) args.push("--model", model);
 
+    const env = cleanEnv();
+
     // Use stream-json when onOutput is provided to get real-time feedback
     if (task.onOutput) {
       args.push("--output-format", "stream-json");
       const streamFilter = createStreamJsonFilter(task.onOutput);
       const res = await runCommand(resolveBin("claude"), args, {
+        env,
         onOutput: streamFilter,
         silenceTimeoutMs: task.silenceTimeoutMs,
         timeout: task.timeoutMs
@@ -90,7 +106,7 @@ export class ClaudeAgent extends BaseAgent {
       return { ok: res.exitCode === 0, output, error: res.stderr, exitCode: res.exitCode };
     }
 
-    const res = await runCommand(resolveBin("claude"), args);
+    const res = await runCommand(resolveBin("claude"), args, { env });
     return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
   }
 
@@ -99,6 +115,7 @@ export class ClaudeAgent extends BaseAgent {
     const model = this.getRoleModel(task.role || "reviewer");
     if (model) args.push("--model", model);
     const res = await runCommand(resolveBin("claude"), args, {
+      env: cleanEnv(),
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/mcp/server-handlers.js

@@ -21,6 +21,7 @@ import { parseMaybeJsonString } from "../review/parser.js";
 import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
 import { resolveReviewProfile } from "../review/profiles.js";
 import { createRunLog, readRunLog } from "../utils/run-log.js";
+import { currentBranch } from "../utils/git.js";
 
 /**
  * Resolve the user's project directory via MCP roots.
@@ -109,6 +110,13 @@ export function classifyError(error) {
     };
   }
 
+  if (lower.includes("you are on the base branch")) {
+    return {
+      category: "branch_error",
+      suggestion: "Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch."
+    };
+  }
+
   if (lower.includes("not a git repository")) {
     return {
       category: "git_error",
@@ -119,6 +127,23 @@ export function classifyError(error) {
   return { category: "unknown", suggestion: null };
 }
 
+export async function assertNotOnBaseBranch(config) {
+  const baseBranch = config?.base_branch || "main";
+  let branch;
+  try {
+    branch = await currentBranch();
+  } catch {
+    return; // not a git repo or detached HEAD — let downstream handle it
+  }
+  if (branch === baseBranch) {
+    throw new Error(
+      `You are on the base branch '${baseBranch}'. Karajan needs a feature branch to compute the diff for review. ` +
+      `Create a new branch first (e.g. 'git checkout -b feat/<task-description>') and then run this command again. ` +
+      `Do NOT run kj_code directly — create the branch first so the full pipeline (code + review) works correctly.`
+    );
+  }
+}
+
 export function enrichedFailPayload(error, toolName) {
   const msg = error?.message || String(error);
   const { category, suggestion } = classifyError(error);
@@ -161,6 +186,7 @@ export function buildAskQuestion(server) {
 
 export async function handleRunDirect(a, server, extra) {
   const config = await buildConfig(a);
+  await assertNotOnBaseBranch(config);
   const logger = createLogger(config.output.log_level, "mcp");
 
   const requiredProviders = [
@@ -304,6 +330,7 @@ export async function handlePlanDirect(a, server, extra) {
 
 export async function handleCodeDirect(a, server, extra) {
   const config = await buildConfig(a, "code");
+  await assertNotOnBaseBranch(config);
   const logger = createLogger(config.output.log_level, "mcp");
 
   const coderRole = resolveRole(config, "coder");
@@ -352,6 +379,7 @@ export async function handleCodeDirect(a, server, extra) {
 
 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");