@worca/app 1.1.1 → 1.2.0-rc.1

package/src/core/settings.mjs

@@ -11,6 +11,12 @@
 //   contextMaxBytesPerFile — §5.4 per-source-file inlining cap.
 //   contextMaxBytesTotal   — §5.4 total memory budget.
 //   skillMount             — §5.6 'copy' (default) | 'symlink' (opt-in).
+//   debugSpawnEnabled      — the stored spawn-diagnostics preference (a UI checkbox).
+//                            claude-runner.mjs reads it fresh on every spawn through
+//                            effectiveDebugSpawn(), so it applies to the UI server AND
+//                            to CLI runs with no restart. A NON-EMPTY WORCA_DEBUG_SPAWN
+//                            in the process environment overrides it (power-user
+//                            override); this module never writes process.env.
 //   pipelineCostLimitUsd   — per-pipeline lifetime USD spend cap; unset = no limit.
 //   totalCostLimitUsd      — windowed all-pipelines USD spend cap; unset = no limit.
 //   costLimitResetPeriod   — total-budget window, 'weekly' | 'monthly' (default).
@@ -42,7 +48,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
-import { EFFORTS, isReservedModelEnvKey, assertModelCost } from './model-env.mjs';
+import { EFFORTS, isReservedModelEnvKey, assertModelCost, envFlag } from './model-env.mjs';
 
 /**
  * The real OS home base, honoring HOME/USERPROFILE so tests can sandbox it.
@@ -526,6 +532,75 @@ export async function setCostLimitResetPeriod(input) {
   return { costLimitResetPeriod: costLimitResetPeriod() };
 }
 
+// ── The keys POST /api/settings understands ──────────────────────────────────
+// The route keeps a legacy contract: a body naming NONE of these clears root
+// (test/settings-projects-root.test.mjs "a bodyless POST resets root"). Every
+// setter's key is listed HERE, beside the setters, so a new key cannot forget
+// to join a hand-maintained exclusion list in the route and wipe the root on
+// its first save.
+export const SETTINGS_POST_KEYS = Object.freeze([
+  'root', 'projectsRoot', 'chat',
+  'pipelineCostLimitUsd', 'totalCostLimitUsd', 'costLimitResetPeriod',
+  'askMaxTurns', 'askMaxBudgetUsd',
+  'debugSpawnEnabled',
+]);
+
+// ── Spawn-debug diagnostics toggle (the stored side of WORCA_DEBUG_SPAWN) ────
+// Like every other stored setting (skillMount, the cost caps, the ask caps) this
+// is READ AT USE TIME: claude-runner.mjs#debugSpawnEnabled calls
+// effectiveDebugSpawn() on every spawn, so a UI save reaches the very next spawn
+// in this process and in any CLI process with no restart, and nothing here ever
+// mutates process.env (a runtime env write would leak an explicit
+// WORCA_DEBUG_SPAWN=0 into every inherited child env and break the runner's
+// "OFF ⇒ byte-identical spawn env" invariant).
+export const DEFAULT_DEBUG_SPAWN_ENABLED = false;
+
+const isBool = (v) => typeof v === 'boolean';
+
+/** @throws {Error} unless `input` is a boolean (the route and the setter share this). */
+export function assertDebugSpawnInput(input) {
+  if (!isBool(input)) throw new Error('debugSpawnEnabled must be true or false');
+}
+
+/** STORED spawn-debug preference: boolean, default OFF. Invalid stored value ⇒ OFF (loudly). */
+export function debugSpawnEnabled() {
+  const v = readSettings().debugSpawnEnabled;
+  if (v === undefined) return DEFAULT_DEBUG_SPAWN_ENABLED;
+  if (isBool(v)) return v;
+  console.warn(`[worca] invalid debugSpawnEnabled ${JSON.stringify(v)} — using the default (${DEFAULT_DEBUG_SPAWN_ENABLED})`);
+  return DEFAULT_DEBUG_SPAWN_ENABLED;
+}
+
+/**
+ * What the runner will actually do on the next spawn, and why. ONE precedence
+ * rule, shared by the runner gate and the settings API: a NON-EMPTY
+ * WORCA_DEBUG_SPAWN in the environment wins (parsed with the envFlag rule, so an
+ * exported "0"/"false" is an explicit OFF override), otherwise the stored
+ * preference applies. An empty export (`export WORCA_DEBUG_SPAWN=` in a profile
+ * or a dotenv template) is NOT an override — the runner would read it as OFF
+ * while the UI showed the stored value checked, with nothing explaining why.
+ * @returns {{enabled: boolean, source: 'env'|'settings'}}
+ */
+export function effectiveDebugSpawn() {
+  const v = process.env.WORCA_DEBUG_SPAWN;
+  if (v !== undefined && v !== '') return { enabled: envFlag('WORCA_DEBUG_SPAWN'), source: 'env' };
+  return { enabled: debugSpawnEnabled(), source: 'settings' };
+}
+
+/**
+ * Persist the preference. Nothing else: the runner reads it back per spawn, so
+ * the change is live everywhere without touching this process's environment.
+ * @throws {Error} unless `input` is a boolean.
+ */
+export async function setDebugSpawnEnabled(input) {
+  assertDebugSpawnInput(input);
+  const settings = readSettings();
+  if (input === DEFAULT_DEBUG_SPAWN_ENABLED) delete settings.debugSpawnEnabled;
+  else settings.debugSpawnEnabled = input;
+  await persistSettings(settings);
+  return { debugSpawnEnabled: debugSpawnEnabled() };
+}
+
 // ---------------------------------------------------------------------------
 // Global model catalog (configurable-models-design.md §4.1). Stored entries are
 // MINIMAL — label only when it differs from id, efforts only when a proper

