karajan-code 2.17.1 → 2.18.1

package/README.md

@@ -23,7 +23,13 @@
 
 ---
 
-> **v2.17.1 released** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
+> **v2.18.1 released** — Patch. Six user-feedback follow-ups to v2.18.0: **`kj-tail` after `kj resume`** (#772, was silent because `resume.js` skipped `withCliRunLog`); **standby waits in-process instead of exiting on a short cooldown** (#773, kj stays alive for waits ≤ 12 h and retries on its own; Ctrl+C during the wait prints `kj standby resume <id>`); **closed KJC-BUG-0040 — SEA linux binaries** (#774, was a race between `gh release create` and softprops, not `better-sqlite3` as the memory said — 60 s poll fix + `make_latest:false`); **stack bias — Python repos no longer get vitest** (#775 + #776 + #777, `detectProjectStack` finally cabled into the coder prompt, the HU auto-generator templates by language, and the synthesizer + `auto-hu-batch` take the stack from the filesystem). 4 971/4 971 tests passing across 416 files. Safe upgrade from 2.18.0.
+>
+> **v2.18.0** — Minor. Closes the **resilience audit** triggered by the public launch: 15 PRs across 5 phases hardening Karajan against the silent-failure family of bugs — *the problem is not that something fails, the problem is failing without telling the user why.* **Phase 1 — hibernation end to end** (#756–#759): a quota cap is classified as a recoverable quota class (incl. Claude Code's `"You've hit your session limit · resets 10:10pm"`); `withBrainRecovery` persists a standby JSON; the orchestrator consumes `action:"hibernate"`, seals the session `hibernated` (resumable) instead of `failed`; the last line printed is the exact resume command (`kj standby resume <id>`). **Phase 2 — don't lie** (#761–#763): `runCommand` surfaces ENOENT so a missing agent CLI gets an actionable error (not an empty one); `silenceTimeoutMs` is forwarded to every role so a hung agent is killed, not waited on forever; all 6 state-file writers go through `writeJsonAtomic` (write-temp + rename) — interrupted writes can no longer truncate plans, sessions, standby snapshots. **Phase 3 — don't lose or block** (#764–#767): a corrupt plan JSON is renamed aside with a loud warn (was silently dropped from `kj plan list`); `kj.config.yml` parse errors throw `Invalid YAML in <path>` (used to brick every kj command including `kj doctor`); `injectLoadedPlan` reconciles HUs left in `coding`/`reviewing`/`running` by a killed `kj run` (cross-checked against the run-registry); board SQLite gets `busy_timeout`, a `user_version` schema gate and corruption recovery. **Phase 4 — don't degrade silently** (#768–#769): `TriageRole` warns loudly when LLM output is unparseable (used to skip researcher/architect/security/tester with a chirpy "fallback defaults" summary); `verifyCoderOutput` distinguishes a git failure from "the coder did nothing" (`gitError` + `retryStrategy: null`) — no more iterations blaming the agent for infra. **Phase 5 — safety net** (#770): a `tests/resilience/` suite indexes every silent-failure mode and pins each one with a test, plus an end-to-end tripwire for the whole quota → hibernate → resume flow. Plus CI runs the `packages/hu-board` suite on every PR (#755). 4 959/4 959 tests passing across 416 files. Safe upgrade from 2.17.2.
+>
+> **v2.17.2** — Patch. Wires quota-exhaustion **hibernation end to end**. A `kj run` / `kj plan` that hits a provider session or usage cap used to abort the task with an opaque `UNKNOWN_FATAL`; now it suspends and tells you how to resume. **Session-limit classification (#756)**: `"You've hit your session limit · resets 10:10pm"` matched no rate-limit pattern → `session limit`/`weekly limit` added, and `parseCooldown` learns the 12-hour `resets 10:10pm` clock. **Hibernation persists (#757)**: `withBrainRecovery` only wrote `~/.kj/standby/<id>.json` with a `sessionState`, which no caller passed — new `buildStandbyState()` assembles it with an allowlisted env subset (never the full `process.env`). **Orchestrator consumes `action:"hibernate"` (#758)**: no code checked for it, so a hibernation sealed the HU `failed`; the coder/refactorer stages now stop cleanly and the session is sealed `hibernated` (resumable). **Resume hint (#759)**: a stopped run's last line is now the exact command — `kj standby resume <id>` for a hibernation, `kj resume <id>` otherwise. Plus CI now runs the `packages/hu-board` suite (#755). 4 931/4 931 tests passing across 410 files. Safe upgrade from 2.17.1.
+>
+> **v2.17.1** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
 >
 > **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
 >

package/package.json

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

package/src/brain/agent-error-classifier.js

@@ -33,7 +33,11 @@ const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 
 const AUTH_PATTERNS = /\b401\b|\b403\b|unauthorized|invalid\s+api\s+key|authentication\s+failed|expired\s+token/i;
 const SILENCED_PATTERNS = /killed\s+after\s+\d+\s*ms|silence\s*timeout|no\s+output\s+for\s+\d+/i;
-const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|daily\s+limit/i;
+// `session\s+limit` / `weekly\s+limit` cover Claude Code's usage caps
+// ("You've hit your session limit · resets 10:10pm"). Without them the
+// message fell through to UNKNOWN_FATAL and the run aborted instead of
+// hibernating until the reset.
+const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|weekly\s+limit|daily\s+limit|session\s+limit/i;
 const API_DOWN_PATTERNS = /\b50[0-4]\b|bad\s+gateway|service\s+unavailable|gateway\s+timeout|overloaded|internal\s+server\s+error/i;
 const NETWORK_PATTERNS = /ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket\s+hang\s+up|fetch\s+failed|network\s+error/i;
 

package/src/brain/standby-store.js

@@ -15,6 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { writeJsonAtomicSync } from "../utils/atomic-write.js";
 
 const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
 
@@ -56,10 +57,46 @@ export function persistStandby(state) {
     createdAt: state.createdAt || new Date().toISOString(),
     persistedAt: new Date().toISOString(),
   };
-  fs.writeFileSync(file, JSON.stringify(payload, null, 2), "utf-8");
+  writeJsonAtomicSync(file, payload);
   return file;
 }
 
+// Only these env vars are carried into the standby snapshot. NEVER
+// persist the whole `process.env` — that would leak API keys and other
+// secrets into ~/.kj/standby/*.json. `kj standby resume` re-spawns with
+// the live env merged on top, so the snapshot only needs what is needed
+// to relaunch from the right place.
+const STANDBY_ENV_ALLOWLIST = ["KJ_HOME", "HOME", "PATH"];
+
+/**
+ * Builds the `sessionState` object that `withBrainRecovery` persists when
+ * a run hibernates. Pulls the session id, the relaunch metadata and an
+ * allowlisted env subset so `kj standby resume` can re-spawn the command.
+ * @param {object} args
+ * @param {object} args.session    - the pipeline session ({ id, plan_id? })
+ * @param {object} [args.config]   - resolved config ({ projectDir?, plan? })
+ * @param {string|null} [args.huId]
+ * @returns {object|null} sessionState, or null when there is no session id
+ */
+export function buildStandbyState({ session, config = {}, huId = null } = {}) {
+  if (!session?.id) return null;
+  const env = {};
+  for (const key of STANDBY_ENV_ALLOWLIST) {
+    if (process.env[key] != null) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("KJ_") && value != null) env[key] = value;
+  }
+  return {
+    sessionId: session.id,
+    planId: session.plan_id || config.plan || null,
+    huId: huId || null,
+    argv: process.argv.slice(2),
+    cwd: config.projectDir || process.cwd(),
+    env,
+  };
+}
+
 /**
  * @param {string} sessionId
  * @returns {object|null}

package/src/brain/with-brain-recovery.js

@@ -7,7 +7,7 @@
 // puede ignorarlo (fallback a long standby capped) hasta que llegue 0414.
 
 import { classifyAgentError, ERROR_CLASS } from "./agent-error-classifier.js";
-import { persistStandby } from "./standby-store.js";
+import { persistStandby, markStandbyDone } from "./standby-store.js";
 
 const ONE_MIN = 60 * 1000;
 
@@ -20,6 +20,13 @@ export const DEFAULT_RECOVERY_POLICY = Object.freeze({
   // KJC-TSK-0415: threshold de fallback. Si retryAfter > esto Y el role
   // tiene fallback configurado → switch provider en vez de hibernar.
   fallbackWaitHoursDefault: DEFAULT_FALLBACK_WAIT_HOURS,
+  // Standby-in-process: when the cooldown is short enough we keep the
+  // process alive and `await sleepFn(retryAfter)`, then retry the
+  // agent. The user sees nothing terminal — kj just pauses. A SIGINT /
+  // SIGTERM during the wait prints `kj standby resume <id>` and exits
+  // cleanly. For waits longer than this the process exits straight
+  // away (a multi-day weekly cap is not worth keeping kj running).
+  standbyWaitHoursMax: DEFAULT_FALLBACK_WAIT_HOURS,
   classes: {
     [ERROR_CLASS.RATE_LIMIT_SHORT]: { mode: "standby", maxRetries: 3 },
     [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: { mode: "hibernate", maxRetries: 1, fallbackEligible: true },
@@ -132,10 +139,15 @@ export async function withBrainRecovery({
       }
     }
 
-    // HIBERNATE: persistir + signal action=hibernate al caller.
-    // Si el caller pasó `sessionState` (TSK-0414 PR2), persistimos el JSON
-    // automáticamente en ~/.kj/standby/<sessionId>.json. Caller decide qué
-    // hacer con action=hibernate (típicamente exit 0 para liberar memoria).
+    // HIBERNATE: the cooldown is too long for a short standby. Persist
+    // the snapshot first so a SIGINT / SIGTERM during the wait leaves a
+    // recoverable session on disk. Then either:
+    //   (a) wait in-process until cooldownUntil and retry (the common
+    //       case — daily quotas reset in a few hours), or
+    //   (b) when the wait would exceed `standbyWaitHoursMax`, return
+    //       action="hibernate" so the caller exits and the user
+    //       resumes later with `kj standby resume <id>` (weekly /
+    //       monthly caps).
     if (classPolicy.mode === "hibernate" && cls.retryAfter && cls.retryAfter > policy.hibernateThresholdMs) {
       let standbyFile = null;
       if (sessionState && sessionState.sessionId) {
@@ -147,13 +159,58 @@ export async function withBrainRecovery({
             role, provider: effectiveProvider,
             classifierMessage: cls.message,
           });
-          logger?.info?.(`[brain] hibernated session ${sessionState.sessionId} → ${standbyFile} (resume at ${cls.retryUntil})`);
         } catch (err) {
           logger?.warn?.(`[brain] failed to persist standby: ${err.message}`);
         }
       }
-      emit(emitter, "brain:hibernate-request", eventBase, { role, class: cls.class, retryUntil: cls.retryUntil, retryAfter: cls.retryAfter, standbyFile });
-      return { ok: false, action: "hibernate", recovery: cls, standbyFile };
+
+      const maxWaitMs = (policy.standbyWaitHoursMax ?? DEFAULT_FALLBACK_WAIT_HOURS) * ONE_HOUR;
+      const tooLongToWait = cls.retryAfter > maxWaitMs;
+
+      if (tooLongToWait) {
+        logger?.info?.(`[brain] hibernated session ${sessionState?.sessionId ?? "(no id)"} → ${standbyFile} (resume at ${cls.retryUntil}; wait > ${Math.round(maxWaitMs/ONE_HOUR)}h, exiting)`);
+        emit(emitter, "brain:hibernate-request", eventBase, { role, class: cls.class, retryUntil: cls.retryUntil, retryAfter: cls.retryAfter, standbyFile });
+        return { ok: false, action: "hibernate", recovery: cls, standbyFile };
+      }
+
+      // Standby-in-process: keep kj alive, sleep until the cooldown,
+      // then retry. A SIGINT / SIGTERM during the wait prints the
+      // resume command and exits — the standby JSON is already on
+      // disk so the user can pick it up later.
+      const sid = sessionState?.sessionId ?? null;
+      const onSignal = (signal) => {
+        // eslint-disable-next-line no-console
+        console.log(`\n⏸  Standby interrupted (${signal}). Resume with:`);
+        // eslint-disable-next-line no-console
+        if (sid) console.log(`     kj standby resume ${sid}`);
+        // eslint-disable-next-line no-console
+        else console.log(`     kj standby list   (no session id was assigned)`);
+        process.exit(signal === "SIGINT" ? 130 : 143);
+      };
+      const detach = () => {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+      };
+      process.once("SIGINT", onSignal);
+      process.once("SIGTERM", onSignal);
+
+      const hours = Math.round((cls.retryAfter / ONE_HOUR) * 10) / 10;
+      logger?.info?.(`[brain] ${role}: standby for ~${hours}h until ${cls.retryUntil} (Ctrl+C to detach; will resume with 'kj standby resume ${sid}').`);
+      emit(emitter, "brain:standby-wait", eventBase, { role, class: cls.class, waitMs: cls.retryAfter, retryUntil: cls.retryUntil, standbyFile });
+
+      try {
+        await sleepFn(cls.retryAfter);
+      } finally {
+        detach();
+      }
+
+      // Wait finished without an interrupt — mark the standby JSON
+      // done so it does not auto-resume from disk later.
+      if (sid) {
+        try { markStandbyDone(sid); } catch { /* ignore */ }
+      }
+      emit(emitter, "brain:standby-resumed", eventBase, { role, class: cls.class });
+      continue;
     }
 
     // STANDBY: espera hasta cooldownUntil (capado por longStandbyCapMs).

