karajan-code 2.7.4 → 2.9.0

package/src/sonar/discovery.js

@@ -0,0 +1,123 @@
+/**
+ * Discover running SonarQube containers regardless of the user's
+ * config. The point: never bother the user about port 9000 being
+ * "occupied by an unknown process" — if there's a Sonar already up
+ * somewhere, just point at it and move on.
+ *
+ * The previous preflight check insisted on owning port 9000 by name
+ * (`karajan-sonarqube`). If you happened to have a `sonarqube` from
+ * another project running on 9000 (or had pulled a different image
+ * tag), we'd error out asking the user to "stop the conflicting
+ * process". That's busywork — Sonar is Sonar; reuse what's there.
+ *
+ * The discovery strategy:
+ *   1. List Docker containers whose image looks like sonarqube
+ *      (image-name regex / ancestor filter — covers `sonarqube`,
+ *      `sonarqube:community`, `sonarqube:lts`, `sonarqube:9.9`, …).
+ *   2. Parse the published host port (`0.0.0.0:9001->9000/tcp`).
+ *   3. Optionally HTTP-probe to confirm it's actually serving
+ *      `/api/system/status` so a misnamed image can't hijack us.
+ */
+
+import { runCommand } from "../utils/process.js";
+import { isSonarReachable } from "./manager.js";
+
+/**
+ * @typedef {Object} DiscoveredSonar
+ * @property {boolean} found
+ * @property {string} [containerName]
+ * @property {string} [image]
+ * @property {number} [port]    - host port (what we connect to)
+ * @property {string} [host]    - http://localhost:<port>
+ * @property {boolean} [reachable] - true after a successful HTTP probe
+ */
+
+/**
+ * Parse the Ports column from `docker ps`. Looks for any host binding
+ * that maps to the container's `internalPort` (default 9000).
+ * Examples:
+ *   "0.0.0.0:9000->9000/tcp"        → 9000
+ *   "127.0.0.1:9001->9000/tcp"      → 9001
+ *   "9000/tcp"                      → null (no host binding)
+ *   "0.0.0.0:9000->9000/tcp, 9092/tcp" → 9000
+ *
+ * @param {string} portsStr
+ * @param {number} [internalPort=9000]
+ * @returns {number|null}
+ */
+export function extractHostPort(portsStr, internalPort = 9000) {
+  if (!portsStr) return null;
+  const re = new RegExp(
+    `(?:0\\.0\\.0\\.0|127\\.0\\.0\\.1|::|\\[::\\]):(\\d+)\\s*->\\s*${internalPort}\\/tcp`,
+    "g"
+  );
+  const matches = [...portsStr.matchAll(re)];
+  if (matches.length === 0) return null;
+  // Prefer the smallest port number (likeliest the "main" binding);
+  // arbitrary but deterministic.
+  return Math.min(...matches.map((m) => Number(m[1])));
+}
+
+/**
+ * Run `docker ps` with a list-of-images filter and parse the result.
+ * Returns the FIRST container with a usable host port, or null.
+ *
+ * @returns {Promise<DiscoveredSonar|null>}
+ */
+async function dockerPsForSonar() {
+  // List all running containers with their image so we can image-match
+  // ourselves. Cheap (single docker call) and tolerant of image tags.
+  const res = await runCommand("docker", [
+    "ps",
+    "--format", "{{.ID}}|{{.Names}}|{{.Image}}|{{.Ports}}",
+  ]);
+  if (res.exitCode !== 0 || !res.stdout?.trim()) return null;
+
+  const lines = res.stdout.trim().split("\n");
+  for (const line of lines) {
+    const [, name, image, ports] = line.split("|");
+    if (!image) continue;
+    if (!/sonarqube/i.test(image)) continue;
+    const port = extractHostPort(ports, 9000);
+    if (!port) continue;
+    return {
+      found: true,
+      containerName: name,
+      image,
+      port,
+      host: `http://localhost:${port}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Public entry point: find a usable, reachable Sonar.
+ *
+ * `probe`: when true (default) HTTP-pings `/api/system/status` to
+ * confirm the container is actually serving Sonar. Tests can disable
+ * the probe for hermetic mocking.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.probe=true]
+ * @param {number} [opts.healthcheckSeconds=5]
+ * @returns {Promise<DiscoveredSonar>}
+ */
+export async function discoverRunningSonar(opts = {}) {
+  const { probe = true, healthcheckSeconds = 5 } = opts;
+  let candidate;
+  try {
+    candidate = await dockerPsForSonar();
+  } catch {
+    candidate = null;
+  }
+  if (!candidate) return { found: false };
+  if (!probe) return { ...candidate, reachable: true };
+  let reachable;
+  try {
+    reachable = await isSonarReachable(candidate.host, healthcheckSeconds);
+  } catch {
+    reachable = false;
+  }
+  return { ...candidate, reachable };
+}

package/src/sonar/manager.js

@@ -87,6 +87,24 @@ export async function sonarUp(hostOverride = null) {
     };
   }
 
+  // Discover-before-spawn (v2.7.5): if there's already a SonarQube
+  // container running anywhere — even under a different name on a
+  // different port — reuse it instead of spinning up a second one.
+  // Avoids the user accidentally accumulating Sonar containers across
+  // projects, and matches what the port preflight check already does.
+  const { discoverRunningSonar } = await import("./discovery.js");
+  const discovered = await discoverRunningSonar({
+    healthcheckSeconds: sonarConfig.timeouts.healthcheckSeconds,
+  });
+  if (discovered.found && discovered.reachable) {
+    return {
+      exitCode: 0,
+      stdout: `Reusing existing SonarQube container "${discovered.containerName}" at ${discovered.host} (skipping container start).`,
+      stderr: "",
+      reusedHost: discovered.host,
+    };
+  }
+
   const compose = await ensureComposeFile(config.sonarqube);
   return runCommand("docker", ["compose", "-f", compose, "up", "-d"], { timeout: sonarConfig.timeouts.composeUpMs });
 }

package/src/sync/detect-drift.js

@@ -0,0 +1,113 @@
+/**
+ * kj sync — drift detection between code and the Canvas / plan
+ * (issue #540, MVP).
+ *
+ * Scope of THIS module: pure data transformation. Given a plan
+ * (with Operations and their file_hints) plus a list of currently
+ * tracked source files (mtime + path), classify each file:
+ *
+ *   - covered      — file IS referenced by some Operation's file_hint
+ *                    AND was modified since the plan was created.
+ *                    (Expected drift; plan still authoritative.)
+ *   - untracked    — file exists, modified, but no Operation references
+ *                    it. The user added it manually after the run; the
+ *                    Canvas needs a new Operation to reflect it.
+ *   - missing      — Operation references a file that no longer exists
+ *                    on disk. Either the file was deleted or the plan
+ *                    is wrong about its location.
+ *   - clean        — file is referenced by an Operation AND has not
+ *                    been modified since the plan. No action needed.
+ *
+ * The classifier is pure: caller does the I/O (walking the tree,
+ * stating files, parsing plan JSON). Easy to unit-test.
+ */
+
+/**
+ * @param {object} plan — plan JSON with `operations` (or `hus`) carrying
+ *                        optional `file_hint` strings, and `createdAt` ISO
+ * @param {Array<{path: string, mtime: Date}>} files — files in the project
+ * @returns {{ covered: object[], untracked: object[], missing: object[], clean: object[] }}
+ */
+export function classifyDrift(plan, files) {
+  const planMtime = new Date(plan?.createdAt || plan?.updatedAt || 0);
+
+  // Collect every file_hint declared by any operation/HU. Both keys
+  // are accepted for back-compat with v2 plans (HUs) and Canvas
+  // (Operations).
+  const ops = Array.isArray(plan?.operations) ? plan.operations
+    : Array.isArray(plan?.hus) ? plan.hus
+    : [];
+  const hinted = new Map(); // file → operation index
+  ops.forEach((op, idx) => {
+    const hint = op.file_hint || op.fileHint;
+    if (typeof hint === "string" && hint.length > 0) {
+      hinted.set(hint, idx);
+    }
+  });
+
+  const out = { covered: [], untracked: [], missing: [], clean: [] };
+  const seenInFs = new Set();
+
+  for (const f of files) {
+    if (!f?.path) continue;
+    seenInFs.add(f.path);
+    const opIdx = hinted.get(f.path);
+    const modified = f.mtime instanceof Date && f.mtime > planMtime;
+
+    if (opIdx === undefined) {
+      // Not referenced by any operation. Two sub-cases:
+      //  - modified: real drift, propose new operation.
+      //  - not modified: probably a pre-existing file from before the
+      //    plan; ignore (no action).
+      if (modified) {
+        out.untracked.push({ path: f.path, mtime: f.mtime, suggestion: "new operation" });
+      }
+      continue;
+    }
+    if (modified) {
+      out.covered.push({ path: f.path, mtime: f.mtime, operationIndex: opIdx });
+    } else {
+      out.clean.push({ path: f.path, operationIndex: opIdx });
+    }
+  }
+
+  // Missing: operation says a file should exist, but we never saw it.
+  for (const [hint, opIdx] of hinted.entries()) {
+    if (!seenInFs.has(hint)) {
+      out.missing.push({ path: hint, operationIndex: opIdx, suggestion: "remove operation OR fix the file_hint" });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Render a drift report as plain-text for the terminal.
+ */
+export function formatDriftReport(report, plan) {
+  const lines = [`Drift report — plan ${plan?.planId || "(unknown)"}`, ""];
+  if (report.untracked.length === 0 && report.missing.length === 0 && report.covered.length === 0) {
+    lines.push("  No drift detected.");
+    return lines.join("\n");
+  }
+  if (report.covered.length > 0) {
+    lines.push(`Covered (${report.covered.length}) — modified, an Operation references it; consider extending its Approach:`);
+    for (const c of report.covered) lines.push(`  ~ ${c.path}  [op #${c.operationIndex + 1}]`);
+    lines.push("");
+  }
+  if (report.untracked.length > 0) {
+    lines.push(`Untracked (${report.untracked.length}) — modified, NO Operation references it; propose new Operation:`);
+    for (const u of report.untracked) lines.push(`  + ${u.path}`);
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push(`Missing (${report.missing.length}) — Operation file_hint points at a file that doesn't exist:`);
+    for (const m of report.missing) lines.push(`  ! ${m.path}  [op #${m.operationIndex + 1}] — ${m.suggestion}`);
+    lines.push("");
+  }
+  if (report.clean.length > 0) {
+    lines.push(`Clean (${report.clean.length}) — covered, unchanged.`);
+  }
+  lines.push("", "Run with --json for machine-readable output. Future: --apply to propose Canvas patches (issue #540 follow-ups).");
+  return lines.join("\n");
+}

package/src/tracker-bootstrap.js

@@ -0,0 +1,44 @@
+/**
+ * Tracker bootstrap — registers the configured task-tracker adapter into
+ * the orchestrator's integrations registry at runtime.
+ *
+ * This module exists so that `src/orchestrator/` never imports
+ * `src/planning-game/` (or any other tracker) directly — the architecture
+ * invariant `tests/architecture/tracker-coupling.test.js` enforces that.
+ * `runFlow` calls `ensureTrackerRegistered(config)` from here; this
+ * module owns the conditional import of each adapter.
+ *
+ * Adding a new tracker:
+ *   1. Write `src/adapters/<name>/adapter.js` with the hook surface
+ *      documented in `src/orchestrator/integrations.js`.
+ *   2. Add a branch below that imports and registers it when the relevant
+ *      config flag is true.
+ *
+ * The function is idempotent: once registered, subsequent calls are
+ * no-ops (the registry already has an entry for the slot).
+ */
+
+import { getIntegration, registerIntegration } from "./orchestrator/integrations.js";
+
+/**
+ * Ensure the tracker adapter configured by `config` is registered under
+ * the `"tracker"` slot. Safe to call on every `runFlow` invocation.
+ *
+ * @param {object|null} config
+ * @returns {Promise<void>}
+ */
+export async function ensureTrackerRegistered(config) {
+  if (getIntegration("tracker")) return; // Already registered.
+
+  if (config?.planning_game?.enabled) {
+    try {
+      const { planningGameAdapter } = await import("./planning-game/pipeline-adapter.js");
+      registerIntegration("tracker", planningGameAdapter);
+    } catch { /* registration failed — non-blocking, adapter stays absent */ }
+    return;
+  }
+
+  // No tracker enabled — the orchestrator's `getIntegration("tracker")`
+  // calls will return undefined and every hook becomes an optional-chain
+  // no-op. That's the intended behavior for "tracker disabled" runs.
+}

package/src/utils/agent-detect.js

@@ -18,17 +18,21 @@ export async function checkBinary(name, versionArg = "--version") {
 }
 
 export async function detectAvailableAgents() {
-  const results = [];
-  for (const agent of KNOWN_AGENTS) {
-    const check = await checkBinary(agent.name);
-    results.push({
-      name: agent.name,
-      available: check.ok,
-      version: check.ok ? check.version : null,
-      install: agent.install
-    });
-  }
-  return results;
+  // PR-J (audit quick win): probe the 5 agent binaries in parallel
+  // via Promise.all instead of awaiting in a for-of. checkBinary is
+  // a pure shell-out (no shared state), so serialising them was
+  // wasted latency. With 5 agents at ~80ms each: O(n) → O(1).
+  return Promise.all(
+    KNOWN_AGENTS.map(async (agent) => {
+      const check = await checkBinary(agent.name);
+      return {
+        name: agent.name,
+        available: check.ok,
+        version: check.ok ? check.version : null,
+        install: agent.install
+      };
+    })
+  );
 }
 
 /**

package/src/utils/board-prompt-bridge.js

@@ -0,0 +1,109 @@
+/**
+ * File-based RPC between a non-interactive Karajan run and the HU
+ * Board. When the runner needs an answer to a question (Solomon
+ * escalation, max-iterations resolution, anything wired to
+ * askQuestion) and stdin is unavailable (the board's ▶ Run plan
+ * spawns with stdio=ignore), it writes a prompt JSON to a known
+ * directory and polls for an "answer" sibling file. The board's
+ * chokidar watcher sees the prompt and surfaces it as a modal; the
+ * user's answer is POSTed back, written as the answer file, and the
+ * runner picks it up and resolves.
+ *
+ * Why files instead of a socket / SSE-back-channel:
+ *   - Zero new server in the runner. A detached child has no listening
+ *     port; opening one would mean discovery + auth + cleanup.
+ *   - Survives a runner restart: if the user kills + resumes, the
+ *     pending prompt is still on disk and the board can re-show it.
+ *   - The board already watches `~/.karajan/`; one more glob is cheap.
+ *
+ * Layout:
+ *   $KJ_HOME/prompts/<promptId>.json         - { sessionId, question, context, createdAt }
+ *   $KJ_HOME/prompts/<promptId>.answer.json  - { answer, answeredAt }    (written by board)
+ *
+ * The bridge owns the lifecycle: write the prompt, poll until the
+ * answer arrives, delete BOTH files, return the answer string (or
+ * null when the user picked "stop"). Aborts cleanly on signal or on
+ * a configurable timeout (default 30 min — long enough for a coffee).
+ */
+
+import { mkdir, writeFile, readFile, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;          // 30 min
+
+function getPromptsDir() {
+  const home = process.env.KJ_HOME || join(homedir(), ".karajan");
+  return join(home, "prompts");
+}
+
+function exists(path) {
+  return stat(path).then(() => true, () => false);
+}
+
+/**
+ * Publish a prompt + wait for the answer. Returns the answer string,
+ * `null` when the user explicitly picked "stop", or rejects on
+ * timeout / abort.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.question
+ * @param {object} [args.context]   - serialised verbatim into the prompt JSON
+ * @param {number} [args.timeoutMs]
+ * @param {AbortSignal} [args.signal]
+ * @param {object} [args.logger]    - { info, warn } — optional, for breadcrumbs
+ * @returns {Promise<string|null>}
+ */
+export async function askThroughBoard({ sessionId, question, context = null, timeoutMs = DEFAULT_TIMEOUT_MS, signal = null, logger = null } = {}) {
+  if (!question) throw new Error("askThroughBoard: question is required");
+
+  const dir = getPromptsDir();
+  await mkdir(dir, { recursive: true });
+
+  const promptId = `prompt-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const promptPath = join(dir, `${promptId}.json`);
+  const answerPath = join(dir, `${promptId}.answer.json`);
+
+  const payload = {
+    promptId,
+    sessionId: sessionId || null,
+    question,
+    context: context || null,
+    createdAt: new Date().toISOString(),
+  };
+  await writeFile(promptPath, JSON.stringify(payload, null, 2), "utf-8");
+  logger?.info?.(`[prompt-bridge] published ${promptId} — waiting for answer via the board`);
+
+  const startedAt = Date.now();
+  try {
+    while (true) {
+      if (signal?.aborted) throw new Error("askThroughBoard: aborted");
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`askThroughBoard: timed out after ${Math.round(timeoutMs / 1000)}s waiting for answer to ${promptId}`);
+      }
+      if (await exists(answerPath)) {
+        const raw = await readFile(answerPath, "utf-8");
+        let answer;
+        try { ({ answer } = JSON.parse(raw)); } catch { answer = null; }
+        await unlink(answerPath).catch(() => {});
+        await unlink(promptPath).catch(() => {});
+        if (typeof answer === "string" && answer.trim().toLowerCase() === "stop") return null;
+        return typeof answer === "string" ? answer.trim() : null;
+      }
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+  } catch (err) {
+    // Best-effort cleanup of the prompt file on error so it doesn't
+    // get stuck pending on the board forever.
+    await unlink(promptPath).catch(() => {});
+    throw err;
+  }
+}
+
+/** Test seam — exposes the resolved prompts dir for assertions. */
+export function _getPromptsDirForTests() {
+  return getPromptsDir();
+}

package/src/utils/cli-progress.js

@@ -0,0 +1,161 @@
+/**
+ * CLI progress reporter — prints live agent activity to the terminal while
+ * an agent (planner, coder, reviewer, auditor, …) is thinking.
+ *
+ * Context: commands like `kj plan --task-file spec.md` used to call
+ * `agent.runTask(...)` without an `onOutput` callback. The CLI then hung
+ * for 30 s – 3 min with zero feedback until a line like "Plan saved: …"
+ * finally appeared. Users assumed the command had deadlocked.
+ *
+ * This helper gives every CLI command the same live feedback the `kj run`
+ * orchestrator already emits: a header with role + start, a stream of
+ * tool calls / short text lines as the agent works, and a footer with
+ * outcome + elapsed time. It wraps `onOutput` so every command can pass
+ * `createCliProgressReporter({ role: "planner" }).onOutput` straight
+ * into the agent's runTask / reviewTask call.
+ *
+ * Output shape:
+ *
+ *   [planner] starting...
+ *     ▸ Read SPEC.md
+ *     ▸ Grep "architecture"
+ *     · Analyzing sections 1–5…
+ *     ▸ Write plan.json
+ *   [planner] done (42.8s)
+ *
+ * Design notes:
+ *   - Writes to `process.stderr` by default (so stdout is reserved for
+ *     structured output like `--json` mode).
+ *   - `onOutput` is shaped as `{ stream, line, kind }` to match the
+ *     contract Claude's `createStreamJsonFilter` emits — so passing
+ *     this reporter's `onOutput` into a runTask{…, onOutput} call Just
+ *     Works with Claude, Codex, Gemini, Aider and OpenCode (each one's
+ *     agent wrapper already normalizes its CLI's stream format into
+ *     that shape).
+ *   - `kind` is optional; when absent the default bullet is used.
+ *   - `quiet: true` turns the reporter into a no-op (useful when the
+ *     command is running under `--json` and should not pollute stdout).
+ */
+
+const ICONS = {
+  tool: "▸",      // ▸ right-pointing small triangle
+  text: "·",      // · middle dot
+  thinking: "…",  // …
+  heartbeat: "⠿", // braille dots — distinct from real activity icons
+};
+
+/**
+ * Rotating idle messages so the user knows the process is alive without
+ * the same string repeating every minute. Picked at random each tick;
+ * the previous one is held back so two ticks in a row never duplicate.
+ */
+const HEARTBEAT_LINES = [
+  "still working…",
+  "thinking through it…",
+  "wading through tokens…",
+  "asking the model nicely…",
+  "crunching the spec…",
+  "burning down the prompt…",
+  "kneading the context window…",
+  "still here, give me a sec…",
+  "the LLM is doing LLM things…",
+  "drafting, redrafting…",
+];
+
+/**
+ * Default cadence for the idle heartbeat. ~45s is short enough to feel
+ * responsive on a quiet planner run (Claude can think for 1-2 min on a
+ * complex spec) without spamming every few seconds.
+ */
+const DEFAULT_HEARTBEAT_MS = 45_000;
+
+/**
+ * @typedef {Object} CliProgressReporter
+ * @property {(event: { stream?: string, line: string, kind?: string }) => void} onOutput
+ * @property {(outcome?: string) => void} finish
+ */
+
+/**
+ * @param {Object} [opts]
+ * @param {string} [opts.role]     - label shown in the header/footer ("planner", "auditor", …).
+ *                                   Default: "agent".
+ * @param {NodeJS.WriteStream} [opts.stream]  - output destination. Default: process.stderr.
+ * @param {boolean} [opts.quiet]   - when true, nothing is printed (useful for --json mode).
+ * @param {number}  [opts.heartbeatMs] - silent interval before printing an
+ *   "alive" line. Defaults to 45 s. Set to 0 to disable the heartbeat
+ *   (useful in tests).
+ * @returns {CliProgressReporter}
+ */
+export function createCliProgressReporter(opts = {}) {
+  const {
+    role = "agent",
+    stream = process.stderr,
+    quiet = false,
+    heartbeatMs = DEFAULT_HEARTBEAT_MS,
+  } = opts;
+
+  if (quiet) {
+    return { onOutput: () => {}, finish: () => {} };
+  }
+
+  const startedAt = Date.now();
+  stream.write(`[${role}] starting...\n`);
+
+  // Idle heartbeat: a periodic timer that prints a varied "still alive"
+  // line whenever the agent goes quiet for longer than `heartbeatMs`.
+  // Reset on every real onOutput so heavy chatter doesn't trigger the
+  // duplicate. Always elapses to a different message than last time so
+  // two consecutive ticks never read the same.
+  let lastActivityAt = Date.now();
+  let lastHeartbeatIdx = -1;
+  let heartbeatTimer = null;
+
+  function pickHeartbeatLine() {
+    let idx;
+    do {
+      idx = Math.floor(Math.random() * HEARTBEAT_LINES.length);
+    } while (idx === lastHeartbeatIdx && HEARTBEAT_LINES.length > 1);
+    lastHeartbeatIdx = idx;
+    return HEARTBEAT_LINES[idx];
+  }
+
+  function tick() {
+    const idleFor = Date.now() - lastActivityAt;
+    if (idleFor < heartbeatMs) return;        // real activity reset us
+    const elapsed = Math.round((Date.now() - startedAt) / 1000);
+    stream.write(`  ${ICONS.heartbeat} ${pickHeartbeatLine()} (${elapsed}s)\n`);
+    lastActivityAt = Date.now();              // collapse next ticks
+  }
+
+  if (heartbeatMs > 0) {
+    heartbeatTimer = setInterval(tick, heartbeatMs);
+    if (typeof heartbeatTimer.unref === "function") heartbeatTimer.unref();
+  }
+
+  const onOutput = (event) => {
+    if (!event || typeof event !== "object") return;
+    const raw = typeof event.line === "string" ? event.line : "";
+    if (!raw) return;
+    // Strip trailing newline — we re-add our own.
+    const line = raw.replace(/\s+$/, "");
+    if (!line) return;
+    lastActivityAt = Date.now();
+    const icon = ICONS[event.kind] || ICONS.text;
+    stream.write(`  ${icon} ${line}\n`);
+  };
+
+  /**
+   * @param {string} [outcome]  default "done". Use "failed", "stopped", "timeout" etc.
+   */
+  const finish = (outcome = "done") => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    const ms = Date.now() - startedAt;
+    const s = (ms / 1000).toFixed(1);
+    stream.write(`[${role}] ${outcome} (${s}s)\n`);
+  };
+
+  return { onOutput, finish };
+}

package/src/utils/cwd-confirm.js

@@ -0,0 +1,39 @@
+/**
+ * PR-F: ask the user "Run on $(pwd)?" before launching `kj run` from
+ * a terminal. Same defensive UX as `git push --force-with-lease`
+ * surfacing the branch — the user wants to know what they're aiming
+ * at before the rocket fires.
+ *
+ * The prompt is plain readline (no extra deps) and accepts any of:
+ *   y, yes, s, sí, ENTER  → true
+ *   n, no, ENTER+Esc      → false
+ *
+ * Skipped automatically by the caller when stdin/stdout are not a
+ * TTY, when --yes is set, or when --json is set. So this module is
+ * never called in CI / non-interactive contexts.
+ */
+
+import readline from "node:readline";
+
+/**
+ * @param {string} projectDir absolute path of the cwd / projectDir
+ * @returns {Promise<boolean>} true to continue, false to abort
+ */
+export async function confirmCwd(projectDir) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  // No emoji — keep terminal-safe even on basic Windows shells.
+  const question = `Karajan va a ejecutarse sobre:\n  ${projectDir}\n\n¿Continuar? [Y/n] `;
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = String(answer || "").trim().toLowerCase();
+      // Empty answer = ENTER = accept the default = yes.
+      if (trimmed === "" || trimmed === "y" || trimmed === "yes" || trimmed === "s" || trimmed === "si" || trimmed === "sí") {
+        resolve(true);
+      } else {
+        resolve(false);
+      }
+    });
+    rl.on("SIGINT", () => { rl.close(); resolve(false); });
+  });
+}