karajan-code 2.17.1 → 2.18.0

package/README.md

@@ -23,7 +23,11 @@
 
 ---
 
-> **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.0 released** — 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.0",
   "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/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/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)

package/src/orchestrator/drivers/iteration-phases/coder-and-refactorer.js

@@ -18,6 +18,25 @@ import { stageRegistry } from "../../stages/stage-classes.js";
 import { runStage } from "../../stages/stage-executor.js";
 import { handleStandbyResult } from "../error-recovery.js";
 
+/**
+ * A coder/refactorer stage hit a provider quota cap and Brain Recovery
+ * hibernated the run. Turn it into a clean loop return carrying
+ * `hibernated:true` — the iteration loop and flow-runner read that to
+ * seal the session as `hibernated` (NOT `failed`) so it stays resumable.
+ */
+function hibernateReturn(stageResult, session) {
+  return {
+    action: "return",
+    result: {
+      hibernated: true,
+      sessionId: session?.id || null,
+      reason: "quota_exhausted",
+      standbyFile: stageResult.standbyFile || null,
+      recovery: stageResult.recovery || null,
+    },
+  };
+}
+
 export async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i, brainCtx }) {
   // Coder via StageRegistry (TSK-0336). canRun = coderRequired !== false; in
   // analysis-only task types coderRequired is set to false by policy, so the
@@ -25,6 +44,7 @@ export async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole
   // runFlow.
   const coderCtx = { coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i, brainCtx, pipelineFlags };
   const coderResult = await runStage(stageRegistry.get("coder"), coderCtx);
+  if (coderResult?.action === "hibernate") return hibernateReturn(coderResult, session);
   if (coderResult?.action === "pause") return { action: "return", result: coderResult.result };
   const coderStandby = await handleStandbyResult({ stageResult: coderResult, session, emitter, eventBase, i, stage: "coder", logger, config });
   if (coderStandby.handled) {
@@ -35,6 +55,7 @@ export async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole
 
   if (pipelineFlags.refactorerEnabled) {
     const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    if (refResult?.action === "hibernate") return hibernateReturn(refResult, session);
     if (refResult?.action === "pause") return { action: "return", result: refResult.result };
     const refStandby = await handleStandbyResult({ stageResult: refResult, session, emitter, eventBase, i, stage: "refactorer", logger, config });
     if (refStandby.handled) {

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -32,6 +32,7 @@ import {
   setLiveOutcomeUpdater, setPreLoopContext,
 } from "#session/mutators.js";
 import { emitProgress, makeEvent } from "#utils/events.js";
+import { listActiveRuns } from "../../../utils/run-registry.js";
 
 /**
  * @param {object} args
@@ -64,6 +65,19 @@ export async function injectLoadedPlan({ flags, updatedConfig, session, stageRes
       message: `Plan loaded: ${flags.plan}`,
       detail: { planId: flags.plan, task: loadedPlan.task, version: loadedPlan.version, huCount: loadedPlan.hus?.length || 0 }
     }));
+
+    // Zombie reconciliation: a previous run may have died mid-flight,
+    // leaving HUs stuck in coding/reviewing/running. The board-side
+    // reaper only runs inside the board; without this, a headless
+    // `kj run --plan` would refuse to pick those HUs up.
+    const reaped = await reconcilePlanHuZombies({ loadedPlan, planId: flags.plan, logger });
+    if (reaped > 0) {
+      await savePlanToDisk(projectDir, loadedPlan);
+      emitProgress(emitter, makeEvent("plan:zombies-reaped", { ...eventBase, stage: "plan" }, {
+        message: `Reset ${reaped} stale HU(s) from a previous run that did not finish`,
+        detail: { planId: flags.plan, count: reaped }
+      }));
+    }
     stageResults.researcher = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
     stageResults.architect = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
     stageResults.planner = { ok: true, summary: "Loaded from persisted plan", fromPlan: flags.plan };
@@ -122,6 +136,48 @@ export async function injectLoadedPlan({ flags, updatedConfig, session, stageRes
   }
 }
 
+/**
+ * Reset HUs that look mid-execution but have no live run behind them.
+ *
+ * Resilience audit, Phase 3 (Hallazgo A1 / status-zombi). A previous
+ * `kj run --plan` flipped HUs to `coding`/`reviewing`/`running` in the
+ * plan JSON, then died (SIGKILL, terminal closed, OOM, crash). The
+ * board-side `hu-zombie-reaper` only queries SQLite and only runs
+ * inside the board process, so the plan JSON on disk kept stale
+ * in-flight statuses forever. The next `kj run --plan` then refused to
+ * pick those HUs up.
+ *
+ * Cross-check via `run-registry`: if there is a live run with our
+ * planId, do NOT touch — that run owns the in-flight HUs. Otherwise
+ * any in-flight status with no live owner is a zombie → reset to
+ * `pending` so it can run again.
+ *
+ * Mutates `loadedPlan.hus` in place. Returns the number of HUs reset
+ * so the caller can persist + emit a progress event.
+ *
+ * @param {object} args
+ * @param {object} args.loadedPlan
+ * @param {string} args.planId
+ * @param {object} [args.logger]
+ * @returns {number}
+ */
+export function reconcilePlanHuZombies({ loadedPlan, planId, logger }) {
+  if (!Array.isArray(loadedPlan?.hus) || loadedPlan.hus.length === 0) return 0;
+  const activeRuns = listActiveRuns({ planId });
+  if (activeRuns.length > 0) return 0;
+  const ZOMBIE_STATES = new Set(["coding", "reviewing", "running"]);
+  let reaped = 0;
+  for (const hu of loadedPlan.hus) {
+    if (ZOMBIE_STATES.has(hu.status)) {
+      const previous = hu.status;
+      hu.status = "pending";
+      reaped += 1;
+      logger?.warn?.(`[plan] HU ${hu.id || hu.hu_id || "?"} was '${previous}' but no live run owns the plan — reset to 'pending'.`);
+    }
+  }
+  return reaped;
+}
+
 /**
  * Throws when any HU lacks an acceptance_tests array with at least
  * one entry. Logs + emits the same `plan:tests-missing` progress

package/src/orchestrator/flow-runner.js

@@ -74,6 +74,7 @@ import { runSecurityStage, runFinalAuditStage } from "./post-loop-stages.js";
  *   approved → "approved"
  *   paused   → "paused"
  *   cancelled → "cancelled"
+ *   hibernated → "hibernated"
  *   anything else → "failed"
  *
  * Idempotent: only writes when the current status is still "running"
@@ -95,6 +96,10 @@ export async function sealSessionStatusIfStillRunning(session, result) {
     if (result?.approved === true) target = "approved";
     else if (result?.paused === true) target = "paused";
     else if (result?.cancelled === true) target = "cancelled";
+    // A run hibernated on a provider quota cap is NOT a failure — it is
+    // suspended and resumable via `kj standby resume`. Sealing it as
+    // `failed` would let the HU-zombie reaper treat it as dead work.
+    else if (result?.hibernated === true) target = "hibernated";
     await markSessionStatus(session, target);
   } catch { /* non-blocking */ }
 }

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

@@ -18,6 +18,7 @@ import { runCoderWithFallback } from "../agent-fallback.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
+import { buildStandbyState } from "../../brain/standby-store.js";
 import { snapshotHomeTopLevel, detectNewHomeEntries, formatLeakMessage, verifyLeaksAgainstTranscript, detectTranscriptCdLeaks } from "../fs-leak-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration, brainCtx, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null }) {
@@ -66,7 +67,10 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // the plan, the rest are scoped to this HU. All four pass through
       // untouched when the caller omits them (legacy single-task runs).
       adrs, specSection, reviewerFindings, huId,
-      onOutput: coderStall.onOutput
+      onOutput: coderStall.onOutput,
+      // Lets Brain Recovery persist a standby snapshot if the coder's
+      // provider hits a quota cap mid-run (KJC hibernation wiring).
+      sessionState: buildStandbyState({ session, config, huId }),
     });
   } finally {
     coderStall.stop();
@@ -75,6 +79,21 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
 
   if (!coderExecResult.ok) {
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";
+    // Quota cap → Brain Recovery already hibernated the run and persisted
+    // the standby snapshot. Stop the stage cleanly: no fallback, no
+    // Solomon. The caller turns this into a clean run halt; the HU is NOT
+    // marked failed — it resumes via `kj standby resume`.
+    if (coderExecResult.result?.action === "hibernate") {
+      emitProgress(emitter, makeEvent("coder:hibernate", { ...eventBase, stage: "coder" }, {
+        message: "Coder hibernated — provider quota exhausted, run can be resumed",
+        detail: { standbyFile: coderExecResult.result?.standbyFile || null }
+      }));
+      return {
+        action: "hibernate",
+        standbyFile: coderExecResult.result?.standbyFile || null,
+        recovery: coderExecResult.result?.recovery || null,
+      };
+    }
     const rateLimitCheck = detectRateLimit({
       stderr: coderExecResult.result?.error || "",
       stdout: coderExecResult.result?.output || ""
@@ -190,8 +209,17 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       baseRef: session.session_start_sha,
       projectDir: config.projectDir || process.cwd()
     });
-    filesChanged = verif.filesChanged || 0;
-  } catch { /* ignore verification errors */ }
+    if (verif.gitError) {
+      // Git failed (bad baseRef, corrupt repo, git missing). Don't
+      // feed filesChanged=0 into stale detection — it would blame the
+      // coder for an infrastructure problem.
+      logger?.warn?.(`[verification-gate] Git failed, change count is unreliable: ${verif.gitError}`);
+    } else {
+      filesChanged = verif.filesChanged || 0;
+    }
+  } catch (err) {
+    logger?.warn?.(`[verification-gate] Skipped: ${err?.message || err}`);
+  }
 
   await addCheckpoint(session, { stage: "coder", iteration, note: "Coder applied changes", provider: coderRole.provider, model: coderRole.model || null, filesChanged });
   emitProgress(
@@ -245,13 +273,28 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
   const refactorerStart = Date.now();
   let refResult;
   try {
-    refResult = await refRole.execute({ task: plannedTask, onOutput: refactorerStall.onOutput });
+    refResult = await refRole.execute({
+      task: plannedTask, onOutput: refactorerStall.onOutput,
+      sessionState: buildStandbyState({ session, config }),
+    });
   } finally {
     refactorerStall.stop();
   }
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
   if (!refResult.ok) {
     const details = refResult.result?.error || refResult.summary || "unknown error";
+    // Quota cap → hibernate cleanly, same as the coder stage above.
+    if (refResult.result?.action === "hibernate") {
+      emitProgress(emitter, makeEvent("refactorer:hibernate", { ...eventBase, stage: "refactorer" }, {
+        message: "Refactorer hibernated — provider quota exhausted, run can be resumed",
+        detail: { standbyFile: refResult.result?.standbyFile || null }
+      }));
+      return {
+        action: "hibernate",
+        standbyFile: refResult.result?.standbyFile || null,
+        recovery: refResult.result?.recovery || null,
+      };
+    }
     const rateLimitCheck = detectRateLimit({
       stderr: refResult.result?.error || "",
       stdout: refResult.result?.output || ""

package/src/orchestrator/verification-gate.js

@@ -47,8 +47,16 @@ export function countChangesSince(baseRef, projectDir = null) {
     }
 
     return { files, filesChanged: files.length, linesAdded, linesDeleted };
-  } catch {
-    return { files: [], filesChanged: 0, linesAdded: 0, linesDeleted: 0 };
+  } catch (err) {
+    // Git itself failed (baseRef invalid, repo corrupt, git binary
+    // missing). Previously we returned `filesChanged: 0` silently —
+    // indistinguishable from "the coder did nothing". Surface the
+    // error so verifyCoderOutput stops blaming the agent for an
+    // infrastructure failure.
+    return {
+      files: [], filesChanged: 0, linesAdded: 0, linesDeleted: 0,
+      gitError: err?.stderr?.toString?.() || err?.message || String(err),
+    };
   }
 }
 
@@ -65,10 +73,13 @@ export function countUntrackedFiles(projectDir = null) {
       encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
     }).trim();
 
-    if (!output) return [];
-    return output.split("\n").filter(Boolean);
-  } catch {
-    return [];
+    if (!output) return { files: [] };
+    return { files: output.split("\n").filter(Boolean) };
+  } catch (err) {
+    return {
+      files: [],
+      gitError: err?.stderr?.toString?.() || err?.message || String(err),
+    };
   }
 }
 