package/src/commands/plan/generate.js

@@ -11,6 +11,8 @@ import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
 import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
+import { buildStandbyState } from "../../brain/standby-store.js";
+import { printResumeHint } from "../../utils/display/resume-hint.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -61,6 +63,13 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   // self-fix iter N por delante.
   const progress = createCliProgressReporter({ role: "planner:initial", quiet: Boolean(json) });
   let result;
+  // `kj plan` has no pipeline session, so synthesise a standby id
+  // (`plan_<stamp>`). If the planner hits a quota cap, withBrainRecovery
+  // persists it and `kj standby resume` re-spawns via the saved argv.
+  const plannerSessionState = buildStandbyState({
+    session: { id: `plan_${new Date().toISOString().replaceAll(/[:.]/g, "-")}` },
+    config,
+  });
   try {
     // KJC-TSK-0413: planner inicial pasa por Brain Recovery — clasifica
     // 401/429/5xx/SILENCED/etc y decide retry/standby/hibernate/abort.
@@ -69,6 +78,7 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       taskArgs: { prompt, role: "planner", silenceTimeoutMs, timeoutMs, onOutput: progress.onOutput },
       role: "planner",
       logger,
+      sessionState: plannerSessionState,
     });
     progress.finish(result.ok ? "done" : (result.action || "failed"));
   } catch (err) {
@@ -76,6 +86,18 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     throw err;
   }
 