package/ui/public/app.js

@@ -626,6 +626,12 @@ function handleServerMessage(msg) {
     refreshBudget();
     return;
   }
+  // Another tab saved a Settings card: repaint ours from the server so a stale
+  // checkbox/field cannot be "saved" back over the change.
+  if (msg.type === 'settings-changed') {
+    loadSettings();
+    return;
+  }
   if (msg.type === 'projects-changed') {
     refreshAllCounts();
     if (currentView() === 'projects') loadProjectsView();
@@ -770,6 +776,7 @@ function onHello(msg) {
       kind: r0.kind || 'run',
       pipelineId: r0.pipelineId || null,
       pauseReason: r0.pauseReason || null,
+      pauseDetail: r0.pauseDetail || null,
       workspaceId: r0.workspaceId || undefined,
       projectNames: Array.isArray(r0.projectNames) && r0.projectNames.length ? r0.projectNames : undefined,
     });
@@ -898,6 +905,7 @@ function nowHMS() {
 function makeRun({
   runId, title, projectDir, status = 'running', startedAt, local = false,
   pendingQuestion = null, kind = 'run', pipelineId = null, pauseReason = null,
+  pauseDetail = null,
   workspaceId = undefined, workspaceName = undefined, projectNames = null,
 }) {
   return {
@@ -912,6 +920,7 @@ function makeRun({
     pipelineId,           // matches a History row id once persisted; used to hide lingerers from History
     pauseReason,          // why it paused, or null — ANY orchestrator pause code rides here
                           // (e.g. 'usage_limit'); only the cost pair renders a cost banner
+    pauseDetail,          // the human-readable cause behind an 'error' pause, or null
     workspaceId,
     workspaceName,
     // Stable ordering key: assigned once per runId, never bumped by activity
@@ -4054,7 +4063,8 @@ function renderGateBody(r, panel, pq) {
 }
 
 // Recovery prompt: a node hit a recoverable error (auth / rate-limit / quota /
-// network). Show the cause and let the user fix it then Retry, or Abort the run.
+// network). Show the cause and let the user fix it then Retry, or park the run
+// with Pause run — nothing here ends a run, only Stop does.
 function renderRecoveryBody(r, panel, pq) {
   const rec = pq.recovery || {};
   const intro = document.createElement('div');
@@ -4062,7 +4072,7 @@ function renderRecoveryBody(r, panel, pq) {
   const hint = rec.cls === 'auth'
     ? 'Re-authenticate (e.g. run `claude setup-token` or `/login`), then Retry.'
     : 'Fix the problem (wait out a limit, restore connectivity, top up credit), then Retry.';
-  intro.textContent = `This step could not reach the model. ${hint}`;
+  intro.textContent = `This step could not reach the model. ${hint} Or pause the run and come back later — only Stop ends it.`;
   panel.appendChild(intro);
 
   if (rec.message) {
@@ -4074,15 +4084,21 @@ function renderRecoveryBody(r, panel, pq) {
 
   const foot = document.createElement('div');
   foot.className = 'qpanel-foot gate-actions';
-  const abort = document.createElement('button');
-  abort.type = 'button';
-  abort.className = 'btn recovery-abort';
-  abort.textContent = 'Abort run';
+  // The give-up option comes from the failure policy's row (options ride the
+  // prompt): 'pause' parks the run, 'abort' ends it. Older payloads carry none.
+  const giveUp = (Array.isArray(rec.options) && rec.options.find((o) => o && o.id !== 'retry')) || { id: 'pause' };
+  const pause = document.createElement('button');
+  pause.type = 'button';
+  pause.className = giveUp.id === 'abort' ? 'btn recovery-abort' : 'btn recovery-pause';
+  pause.textContent = giveUp.id === 'abort' ? 'Abort run' : 'Pause run';
+  pause.title = giveUp.id === 'abort'
+    ? 'End the run here with this error. The worktree is torn down.'
+    : 'Park the run here with this error as the reason. Nothing is discarded — Resume retries the step later.';
   const retry = document.createElement('button');
   retry.type = 'button';
   retry.className = 'btn btn-primary recovery-retry';
   retry.textContent = 'Retry';
-  foot.append(abort, retry);
+  foot.append(pause, retry);
   panel.appendChild(foot);
 }
 
@@ -4269,6 +4285,9 @@ function onDone(r, msg) {
   // unconditionally so a later reasonless done clears it, matching the server's
   // own entry.pauseReason reset in wireRun.
   r.pauseReason = msg.reason || null;
+  // An 'error' pause also carries the cause it parked on; assigned unconditionally
+  // for the same reason as the code above — a later reasonless done must clear it.
+  r.pauseDetail = msg.detail || null;
   finishRun(r, msg.status || 'done');
   // Nothing else picks up the FINAL spend delta: a non-cost `done` broadcasts no
   // budget-changed, and startBudgetTick refetches only while runs are live. Without
@@ -7682,9 +7701,11 @@ async function loadSettings() {
     paintSettings(data);
     paintBudgetSettings(data);
     paintAskSettings(data);
+    paintDebugSpawnSettings(data);
     paintBudgetReadout();
     refreshBudget();
     paintChatSettings(data.chat);
+    loadAskHistory();
     setSettingsMsg('');
   } catch (e) { setSettingsMsg(e.message, 'err'); }
 }
@@ -7962,10 +7983,27 @@ if (el.budgetReset) {
 }
 
 // ---- Ask Worca limits card (budget-card pattern above) ---------------------
-function setAskLimitsMsg(text, kind) {
-  const n = document.getElementById('askLimitsMsg');
+// Shared by the small Settings cards (Ask Worca, Spawn diagnostics): one hint
+// setter and one "POST /api/settings → parse → paint or show the error" routine,
+// so a fix to the fetch/parse/error path lands in every card at once.
+function setHintMsg(id, text, kind) {
+  const n = document.getElementById(id);
   if (n) { n.textContent = text || ''; n.className = `hint${kind ? ` ${kind}` : ''}`; }
 }
+async function postSettingsCard(body, { setMsg, paint, savedText = 'Saved.' }) {
+  setMsg('');
+  let res;
+  try {
+    res = await fetch('/api/settings', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  } catch (e) { setMsg(e.message || 'network error', 'err'); return; }
+  const data = await safeJson(res);
+  if (!res.ok) { setMsg(data.error || `HTTP ${res.status}`, 'err'); return; }
+  // A 2xx with an unparsable body yields {} — leave the card as the user set it
+  // rather than painting every field as "unset".
+  if (Object.keys(data).length) paint(data);
+  setMsg(savedText);
+}
+function setAskLimitsMsg(text, kind) { setHintMsg('askLimitsMsg', text, kind); }
 function paintAskSettings(data) {
   const turns = document.getElementById('askMaxTurns');
   const budget = document.getElementById('askMaxBudgetUsd');
@@ -7976,17 +8014,8 @@ function paintAskSettings(data) {
   budget.disabled = noCap.checked;
   budget.value = data.askMaxBudgetUsd == null ? '' : String(data.askMaxBudgetUsd);
 }
-async function postAskLimits(body) {
-  setAskLimitsMsg('');
-  let res = null;
-  try {
-    res = await fetch('/api/settings', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
-  } catch { setAskLimitsMsg('network error', 'err'); return; }
-  let data = null;
-  try { data = await res.json(); } catch { data = null; }
-  if (!res.ok) { setAskLimitsMsg((data && data.error) || `save failed (${res.status})`, 'err'); return; }
-  paintAskSettings(data || {});
-  setAskLimitsMsg('Saved.');
+function postAskLimits(body) {
+  return postSettingsCard(body, { setMsg: setAskLimitsMsg, paint: paintAskSettings });
 }
 function saveAskLimits() {
   const turnsRaw = document.getElementById('askMaxTurns').value.trim();
@@ -8014,6 +8043,108 @@ document.getElementById('askNoCap')?.addEventListener('change', () => {
   if (budget) budget.disabled = document.getElementById('askNoCap').checked;
 });
 
+// ---- Ask Worca chat history (same card, same hint pattern) -----------------
+// The counts line paints with the settings view; the destructive button refetches
+// GET /api/ask/history so the dialog quotes what is about to go, then one bulk
+// DELETE /api/ask/threads. The server broadcasts ask-history-cleared afterwards
+// — the ask panel resets itself off that frame, nothing to do here.
+function setAskHistoryMsg(text, kind) {
+  const n = document.getElementById('askHistoryMsg');
+  if (n) { n.textContent = text || ''; n.className = `hint${kind ? ` ${kind}` : ''}`; }
+}
+function askHistoryCount(n, one, many = `${one}s`) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+function normalizeAskHistory(data) {
+  const num = (v) => (Number.isInteger(v) && v > 0 ? v : 0);
+  return { threads: num(data?.threads), worktrees: num(data?.worktrees), attachments: num(data?.attachments), inFlight: num(data?.inFlight) };
+}
+function paintAskHistory(counts) {
+  const line = document.getElementById('askHistoryCounts');
+  const btn = document.getElementById('askHistoryDelete');
+  if (!line || !btn) return;
+  line.textContent = counts.threads
+    ? `${askHistoryCount(counts.threads, 'chat')} · ${askHistoryCount(counts.worktrees, 'worktree')}`
+    : 'No saved chats.';
+  btn.disabled = counts.threads === 0;
+}
+async function fetchAskHistory() {
+  const res = await fetch('/api/ask/history');
+  const data = await safeJson(res);
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return normalizeAskHistory(data);
+}
+async function loadAskHistory() {
+  if (!document.getElementById('askHistoryCounts')) return;
+  try { paintAskHistory(await fetchAskHistory()); } catch (e) { setAskHistoryMsg(e.message, 'err'); }
+}
+// One bullet per non-zero count; the in-progress line only when a turn is live.
+function askHistoryConfirmMessage(c) {
+  const lines = ['This permanently deletes all Ask Worca chat history:'];
+  if (c.threads) lines.push(`• ${askHistoryCount(c.threads, 'chat thread')} and ${c.threads === 1 ? 'its transcript' : 'their transcripts'}`);
+  if (c.worktrees) {
+    lines.push(`• ${askHistoryCount(c.worktrees, 'git worktree')} checked out for ${c.threads === 1 ? 'that chat' : 'those chats'} (removed from ${c.worktrees === 1 ? 'its source repo' : 'their source repos'})`);
+  }
+  if (c.attachments) lines.push(`• ${askHistoryCount(c.attachments, 'attachment')}`);
+  if (c.inFlight) lines.push(`• ${askHistoryCount(c.inFlight, 'chat')} currently in progress will be stopped`);
+  lines.push('Runs started from these chats are not affected. This cannot be undone.');
+  return lines.join('\n');
+}
+async function deleteAskHistory() {
+  setAskHistoryMsg('');
+  let counts;
+  try { counts = await fetchAskHistory(); } catch (e) { setAskHistoryMsg(e.message, 'err'); return; }
+  paintAskHistory(counts);
+  if (!counts.threads) return;   // emptied meanwhile — nothing to confirm
+  const ok = await confirmModal({
+    title: 'Delete all chat history?',
+    message: askHistoryConfirmMessage(counts),
+    confirmLabel: 'Delete everything',
+    danger: true,
+  });
+  if (!ok) return;
+  let res = null;
+  try {
+    res = await fetch('/api/ask/threads', { method: 'DELETE' });
+  } catch { setAskHistoryMsg('network error', 'err'); return; }
+  const data = await safeJson(res);
+  if (!res.ok) { setAskHistoryMsg(data.error || `HTTP ${res.status}`, 'err'); await loadAskHistory(); return; }
+  const removed = normalizeAskHistory(data.removed);
+  const failed = Array.isArray(data.failed) ? data.failed.length : 0;
+  const summary = `Deleted ${askHistoryCount(removed.threads, 'chat')} and ${askHistoryCount(removed.worktrees, 'worktree')}.`;
+  if (failed) setAskHistoryMsg(`${summary} ${askHistoryCount(failed, 'chat')} could not be removed.`, 'err');
+  else setAskHistoryMsg(summary);
+  await loadAskHistory();
+}
+document.getElementById('askHistoryDelete')?.addEventListener('click', deleteAskHistory);
+
+// ---- Spawn-debug diagnostics card (shares the Ask card's helpers above) ----
+function setDebugSpawnMsg(text, kind) { setHintMsg('debugSpawnMsg', text, kind); }
+// The checkbox is the STORED preference; the note says when the environment
+// overrides it (a non-empty WORCA_DEBUG_SPAWN at launch), so an operator never
+// sees an unchecked box while diagnostics are flowing — or the reverse.
+function paintDebugSpawnSettings(data) {
+  const cb = document.getElementById('debugSpawnEnabled');
+  if (!cb) return;
+  cb.checked = !!data.debugSpawnEnabled;
+  const eff = data.debugSpawnEffective;
+  const envOverride = !!eff && eff.source === 'env';
+  setHintMsg('debugSpawnEnvNote', envOverride
+    ? `WORCA_DEBUG_SPAWN is set in the environment: diagnostics are ${eff.enabled ? 'ON' : 'OFF'} regardless of this setting.`
+    : '', envOverride ? 'warn' : '');
+}
+function postDebugSpawn(body) {
+  return postSettingsCard(body, {
+    setMsg: setDebugSpawnMsg, paint: paintDebugSpawnSettings,
+    savedText: 'Saved. Applies to the next spawn — no restart needed.',
+  });
+}
+function saveDebugSpawn() {
+  postDebugSpawn({ debugSpawnEnabled: document.getElementById('debugSpawnEnabled').checked });
+}
+document.getElementById('debugSpawnSave')?.addEventListener('click', saveDebugSpawn);
+document.getElementById('debugSpawnReset')?.addEventListener('click', () => postDebugSpawn({ debugSpawnEnabled: false }));
+
 // Browse… for the projects root: native OS dialog, in-app modal fallback —
 // the same two endpoints the add-project Browse button uses (app.js:3793).
 if (el.settingsProjectsRootBrowse) {
@@ -9435,7 +9566,7 @@ if (runListEl) {
 
     // qpanel actions. Resolve the run per-card via the enclosing .run-card so
     // delegation works for any dynamically-built card.
-    const qbtn = e.target.closest && e.target.closest('.qpanel .btn-go, .qpanel .gate-continue, .qpanel .gate-another, .qpanel .recovery-retry, .qpanel .recovery-abort');
+    const qbtn = e.target.closest && e.target.closest('.qpanel .btn-go, .qpanel .gate-continue, .qpanel .gate-another, .qpanel .recovery-retry, .qpanel .recovery-pause, .qpanel .recovery-abort');
     if (qbtn) {
       const card = qbtn.closest('.run-card');
       const runId = card && card.dataset.runId;
@@ -9444,6 +9575,7 @@ if (runListEl) {
       if (qbtn.classList.contains('gate-continue')) postAnswer(r, { decision: 'continue' });
       else if (qbtn.classList.contains('gate-another')) postAnswer(r, { decision: 'another' });
       else if (qbtn.classList.contains('recovery-retry')) postAnswer(r, { decision: 'retry' });
+      else if (qbtn.classList.contains('recovery-pause')) postAnswer(r, { decision: 'pause' });
       else if (qbtn.classList.contains('recovery-abort')) postAnswer(r, { decision: 'abort' });
       else submitAnswer(r, qbtn.closest('.qpanel'));
     }
@@ -10288,12 +10420,19 @@ const PAUSED_STATUSES = ['paused', 'pausing', 'interrupted'];
 // Disable a history Resume button while a total-budget pause is still blocked by
 // the current window. Shared by setupHdActions (first paint) and
 // refreshHistResumeGating (every later budget change).
-function applyHistResumeGate(btn, pauseReason, budget) {
+function applyHistResumeGate(btn, pauseReason, budget, pauseDetail = '') {
   const totalBlocked = pauseReason === 'cost_total' && !!(budget && budget.blocked);
   btn.disabled = totalBlocked;
-  btn.title = totalBlocked
-    ? `Total budget reached — blocked until ${fmtResetAtLocal(budget.windowEndMs)} or a higher total limit`
-    : '';
+  if (totalBlocked) {
+    btn.title = `Total budget reached — blocked until ${fmtResetAtLocal(budget.windowEndMs)} or a higher total limit`;
+  } else if (pauseReason === 'error' || pauseReason === 'recoverable') {
+    // An error pause is never gated — the tooltip carries the cause instead.
+    btn.title = pauseReason === 'recoverable'
+      ? `Paused on a recoverable error${pauseDetail ? `: ${pauseDetail}` : ''} — resume once it clears`
+      : `Paused after an error${pauseDetail ? `: ${pauseDetail}` : ''} — fix the cause, then resume`;
+  } else {
+    btn.title = '';
+  }
 }
 
 // Re-gate the mounted history Resume button from the dataset.pauseReason stamp
@@ -10312,7 +10451,7 @@ function refreshHistResumeGating() {
     // otherwise a `cost_total` block that lands later leaves the button enabled and
     // the user clicks into a guaranteed 403. Re-gate, then restore the D3 error
     // title when gating did not take the button away.
-    applyHistResumeGate(btn, root.dataset.pauseReason || '', budgetState.budget);
+    applyHistResumeGate(btn, root.dataset.pauseReason || '', budgetState.budget, root.dataset.pauseDetail || '');
     if (btn.dataset.resumeState === 'error' && btn.dataset.resumeError && !btn.disabled) {
       btn.title = btn.dataset.resumeError;
     }
@@ -10434,14 +10573,21 @@ function buildHistCard(projectDir, p, ghAvailable = false) {
   // Pause note. Resume + its budget gating live on the detail page now; the
   // dataset stamp survives for parity/debugging.
   const pauseReason = typeof p.pauseReason === 'string' ? p.pauseReason : '';
+  const pauseDetail = typeof p.pauseDetail === 'string' ? p.pauseDetail : '';
   if (pauseReason) node.dataset.pauseReason = pauseReason;
+  if (pauseDetail) node.dataset.pauseDetail = pauseDetail;
   const noteEl = node.querySelector('.hist-pausenote');
-  const costPaused = PAUSED_STATUSES.includes(String(p.status || '').toLowerCase())
-    && pauseReason.startsWith('cost_');
-  noteEl.hidden = !costPaused;
+  const parked = PAUSED_STATUSES.includes(String(p.status || '').toLowerCase());
+  const costPaused = parked && pauseReason.startsWith('cost_');
+  const errorPaused = parked && (pauseReason === 'error' || pauseReason === 'recoverable');
+  noteEl.hidden = !(costPaused || errorPaused);
   noteEl.textContent = costPaused
-    ? (pauseReason === 'cost_total' ? 'paused · total budget' : 'paused · cost limit') : '';
+    ? (pauseReason === 'cost_total' ? 'paused · total budget' : 'paused · cost limit')
+    : (errorPaused ? (pauseReason === 'recoverable' ? 'paused · recoverable' : 'paused · error') : '');
+  // The cause is too long for the caption line — it rides as the tooltip.
+  noteEl.title = errorPaused ? pauseDetail : '';
   noteEl.classList.toggle('total', costPaused && pauseReason === 'cost_total');
+  noteEl.classList.toggle('error', errorPaused);
 
   renderRetainedWork(node, p);           // badge only — the card has no banner node
   setupPrButton(node, projectDir, p, ghAvailable);
@@ -11466,14 +11612,48 @@ function hdRetainedFor(record, st) {
   return { retained: derived, provisional: true };
 }
 
+// Error-pause banner (D11): the cause, and the promise that nothing was discarded.
+function renderErrorPauseBanner(detail, reason = 'error') {
+  const recoverable = reason === 'recoverable';
+  const el = document.createElement('div');
+  el.className = 'pause-error-banner';
+  el.dataset.reason = reason;
+  const b = document.createElement('b');
+  b.textContent = recoverable ? 'Paused on a recoverable error' : 'Paused after an error';
+  const text = document.createElement('div');
+  text.className = 'peb-text';
+  text.textContent = detail || 'The run hit an error it could not recover from.';
+  const hint = document.createElement('div');
+  hint.className = 'peb-hint';
+  hint.textContent = recoverable
+    ? 'The run could not reach the model and parked itself. Nothing was discarded — once the cause clears (re-login, connectivity, credit, a rate limit), Resume retries the step.'
+    : 'Nothing was discarded: the worktree and the run position are kept. Fix the cause, then Resume.';
+  el.append(b, text, hint);
+  return el;
+}
+
 function paintHdBanners(screen, record, data) {
   const st = data.state;
   const banners = screen.querySelector('.hd-banners');
 
-  // Cost-pause banner. pauseReason lives on LIST rows only (rowToState has none),
-  // so a deep link gets it late — rebuild idempotently instead of once.
-  const pauseReason = typeof record.pauseReason === 'string' ? record.pauseReason : '';
+  // Pause banners. The LIST row is authoritative, but a deep link has only the
+  // stub until the row lands — so fall back to the DETAIL payload, which now
+  // carries both keys too. Rebuild idempotently instead of once.
+  const pauseReason = typeof record.pauseReason === 'string' ? record.pauseReason
+    : (typeof st.pauseReason === 'string' ? st.pauseReason : '');
   if (pauseReason) screen.dataset.pauseReason = pauseReason; else delete screen.dataset.pauseReason;
+  const pauseDetail = typeof record.pauseDetail === 'string' ? record.pauseDetail
+    : (typeof st.pauseDetail === 'string' ? st.pauseDetail : '');
+  if (pauseDetail) screen.dataset.pauseDetail = pauseDetail; else delete screen.dataset.pauseDetail;
+  // Keyed on the detail so a corrected cause replaces the banner instead of stacking.
+  const wantErr = (pauseReason === 'error' || pauseReason === 'recoverable') && HD_RESUMABLE.has(String(st.status || '').toLowerCase());
+  const oldErr = banners.querySelector('.pause-error-banner');
+  if (oldErr && (!wantErr || oldErr.dataset.detail !== pauseDetail || oldErr.dataset.reason !== pauseReason)) oldErr.remove();
+  if (wantErr && !banners.querySelector('.pause-error-banner')) {
+    const errBanner = renderErrorPauseBanner(pauseDetail, pauseReason);
+    errBanner.dataset.detail = pauseDetail;
+    banners.prepend(errBanner);
+  }
   // Rebuild the cost banner ONLY when the reason actually changed. An
   // unconditional remove+rebuild detaches the `.cb-override` button mid-flight:
   // that click awaits confirmModal then resumePipeline, and ANY paintHistory()
@@ -11585,7 +11765,7 @@ function setupHdActions(screen, record, data) {
   const resumeBtn = screen.querySelector('.hd-resume');
   if (HD_RESUMABLE.has(status) && st.resumable !== false) {
     resumeBtn.hidden = false;
-    applyHistResumeGate(resumeBtn, screen.dataset.pauseReason || '', budgetState.budget);
+    applyHistResumeGate(resumeBtn, screen.dataset.pauseReason || '', budgetState.budget, screen.dataset.pauseDetail || '');
     resumeBtn.addEventListener('click', () => {
       const r = hdCurrentRecord(record);              // never the load-time object
       resumePipeline(r, r.projectDir || null, resumeBtn);
@@ -13486,6 +13666,21 @@ function rdStateCopy(r, stepName) {
   // line and the banner above the graph never disagree.
   if (r.pauseReason === 'cost_pipeline') return 'Paused — pipeline cost limit reached.';
   if (r.pauseReason === 'cost_total') return 'Paused — total budget reached.';
+  if (r.pauseReason === 'error') {
+    const why = r.pauseDetail ? `: ${r.pauseDetail}` : '';
+    return `Paused after an error${why}. Fix the cause, then Resume — the worktree and progress are kept.`;
+  }
+  if (r.pauseReason === 'recoverable') {
+    const why = r.pauseDetail ? ` (${r.pauseDetail})` : '';
+    return `Paused on a recoverable error${why}. Once it clears, Resume retries the step — the worktree and progress are kept.`;
+  }
+  if (r.pauseReason === 'usage_limit') {
+    return `Paused — session/usage limit reached${r.pauseDetail ? ` (${r.pauseDetail})` : ''}. Resume after the reset.`;
+  }
+  if (r.pauseReason && (r.status === 'paused' || r.status === 'pausing' || r.status === 'interrupted')) {
+    // A legacy reason is the orchestrator's own text (a pre-policy session/usage-limit line).
+    return `Paused — ${r.pauseReason}. Resume once it clears.`;
+  }
   if (r.status === 'paused' || r.status === 'pausing' || r.status === 'interrupted') {
     return 'Paused by you. Agents in flight finished their checkpoint; nothing new is dispatched.';
   }
@@ -14274,10 +14469,14 @@ function statusPill(r) {
     // A cost pause names its cause so the pill alone explains why the run parked.
     if (r.pauseReason === 'cost_pipeline') return { family: 'amber', text: 'Paused · cost limit' };
     if (r.pauseReason === 'cost_total') return { family: 'amber', text: 'Paused · total budget' };
+    // An error pause is parked and resumable (never dead), so it stays in the amber family.
+    if (r.pauseReason === 'error') return { family: 'amber', text: 'Paused · error' };
+    if (r.pauseReason === 'recoverable') return { family: 'amber', text: 'Paused · recoverable' };
+    if (r.pauseReason === 'usage_limit') return { family: 'amber', text: 'Paused · usage limit' };
     return { family: 'amber', text: 'Paused' };
   }
   // Same family as `paused`: an interrupted run is parked and resumable, and
-  // PAUSED_STATUSES (app.js:8726) already treats it that way.
+  // PAUSED_STATUSES (app.js:10286) already treats it that way.
   if (r.status === 'interrupted') return { family: 'amber', text: 'Interrupted' };
   if (r.pendingQuestion != null) return { family: 'amber', text: 'Paused · awaiting answers' };
   if (r.status === 'starting') return { family: 'peach', text: 'Starting' };
@@ -14857,9 +15056,16 @@ function paintRunCard(r) {
   const totalBlocked = r.pauseReason === 'cost_total' && budgetState.budget?.blocked;
   if (resumeBtn) {
     resumeBtn.disabled = !!totalBlocked;
-    resumeBtn.title = totalBlocked
-      ? `Total budget reached — blocked until ${fmtResetAtLocal(budgetState.budget.windowEndMs)} or a higher total limit`
-      : stockResumeTitle();
+    if (totalBlocked) {
+      resumeBtn.title = `Total budget reached — blocked until ${fmtResetAtLocal(budgetState.budget.windowEndMs)} or a higher total limit`;
+    } else if (r.pauseReason === 'error' || r.pauseReason === 'recoverable') {
+      // The cause the run parked on, so the card alone explains what to fix.
+      resumeBtn.title = r.pauseReason === 'recoverable'
+        ? `Paused on a recoverable error${r.pauseDetail ? `: ${r.pauseDetail}` : ''} — resume once it clears`
+        : `Paused after an error${r.pauseDetail ? `: ${r.pauseDetail}` : ''} — fix the cause, then resume`;
+    } else {
+      resumeBtn.title = stockResumeTitle();
+    }
   }
 }
 
@@ -15273,6 +15479,19 @@ function paintRdBanners(screen, r) {
     banners.prepend(fresh);                      // above the retained-work banner
   }
 
+  // ---- error-pause banner (D11) ----
+  // Same conditional-rebuild shape as paintHdBanners': keyed on the detail so a
+  // repaint neither stacks a second banner nor freezes a corrected cause.
+  const errPaused = isPaused(r) && (r.pauseReason === 'error' || r.pauseReason === 'recoverable');
+  const errDetail = r.pauseDetail || '';
+  const oldErr = banners.querySelector('.pause-error-banner');
+  if (oldErr && (!errPaused || oldErr.dataset.detail !== errDetail)) oldErr.remove();
+  if (errPaused && !banners.querySelector('.pause-error-banner')) {
+    const errBanner = renderErrorPauseBanner(errDetail);
+    errBanner.dataset.detail = errDetail;
+    banners.prepend(errBanner);
+  }
+
   // ---- retained work (D11) ----
   // renderRetainedWork only READS `p.retainedWork`, so a derived carrier is fine
   // for the paint; every MUTATING helper below gets the same carrier so the
@@ -15319,11 +15538,12 @@ el.runDetail?.addEventListener('click', (e) => {
   if (override) { confirmCostOverride(r.runId, override); return; }   // async, fire-and-forget
   if (e.target.closest && e.target.closest('.cb-settings')) { location.hash = 'settings'; return; }
   const qbtn = e.target.closest && e.target.closest(
-    '.qpanel .btn-go, .qpanel .gate-continue, .qpanel .gate-another, .qpanel .recovery-retry, .qpanel .recovery-abort');
+    '.qpanel .btn-go, .qpanel .gate-continue, .qpanel .gate-another, .qpanel .recovery-retry, .qpanel .recovery-pause, .qpanel .recovery-abort');
   if (!qbtn) return;
   if (qbtn.classList.contains('gate-continue')) postAnswer(r, { decision: 'continue' });
   else if (qbtn.classList.contains('gate-another')) postAnswer(r, { decision: 'another' });
   else if (qbtn.classList.contains('recovery-retry')) postAnswer(r, { decision: 'retry' });
+  else if (qbtn.classList.contains('recovery-pause')) postAnswer(r, { decision: 'pause' });
   else if (qbtn.classList.contains('recovery-abort')) postAnswer(r, { decision: 'abort' });
   else submitAnswer(r, qbtn.closest('.qpanel'));
 });