@@ -87,11 +98,29 @@ export function verifyCoderOutput({ baseRef, projectDir = null, minFiles = 1, mi
   const tracked = countChangesSince(baseRef, projectDir);
   const untracked = countUntrackedFiles(projectDir);
 
-  const totalFiles = tracked.filesChanged + untracked.length;
+  // Git infra failure (bad baseRef, corrupt repo, git missing) — not
+  // the coder's fault. Bail out with `gitError` so the caller can log
+  // it and skip the "retry with explicit file paths" feedback that
+  // would otherwise blame the agent.
+  const gitError = tracked.gitError || untracked.gitError;
+  if (gitError) {
+    return {
+      passed: false,
+      filesChanged: 0,
+      linesChanged: 0,
+      files: [],
+      reason: `Git verification failed: ${gitError}`,
+      retryStrategy: null,
+      gitError,
+    };
+  }
+
+  const untrackedFiles = untracked.files || [];
+  const totalFiles = tracked.filesChanged + untrackedFiles.length;
   const totalLines = tracked.linesAdded + tracked.linesDeleted;
-  const allFiles = [...tracked.files, ...untracked];
+  const allFiles = [...tracked.files, ...untrackedFiles];
 
-  const passed = totalFiles >= minFiles && (untracked.length > 0 || totalLines >= minLines);
+  const passed = totalFiles >= minFiles && (untrackedFiles.length > 0 || totalLines >= minLines);
 
   if (passed) {
     return {

package/src/plan/plan-store.js

@@ -7,7 +7,35 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+import { writeJsonAtomic } from "../utils/atomic-write.js";
 import { generatePlanId, normaliseAlias } from "./plan-id.js";
+
+/**
+ * A plan JSON file failed to parse — typically an interrupted write
+ * leaves it truncated. Previously every read site swallowed this with
+ * a silent catch and the plan vanished from `kj plan list` and
+ * `kj plan load` as if it had never existed.
+ *
+ * Now: warn loudly so the user knows their plan is corrupt, and rename
+ * the file to `<name>.corrupt-<ts>` so it stops blocking subsequent
+ * reads of the same alias / planId (without destroying evidence).
+ * Best-effort: if the rename itself fails (read-only FS, permissions),
+ * we log and move on — never escalate to a throw, that would block the
+ * caller from reading the rest of the directory.
+ */
+async function handleCorruptPlanFile(filePath, error) {
+  const corruptPath = `${filePath}.corrupt-${Date.now()}`;
+  // eslint-disable-next-line no-console
+  console.warn(`[plan-store] Corrupt plan JSON at ${filePath}: ${error.message}`);
+  try {
+    await fs.rename(filePath, corruptPath);
+    // eslint-disable-next-line no-console
+    console.warn(`[plan-store] Renamed to ${path.basename(corruptPath)} so it stops blocking subsequent reads.`);
+  } catch (renameErr) {
+    // eslint-disable-next-line no-console
+    console.warn(`[plan-store] Could not rename ${filePath}: ${renameErr.message}`);
+  }
+}
 import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
 // Per-process tmp dir for VITEST runs that forget to set KJ_HOME. We
@@ -83,7 +111,7 @@ export async function savePlan(projectDir, planResult) {
     if (!planResult.alias && planResult.name) {
       planResult.alias = await resolveUniqueAlias(dir, planResult.planId, normaliseAlias(planResult.name));
     }
-    await fs.writeFile(filePath, JSON.stringify(planResult, null, 2), "utf8");
+    await writeJsonAtomic(filePath, planResult);
     return planResult.planId;
   }
 
@@ -100,7 +128,7 @@ export async function savePlan(projectDir, planResult) {
   };
 
   const filePath = path.join(dir, `${planId}.json`);
-  await fs.writeFile(filePath, JSON.stringify(record, null, 2), "utf8");
+  await writeJsonAtomic(filePath, record);
   return planId;
 }
 
@@ -119,11 +147,14 @@ async function resolveUniqueAlias(dir, ownPlanId, base) {
   const taken = new Set();
   for (const f of files) {
     if (!f.endsWith(".json")) continue;
+    const filePath = path.join(dir, f);
     try {
-      const record = JSON.parse(await fs.readFile(path.join(dir, f), "utf8"));
+      const record = JSON.parse(await fs.readFile(filePath, "utf8"));
       if (record.planId === ownPlanId) continue;
       if (record.alias) taken.add(record.alias);
-    } catch { /* skip corrupt */ }
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
   }
   if (!taken.has(base)) return base;
   for (let i = 2; i < 1000; i += 1) {
@@ -151,19 +182,28 @@ export async function loadPlan(projectDir, ref) {
     const plan = JSON.parse(data);
     if (!isPlanV2(plan)) return migratePlanV1toV2(plan);
     return plan;
-  } catch { /* fall through to alias scan */ }
+  } catch (err) {
+    // ENOENT is expected (caller may have passed an alias, not a planId)
+    // → fall through to the alias scan. Anything else means the file is
+    // there but unreadable / corrupt; surface it instead of silently
+    // hiding the plan.
+    if (err.code !== "ENOENT") await handleCorruptPlanFile(direct, err);
+  }
   // 2. Escaneo del dir por alias. Coste O(N) pero N suele ser <10.
   let files;
   try { files = await fs.readdir(dir); } catch { return null; }
   for (const f of files) {
     if (!f.endsWith(".json")) continue;
+    const filePath = path.join(dir, f);
     try {
-      const record = JSON.parse(await fs.readFile(path.join(dir, f), "utf8"));
+      const record = JSON.parse(await fs.readFile(filePath, "utf8"));
       if (record.alias === ref || record.planId === ref) {
         if (!isPlanV2(record)) return migratePlanV1toV2(record);
         return record;
       }
-    } catch { /* skip corrupt */ }
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
   }
   return null;
 }
@@ -197,8 +237,10 @@ export async function listPlans(projectDir) {
   const plans = [];
   for (const file of files) {
     if (!file.endsWith(".json")) continue;
+    if (file.includes(".corrupt-")) continue; // own renamed-aside files
+    const filePath = path.join(dir, file);
     try {
-      const data = await fs.readFile(path.join(dir, file), "utf8");
+      const data = await fs.readFile(filePath, "utf8");
       const record = JSON.parse(data);
       plans.push({
         planId: record.planId,
@@ -210,7 +252,9 @@ export async function listPlans(projectDir) {
         huCount: Array.isArray(record.hus) ? record.hus.length : 0,
         createdAt: record.createdAt
       });
-    } catch { /* skip corrupt */ }
+    } catch (err) {
+      if (err.code !== "ENOENT") await handleCorruptPlanFile(filePath, err);
+    }
   }
 
   plans.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));

package/src/roles/agent-role.js

@@ -17,6 +17,19 @@ import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
+/**
+ * Silence timeout (ms) for an agent subprocess, from
+ * config.session.max_agent_silence_minutes. runCommand kills a child
+ * that produces no output for this long — without it a hung coder /
+ * reviewer leaves `kj run` waiting forever. Returns null when unset.
+ * @param {object} config
+ * @returns {number|null}
+ */
+export function resolveAgentSilenceTimeoutMs(config) {
+  const minutes = Number(config?.session?.max_agent_silence_minutes);
+  return Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes * 60 * 1000) : null;
+}
+
 export class AgentRole extends BaseRole {
   constructor({ name, config, logger, emitter = null, createAgentFn = null }) {
     super({ name, config, logger, emitter });
@@ -116,6 +129,11 @@ export class AgentRole extends BaseRole {
 
     const runArgs = { prompt, role: this.name };
     if (onOutput) runArgs.onOutput = onOutput;
+    // Kill a hung agent: without a silence timeout a coder / reviewer
+    // that stalls with no output left `kj run` waiting indefinitely.
+    // PlannerRole set this itself; every other role was unprotected.
+    const silenceTimeoutMs = resolveAgentSilenceTimeoutMs(this.config);
+    if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
 
     // KJC-TSK-0413 step B: TODAS las roles que heredan de AgentRole pasan
     // por Brain Recovery aquí — cubre AuditRole, SecurityRole, HuReviewerRole,
@@ -130,13 +148,18 @@ export class AgentRole extends BaseRole {
       provider,
       emitter: this.emitter,
       logger: this.logger,
+      // KJC: sessionState lets withBrainRecovery persist a hibernating run
+      // to ~/.kj/standby/ so it can be resumed. Without it a quota-exhausted
+      // run had nothing to resume from. Caller (coder-stage etc.) passes it
+      // through the input object; extractInput forwards it via `...input`.
+      sessionState: extracted.sessionState || this.context?.sessionState || null,
     });
 
     if (!result.ok) {
       const recoveryNote = result.recovery?.class ? ` [${result.recovery.class}]` : "";
       return {
         ok: false,
-        result: { error: result.error || result.output || `${this.name} failed${recoveryNote}`, provider, recovery: result.recovery, action: result.action },
+        result: { error: result.error || result.output || `${this.name} failed${recoveryNote}`, provider, recovery: result.recovery, action: result.action, standbyFile: result.standbyFile || null },
         summary: `${this.name} failed${recoveryNote}: ${result.recovery?.message || result.error || "unknown error"}`,
         usage: result.usage
       };

package/src/roles/triage-role.js

@@ -61,20 +61,39 @@ export class TriageRole extends AgentRole {
   }
 
   handleParseNull(agentResult, provider) {
-    return {
-      ok: true,
-      result: { ...FALLBACK_RESULT, reasoning: "Unstructured output, using safe defaults.", provider, raw: agentResult.output },
-      summary: "Triage complete (fallback defaults)",
-      usage: agentResult.usage
-    };
+    return this.degradedTriageResult({
+      agentResult, provider,
+      reason: "parse-null",
+      reasoning: "Unstructured output, using safe defaults.",
+      message: "[triage] LLM output was unstructured — falling back to defaults; the pipeline may skip optional roles.",
+    });
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degradedTriageResult({
+      agentResult, provider,
+      reason: "parse-error",
+      reasoning: `Failed to parse triage output (${err?.message || "unknown error"}), using safe defaults.`,
+      message: `[triage] Could not parse LLM output — falling back to defaults: ${err?.message || "unknown"}.`,
+    });
   }
 
-  handleParseError(_err, agentResult, provider) {
+  // Triage degradation is what made a complex task quietly run as
+  // `level: "medium", roles: ["reviewer"]` — researcher / architect /
+  // security / tester silently skipped. The fallback is preserved so
+  // the pipeline still moves, but the user (and any board / kj-tail
+  // listener) now learns it happened. result.degraded = true lets
+  // downstream code react if it wants.
+  // Same shape as before so downstream cost / event accounting is
+  // byte-identical; the only change is the loud logger.warn, which is
+  // what makes the silent degradation visible to the user / kj-tail.
+  degradedTriageResult({ agentResult, provider, reason: _reason, reasoning, message }) {
+    this.logger?.warn?.(message);
     return {
       ok: true,
-      result: { ...FALLBACK_RESULT, reasoning: "Failed to parse triage output, using safe defaults.", provider, raw: agentResult.output },
+      result: { ...FALLBACK_RESULT, reasoning, provider, raw: agentResult.output },
       summary: "Triage complete (fallback defaults)",
-      usage: agentResult.usage
+      usage: agentResult.usage,
     };
   }
 }

package/src/session/store.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ensureDir, exists } from "../utils/fs.js";
 import { getSessionRoot } from "../utils/paths.js";
+import { writeJsonAtomic } from "../utils/atomic-write.js";
 
 const SESSION_ROOT = getSessionRoot();
 
@@ -31,7 +32,7 @@ export async function saveSession(session) {
   const dir = path.join(SESSION_ROOT, session.id);
   await ensureDir(dir);
   session.updated_at = new Date().toISOString();
-  await fs.writeFile(path.join(dir, "session.json"), JSON.stringify(session, null, 2), "utf8");
+  await writeJsonAtomic(path.join(dir, "session.json"), session);
 }
 
 export async function loadSession(sessionId) {

package/src/utils/atomic-write.js

@@ -0,0 +1,43 @@
+// Atomic JSON writes for persistent state (resilience audit, Phase 2).
+//
+// A plain `writeFile(path, JSON.stringify(...))` truncates the live file
+// before the new content lands. If the process is killed mid-write
+// (SIGKILL, crash, power loss) the file is left truncated and the only
+// good copy is already gone — the plan / session / standby JSON
+// silently corrupts.
+//
+// write-temp + rename fixes it: `rename` is atomic on the same
+// filesystem, so a reader sees either the old file or the complete new
+// one, never a half-written one. The temp file sits next to the target
+// (same dir → same FS) and is uniquely named so concurrent writers do
+// not clobber each other's temp. A crash before the rename leaves an
+// orphan `.tmp` but never a corrupt target.
+
+import { writeFileSync, renameSync } from "node:fs";
+import { writeFile, rename } from "node:fs/promises";
+
+function tempPath(target) {
+  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+}
+
+/**
+ * Atomically write `obj` as pretty JSON to `target` (synchronous).
+ * @param {string} target - destination path; its directory must exist
+ * @param {unknown} obj
+ */
+export function writeJsonAtomicSync(target, obj) {
+  const tmp = tempPath(target);
+  writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
+  renameSync(tmp, target);
+}
+
+/**
+ * Atomically write `obj` as pretty JSON to `target` (async).
+ * @param {string} target - destination path; its directory must exist
+ * @param {unknown} obj
+ */
+export async function writeJsonAtomic(target, obj) {
+  const tmp = tempPath(target);
+  await writeFile(tmp, JSON.stringify(obj, null, 2), "utf-8");
+  await rename(tmp, target);
+}

package/src/utils/display/resume-hint.js

@@ -0,0 +1,41 @@
+/**
+ * Prints — as the LAST line of a stopped `kj run` / `kj plan` — the exact
+ * command to resume it. A halted run that never tells you how to restart
+ * it is the resilience gap this closes (resilience audit, Phase 1).
+ *
+ *   Quota hibernation → `kj standby resume <id>`
+ *   Solomon pause     → `kj resume <id> --answer "..."`
+ *   Stopped / failed  → `kj resume <id>`
+ *   Success           → nothing.
+ *
+ * @param {object} result          - the flow / command result
+ * @param {object} [opts]
+ * @param {(line:string)=>void} [opts.print] - sink, default console.log
+ */
+export function printResumeHint(result, { print = console.log } = {}) {
+  if (!result || typeof result !== "object") return;
+  const id = result.sessionId || result.session?.id || null;
+
+  if (result.hibernated === true) {
+    print("");
+    print("⏸  Run hibernated — provider quota exhausted.");
+    print(`   Resume when the quota resets:  kj standby resume ${id || "<session-id>"}`);
+    if (!id) print("   (run `kj standby list` to find the id)");
+    return;
+  }
+
+  if (result.paused === true && id) {
+    print("");
+    print("⏸  Run paused — waiting for your input.");
+    print(`   Resume:  kj resume ${id} --answer "<your answer>"`);
+    return;
+  }
+
+  // Stopped / failed / aborted but with a session on record → resumable.
+  // A successful run has approved === true and prints nothing.
+  if (id && result.approved !== true && result.paused !== true) {
+    print("");
+    print("✗  Run stopped before finishing.");
+    print(`   Resume:  kj resume ${id}`);
+  }
+}

package/src/utils/process.js

@@ -152,6 +152,24 @@ export async function runCommand(command, args = [], options = {}) {
 function enrichResult(result, stdoutAccum, _stderrAccum) {
   if (result.timedOut) return result;
 
+  // execa with reject:false RESOLVES (does not throw) on a spawn
+  // failure — ENOENT (binary not in PATH), EACCES, etc. The result
+  // then carries exitCode null/undefined, an empty stderr, and the
+  // real cause only in `code` / `shortMessage`. Surface it: a missing
+  // agent CLI used to fail with a completely empty error message,
+  // leaving the user with "coder failed" and no idea what to install.
+  if (result.failed && result.exitCode == null && !result.signal) {
+    const reason = result.shortMessage || result.message
+      || `spawn failed${result.code ? ` (${result.code})` : ""}`;
+    return {
+      ...result,
+      exitCode: 1,
+      stdout: result.stdout || stdoutAccum,
+      stderr: result.stderr || reason,
+      spawnError: result.code || true,
+    };
+  }
+
   const killed = result.killed || !!result.signal;
   const signal = result.signal || null;
 

package/src/utils/rate-limit-detector.js

@@ -39,6 +39,26 @@ export function parseCooldown(message) {
     }
   }
 
+  // 5. Claude Code session / weekly limit: "resets 10:10pm" / "resets 4am"
+  //    (12-hour clock, no date). Resolve to the next wall-clock occurrence
+  //    of that time in the machine's local timezone. Claude Code reports
+  //    the reset in the user's local TZ and kj runs on the same machine,
+  //    so the parenthesised "(Europe/Madrid)" hint is ignored on purpose.
+  const ampmMatch = /reset(?:s|ting)?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b/i.exec(
+    message
+  );
+  if (ampmMatch) {
+    let hour = Number.parseInt(ampmMatch[1], 10) % 12;
+    if (/pm/i.test(ampmMatch[3])) hour += 12;
+    const minute = ampmMatch[2] ? Number.parseInt(ampmMatch[2], 10) : 0;
+    if (hour < 24 && minute < 60) {
+      const target = new Date();
+      target.setHours(hour, minute, 0, 0);
+      if (target.getTime() <= Date.now()) target.setDate(target.getDate() + 1);
+      return { cooldownUntil: target.toISOString(), cooldownMs: target.getTime() - Date.now() };
+    }
+  }
+
   // 2. Relative seconds: "retry after 120 seconds" / "retry in 120s" / "Retry-After: 120"
   const secMatch = /(?:retry[\s-]*after|retry\s+in|wait)\s*:?\s*(\d+)\s*(?:seconds?|secs?|s\b)/i.exec(
     message
@@ -69,6 +89,8 @@ const RATE_LIMIT_PATTERNS = [
   { pattern: /usage limit/i, agent: "claude" },
   { pattern: /plan's usage limit/i, agent: "claude" },
   { pattern: /Claude Pro usage limit/i, agent: "claude" },
+  { pattern: /session limit/i, agent: "claude" },
+  { pattern: /weekly limit/i, agent: "claude" },
 
   // OpenAI / Codex CLI
   { pattern: /exceeded your current quota/i, agent: "codex" },

package/src/utils/run-registry.js

@@ -20,6 +20,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { writeJsonAtomicSync } from "./atomic-write.js";
 
 /**
  * Directorio raíz donde viven los registros de run.
@@ -54,7 +55,7 @@ export function registerRun(info = {}) {
       source: info.source || "cli",
       startedAt: new Date().toISOString(),
     };
-    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), "utf8");
+    writeJsonAtomicSync(filePath, entry);
     return runId;
   } catch {
     return null;