karajan-code 2.34.0 → 3.1.0

package/packages/hu-board/public/utils/project-picker-view.js

@@ -0,0 +1,139 @@
+// KJC-TSK-0501 step 7/8 — Project picker view (default Board landing).
+//
+// Classic script (no exports). Loaded by index.html before app.js so
+// the function declaration hoists into the script-level lexical
+// environment and app.js can call renderProjectPicker() from its
+// router.
+//
+// Globals consumed from earlier scripts / app.js:
+//   - api()                       (utils/api.js)
+//   - esc()                       (app.js)
+//   - renderEmptyState()          (app.js)
+//   - resolveProjectMeta()        (app.js)
+//   - projectNameCache            (mutable, app.js)
+//   - humaniseProjectName()       (app.js)
+
+/**
+ * "Pick a project" view shown by the Board tab when nothing is
+ * selected. Lists every project that has at least one HU with the
+ * pending / running / done / failed counts — clicking takes the
+ * user into that project's kanban (`#board/<slug>`).
+ *
+ * Why this instead of an "All projects" merged kanban: HU short ids
+ * collide across projects (every project has a `*-001`), the column
+ * counts become meaningless, and "missing test contract" warnings
+ * apply to whatever-project so the user can't tell what to act on.
+ * Forcing a project pick before the kanban is the cheapest way to
+ * keep every other UI invariant honest.
+ */
+async function renderProjectPicker() {
+  const app = document.getElementById('app');
+  const projects = await api('/api/projects');
+  // Pre-resolve human names so the rendered list matches what the
+  // header / dropdown show elsewhere.
+  await Promise.all(projects.map((p) => resolveProjectMeta(p.id)));
+
+  if (projects.length === 0) {
+    app.innerHTML = renderEmptyState(
+      'No projects yet',
+      'Run kj plan or click ⚡ in the header to generate one. The board will pick it up automatically.'
+    );
+    return;
+  }
+
+  // Per-project status counts come from /api/projects/:id/stories.
+  // One round-trip per project; cheap on a local SQLite-backed API.
+  const allStories = await Promise.all(
+    projects.map((p) => api(`/api/projects/${encodeURIComponent(p.id)}/stories`).then((s) => ({ id: p.id, stories: s })))
+  );
+  const byProject = new Map(allStories.map((entry) => [entry.id, entry.stories]));
+
+  function bucket(stories) {
+    const c = { pending: 0, running: 0, done: 0, failed: 0 };
+    for (const s of stories) {
+      if (['pending', 'certified', 'needs_context', 'blocked'].includes(s.status)) c.pending += 1;
+      else if (['coding', 'reviewing'].includes(s.status)) c.running += 1;
+      else if (s.status === 'done') c.done += 1;
+      else if (s.status === 'failed') c.failed += 1;
+    }
+    return c;
+  }
+
+  // Sort: most recent activity first. Falls back to alphabetic when
+  // last_activity is missing (older projects synced pre-#480).
+  const sorted = [...projects].sort((a, b) => {
+    const la = a.last_activity || '';
+    const lb = b.last_activity || '';
+    if (la && lb && la !== lb) return lb.localeCompare(la);
+    return (a.name || a.id).localeCompare(b.name || b.id);
+  });
+
+  app.innerHTML = `
+    <div class="section-header">
+      <span class="section-header__title">Story Board</span>
+      <span class="section-header__count">${sorted.length} project${sorted.length === 1 ? '' : 's'}</span>
+    </div>
+    <p style="padding:8px 4px 16px;color:var(--text-muted);font-size:0.9rem">
+      Pick a project to see its kanban. Use the project selector in the header to switch later.
+    </p>
+    <div style="display:grid;grid-template-columns:repeat(auto-fill, minmax(320px, 1fr));gap:14px">
+      ${sorted.map((p) => {
+        const counts = bucket(byProject.get(p.id) || []);
+        const total = counts.pending + counts.running + counts.done + counts.failed;
+        const name = projectNameCache[p.id] || p.name || humaniseProjectName(p.id);
+        // div en lugar de <button> para poder anidar el botón de
+        // delete (HTML no permite buttons anidados). role+tabindex
+        // mantienen la accesibilidad equivalente.
+        return `
+          <div role="button" tabindex="0" class="project-picker__card" data-project-id="${esc(p.id)}"
+                  style="position:relative;text-align:left;display:flex;flex-direction:column;gap:8px;padding:14px 16px;
+                         background:var(--bg-secondary);border:1px solid var(--border);
+                         border-radius:var(--radius-sm);cursor:pointer;color:var(--text);
+                         transition:border-color 120ms">
+            <button class="project-card__delete" title="Borrar proyecto (cascade)"
+                    data-project-id="${esc(p.id)}" data-project-name="${esc(name)}">🗑️</button>
+            <div style="display:flex;align-items:baseline;justify-content:space-between;gap:8px;padding-right:32px">
+              <strong style="font-size:0.95rem">${esc(name)}</strong>
+              <span style="font-size:0.75rem;color:var(--text-muted)">${total} HU${total === 1 ? '' : 's'}</span>
+            </div>
+            <div style="display:flex;flex-wrap:wrap;gap:6px;font-size:0.78rem">
+              ${counts.pending > 0 ? `<span title="Pending" style="padding:2px 8px;border-radius:var(--radius-sm);background:var(--bg-primary)">⏳ ${counts.pending}</span>` : ''}
+              ${counts.running > 0 ? `<span title="Running" style="padding:2px 8px;border-radius:var(--radius-sm);background:rgba(234,179,8,0.18);color:#facc15">⚙ ${counts.running}</span>` : ''}
+              ${counts.done > 0 ? `<span title="Done" style="padding:2px 8px;border-radius:var(--radius-sm);background:rgba(74,222,128,0.18);color:#4ade80">✓ ${counts.done}</span>` : ''}
+              ${counts.failed > 0 ? `<span title="Failed" style="padding:2px 8px;border-radius:var(--radius-sm);background:rgba(248,113,113,0.18);color:#f87171">✗ ${counts.failed}</span>` : ''}
+              ${total === 0 ? `<span style="color:var(--text-muted)">empty</span>` : ''}
+            </div>
+            <div style="font-family:var(--font-mono, monospace);font-size:0.7rem;color:var(--text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(p.id)}">
+              ${esc(p.id)}
+            </div>
+          </div>
+        `;
+      }).join('')}
+    </div>
+  `;
+
+  app.querySelectorAll('.project-picker__card').forEach((btn) => {
+    const enter = () => {
+      const id = btn.dataset.projectId;
+      // Use the existing route so back/forward work and the dropdown
+      // syncs via handleRoute().
+      window.location.hash = `board/${encodeURIComponent(id)}`;
+    };
+    btn.addEventListener('click', (e) => {
+      // Click sobre el botón delete anidado — el handler global ya
+      // hace stopPropagation + preventDefault, pero por defensa
+      // ignoramos aquí cualquier click que venga de dentro de él.
+      if (e.target.closest('.project-card__delete')) return;
+      enter();
+    });
+    btn.addEventListener('keydown', (e) => {
+      if ((e.key === 'Enter' || e.key === ' ') && !e.target.closest('.project-card__delete')) {
+        e.preventDefault();
+        enter();
+      }
+    });
+    // Tiny hover affordance — no CSS file edit needed.
+    btn.addEventListener('mouseenter', () => { btn.style.borderColor = 'var(--color-green)'; });
+    btn.addEventListener('mouseleave', () => { btn.style.borderColor = 'var(--border)'; });
+  });
+}