+  if (!result.ok && result.action === "hibernate") {
+    // Quota cap: Brain Recovery persisted a standby snapshot. Stop
+    // cleanly with a resume hint instead of throwing a generic error.
+    const hibResult = {
+      ok: false, hibernated: true,
+      sessionId: plannerSessionState?.sessionId || null,
+      standbyFile: result.standbyFile || null,
+    };
+    if (!json) printResumeHint(hibResult);
+    process.exitCode = 1;
+    return hibResult;
+  }
   if (!result.ok) throw new Error(result.error || result.output || "Planner failed");
 
   const parsed = parseMaybeJsonString(result.output);

package/src/commands/resume.js

@@ -3,6 +3,8 @@ import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
+import { registerRun, unregisterRun } from "../utils/run-registry.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -51,36 +53,55 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
   const jsonMode = flags?.json;
   const quietMode = config.output?.quiet !== false;
 
-  const emitter = new EventEmitter();
-  let activityLog = null;
+  // Same wrapper as every other CLI command — without it `.kj/run.log`
+  // is never opened during the resume and `kj-tail` stays silent
+  // (every line of the resumed run goes only to the per-session
+  // activity log + the local console). Also registers the run so the
+  // HU Board shows it as live and can offer its Stop button.
+  return withCliRunLog("resume", { projectDir: config?.projectDir, logger }, async ({ forwardProgress }) => {
+    const runId = registerRun({
+      pid: process.pid,
+      planId: flags?.plan || null,
+      huIds: null,
+      projectDir: config?.projectDir || process.cwd(),
+      source: "cli-resume",
+    });
+    const cleanupRegistry = () => { if (runId) unregisterRun(runId); };
+    process.once("exit", cleanupRegistry);
+    process.once("SIGTERM", () => { cleanupRegistry(); process.exit(143); });
+    process.once("SIGINT", () => { cleanupRegistry(); process.exit(130); });
 
-  emitter.on("progress", (event) => {
-    if (!activityLog && event.sessionId) {
-      activityLog = createActivityLog(event.sessionId);
-      logger.onLog((entry) => activityLog.write(entry));
-    }
+    const emitter = new EventEmitter();
+    let activityLog = null;
+    forwardProgress(emitter);
 
-    if (activityLog) {
-      activityLog.writeEvent(event);
-    }
+    emitter.on("progress", (event) => {
+      if (!activityLog && event.sessionId) {
+        activityLog = createActivityLog(event.sessionId);
+        logger.onLog((entry) => activityLog.write(entry));
+      }
+      if (activityLog) {
+        activityLog.writeEvent(event);
+      }
+      if (!jsonMode) {
+        printEvent(event, { quiet: quietMode });
+      }
+    });
 
-    if (!jsonMode) {
-      printEvent(event, { quiet: quietMode });
-    }
-  });
+    const askQuestion = createCliAskQuestion();
+    const result = await resumeFlow({
+      sessionId,
+      answer: answer || null,
+      config,
+      logger,
+      flags: flags || {},
+      emitter,
+      askQuestion
+    });
 
-  const askQuestion = createCliAskQuestion();
-  const result = await resumeFlow({
-    sessionId,
-    answer: answer || null,
-    config,
-    logger,
-    flags: flags || {},
-    emitter,
-    askQuestion
+    if (jsonMode || !answer) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return result;
   });
-
-  if (jsonMode || !answer) {
-    console.log(JSON.stringify(result, null, 2));
-  }
 }

package/src/commands/run.js

@@ -7,6 +7,7 @@ import { withCliRunLog } from "../utils/cli-run-log.js";
 import { registerRun, unregisterRun } from "../utils/run-registry.js";
 import { printHeader } from "../utils/display/header.js";
 import { printEvent } from "../utils/display/event-handlers.js";
+import { printResumeHint } from "../utils/display/resume-hint.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
@@ -175,6 +176,10 @@ export async function runCommandHandler({ task, config, logger, flags }) {
 
     if (jsonMode) {
       console.log(JSON.stringify(result, null, 2));
+    } else {
+      // Last line printed: if the run stopped (hibernated / paused /
+      // failed), tell the user the exact command to resume it.
+      printResumeHint(result);
     }
     return { ok: !result?.paused && result?.approved !== false };
   });

