@karajan-family/code 4.21.0

package/packages/hu-board/src/ephemeral-cleaner.js

@@ -0,0 +1,196 @@
+/**
+ * Ephemeral project cleaner for the HU Board (board-polish #3,
+ * KJC-TSK-0371 — dogfooding 2026-05-07).
+ *
+ * Why this exists
+ * ===============
+ *
+ * Every `kj run` against a throwaway directory (`/tmp/kj-test-1`,
+ * `/tmp/demo-foo`, ad-hoc scratch projects under `tmp_*`) produces
+ * a board project that hangs around forever, even after the user
+ * has long since rm-rf'd the source tree. After 12 days of
+ * dogfooding the board ended up with 30+ "kj-test-N" projects
+ * the user couldn't tell apart from real ones — exactly the
+ * "noise on the demo" risk the user flagged on 2026-05-07.
+ *
+ * Heuristic (per the user's spec on the same session, "solución
+ * c — heurística + flag visible"):
+ *
+ *   1. Project is ephemeral when:
+ *        a) `is_test = 1` (user explicitly marked it test), OR
+ *        b) project id matches /^(tmp_|test_|demo_|kj-test-)/i
+ *           AND `is_test IS NULL` (no override).
+ *   2. AND last_activity is older than `ttlHours` (default 24h).
+ *
+ *   3. Override: when `is_test = 0` (user clicked "keep it"), the
+ *      project is NEVER deleted, even if the heuristic would match.
+ *
+ * What "cleanup" means: DELETE the project row + cascade-delete its
+ * stories and sessions, ADD a project tombstone, and rm-rf the
+ * on-disk dirs (`hu-stories/<sid>/`, `sessions/<sid>/`,
+ * `~/.kj/plans/<projectId>/`). Without the tombstone + fs cleanup,
+ * the very next chokidar `add` event or `fullScan` would re-import
+ * those files as a brand-new project (KJC-BUG-0055).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { addTombstone, getKjHome } from "./db.js";
+
+const DEFAULT_TTL_HOURS = 24;
+const EPHEMERAL_ID_PATTERNS = [
+  /^tmp_/i,
+  /^test_/i,
+  /^demo_/i,
+  /^kj-test-/i,
+  /^auto-tmp_/i,    // also covers auto-batch projects derived from /tmp/
+  /^auto-test_/i,
+  /^auto-demo_/i,
+  // KJC-TSK-0377: stray session/plan-prefixed projects accumulate during
+  // dogfooding when a kj run is invoked without a proper projectDir.
+  // The HU Board's sync_*File handlers create a placeholder project row
+  // with `id = session_id` or `id = plan_id`, which after 24h of
+  // inactivity is the same kind of zombi the other patterns target.
+  /^s_/i,
+  /^plan-/i,
+];
+
+/**
+ * Decide whether a single project row qualifies as an ephemeral
+ * candidate ready for deletion at `now`. Pure function — no I/O.
+ *
+ * The matrix:
+ *   is_test = 1         → ephemeral (user marked it)
+ *   is_test = 0         → not ephemeral, EVER (user override wins)
+ *   is_test = NULL/und. → fall back to id-pattern heuristic
+ *   too recent          → not ephemeral (still in use)
+ *
+ * @param {{ id: string, last_activity?: string|null, first_seen?: string|null,
+ *           is_test?: number|null }} project
+ * @param {{ now: number, ttlHours: number }} ctx
+ * @returns {{ ephemeral: boolean, reason?: string }}
+ */
+export function classifyEphemeral(project, ctx) {
+  if (!project || !project.id) return { ephemeral: false };
+  // Explicit user override always wins. is_test=0 means "keep it".
+  if (project.is_test === 0) return { ephemeral: false };
+
+  const idMatch = EPHEMERAL_ID_PATTERNS.some((re) => re.test(project.id));
+  const explicitTest = project.is_test === 1;
+  if (!idMatch && !explicitTest) return { ephemeral: false };
+
+  const refIso = project.last_activity || project.first_seen;
+  if (!refIso) return { ephemeral: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { ephemeral: false };
+  const ageHours = (ctx.now - refTs) / 3_600_000;
+  if (ageHours <= 0) return { ephemeral: false };
+  if (ageHours < ctx.ttlHours) return { ephemeral: false };
+
+  const why = explicitTest ? "is_test=1" : "id heuristic";
+  return {
+    ephemeral: true,
+    reason: `${why}, ${ageHours.toFixed(1)}h inactive (>= ${ctx.ttlHours}h)`,
+  };
+}
+
+/**
+ * Filter a list of project rows down to the ephemeral ones. Pure.
+ *
+ * @param {Array<object>} projects
+ * @param {{ now?: number, ttlHours?: number }} [opts]
+ * @returns {Array<{ project: object, reason: string }>}
+ */
+export function findEphemeralProjects(projects, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    ttlHours: opts.ttlHours ?? DEFAULT_TTL_HOURS,
+  };
+  const out = [];
+  for (const project of projects || []) {
+    const verdict = classifyEphemeral(project, ctx);
+    if (verdict.ephemeral) out.push({ project, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Cascade-delete every ephemeral project at `now`. Side-effecting.
+ * Returns the list of cleaned projects so the server can log them.
+ *
+ * Idempotent: cleanup deletes the rows outright, so running twice
+ * has no effect on the second pass.
+ *
+ * @param {object} deps
+ * @param {object} deps.db        better-sqlite3 Database handle
+ * @param {object} [deps.opts]    threshold overrides
+ * @param {Function} [deps.now]   () => number, for tests
+ * @returns {Array<{ id: string, reason: string, stories_deleted: number, sessions_deleted: number }>}
+ */
+export function cleanupEphemeralProjects({
+  db,
+  opts = {},
+  now = () => Date.now(),
+  // Deps are injectable so the legacy in-memory tests (which never
+  // call `initDb()`) can pass no-op stubs and still verify the
+  // cascade-delete logic. Production callers omit them and get the
+  // real persistence + fs side-effects.
+  tombstone = (type, id, o) => {
+    try { addTombstone(type, id, o); } catch { /* DB not initialised (test) */ }
+  },
+  kjHome = () => {
+    try { return getKjHome(); } catch { return null; }
+  },
+} = {}) {
+  if (!db) return [];
+  const allProjects = db
+    .prepare("SELECT id, last_activity, first_seen, is_test FROM projects")
+    .all();
+  const candidates = findEphemeralProjects(allProjects, { ...opts, now: now() });
+  if (candidates.length === 0) return [];
+
+  const delStories = db.prepare("DELETE FROM stories WHERE project_id = ?");
+  const delSessions = db.prepare("DELETE FROM sessions WHERE project_id = ?");
+  const delProject = db.prepare("DELETE FROM projects WHERE id = ?");
+
+  const selStories = db.prepare("SELECT id FROM stories WHERE project_id = ?");
+  const selSessions = db.prepare("SELECT id FROM sessions WHERE project_id = ?");
+  const plansRoot = process.env.KJ_PLANS_DIR
+    || path.join(homedir(), ".kj", "plans");
+  const home = kjHome();
+  const cleaned = [];
+  for (const { project, reason } of candidates) {
+    const storyIds = selStories.all(project.id).map((r) => r.id);
+    const sessionIds = selSessions.all(project.id).map((r) => r.id);
+    const fsPaths = home
+      ? [
+          ...storyIds.map((sid) => path.join(home, "hu-stories", sid)),
+          ...sessionIds.map((sid) => path.join(home, "sessions", sid)),
+          path.join(plansRoot, project.id),
+        ]
+      : [];
+    db.transaction(() => {
+      delStories.run(project.id);
+      delSessions.run(project.id);
+      delProject.run(project.id);
+    })();
+    // Tombstone the lot + best-effort rm-rf. If the fs op fails (perm
+    // error, file in use) we still keep the tombstone — that alone is
+    // enough to stop sync.js from re-importing on the next chokidar
+    // event, and `fullScan` will retry the rm-rf at next boot.
+    tombstone("project", project.id, { source: "ephemeral-cleaner", fsPaths });
+    for (const sid of storyIds) tombstone("story", sid, { source: "ephemeral-cleaner" });
+    for (const sid of sessionIds) tombstone("session", sid, { source: "ephemeral-cleaner" });
+    for (const p of fsPaths) {
+      try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+    cleaned.push({
+      id: project.id,
+      reason,
+      stories_deleted: storyIds.length,
+      sessions_deleted: sessionIds.length,
+    });
+  }
+  return cleaned;
+}

package/packages/hu-board/src/event-bus.js

@@ -0,0 +1,58 @@
+/**
+ * Tiny pub/sub used to push sync-related events to connected SSE
+ * clients. The chokidar watcher calls `publish(event)` whenever a plan
+ * / session / batch file changes; the SSE endpoint subscribes each
+ * connected response and writes the JSON-encoded event as a message.
+ *
+ * No external dependency on purpose — `events.EventEmitter` would work
+ * but would make testing the endpoint awkward (we need deterministic
+ * subscribe/publish semantics for the integration tests in
+ * sse.test.js). The contract is:
+ *
+ *   subscribe(fn)   → returns an unsubscribe function
+ *   publish(event)  → calls every current subscriber once
+ *   subscriberCount → how many listeners are live (tests only)
+ *
+ * Events are plain JSON objects. Callers pick the shape:
+ *
+ *   { type: 'plan',    planId, projectId }   — a plan JSON was synced
+ *   { type: 'session', sessionId, projectId }— a session JSON was synced
+ *   { type: 'story',   storyId, projectId }  — a single HU row mutated
+ *
+ * The board's client treats these as hints: the usual response is to
+ * re-fetch the affected project's stories and patch the kanban in
+ * place, so no full page reload is ever required.
+ */
+
+const subscribers = new Set();
+
+/**
+ * @param {(event: object) => void} fn
+ * @returns {() => void} unsubscribe
+ */
+export function subscribe(fn) {
+  subscribers.add(fn);
+  return () => { subscribers.delete(fn); };
+}
+
+/**
+ * @param {object} event
+ */
+export function publish(event) {
+  for (const fn of subscribers) {
+    try { fn(event); } catch (err) {
+      // A broken subscriber must not take the bus down. Log and move on.
+      console.error('[event-bus] subscriber threw:', err.message);
+    }
+  }
+}
+
+/** @returns {number} */
+export function subscriberCount() {
+  return subscribers.size;
+}
+
+/** Test helper — drops every subscriber. */
+export function _resetForTests() {
+  subscribers.clear();
+}

package/packages/hu-board/src/format.js

@@ -0,0 +1,207 @@
+/**
+ * Pure formatters used by the board UI to turn database rows into
+ * human-friendly labels. No DOM, no node APIs — easy to unit-test.
+ */
+
+const TIME_RE_FALLBACK = "—";
+const MAX_TASK_CHARS = 60;
+const MAX_PROJECT_CHARS = 40;
+
+/**
+ * Format an ISO 8601 timestamp as `HH:MM` (24h, local time of the
+ * server). Falls back to `—` when the input is missing or unparseable
+ * so the UI never renders `Invalid Date` or `null`.
+ *
+ * @param {string|null|undefined} iso
+ * @returns {string}
+ */
+export function formatHHMM(iso) {
+  if (!iso) return TIME_RE_FALLBACK;
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return TIME_RE_FALLBACK;
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  return `${hh}:${mm}`;
+}
+
+/**
+ * Truncate a task description to a max of N chars, collapsing internal
+ * whitespace, suffixed with "…" when truncated. Returns "" when the
+ * input is empty so the caller can decide whether to render the slot.
+ *
+ * @param {string|null|undefined} text
+ * @param {number} [max=MAX_TASK_CHARS]
+ * @returns {string}
+ */
+export function shortTask(text, max = MAX_TASK_CHARS) {
+  if (!text) return "";
+  const collapsed = String(text).replace(/\s+/g, " ").trim();
+  if (collapsed.length <= max) return collapsed;
+  return collapsed.slice(0, max - 1).trimEnd() + "…";
+}
+
+/**
+ * Build the label tuple used by `renderSessionCard` and
+ * `showSessionDetail`. The board used to print the session.id verbatim
+ * (e.g. `s_2026-05-07T08-35-58-010Z`) which is technically correct but
+ * impossible to scan at a glance — the user explicitly flagged this
+ * during pre-talk testing on 2026-05-07.
+ *
+ * Returned shape:
+ *   - `title`: bold-line title for the card (project + time).
+ *     Always non-empty; falls back to the session id when no project
+ *     is known so the card is never blank.
+ *   - `subtitle`: short task summary (≤ 60 chars). Empty when the
+ *     session has no task field — caller hides the slot.
+ *   - `idChip`: the cryptic session id, kept available for the user
+ *     who needs it for `kj resume <id>` and as a tooltip on the title.
+ *
+ * @param {{ id: string, project_name?: string|null, task?: string|null,
+ *           created_at?: string|null }} session
+ * @returns {{ title: string, subtitle: string, idChip: string }}
+ */
+/**
+ * Format a per-HU cost (USD) for the card badge. Cost F (KJC-TSK-0517).
+ *
+ * Two outputs in one call so the UI can render both at once:
+ *   - `label`: 2-decimal "$X.XX" shown on the card (compact).
+ *   - `tooltip`: 4-decimal "Estimated cost: $X.XXXX" shown on hover
+ *     (matches the precision aggregated by Cost B/C/D, see
+ *     `packages/core/src/cost/index.js`).
+ *
+ * Returns `null` for null/undefined/non-finite inputs so the caller
+ * skips the badge entirely (rendering "$0.00" for an unknown cost
+ * would be misleading — there is a real difference between "we know it
+ * was free" and "we haven't measured it yet").
+ *
+ * @param {number|null|undefined} costUsd
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+/**
+ * Φ0-G (KJC-TSK-0525): per-HU and per-plan cached-tokens badge.
+ *
+ * Returns `{ label, tooltip }` for "🎯 23%" with a tooltip showing the
+ * exact numerator/denominator. Same "don't render 0% when there is no
+ * data" stance as formatCost — returns null when:
+ *   - either arg is null/undefined/non-finite,
+ *   - tokens_in is 0 (no input → ratio undefined, not zero),
+ *   - cached is negative (would only happen from corrupted telemetry).
+ *
+ * The badge intentionally shows 1 decimal to keep narrow runs (e.g.
+ * a 73-token cache out of 1 200) readable without rounding to 0%.
+ *
+ * @param {number|null|undefined} cachedTokens
+ * @param {number|null|undefined} tokensIn
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCacheRatio(cachedTokens, tokensIn) {
+  // Reject null/undefined explicitly — Number(null) coerces to 0,
+  // which would otherwise render an honest-looking "🎯 0%" badge for
+  // runs where we simply have no telemetry. Same stance as formatCost.
+  if (cachedTokens === null || cachedTokens === undefined) return null;
+  if (tokensIn === null || tokensIn === undefined) return null;
+  const c = Number(cachedTokens);
+  const t = Number(tokensIn);
+  if (!Number.isFinite(c) || !Number.isFinite(t)) return null;
+  if (t <= 0 || c < 0) return null;
+  const pct = Math.round((c / t) * 1000) / 10;
+  const num = c.toLocaleString("en-US");
+  const den = t.toLocaleString("en-US");
+  return {
+    label: `🎯 ${pct}%`,
+    tooltip: `Cache hits: ${num} / ${den} input tokens (${pct}%)`,
+  };
+}
+
+/**
+ * Format the aggregated project-level cost chip rendered in the board
+ * header. Cost G (KJC-TSK-0518). Consumes the shape returned by
+ * `GET /api/projects/:id/cost` (Cost E):
+ *   { totalUsd, byPlan: [{planId, totalUsd, huCount}, …],
+ *     unknownModelTokens: { tokensIn, tokensOut, models }, currency }
+ *
+ * Returns `{ label, tooltip }` where:
+ *   - `label` is the compact "Total: $X.XX" shown in the header.
+ *   - `tooltip` is a multi-line string with full precision, the
+ *     per-plan breakdown, and a note when some tokens used a model we
+ *     don't price (they aren't included in the total — surfacing the
+ *     skip is more honest than silently swallowing it).
+ *
+ * Returns `null` when there is nothing to show (no input, or no
+ * measured cost yet and no plans). The chip is then hidden — same
+ * reasoning as `formatCost`: "$0.00" with no data is misleading.
+ *
+ * @param {{totalUsd:number, byPlan?:Array, unknownModelTokens?:object}|null|undefined} cost
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  // Φ0-G (KJC-TSK-0525): when the API includes project-level cache
+  // counters, show the aggregate cached% line right under the total
+  // so users can see at a glance how much was served from cache.
+  const projCache = formatCacheRatio(cost.cachedTokens, cost.tokensIn);
+  if (projCache) lines.push(`Cache: ${projCache.tooltip.split(": ")[1]}`);
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      const cachePct = p?.cachedRatioPct;
+      const cacheSuffix = (cachePct !== null && cachePct !== undefined && Number.isFinite(Number(cachePct)))
+        ? ` 🎯 ${cachePct}%`
+        : "";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})${cacheSuffix}`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
+export function formatSessionLabel(session) {
+  if (!session || !session.id) {
+    return { title: "(no session)", subtitle: "", idChip: "" };
+  }
+  const projectName = (session.project_name || "").trim();
+  const time = formatHHMM(session.created_at);
+  const projectPart = projectName
+    ? projectName.length > MAX_PROJECT_CHARS
+      ? projectName.slice(0, MAX_PROJECT_CHARS - 1) + "…"
+      : projectName
+    : session.id;  // fall back so a card without a joined project never
+                   // ends up blank — the cryptic id is better than empty
+  const title = time !== TIME_RE_FALLBACK
+    ? `${projectPart} · ${time}`
+    : projectPart;
+  return {
+    title,
+    subtitle: shortTask(session.task, MAX_TASK_CHARS),
+    idChip: session.id,
+  };
+}

package/packages/hu-board/src/hu-zombie-reaper.js

@@ -0,0 +1,103 @@
+/**
+ * HU-level zombie reaper (KJC-TSK-0394 step 3).
+ *
+ * Counterpart to zombie-reaper.js (que opera sobre sesiones). Detecta
+ * HUs que el orquestador dejó stuck en `coding`/`reviewing` —síntoma
+ * de crash mid-iteration— y las resetea a `pending`.
+ *
+ * Threshold separado de las sesiones: una sesión legítima puede
+ * tardar horas (loop largo), una HU individual rara vez >30 min. Por
+ * eso este reaper trabaja en minutos, no en horas.
+ *
+ * Semántica del reap: status → `pending` (NO `failed`: el orquestador
+ * perdió contacto, no podemos afirmar el outcome). El campo `result`
+ * NO se toca — se conserva como historial. La persistencia pasa por
+ * plan-mutations::setHuStatus (escribe el plan JSON + resync DB). Si
+ * el JSON write falla cae al fallback DB-only.
+ */
+
+const DEFAULT_RUNNING_MINUTES = 30;
+// `coding` + `reviewing` son los nombres legacy; `running` es el
+// canónico tras step 5. Aceptamos los tres durante la transición.
+const RUNNING_STATUSES = new Set(["coding", "reviewing", "running"]);
+
+/**
+ * Pure. Decide si un HU row es zombi a `now`.
+ */
+export function classifyHuZombie(hu, ctx) {
+  if (!hu || !hu.status) return { zombie: false };
+  const status = String(hu.status).toLowerCase();
+  if (!RUNNING_STATUSES.has(status)) return { zombie: false };
+  const refIso = hu.updated_at;
+  if (!refIso) return { zombie: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { zombie: false };
+  const ageMinutes = (ctx.now - refTs) / 60_000;
+  if (ageMinutes < ctx.runningMinutes) return { zombie: false };
+  return {
+    zombie: true,
+    reason: `${status} ${ageMinutes.toFixed(0)}min inactive (>= ${ctx.runningMinutes}min)`,
+  };
+}
+
+/** Pure. Filtra solo los zombis. */
+export function findZombieHus(hus, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    runningMinutes: opts.runningMinutes ?? DEFAULT_RUNNING_MINUTES,
+  };
+  const out = [];
+  for (const hu of hus || []) {
+    const verdict = classifyHuZombie(hu, ctx);
+    if (verdict.zombie) out.push({ hu, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Resetea a `pending` cada HU zombi en la DB Y en el fichero del
+ * plan. `setHuStatus` se inyecta para que los tests no necesiten un
+ * plan-file real. Devuelve la lista de reapeados para el log.
+ */
+export function reapZombieHus({ db, setHuStatus, setHuFailResult, opts = {}, now = () => Date.now() }) {
+  if (!db || typeof setHuStatus !== "function") return [];
+  const rows = db.prepare(
+    "SELECT id, project_id, plan_id, status, updated_at FROM stories WHERE status IN ('coding', 'reviewing', 'running')",
+  ).all();
+  const zombies = findZombieHus(rows, { ...opts, now: now() });
+  if (zombies.length === 0) return [];
+  const reaped = [];
+  for (const { hu, reason } of zombies) {
+    // El id compuesto del board es `${projectId}::${huId}`; setHuStatus
+    // quiere el huId local.
+    const localHuId = hu.id.includes("::") ? hu.id.split("::").slice(1).join("::") : hu.id;
+    let planPersisted = false;
+    if (hu.plan_id) {
+      try {
+        const result = setHuStatus({ planId: hu.plan_id, huId: localHuId, status: "pending", projectId: hu.project_id });
+        planPersisted = !!(result && result.ok);
+      } catch { /* swallow — never block startup */ }
+      // KJC-TSK-0404: además de resetear status=pending, marcar la HU con
+      // result=fail + blocker. El siguiente `kj run` ve el blocker y se
+      // lo inyecta al coder como "## PREVIOUS ATTEMPT FAILED" para que
+      // no repita el mismo error. No-op si la fn no se inyectó.
+      if (planPersisted && typeof setHuFailResult === "function") {
+        try {
+          setHuFailResult({
+            planId: hu.plan_id, huId: localHuId, projectId: hu.project_id,
+            blocker: `timeout: ${reason}`,
+          });
+        } catch { /* swallow — el status reset ya está hecho */ }
+      }
+    }
+    // Fallback DB-only para legacy rows (plan_id null) o si el write al
+    // plan falló. setHuStatus ya resincroniza en el caso happy.
+    if (!planPersisted) {
+      try {
+        db.prepare("UPDATE stories SET status = 'pending', updated_at = ? WHERE id = ?").run(new Date(now()).toISOString(), hu.id);
+      } catch { /* swallow */ }
+    }
+    reaped.push({ id: hu.id, status_before: hu.status, reason, plan_persisted: planPersisted });
+  }
+  return reaped;
+}