package/packages/hu-board/public/utils/run-launcher.js

@@ -0,0 +1,169 @@
+// KJC-TSK-0501 step 8f/8 — Preflight gate + run launcher.
+//
+// Classic script (no exports). Loaded by index.html before app.js so the
+// top-level `function`/`let` declarations are hoisted into the shared
+// realm and the inline handlers in app.js (and elsewhere) resolve
+// `runProject` / `confirmRunWithPreflight` via that hoisting.
+//
+// Globals consumed from earlier scripts / app.js:
+//   - esc()                  (utils/formatters.js)
+//   - ensureDialog()         (app.js)
+//   - showError()            (utils/modals.js)
+//   - renderBoard()          (app.js)
+//   - openLogViewer()        (utils/log-panel.js)
+//   - lastLaunchedPlanId     (mutable in app.js — assignment crosses
+//                             scripts transparently)
+//   - lastOpenedLog          (mutable in app.js — same)
+
+// ---- Preflight panel + safety modal ----
+//
+// Goal: when a non-technical user opens a project, they should see at
+// a glance whether the environment is ready (git initialised, remote
+// configured, agents installed, Node version, etc.). Each missing
+// item is rendered with a plain-Spanish "consequence" so the user
+// understands what's at stake.
+//
+// The panel doubles as the gate for ▶ Run plan / ▶ Run HU: if any
+// blocker (status:fail with blocking:true) is present, we refuse to
+// launch. If only warnings are present, we open a confirm modal
+// listing them and require an explicit "Lanzar de todos modos".
+
+let preflightCache = null;     // memoise per-render so the modal can re-use what the panel already fetched
+
+async function fetchPreflight(projectId) {
+  try {
+    const r = await fetch(`/api/projects/${encodeURIComponent(projectId)}/preflight`);
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; }
+}
+
+function preflightStatusIcon(status) {
+  if (status === 'ok') return '✓';
+  if (status === 'warn') return '⚠';
+  if (status === 'fail') return '✗';
+  return 'ℹ';
+}
+function preflightStatusColor(status) {
+  if (status === 'ok') return 'var(--color-green)';
+  if (status === 'warn') return 'var(--color-yellow,#eab308)';
+  if (status === 'fail') return 'var(--color-red,#ef4444)';
+  return 'var(--text-muted)';
+}
+
+/**
+ * Pre-run safety modal. Returns true if the user wants to proceed,
+ * false to cancel. Call BEFORE invoking the run endpoint.
+ *
+ * Behaviour:
+ *   - All green → returns true immediately (no modal).
+ *   - Blockers present → modal explains them in plain Spanish; only
+ *     "Cancelar" button (no proceed-anyway) because blockers are
+ *     known to break the run.
+ *   - Only warnings → modal lists them with their consequences and
+ *     offers "Cancelar" or "Lanzar de todos modos" (red button so
+ *     the user notices they're accepting risk).
+ */
+async function confirmRunWithPreflight(projectId) {
+  const data = preflightCache || await fetchPreflight(projectId);
+  if (!data) return true;             // can't fetch → don't block the user
+  const blockers = data.blockers || [];
+  const warnings = data.warnings || [];
+  if (blockers.length === 0 && warnings.length === 0) return true;
+
+  return await new Promise((resolve) => {
+    const dlg = document.getElementById('app-dialog') || ensureDialog();
+    const isBlocked = blockers.length > 0;
+    const headerColor = isBlocked ? 'var(--color-red,#ef4444)' : 'var(--color-yellow,#eab308)';
+    const allItems = [...blockers, ...warnings];
+    dlg.innerHTML = `
+      <div style="padding:14px 18px;border-bottom:1px solid var(--border);font-weight:700;display:flex;align-items:center;gap:10px;background:${headerColor};color:#000;">
+        <span style="font-size:1.2rem;">${isBlocked ? '✗' : '⚠'}</span>
+        <span>${isBlocked ? 'No se puede lanzar — falta algo crítico' : 'Atención antes de lanzar'}</span>
+      </div>
+      <div style="padding:14px 18px;max-height:60vh;overflow:auto;">
+        <p style="margin:0 0 10px;font-size:0.9rem;color:var(--text);">
+          ${isBlocked
+            ? 'Se detectaron problemas bloqueantes que impedirán que Karajan funcione correctamente:'
+            : 'Se detectaron avisos. Karajan puede ejecutarse, pero con limitaciones:'}
+        </p>
+        <ul style="list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:8px;">
+          ${allItems.map((c) => `
+            <li style="padding:8px 10px;background:var(--bg-primary);border-left:3px solid ${preflightStatusColor(c.status)};border-radius:var(--radius-sm);">
+              <div style="font-weight:600;color:var(--text);font-size:0.85rem;">
+                ${preflightStatusIcon(c.status)} ${esc(c.label)} — <span style="color:var(--text-muted);font-weight:400;">${esc(c.detail || '')}</span>
+              </div>
+              ${c.consequence ? `<div style="font-size:0.8rem;color:var(--text);margin-top:4px;">${esc(c.consequence)}</div>` : ''}
+            </li>
+          `).join('')}
+        </ul>
+      </div>
+      <div style="padding:12px 18px;border-top:1px solid var(--border);display:flex;gap:8px;justify-content:flex-end;">
+        <button id="preflight-cancel" style="padding:8px 16px;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);cursor:pointer;">Cancelar</button>
+        ${isBlocked ? '' : `<button id="preflight-proceed" style="padding:8px 16px;background:var(--color-red,#ef4444);border:none;color:#fff;border-radius:var(--radius-sm);cursor:pointer;font-weight:600;">Lanzar de todos modos</button>`}
+      </div>
+    `;
+    if (typeof dlg.showModal === 'function' && !dlg.open) dlg.showModal();
+    const cancel = dlg.querySelector('#preflight-cancel');
+    const proceed = dlg.querySelector('#preflight-proceed');
+    const close = (val) => { try { dlg.close(); } catch { /* ignore */ } resolve(val); };
+    cancel?.addEventListener('click', () => close(false), { once: true });
+    proceed?.addEventListener('click', () => close(true), { once: true });
+    dlg.addEventListener('close', () => resolve(false), { once: true });
+  });
+}
+
+async function runProject(projectId) {
+  try {
+    const res = await fetch(`/api/projects/${encodeURIComponent(projectId)}/run`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    if (!res.ok) {
+      if (res.status === 404) {
+        await showError(
+          'The board server does not recognise the "run" endpoint.\n\n'
+          + 'Most likely cause: the board process is running a pre-v2.7.5 build. '
+          + 'Restart it with:\n\n'
+          + '    kj board stop && kj board start',
+          { title: 'Board out of date' }
+        );
+        return;
+      }
+      const msg = (await res.json().catch(() => ({}))).error || `HTTP ${res.status}`;
+      await showError(msg, { title: 'Could not launch run' });
+      return;
+    }
+    const body = await res.json();
+    // Best-effort: a chokidar tick may still be in flight, so fetch
+    // once explicitly to surface the "running" state without waiting
+    // for the watcher debounce.
+    await fetch('/api/sync', { method: 'POST' }).catch(() => {});
+    await renderBoard();
+
+    // Remember the first successful planId so the section header can
+    // offer a "View log" button without the user having to re-launch.
+    const firstOk = (body.results || []).find((r) => r.ok);
+    if (firstOk && firstOk.planId) {
+      lastLaunchedPlanId = firstOk.planId;
+      lastOpenedLog = {
+        id: firstOk.planId,
+        label: 'Run log',
+        tailUrl: (offset) => `/api/plans/${encodeURIComponent(firstOk.planId)}/log?offset=${offset}`,
+      };
+      // Open the log viewer straight away — the user's mental model is
+      // "I clicked Run, I want to see what's happening", not "I clicked
+      // Run, now where do I look".
+      openLogViewer(firstOk.planId);
+    } else {
+      await showError(
+        `Pipeline launched for ${body.launched}/${body.total} plan(s) but `
+        + 'no planId came back, so there\'s no log to show.',
+        { title: 'Run started' }
+      );
+    }
+  } catch (err) {
+    await showError(err.message, { title: 'Could not launch run' });
+  }
+}

package/packages/hu-board/public/utils/server-push.js

@@ -0,0 +1,252 @@
+// KJC-TSK-0501 step 8g/8 — Server-push updates (SSE → smart DOM patch).
+//
+// Classic script (no exports). Loaded by index.html before app.js so
+// the top-level `function` / `let` declarations are hoisted into the
+// shared realm and `subscribeToServerEvents` is callable from app.js's
+// DOMContentLoaded handler.
+//
+// Globals consumed from earlier scripts / app.js:
+//   - showPromptModal()              (utils/modals.js)
+//   - closePromptModalIfMatches()    (utils/modals.js)
+//   - render()                       (app.js)
+//   - api()                          (utils/api.js)
+//   - renderStoryCard()              (utils/board-view.js)
+//   - cssEscape()                    (utils/formatters.js)
+//   - currentView                    (mutable in app.js — read here)
+//   - selectedProject                (mutable in app.js — read here)
+
+// ---- Server-push updates ----
+//
+// The board gets a one-way stream of events from the server via
+// Server-Sent Events; each event hints at what changed (plan file,
+// session, batch). On receipt we refresh the current view in a way
+// that preserves scroll position and any open modal. Full-page
+// re-render is no longer on the table — clicking around doesn't
+// reset your scroll anymore.
+//
+// EventSource auto-reconnects on drop, so we don't manage lifecycle
+// ourselves. The status line below the header flashes briefly on
+// each update so the user can see the data is live.
+
+let sseSource = null;
+let sseRefreshTimer = null;
+
+function subscribeToServerEvents() {
+  if (typeof EventSource === 'undefined') return;   // ancient browser
+  if (sseSource) sseSource.close();
+  sseSource = new EventSource('/api/events');
+  sseSource.addEventListener('message', (e) => {
+    // Try to parse the event as a typed payload. Prompt events drive
+    // the prompt modal; everything else just nudges a re-render.
+    let payload;
+    try { payload = JSON.parse(e.data); } catch { payload = null; }
+
+    if (payload?.type === 'prompt' && payload.promptId) {
+      // A non-interactive runner is asking for input — pop the modal
+      // immediately. fetch the full prompt body from the API so we
+      // don't depend on the SSE event carrying every field.
+      fetch(`/api/prompts`).then(r => r.ok ? r.json() : []).then((list) => {
+        const match = list.find((p) => p.promptId === payload.promptId);
+        if (match) showPromptModal(match);
+      }).catch(() => {});
+      return;
+    }
+    if (payload?.type === 'prompt-resolved' && payload.promptId) {
+      // Runner read its answer file — close the modal if it's still open.
+      closePromptModalIfMatches(payload.promptId);
+      return;
+    }
+
+    // Default: data changed somewhere. Try the targeted DOM patch
+    // first (no parpadeo, preserves scroll + hover state) and only
+    // fall back to a full re-render when the patch can't apply
+    // (different view, missing markers, etc.). This is the fix for
+    // the "todo el board parpadea cada vez que algo cambia" UX bug.
+    if (sseRefreshTimer) clearTimeout(sseRefreshTimer);
+    sseRefreshTimer = setTimeout(() => smartRefresh(payload), 150);
+  });
+  sseSource.addEventListener('error', () => {
+    // EventSource handles reconnection. Nothing to do; browsers retry
+    // the `retry:` value we sent on open.
+  });
+
+  // On boot, also fetch any prompts that were already pending before
+  // this tab connected (we missed their SSE add-event).
+  fetch('/api/prompts').then((r) => r.ok ? r.json() : []).then((list) => {
+    for (const p of list) showPromptModal(p);
+  }).catch(() => {});
+}
+
+/**
+ * Refresh the current SPA view without touching scroll position or
+ * any modal state. The heavy lifting already lives in renderBoard /
+ * renderGraph / renderSessions; this just re-calls them while the
+ * scroll offset is pinned, so the visual effect is "the card
+ * status updated in place".
+ * @param {string} _rawEvent unused for now — we could branch on
+ *   event type later to patch only the touched card, but a full
+ *   re-render with scroll preservation is already invisible to
+ *   the user and a lot simpler to reason about.
+ */
+async function refreshCurrentView(_rawEvent) {
+  const app = document.getElementById('app');
+  const scrollTop = app?.scrollTop ?? 0;
+  const scrollLeft = app?.scrollLeft ?? 0;
+  // Modal is in a separate DOM branch (#modal-backdrop) so render()
+  // never touches it — we don't need to save its state.
+  try {
+    await render();
+  } finally {
+    const fresh = document.getElementById('app');
+    if (fresh) {
+      fresh.scrollTop = scrollTop;
+      fresh.scrollLeft = scrollLeft;
+    }
+  }
+}
+
+/**
+ * Smart refresh: pick the cheapest possible DOM update for the
+ * incoming SSE event. Today the server sends coarse-grained events
+ * (`{type: 'plan'|'batch'|'session'|'prompt'|...}`), so we route by
+ * type:
+ *
+ *   plan / batch on the board view  → patchBoardIncremental()
+ *   anything else                    → refreshCurrentView() (full re-render)
+ *
+ * The patch path preserves DOM nodes (no innerHTML rewrite, no
+ * scroll reset, no hover/focus loss) — this is what kills the
+ * "parpadeo" the user reported.
+ *
+ * @param {object|null} payload The parsed SSE payload, or null when
+ *   the event wasn't valid JSON. Coarse types still work (we just
+ *   degrade to a full re-render).
+ */
+async function smartRefresh(payload) {
+  const onBoard = currentView === 'board' && Boolean(selectedProject);
+  const isStoryRelated = payload && ['plan', 'batch'].includes(payload.type);
+  if (onBoard && isStoryRelated) {
+    const ok = await patchBoardIncremental();
+    if (ok) return;
+  }
+  await refreshCurrentView();
+}
+
+/**
+ * Targeted DOM patch for the Kanban board. Re-fetches the project's
+ * stories, diffs them against the cards already rendered, and only
+ * touches the affected nodes:
+ *
+ *   - status changed → move the card to the new column with a
+ *     subtle animation (no DOM recreation, listeners survive)
+ *   - new story      → render + insert into the right column
+ *   - story removed  → fade + remove
+ *   - column counts and the running badge are updated in place
+ *
+ * Returns false if the board's DOM markers aren't present (different
+ * view, error state, etc.) so smartRefresh can fall back to a full
+ * re-render.
+ *
+ * @returns {Promise<boolean>}
+ */
+async function patchBoardIncremental() {
+  const kanban = document.querySelector('.kanban');
+  if (!kanban) return false;          // not on the board view
+  const columns = {};
+  for (const col of kanban.querySelectorAll('.kanban__column')) {
+    const cls = col.dataset.column;
+    if (cls) columns[cls] = col;
+  }
+  if (!columns.pending || !columns.running) return false;
+
+  let stories;
+  try {
+    stories = await api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`);
+  } catch { return false; }
+
+  // Re-derive the column → status mapping (kept in lockstep with
+  // renderBoard's `columns` object — change there, change here).
+  const statusToColumn = (status) => {
+    if (['pending', 'certified', 'needs_context', 'blocked'].includes(status)) return 'pending';
+    if (['coding', 'reviewing'].includes(status)) return 'running';
+    if (status === 'done') return 'done';
+    if (status === 'failed') return 'failed';
+    return 'pending';                  // safe default
+  };
+
+  const seen = new Set();
+  for (const story of stories) {
+    seen.add(story.id);
+    const targetCol = columns[statusToColumn(story.status)];
+    if (!targetCol) continue;
+    const existing = kanban.querySelector(`.story-card[data-story-id="${cssEscape(story.id)}"]`);
+    if (!existing) {
+      // New story — append to its column.
+      const wrapper = document.createElement('div');
+      wrapper.innerHTML = renderStoryCard(story).trim();
+      const node = wrapper.firstElementChild;
+      if (node) {
+        node.style.opacity = '0';
+        targetCol.appendChild(node);
+        requestAnimationFrame(() => { node.style.transition = 'opacity 200ms'; node.style.opacity = '1'; });
+      }
+      continue;
+    }
+    const previousStatus = existing.dataset.status;
+    if (previousStatus !== story.status) {
+      // Status changed — move the node + replace its inner content
+      // (counters, time-ago, status pill) without recreating the
+      // outer node so click handlers + transitions survive.
+      const wrapper = document.createElement('div');
+      wrapper.innerHTML = renderStoryCard(story).trim();
+      const fresh = wrapper.firstElementChild;
+      if (fresh) {
+        existing.innerHTML = fresh.innerHTML;
+        existing.dataset.status = story.status;
+        existing.setAttribute('onclick', fresh.getAttribute('onclick') || '');
+        if (existing.parentElement !== targetCol) {
+          existing.style.transition = 'opacity 150ms';
+          existing.style.opacity = '0.3';
+          setTimeout(() => {
+            targetCol.appendChild(existing);
+            requestAnimationFrame(() => { existing.style.opacity = '1'; });
+          }, 150);
+        }
+      }
+    } else {
+      // Same status — just refresh the inner block (counters / time
+      // ago / antipatterns may have changed) without moving.
+      const wrapper = document.createElement('div');
+      wrapper.innerHTML = renderStoryCard(story).trim();
+      const fresh = wrapper.firstElementChild;
+      if (fresh && fresh.innerHTML !== existing.innerHTML) {
+        existing.innerHTML = fresh.innerHTML;
+      }
+    }
+  }
+  // Cards that no longer exist on the server → remove with a fade.
+  for (const node of kanban.querySelectorAll('.story-card')) {
+    if (!seen.has(node.dataset.storyId)) {
+      node.style.transition = 'opacity 150ms';
+      node.style.opacity = '0';
+      setTimeout(() => node.remove(), 160);
+    }
+  }
+  // Recount each column + update the "N running" badge in the header.
+  for (const [cls, col] of Object.entries(columns)) {
+    const counter = col.querySelector('[data-column-count]');
+    if (counter) counter.textContent = String(col.querySelectorAll('.story-card').length);
+    col.style.opacity = col.querySelectorAll('.story-card').length === 0 ? '0.55' : '1';
+  }
+  const runningCount = columns.running.querySelectorAll('.story-card').length;
+  const runningBadge = document.querySelector('.section-header__badge');
+  if (runningBadge) {
+    if (runningCount > 0) {
+      runningBadge.textContent = `⚙ ${runningCount} running…`;
+      runningBadge.style.display = '';
+    } else {
+      runningBadge.style.display = 'none';
+    }
+  }
+  return true;
+}