karajan-code 2.10.1 → 2.11.0

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/sonar/token-bootstrap.js

@@ -0,0 +1,182 @@
+/**
+ * Sonar token bootstrap (KJC-TSK-0367).
+ *
+ * On `kj init`, after the SonarQube container is up, try to generate the
+ * analysis token via the REST API instead of asking the user to walk
+ * through the web UI manually. The bootstrapper:
+ *
+ *   1. Probes the host with admin/admin (the container default).
+ *   2. If login succeeds AND the password is still default, it rotates
+ *      the password to a freshly generated value and persists that to
+ *      `~/.karajan/sonar.admin-password` (mode 0600). This avoids
+ *      leaving the deployment with the well-known default credentials.
+ *   3. Generates a Global Analysis Token named `karajan-cli` via
+ *      `POST /api/user_tokens/generate` and returns it.
+ *   4. Persists the token to `~/.karajan/sonar.token` (mode 0600). The
+ *      caller writes it into `config.sonarqube.token` separately.
+ *
+ * On any HTTP error, we return `{ ok: false, reason }` and let the
+ * caller fall back to the manual-flow instructions that existed before
+ * this card. We never throw — the wizard must keep going.
+ */
+
+import { writeFileSync, chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getKarajanHome } from "../utils/paths.js";
+import path from "node:path";
+
+const DEFAULT_USER = "admin";
+const DEFAULT_PASS = "admin";
+const TOKEN_NAME = "karajan-cli";
+
+/**
+ * @param {string} host        e.g. http://localhost:9000
+ * @param {string} pathname    "/api/..."
+ * @param {object} opts
+ * @param {"GET"|"POST"} [opts.method="GET"]
+ * @param {Record<string,string>} [opts.form]   form-urlencoded body
+ * @param {string} opts.user
+ * @param {string} opts.pass
+ * @returns {Promise<{ status: number, body: any }>}
+ */
+async function call(host, pathname, opts) {
+  const url = host.replace(/\/$/, "") + pathname;
+  const headers = {
+    Authorization: "Basic " + Buffer.from(`${opts.user}:${opts.pass}`).toString("base64"),
+  };
+  let body;
+  if (opts.method === "POST" && opts.form) {
+    headers["Content-Type"] = "application/x-www-form-urlencoded";
+    body = new URLSearchParams(opts.form).toString();
+  }
+  const res = await fetch(url, { method: opts.method || "GET", headers, body });
+  let parsed = null;
+  const text = await res.text();
+  if (text) {
+    try { parsed = JSON.parse(text); } catch { parsed = text; }
+  }
+  return { status: res.status, body: parsed };
+}
+
+/**
+ * Generate a strong (32-byte hex) random password. We never re-use the
+ * default `admin` password and never persist `admin` to disk.
+ */
+function generatePassword() {
+  return randomBytes(24).toString("base64url");
+}
+
+/**
+ * Persist a value at `~/.karajan/<filename>` with mode 0600.
+ */
+function persistSecret(filename, value) {
+  const home = getKarajanHome();
+  const target = path.join(home, filename);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, value, { mode: 0o600 });
+  try { chmodSync(target, 0o600); } catch { /* best-effort on Windows */ }
+  return target;
+}
+
+/**
+ * Bootstrap the Sonar analysis token. Idempotent: if the
+ * `karajan-cli` token already exists Sonar will refuse to create it
+ * again (HTTP 400 with `"errors":[{"msg":"A user token...exists"}]`).
+ * In that case we delete-and-recreate so kj init always returns a
+ * usable token.
+ *
+ * @param {object} opts
+ * @param {string} opts.host           Default http://localhost:9000
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   token?: string,
+ *   savedTo?: string,
+ *   passwordRotated?: boolean,
+ *   passwordSavedTo?: string,
+ *   reason?: string,
+ * }>}
+ */
+export async function bootstrapSonarToken({ host = "http://localhost:9000" } = {}) {
+  let user = DEFAULT_USER;
+  let pass = DEFAULT_PASS;
+  let passwordRotated = false;
+  let passwordSavedTo = null;
+
+  // 1) Probe: does admin/admin still work?
+  const probe = await call(host, "/api/authentication/validate", { user, pass }).catch((err) => ({ status: 0, body: err.message }));
+  if (probe.status === 0) {
+    return { ok: false, reason: `network error reaching ${host}: ${probe.body}` };
+  }
+  if (probe.status === 401 || (probe.body && probe.body.valid === false)) {
+    return { ok: false, reason: "admin/admin login failed (password may already be customized — set sonarqube.token manually)" };
+  }
+
+  // 2) Rotate the default password if it's still in place. This stops
+  //    the well-known credentials from being a stable attack surface
+  //    on this user's machine.
+  const newPass = generatePassword();
+  const change = await call(host, "/api/users/change_password", {
+    method: "POST",
+    user,
+    pass,
+    form: { login: user, previousPassword: pass, password: newPass },
+  }).catch((err) => ({ status: 0, body: err.message }));
+
+  if (change.status === 204 || change.status === 200) {
+    pass = newPass;
+    passwordRotated = true;
+    passwordSavedTo = persistSecret("sonar.admin-password", pass);
+  } else if (change.status === 400 && Array.isArray(change.body?.errors)
+              && change.body.errors.some(e => /default/i.test(e.msg))) {
+    // Sonar complained the password matches a default — rare. Try with
+    // a longer one.
+    const longerPass = generatePassword() + generatePassword();
+    const retry = await call(host, "/api/users/change_password", {
+      method: "POST",
+      user,
+      pass,
+      form: { login: user, previousPassword: pass, password: longerPass },
+    }).catch(() => ({ status: 0 }));
+    if (retry.status === 204 || retry.status === 200) {
+      pass = longerPass;
+      passwordRotated = true;
+      passwordSavedTo = persistSecret("sonar.admin-password", pass);
+    }
+  } else if (change.status !== 0 && change.status !== 401) {
+    // Non-fatal: probably the admin already changed the password. We
+    // continue using whatever credentials worked at the probe step.
+  }
+
+  // 3) Token already exists? Revoke it so we can re-create cleanly.
+  await call(host, "/api/user_tokens/revoke", {
+    method: "POST",
+    user,
+    pass,
+    form: { name: TOKEN_NAME },
+  }).catch(() => { /* token may not exist — that's fine */ });
+
+  // 4) Generate the analysis token.
+  const gen = await call(host, "/api/user_tokens/generate", {
+    method: "POST",
+    user,
+    pass,
+    form: { name: TOKEN_NAME, type: "GLOBAL_ANALYSIS_TOKEN" },
+  }).catch((err) => ({ status: 0, body: err.message }));
+
+  if (gen.status !== 200 || !gen.body?.token) {
+    const detail = gen.body?.errors?.[0]?.msg || gen.body || `HTTP ${gen.status}`;
+    return { ok: false, reason: `token generation failed: ${detail}`, passwordRotated, passwordSavedTo };
+  }
+
+  const token = gen.body.token;
+  const savedTo = persistSecret("sonar.token", token);
+
+  return {
+    ok: true,
+    token,
+    savedTo,
+    passwordRotated,
+    passwordSavedTo: passwordRotated ? passwordSavedTo : null,
+  };
+}

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]