karajan-code 2.10.2 → 2.11.0

package/README.md

@@ -23,7 +23,9 @@
 
 ---
 
-> **v2.10.2 released** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
+> **v2.11.0 released** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
+>
+> **v2.10.2** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
 >
 > **v2.10.1** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
 >

package/package.json

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

package/src/audit/sonar-findings.js

@@ -22,6 +22,7 @@
 
 import { isSonarReachable } from "../sonar/manager.js";
 import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+import { canResolveSonarProjectKey } from "../sonar/project-key.js";
 
 /**
  * Collect deterministic Sonar findings for the audit prompt.
@@ -43,6 +44,17 @@ export async function collectSonarFindings(config, logger = null) {
     return { available: false, reason: `sonar host ${host} not reachable` };
   }
 
+  // No git remote and no explicit project_key → silent skip. This is the
+  // typical `kj run` in a fresh /tmp/... folder. Reporting it as a
+  // warning treats it like an error (which it isn't — sonar simply
+  // doesn't apply to a remoteless repo).
+  if (!(await canResolveSonarProjectKey(config))) {
+    return {
+      available: false,
+      reason: "not applicable: no git remote and no sonarqube.project_key configured",
+    };
+  }
+
   let issuesResult;
   try {
     issuesResult = await getOpenIssues(config);

package/src/cli/register-meta.js

@@ -24,7 +24,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("discover")
     .description("Analyze task for gaps, ambiguities and missing info")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
     .option("--discover <name>", "Override discover agent")
@@ -41,7 +41,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("triage")
     .description("Classify task complexity and recommend pipeline roles")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--triage <name>", "Override triage agent")
     .option("--triage-model <name>", "Override triage model")
@@ -57,7 +57,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("researcher")
     .description("Research codebase for a task (files, patterns, constraints)")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--researcher <name>", "Override researcher agent")
     .option("--researcher-model <name>", "Override researcher model")
@@ -72,7 +72,7 @@ export function registerMeta(program, { pkgVersion }) {
   program
     .command("architect")
     .description("Design solution architecture (layers, patterns, contracts)")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--architect <name>", "Override architect agent")
     .option("--architect-model <name>", "Override architect model")

package/src/cli/register-pipeline.js

@@ -40,7 +40,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("run")
     .description("Run coder+sonar+reviewer loop")
-    .argument("[task]", "Task description (or use --task-file to read from a .md file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
     .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
     .option("--planner <name>")
@@ -135,7 +135,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("code")
     .description("Run only coder")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--coder <name>")
     .option("--coder-model <name>")
@@ -150,7 +150,7 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("review")
     .description("Run only reviewer")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--reviewer <name>")
     .option("--reviewer-model <name>")

package/src/cli/register-plan.js

@@ -26,7 +26,7 @@ export function registerPlan(program, { pkgVersion }) {
   plan
     .command("generate", { isDefault: true })
     .description("Generate implementation plan with HUs")
-    .argument("[task]", "Task description (or use --task-file)")
+    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--planner <name>")
     .option("--planner-model <name>")

package/src/commands/board.js

@@ -126,14 +126,29 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   const karajanHome = getKarajanHome();
   fs.mkdirSync(karajanHome, { recursive: true });
 
+  // Open a log file for the daemon. Pre-fix the daemon was spawned
+  // with `stdio: "ignore"`, so every `console.log` from server.js
+  // (including the new [zombie-reaper] messages) went straight to
+  // /dev/null and the user had no way to see what was happening.
+  // The file is opened in append-only mode so successive starts
+  // don't truncate the history.
+  const logPath = path.join(karajanHome, "hu-board.log");
+  const logFd = fs.openSync(logPath, "a");
+  fs.writeSync(
+    logFd,
+    `\n--- kj board start at ${new Date().toISOString()} (port ${port}, bind ${bind}) ---\n`,
+  );
+
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
   const child = spawn(process.execPath, [serverPath], {
     env: { ...process.env, PORT: String(port), BIND_HOST: bind },
     detached: true,
-    stdio: "ignore",
+    stdio: ["ignore", logFd, logFd],
     cwd: BOARD_DIR
   });
+  // The parent doesn't need the fd anymore — the child inherited it.
+  fs.closeSync(logFd);
   // Swallow spawn errors so an HU Board failure never crashes the pipeline.
   child.on("error", () => { /* non-blocking — caller logs via tryAutoStartBoard catch */ });
   if (!child.pid) {
@@ -143,10 +158,16 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference
   // to the child handle and `kj board start` hangs at the prompt
-  // instead of returning. Pair this with stdio:"ignore" (already set)
-  // to ensure the parent isn't waiting on any of the child's pipes.
+  // instead of returning.
   child.unref();
-  return { ok: true, alreadyRunning: false, pid: child.pid, url: buildBoardUrl(port, projectSlug), port };
+  return {
+    ok: true,
+    alreadyRunning: false,
+    pid: child.pid,
+    url: buildBoardUrl(port, projectSlug),
+    port,
+    logPath,
+  };
 }
 
 export async function stopBoard(opts = {}) {
@@ -273,6 +294,9 @@ export async function boardCommand({ action = "start", port = 4000, bind = "127.
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {
         logger.info(`HU Board started (PID ${result.pid}) at ${result.url}`);
+        if (result.logPath) {
+          logger.info(`Daemon logs: tail -f ${result.logPath}`);
+        }
         if (bind !== "127.0.0.1" && bind !== "localhost") {
           logger.warn(`HU Board bound to ${bind} — token auth enforced for non-loopback peers. Token: ~/.karajan/hu-board/token`);
         }

package/src/commands/init.js

@@ -277,6 +277,22 @@ async function runWizard(config, logger) {
   return config;
 }
 
+/**
+ * Backwards-compatible alias for `writeConfig`. Pre-KJC-BUG-0036 this
+ * wrapper was the *only* writer that stripped `sonarqube.enabled`
+ * before serialising — we needed it because the global `writeConfig`
+ * would happily persist the wizard's transient hint. KJC-BUG-0036
+ * moved that strip (and the equivalent `_deprecated` strip) into
+ * `writeConfig` itself, so this is now a thin alias kept around to
+ * keep callers and tests stable. Prefer `writeConfig` in new code.
+ *
+ * @param {string} configPath
+ * @param {object} config
+ */
+export async function writeInitConfig(configPath, config) {
+  await writeConfig(configPath, config);
+}
+
 async function handleConfigSetup({ config, configExists, interactive, configPath, logger }) {
   if (configExists && interactive) {
     const wizard = createWizard();
@@ -284,7 +300,7 @@ async function handleConfigSetup({ config, configExists, interactive, configPath
       const reconfigure = await wizard.confirm("Config already exists. Reconfigure?", false);
       if (reconfigure) {
         const updated = await runWizard(config, logger);
-        await writeConfig(configPath, updated);
+        await writeInitConfig(configPath, updated);
         logger.info(`Updated ${configPath}`);
       } else {
         logger.info("Keeping existing config.");
@@ -294,10 +310,10 @@ async function handleConfigSetup({ config, configExists, interactive, configPath
     }
   } else if (!configExists && interactive) {
     const updated = await runWizard(config, logger);
-    await writeConfig(configPath, updated);
+    await writeInitConfig(configPath, updated);
     logger.info(`Created ${configPath}`);
   } else if (!configExists) {
-    await writeConfig(configPath, config);
+    await writeInitConfig(configPath, config);
     logger.info(`Created ${configPath}`);
   }
 }
@@ -561,7 +577,7 @@ export async function initCommand({ logger, flags = {} }) {
       config.development.methodology = config.development.methodology || "tdd";
     }
 
-    await writeConfig(configPath, config);
+    await writeInitConfig(configPath, config);
   } else {
     logger.info("No project stack detected — using default configuration.");
   }
@@ -582,7 +598,10 @@ export async function initCommand({ logger, flags = {} }) {
   await scaffoldCiGateway(config, flags, logger);
 
   // Persist any changes setupSonarQube made (token, etc.) back to disk.
-  await writeConfig(configPath, config);
+  // Use writeInitConfig so the deprecated `sonarqube.enabled` key —
+  // which setupSonarQube still mutates as an in-memory hint — never
+  // reaches the YAML file.
+  await writeInitConfig(configPath, config);
 
   // Telemetry: anonymous install event (non-blocking)
   const { sendTelemetryEvent } = await import("../utils/telemetry.js");

package/src/config/loader.js

@@ -128,9 +128,40 @@ export async function loadConfig(projectDir) {
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
+/**
+ * Runtime-only keys that the loader synthesises on every load (or that
+ * a wizard uses as transient in-memory hints). They MUST NOT survive
+ * to the on-disk YAML — otherwise the `kj run` deprecation warning
+ * fossilises (KJC-BUG-0036, observed in dogfooding 2026-05-07: the
+ * `_deprecated.sonarqubeEnabledKey: true` block ended up baked into
+ * `~/.karajan/kj.config.yml` and re-fired the warning on every run
+ * even after the user cleaned `sonarqube.enabled`).
+ *
+ * Pure: returns a shallow-copied config without the runtime keys —
+ * the caller's object is left untouched.
+ */
+function stripRuntimeOnlyKeys(config) {
+  if (!config || typeof config !== "object") return config;
+  const out = { ...config };
+  // _deprecated is loader-synthesised — never written intentionally.
+  if ("_deprecated" in out) delete out._deprecated;
+  // sonarqube.enabled was deprecated in v2.7.4. The init wizard still
+  // uses it as a hint to drive setupSonarQube during install, but the
+  // runtime ignores it. Persisting it would re-trigger the deprecation
+  // warning on every subsequent kj run.
+  if (out.sonarqube && typeof out.sonarqube === "object"
+      && Object.prototype.hasOwnProperty.call(out.sonarqube, "enabled")) {
+    const { enabled: _drop, ...rest } = out.sonarqube;
+    void _drop;
+    out.sonarqube = rest;
+  }
+  return out;
+}
+
 export async function writeConfig(configPath, config) {
   await ensureDir(path.dirname(configPath));
-  await fs.writeFile(configPath, yaml.dump(config, { lineWidth: 120 }), "utf8");
+  const sanitized = stripRuntimeOnlyKeys(config);
+  await fs.writeFile(configPath, yaml.dump(sanitized, { lineWidth: 120 }), "utf8");
 }
 
 // Declarative mappings for applyRunOverrides to reduce cognitive complexity.

package/src/git/automation.js

@@ -15,14 +15,88 @@ import {
   buildBranchName,
   commitAll,
   pushBranch,
-  createPullRequest
+  createPullRequest,
+  listPendingPaths
 } from "../utils/git.js";
 
-export function commitMessageFromTask(task) {
+/**
+ * Karajan writes / updates several internal directories during a pipeline
+ * run (the workspace scaffold + the session journal). When they're the
+ * ONLY thing pending at finalization, the post-loop commit shouldn't
+ * inherit the user task's `feat:` message — it should be a clear
+ * `chore: scaffold karajan workspace` so `git log --oneline` reads:
+ *
+ *     2d770aa  docs: add JSDoc comment to index.js
+ *     abc1234  chore: scaffold karajan workspace
+ *     8a95ef0  initial
+ *
+ * A path counts as scaffolding when it lives at one of these prefixes
+ * OR is the project's root `.gitignore` (we extend it to include
+ * stack-specific entries during triage).
+ */
+const KARAJAN_SCAFFOLD_PREFIXES = [
+  ".karajan/",
+  ".reviews/",
+  ".kj/",
+  ".agent/",
+];
+
+function isKarajanScaffoldPath(p) {
+  if (p === ".gitignore") return true;
+  return KARAJAN_SCAFFOLD_PREFIXES.some((prefix) => p.startsWith(prefix));
+}
+
+/**
+ * @param {string[]} paths
+ * @returns {boolean} true when every pending path is a Karajan internal
+ */
+export function pendingPathsAreOnlyKarajanScaffold(paths) {
+  if (!Array.isArray(paths) || paths.length === 0) return false;
+  return paths.every(isKarajanScaffoldPath);
+}
+
+/**
+ * Map the taskType (as classified by triage) to the matching
+ * Conventional Commits prefix. When triage hasn't run or the type is
+ * unknown we default to `feat:` (the pre-fix behaviour).
+ */
+const TASK_TYPE_TO_PREFIX = {
+  doc: "docs",
+  "add-tests": "test",
+  refactor: "refactor",
+  infra: "chore",
+  sw: "feat",
+};
+
+function prefixForTaskType(taskType) {
+  return TASK_TYPE_TO_PREFIX[taskType] || "feat";
+}
+
+export function commitMessageFromTask(task, taskType = null) {
   const clean = String(task || "")
     .replaceAll(/\s+/g, " ")
     .trim();
-  return `feat: ${clean.slice(0, 72) || "karajan update"}`;
+  const prefix = prefixForTaskType(taskType);
+  return `${prefix}: ${clean.slice(0, 72) || "karajan update"}`;
+}
+
+/**
+ * Build the message used by `finalizeGitAutomation` for the post-loop
+ * commit. Two paths:
+ *   - When the only pending changes are Karajan scaffold files
+ *     (.gitignore, .karajan/, .reviews/, ...), use a fixed
+ *     `chore: scaffold karajan workspace` message. This avoids the
+ *     "duplicate feat:" git log seen when triage extends .gitignore
+ *     for a freshly detected stack and the coder already committed
+ *     the user-visible change.
+ *   - Otherwise, fall back to `commitMessageFromTask(task, taskType)`,
+ *     respecting the type for the prefix.
+ */
+export function buildFinalizeCommitMessage({ task, taskType, pendingPaths }) {
+  if (pendingPathsAreOnlyKarajanScaffold(pendingPaths)) {
+    return "chore: scaffold karajan workspace";
+  }
+  return commitMessageFromTask(task, taskType);
 }
 
 export async function prepareGitAutomation({ config, task, logger, session }) {
@@ -173,7 +247,23 @@ export async function incrementalPush({ gitCtx, task, logger, session }) {
 export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
   if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
 
-  const commitMsg = config.git.commit_message || commitMessageFromTask(task);
+  // Take a snapshot of pending paths BEFORE staging so we can decide
+  // whether what's about to be committed is just Karajan scaffolding
+  // (in which case we use `chore: scaffold karajan workspace`) or a
+  // real, user-visible change (in which case we honour the task's
+  // taskType for the Conventional Commits prefix).
+  const taskType = stageResults?.triage?.taskType ?? null;
+  let pendingPaths = [];
+  if (config.git.auto_commit) {
+    try {
+      pendingPaths = await listPendingPaths();
+    } catch { /* best-effort — fall back to default message */ }
+  }
+
+  const commitMsg =
+    config.git.commit_message
+    || buildFinalizeCommitMessage({ task, taskType, pendingPaths });
+
   let committed = false;
   const commits = [];
   if (config.git.auto_commit) {

package/src/git/hu-automation.js

@@ -41,6 +41,34 @@ export function resolveHuBase(story, huBranches, baseBranch) {
   return baseBranch;
 }
 
+/**
+ * Resolve to an actually-existing local ref. Tries the preferred branch
+ * first, then `main` and `master`, then plain `HEAD` as last resort.
+ *
+ * Why: N6 plan-flow dogfooding (2026-05-07) on a `git init -q` repo
+ * with `init.defaultBranch=master` produced 7 identical warnings:
+ *   `failed to create branch feat/...-001 from main:
+ *    fatal: 'main' is not a commit and a branch can't be created`.
+ * Every HU then fell back to running on the original branch, which
+ * defeats the per-HU isolation the sub-pipeline was supposed to give.
+ *
+ * The configured base_branch is honoured when it exists; otherwise we
+ * pick the most likely default. HEAD always exists once the repo has
+ * any commit, so the fallback never throws past the gate.
+ *
+ * @param {string} preferred
+ * @returns {Promise<string>}
+ */
+async function resolveExistingBranchRef(preferred) {
+  const candidates = [preferred, "main", "master", "HEAD"]
+    .filter((c, i, arr) => c && arr.indexOf(c) === i); // unique, truthy
+  for (const ref of candidates) {
+    const probe = await runCommand("git", ["rev-parse", "--verify", "--quiet", ref], {});
+    if (probe.exitCode === 0) return ref;
+  }
+  return preferred; // give up; caller will surface the original error
+}
+
 /**
  * Create a branch for an HU starting from its resolved base.
  * Returns the branch name created (or null if git automation is disabled).
@@ -57,17 +85,21 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
     return null;
   }
   const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
+  const effectiveBase = await resolveExistingBranchRef(baseBranch);
+  if (effectiveBase !== baseBranch) {
+    logger.info(`HU git: configured base '${baseBranch}' not found locally — using '${effectiveBase}' instead`);
+  }
   const prefix = config.git?.branch_prefix || "feat/";
   const branchName = buildHuBranchName(prefix, story);
 
   // Checkout from the resolved base. Use `git checkout -B` to overwrite if rerun.
-  const res = await runCommand("git", ["checkout", "-B", branchName, baseBranch], {});
+  const res = await runCommand("git", ["checkout", "-B", branchName, effectiveBase], {});
   if (res.exitCode !== 0) {
-    logger.warn(`HU git: failed to create branch ${branchName} from ${baseBranch}: ${res.stderr}`);
+    logger.warn(`HU git: failed to create branch ${branchName} from ${effectiveBase}: ${res.stderr}`);
     return null;
   }
   huBranches.set(story.id, branchName);
-  logger.info(`HU ${story.id}: branch '${branchName}' from '${baseBranch}'`);
+  logger.info(`HU ${story.id}: branch '${branchName}' from '${effectiveBase}'`);
   return branchName;
 }
 

package/src/orchestrator/config-init.js

@@ -5,6 +5,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { computeBaseRef, setSnapshot } from "../review/diff-generator.js";
+import { revParse } from "../utils/git.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
@@ -367,12 +368,28 @@ export async function initializeSession({ task, config, flags, pgTaskId, pgProje
   const projectDir = config.projectDir || process.cwd();
   const project_id = projectSlug(projectDir);
 
+  // Capture HEAD at the very start of the run, separately from base_ref.
+  // session_start_sha was being conflated with base_ref (used for `git diff`)
+  // — when the user's repo had a single commit and no remote main, base_ref
+  // fell through to git's empty-tree SHA. The post-loop journal then read
+  // session_start_sha to enumerate "commits made by this run" and got back
+  // the entire history, including pre-existing commits. Capturing actual
+  // HEAD here makes "what did the run produce?" deterministic and correct.
+  // Falls back to baseRef when HEAD doesn't exist (zero-commits repo); in
+  // that case "everything since baseRef" still equals "everything the run
+  // produced" because there was no prior history.
+  let headAtStart;
+  try {
+    headAtStart = (await revParse("HEAD")) || baseRef;
+  } catch { headAtStart = baseRef; }
+
   const sessionInit = {
     task,
     project_id,
     config_snapshot: config,
     base_ref: baseRef,
     session_start_sha: baseRef,
+    head_at_start: headAtStart,
     last_reviewer_feedback: null,
     repeated_issue_count: 0,
     sonar_retry_count: 0,

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

@@ -23,6 +23,7 @@
 
 import { generateDiff } from "../../review/diff-generator.js";
 import { finalizeGitAutomation } from "../../git/automation.js";
+import { listCommitsBetween } from "../../utils/git.js";
 import { saveSession, markSessionStatus } from "../../session/store.js";
 import {
   setReviewerFeedback, setBudget, setRtkSavings, resetRetryCount,
@@ -151,6 +152,20 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
       const { writeSummaryJournal: writeSummaryJournalV2 } =
         await import("../../session/journal/summary-writer.js");
       const startedAt = session._startedAt ? new Date(session._startedAt).toISOString() : undefined;
+      // 2026-05-07 dogfooding: gitResult.commits only carries the post-loop
+      // commit (scaffold), not the coder's own commit. The summary's
+      // "Commits" section was therefore misleading — it claimed the run
+      // produced one chore commit when in fact the coder had also written
+      // a docs/feat commit. Compute the full range from session_start_sha
+      // so every commit between then and HEAD shows up in execution order.
+      // try/catch (instead of `.catch(...)`) so we tolerate both promise
+      // rejection AND a sync return of undefined — the latter happens
+      // when a test mocks listCommitsBetween with a plain vi.fn() that
+      // resetAllMocks has stripped of its mockResolvedValue.
+      let allCommits = [];
+      try { allCommits = (await listCommitsBetween(session.head_at_start || session.session_start_sha)) || []; }
+      catch { allCommits = gitResult?.commits || []; }
+      const summaryCommits = allCommits.length > 0 ? allCommits : (gitResult?.commits || []);
       await writeSummaryJournalV2(journalDir, {
         task: session.task,
         result: "APPROVED",
@@ -159,7 +174,7 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
         durationMs: Date.now() - (session._startedAt || Date.now()),
         budget: budgetSummary(),
         stages: stageResults,
-        commits: gitResult?.commits || [],
+        commits: summaryCommits,
         files: journalFiles,
         startedAt,
         finishedAt: new Date().toISOString(),
@@ -180,7 +195,21 @@ export async function finalizeApprovedSession({ config, gitCtx, task, logger, se
     }
   }
 
-  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues };
+  // Mirror the same enriched commit list into the session:end event so the
+  // terminal `🏁 Result` banner (printSessionGit) shows every commit the
+  // run produced, not just the post-loop scaffold one. We compute again
+  // (cheap: one git log call) rather than threading a variable through
+  // because the journal block is wrapped in try/catch and may have set
+  // `summaryCommits` to a fallback we don't want for the event detail.
+  // try/catch tolerates both promise rejection and sync undefined returns
+  // (see the journal block above for the detailed rationale).
+  let eventCommits = null;
+  try { eventCommits = await listCommitsBetween(session.head_at_start || session.session_start_sha); }
+  catch { /* leave null — we'll use gitResult unchanged */ }
+  const gitForEvent = (Array.isArray(eventCommits) && eventCommits.length > 0)
+    ? { ...gitResult, commits: eventCommits }
+    : gitResult;
+  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitForEvent, budget: budgetSummary(), deferredIssues };
   if (rtkSavings) endDetail.rtk_savings = rtkSavings;
   emitProgress(
     emitter,

package/src/orchestrator/flow-runner.js

@@ -60,6 +60,45 @@ import { runSecurityStage, runFinalAuditStage } from "./post-loop-stages.js";
 // PG card "In Progress" logic moved to src/planning-game/pipeline-adapter.js → initPgAdapter()
 
 
+/**
+ * Boundary guard: make sure the session's terminal status reflects what
+ * actually happened, even if some inner exit path forgot to call
+ * `markSessionStatus`. KJC-BUG-0037 (N1 dogfooding 2026-05-07): runs
+ * that took the Brain "max_iterations approved" / "Solomon-after-error
+ * approved" / "Brain solomon-approved" exits returned `{approved:true}`
+ * upstream but left `session.status = "running"` on disk indefinitely.
+ * `kj status` then showed "Pipeline RUNNING" forever and the HU Board
+ * carried a perma-zombie.
+ *
+ * Maps the result shape to a terminal status:
+ *   approved → "approved"
+ *   paused   → "paused"
+ *   cancelled → "cancelled"
+ *   anything else → "failed"
+ *
+ * Idempotent: only writes when the current status is still "running"
+ * (or unset). If an inner path already sealed it correctly, this is a
+ * no-op.
+ *
+ * Safe-by-default: never throws. A failure here must not block the
+ * top-level result from being returned to the caller.
+ *
+ * @param {object} session
+ * @param {object} [result]
+ */
+export async function sealSessionStatusIfStillRunning(session, result) {
+  try {
+    if (!session) return;
+    const current = session.status;
+    if (current && current !== "running") return;
+    let target = "failed";
+    if (result?.approved === true) target = "approved";
+    else if (result?.paused === true) target = "paused";
+    else if (result?.cancelled === true) target = "cancelled";
+    await markSessionStatus(session, target);
+  } catch { /* non-blocking */ }
+}
+
 export async function runFlow(opts) {
   // TSK-0338: isolate per-run state (git/diff runner, projectDir, snapshot)
   // inside an AsyncLocalStorage scope. Two concurrent `runFlow` invocations
@@ -193,12 +232,14 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
     // policies + acceptance-tests gate + Sonar + tester translation.
     const huBatch = await runHuBatch({ ctx, task, askQuestion, emitter, logger });
     if (huBatch.handled) {
+      await sealSessionStatusIfStillRunning(ctx.session, huBatch.result);
       return huBatch.result;
     }
 
     // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
     const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
     await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
+    await sealSessionStatusIfStillRunning(ctx.session, result);
     return result;
   } finally {
     // --- Cleanup auto-installed skills ---

package/src/orchestrator/stages/sonar-stage.js

@@ -11,6 +11,7 @@ import {
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { sonarUp, isSonarReachable } from "../../sonar/manager.js";
+import { canResolveSonarProjectKey } from "../../sonar/project-key.js";
 import { addEntries } from "../feedback-queue.js";
 
 /**
@@ -222,6 +223,24 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
     logger.info("SonarQube is ready");
   }
 
+  // 2026-05-07 (N4 dogfooding): when the working tree has neither a git
+  // remote nor an explicit `sonarqube.project_key`, the scanner inside
+  // SonarRole would throw "Missing git remote.origin.url" — the Brain
+  // logs that as a sonar error, the iteration cap is reached, and the
+  // run finalises as "approved" by exhaustion fallback even though no
+  // sonar gate ever ran. KJC-TSK-0373 silenced this for the audit
+  // collector but the run loop hit it on the parallel code path.
+  // Skipping cleanly here means the gate reports "SKIPPED" once and
+  // the iteration loop progresses on the next stage.
+  if (!await canResolveSonarProjectKey(config)) {
+    logger.info("Sonar gate skipped: no git remote and no sonarqube.project_key configured");
+    emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
+      status: "skip",
+      message: "Sonar skipped — no git remote and no sonarqube.project_key configured (run `git remote add origin …` or set `sonarqube.project_key` to enable)"
+    }));
+    return { action: "ok", stageResult: { gateStatus: "SKIPPED", reason: "no git remote and no sonarqube.project_key configured" } };
+  }
+
   const sonarRole = new SonarRole({ config, logger, emitter });
   await sonarRole.init({ iteration });
   const sonarStart = Date.now();

package/src/skills/addyosmani-catalog.js

@@ -146,7 +146,7 @@ export async function ensureCatalog(opts = {}) {
  * ensureCatalog().
  *
  * @param {{ refreshMs?: number, repoUrl?: string, force?: boolean, logger?: object }} [opts]
- * @returns {Promise<{ok: boolean, action: "cloned"|"pulled"|"fresh"|"skipped", error?: string}>}
+ * @returns {Promise<{ok: boolean, action: "cloned"|"pulled"|"reset"|"fresh"|"skipped", error?: string}>}
  */
 export async function refreshIfStale(opts = {}) {
   const { refreshMs = DEFAULT_REFRESH_MS, repoUrl = REPO_URL, force = false, logger } = opts;
@@ -171,16 +171,38 @@ export async function refreshIfStale(opts = {}) {
     return { ok: true, action: "skipped" };
   }
 
-  const result = await runCommand(
+  const pullResult = await runCommand(
     "git",
     ["-C", root, "pull", "--ff-only", "--depth", "1"],
     { timeout: 60_000 }
   );
 
-  if (result.exitCode !== 0) {
-    const stderr = (result.stderr || "").trim();
-    logger?.warn?.(`addyosmani-catalog: git pull failed — ${stderr} (keeping stale cache)`);
-    return { ok: false, action: "skipped", error: stderr };
+  let action = "pulled";
+  if (pullResult.exitCode !== 0) {
+    // The cached catalog is read-only (we never commit to it), so a
+    // non-fast-forward result is virtually always upstream rewriting
+    // history with `git push --force` — see KJC-BUG-0033 / N3-2 (the
+    // user hit this on 2026-05-07 when addyosmani force-pushed his
+    // skills repo). Recover by fetching shallow and hard-resetting to
+    // FETCH_HEAD: there's nothing local to lose.
+    const fetchResult = await runCommand(
+      "git",
+      ["-C", root, "fetch", "--depth", "1", "origin", "HEAD"],
+      { timeout: 60_000 }
+    );
+    const resetResult = fetchResult.exitCode === 0
+      ? await runCommand("git", ["-C", root, "reset", "--hard", "FETCH_HEAD"], { timeout: 30_000 })
+      : { exitCode: fetchResult.exitCode, stderr: fetchResult.stderr };
+
+    if (resetResult.exitCode !== 0) {
+      const pullErr = (pullResult.stderr || "").trim();
+      const recoveryErr = (resetResult.stderr || "").trim();
+      const combined = recoveryErr ? `${pullErr} | recovery: ${recoveryErr}` : pullErr;
+      logger?.warn?.(`addyosmani-catalog: git pull failed — ${combined} (keeping stale cache)`);
+      return { ok: false, action: "skipped", error: combined };
+    }
+    action = "reset";
+    logger?.info?.("addyosmani-catalog: ff-only failed, recovered via fetch+reset (upstream force-pushed)");
   }
 
   await writeMeta({
@@ -189,7 +211,7 @@ export async function refreshIfStale(opts = {}) {
     lastPullAt: new Date().toISOString(),
   });
 
-  return { ok: true, action: "pulled" };
+  return { ok: true, action };
 }
 
 /**

package/src/sonar/project-key.js

@@ -81,3 +81,40 @@ export async function resolveSonarProjectKey(config, options = {}) {
   const repo = slug(repoId.split("/").pop());
   return normalizeProjectKey(`kj-${repo}-${digest(repoId)}`);
 }
+
+/**
+ * Non-throwing predicate: can a Sonar project key be resolved for `config`?
+ *
+ * Used by callers (audit collector, run-loop SonarStage) that want to skip
+ * the Sonar work cleanly instead of letting `resolveSonarProjectKey` throw
+ * "Missing git remote.origin.url" deep inside the scanner. The scanner's
+ * thrown error is fine for an explicit `kj sonar` call (the user asked
+ * for it), but for implicit pipeline gates it produces a noisy "Sonar
+ * scan failed" loop in fresh /tmp/... repos.
+ *
+ * Returns true when EITHER:
+ *   - an explicit `project_key` is set (env var, config, or per-call option),
+ *   - OR `git config --get remote.origin.url` succeeds with a non-empty value.
+ *
+ * Side-effect-free apart from the git probe.
+ *
+ * @param {object} config
+ * @param {object} [options]
+ * @param {string} [options.projectKey]
+ * @returns {Promise<boolean>}
+ */
+export async function canResolveSonarProjectKey(config, options = {}) {
+  const explicit = String(
+    options.projectKey || process.env.KJ_SONAR_PROJECT_KEY || config?.sonarqube?.project_key || ""
+  ).trim();
+  if (explicit) return true;
+  // try/catch (instead of `.catch(...)`) tolerates two legitimate test
+  // realities: a runCommand mock that returns undefined, and a real
+  // promise rejection from a missing git binary. Either way we treat
+  // it as "no remote available" and let the caller skip Sonar cleanly.
+  let remote;
+  try { remote = await runCommand("git", ["config", "--get", "remote.origin.url"]); }
+  catch { return false; }
+  if (!remote) return false;
+  return remote.exitCode === 0 && String(remote.stdout || "").trim().length > 0;
+}

package/src/types/session.js

@@ -64,7 +64,8 @@
  * @property {string[]} [skillsRecommended]               - wouldHaveUsed when openskills missing
  * @property {string[]} [autoInstalledSkills]
  * @property {RtkSavings} [rtk_savings]
- * @property {string} [session_start_sha]
+ * @property {string} [session_start_sha]                 - baseline for `git diff`; may be the empty-tree SHA when no prior commits exist
+ * @property {string} [head_at_start]                     - actual HEAD when the run started; used by the post-loop journal to enumerate commits produced BY the run. Falls back to session_start_sha in zero-commits repos. (2026-05-07 dogfooding fix.)
  * @property {string} [_journalDir]                       - runtime journal path
  * @property {string[]} [_journalIterations]              - rendered iteration markdown
  * @property {string[]} [_journalFiles]

package/src/utils/display/session-summary.js

@@ -26,9 +26,19 @@ function printSessionPlanner(planner) {
   }
 }
 
-function printSessionSonar(sonar) {
+export function printSessionSonar(sonar) {
   if (!sonar) return;
-  const gateLabel = sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
+  // Three buckets so the banner reads correctly:
+  //   - OK                                 \u2192 green (real pass).
+  //   - SKIPPED / PENDING                  \u2192 gray (informational; sonar
+  //     wasn't gated against, this is NOT a fail). Pre-2026-05-07 N4
+  //     dogfooding these were rendered red, which made a clean run
+  //     look like a sonar failure during the live demo.
+  //   - everything else (ERROR, WARN, ...) \u2192 red (real fail).
+  let gateLabel;
+  if (sonar.gateStatus === "OK") gateLabel = ANSI.green;
+  else if (sonar.gateStatus === "SKIPPED" || sonar.gateStatus === "PENDING") gateLabel = ANSI.gray;
+  else gateLabel = ANSI.red;
   console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
   if (typeof sonar.issuesInitial === "number" || typeof sonar.issuesResolved === "number") {
     const issuesInitial = sonar.issuesInitial ?? sonar.openIssues ?? 0;

package/src/utils/git.js

@@ -65,6 +65,42 @@ export async function revParse(ref) {
   return runGit(["rev-parse", ref]);
 }
 
+/**
+ * List commits in the range `fromSha..toRef`. Used by the post-loop
+ * journal builder to enumerate every commit produced during a `kj run`
+ * — both the coder's own commits AND the post-loop scaffold commit —
+ * so the user-visible summary doesn't lose track of them. Pre-fix the
+ * summary only listed `gitResult.commits` (post-loop only), which made
+ * `kj run "..."` runs look like the coder hadn't committed.
+ *
+ * Returns oldest-first so the list reads in execution order.
+ *
+ * @param {string|null|undefined} fromSha The SHA right BEFORE the run started
+ *   (typically `session.session_start_sha`). Empty/missing → returns [].
+ * @param {string} [toRef="HEAD"]
+ * @returns {Promise<Array<{hash: string, message: string}>>}
+ */
+export async function listCommitsBetween(fromSha, toRef = "HEAD") {
+  if (!fromSha) return [];
+  const result = await run(
+    "git",
+    ["log", "--reverse", "--format=%H%x09%s", `${fromSha}..${toRef}`],
+  ).catch(() => null);
+  if (!result || result.exitCode !== 0) return [];
+  return String(result.stdout || "")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const tabIdx = line.indexOf("\t");
+      // Defensive: if git emitted no tab (shouldn't happen with our format)
+      // treat the whole line as the hash and leave the message empty rather
+      // than throw — caller can still render the row.
+      if (tabIdx === -1) return { hash: line, message: "" };
+      return { hash: line.slice(0, tabIdx), message: line.slice(tabIdx + 1) };
+    });
+}
+
 export async function syncBaseBranch({ baseBranch, autoRebase }) {
   const local = await revParse(baseBranch);
   const remote = await revParse(`origin/${baseBranch}`);
@@ -109,11 +145,79 @@ export async function hasChanges() {
   return status.length > 0;
 }
 
+/**
+ * Return the relative paths of every uncommitted change (modified,
+ * untracked, staged, etc.) in the working tree. Each path is the
+ * filename as `git status --porcelain` reports it (after the 2-char
+ * status code + space). Returns an empty array when the tree is clean.
+ *
+ * Used by `finalizeGitAutomation` to decide whether the changes
+ * pending at the end of a pipeline are exclusively Karajan
+ * scaffolding (and thus deserve a `chore:` commit message instead
+ * of inheriting the user task's `feat:`).
+ *
+ * NOTE: bypasses `runGit()` because that helper trims stdout, which
+ * eats the leading space of porcelain lines whose first status char
+ * is " " (e.g. " M .gitignore" → "M .gitignore"). The leading space
+ * is structural here — without it the slice(3) below would crop one
+ * character off the first path.
+ */
+export async function listPendingPaths() {
+  const res = await run("git", ["status", "--porcelain"]);
+  if (res.exitCode !== 0) {
+    throw new Error(`git status --porcelain failed: ${res.stderr || res.stdout}`);
+  }
+  const stdout = res.stdout;
+  if (!stdout) return [];
+  const lines = stdout.split("\n").map((l) => l.replace(/\r$/, "")).filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    // Each line is "XY <path>" (XY = 2-char status, space, path).
+    // Renames look like "R  old -> new"; we want the new path.
+    const after = line.slice(3);
+    const arrow = after.indexOf(" -> ");
+    out.push(arrow !== -1 ? after.slice(arrow + 4) : after);
+  }
+  return out;
+}
+
+// Locale-tolerant detection of "git commit refused because the working
+// tree was already clean by the time we ran it". Observed in N4
+// dogfooding (2026-05-07) — `hasChanges()` reported true after `add -A`
+// but `git commit` then failed with the Spanish message "nada para hacer
+// commit, el árbol de trabajo está limpio". The race window is real:
+// post-loop journal writes can finish between hasChanges and commit, and
+// some files come back from `add -A` with no diff vs HEAD even though
+// they show up in `git status --porcelain`. We treat any of those as
+// "no commit needed" rather than escalating to Solomon.
+const NOTHING_TO_COMMIT_PATTERNS = [
+  /nothing to commit/i,
+  /nada para hacer commit/i,         // git in es_ES locale
+  /no hay nada para confirmar/i,     // git in es_ES alt phrasing
+  /aucune modification ajout[ée]e au commit/i, // fr_FR
+  /nichts zu committen/i,            // de_DE
+];
+function isNothingToCommit(message) {
+  const m = String(message || "");
+  return NOTHING_TO_COMMIT_PATTERNS.some((re) => re.test(m));
+}
+
 export async function commitAll(message) {
   await runGit(["add", "-A"]);
   const changed = await hasChanges();
   if (!changed) return { committed: false };
-  await runGit(["commit", "-m", message]);
+  try {
+    await runGit(["commit", "-m", message]);
+  } catch (err) {
+    // `git status --porcelain` and `git commit` disagreed about whether
+    // there was anything to commit. Don't escalate — the only outcome
+    // either way is "no new commit was created", which the caller
+    // already handles via committed=false.
+    if (isNothingToCommit(err?.message)) {
+      return { committed: false };
+    }
+    throw err;
+  }
   const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"]);
   const [hash, commitMessage] = raw.split("\x1f");
   return { committed: true, commit: { hash, message: commitMessage } };