package/src/config/loader.js

@@ -28,6 +28,30 @@ import { safeParseConfig, formatConfigIssues } from "./schema.js";
 import { DEFAULTS } from "./defaults.js";
 import { resolveTestHarness } from "./test-harness.js";
 
+/**
+ * Parse a YAML config file with an actionable error message.
+ * Plain `yaml.load` throws `YAMLException: bad indentation ...` with NO
+ * file path, so a single bad edit bricked the entire CLI (including
+ * `kj doctor`, the one command meant to diagnose it). Wrapping every
+ * read site in the same prefix means the user always knows which file
+ * they need to fix.
+ * @param {string} raw - file contents
+ * @param {string} filePath - absolute path (for the error message)
+ * @returns {object}
+ */
+function parseYamlOrThrow(raw, filePath) {
+  try {
+    return yaml.load(raw, { json: true }) || {};
+  } catch (err) {
+    const detail = err?.message || String(err);
+    const e = new Error(`Invalid YAML in ${filePath}:\n  ${detail}`);
+    e.cause = err;
+    e.code = "INVALID_YAML";
+    e.path = filePath;
+    throw e;
+  }
+}
+
 export function mergeDeep(base, override) {
   const output = { ...base };
   for (const [key, value] of Object.entries(override || {})) {
@@ -56,7 +80,7 @@ export async function loadProjectConfig(projectDir = process.cwd()) {
     return null;
   }
   const raw = await fs.readFile(projectConfigPath, "utf8");
-  return yaml.load(raw, { json: true }) || {};
+  return parseYamlOrThrow(raw, projectConfigPath);
 }
 
 async function loadProjectPricingOverrides(projectDir = process.cwd()) {
@@ -66,7 +90,7 @@ async function loadProjectPricingOverrides(projectDir = process.cwd()) {
   }
 
   const raw = await fs.readFile(projectConfigPath, "utf8");
-  const parsed = yaml.load(raw, { json: true }) || {};
+  const parsed = parseYamlOrThrow(raw, projectConfigPath);
   const pricing = parsed?.budget?.pricing;
   if (!pricing || typeof pricing !== "object") {
     return null;
@@ -84,7 +108,7 @@ export async function loadConfig(projectDir) {
   const globalExists = await exists(configPath);
   if (globalExists) {
     const raw = await fs.readFile(configPath, "utf8");
-    globalConfig = yaml.load(raw, { json: true }) || {};
+    globalConfig = parseYamlOrThrow(raw, configPath);
   }
 
   // Load project config (.karajan/kj.config.yml)