create-pmos 0.517.0 → 0.519.0

package/workspace/lib/routes-next-prompt.js

@@ -2,16 +2,17 @@
 /* routes-next-prompt.js — the chat's suggested next prompt and its Sharper card over HTTP (batch 26 item 2, design B; lib/next-prompt.js).
  *
  *   GET  /api/next-prompt/prefs                    → { ok, next, sharpen, sharpenSet, style, rules, api }
- *        next: suggestions after a reply are on. sharpen: Sharpen as I type is on now ('auto' is on when Claude's runs go to the API, where a
- *        call takes about 2 s; a background `claude -p` run takes 10 s or more, too slow to follow typing). sharpenSet: 'auto'|'on'|'off'.
- *        style: 'polish'|'engineer'|'own'. rules: whether Your own rules are written. api: a key for the Claude API is set.
+ *        next: suggestions after a reply are on. sharpen: Sharpen as I type is on now (on unless the PM turned it off; 'auto' is off only
+ *        while an opted-in API path is failing). sharpenSet: 'auto'|'on'|'off'. style: 'polish'|'engineer'|'own'. rules: whether Your own
+ *        rules are written. api: the opted-in API path is in use (PMOS_NEXT_PROMPT_API=on and a key). apiDown: { why, auth } while it fails.
  *   POST /api/next-prompt/prefs   { key: 'next'|'sharpen'|'style'|'rules', value }          → { ok } (saved in <runtime>/next-prompt/prefs.json)
  *   POST /api/next-prompt/next    { key, asked, reply, initiative?, stage?, product?, title? }  → { ok, on, cards: [{ text, move, rec }] }
  *   POST /api/next-prompt/sharpen { key, text, reply?, initiative?, title? }                  → { ok, on, text | null }
  *
  * Both POSTs are page presses (lib/pm-guard.js requirePagePress; an agent session header is refused) and run ONE short Claude call:
- * on the API with the PM's key when one is set (lib/anthropic-key.js, model PMOS_NEXT_PROMPT_MODEL or claude-sonnet-5-5), else a headless
- * read-only run (lib/headless.js kind 'ask', origin briefing-ask:next-prompt:…). The answer goes through the shared door, lib/ai-guard.js file():
+ * a background read-only `claude -p` run on the PM's own Claude login (lib/headless.js kind 'ask', origin briefing-ask:next-prompt:…), the
+ * default (Wawan 2026-11-04). Only with PMOS_NEXT_PROMPT_API=on does it go to the API with the PM's key (lib/anthropic-key.js, model
+ * PMOS_NEXT_PROMPT_MODEL or claude-sonnet-5-5), and a failed API call then falls back to the background run. The answer goes through the shared door, lib/ai-guard.js file():
  * the kill switch (`pmos ai off next-prompt`, `pmos ai off sharpen-prompt`, PMOS_AI=off), the replay gate (fixtures/next-prompt-replay.json,
  * recorded answers, never a model), the citation check and the audit (<runtime>/ai-audit.jsonl). A card with no verified source is never
  * shown. The reply and the typed text a card cites are kept in <runtime>/next-prompt/ (the newest 30 files), outside every repository.
@@ -61,14 +62,29 @@ function setPref(runtimeDir, key, value) {
 const get = (ctx, k) => { const v = readPrefs(ctx.runtimeDir)[k]; return PREFS[k](v) ? v : undefined; };
 const envOf = (ctx) => ctx.env || process.env;
 
+/* Wawan 2026-11-04: "just default to normal claude session with -p". Both calls run as a background `claude -p` on the PM's own Claude login.
+ * The API key is used only when PMOS_NEXT_PROMPT_API=on opts in. */
 function apiKey(ctx) {
   const env = envOf(ctx);
-  if (/^(off|0|false|no)$/i.test(String(env.PMOS_NEXT_PROMPT_API || ''))) return null;
+  if (!/^(on|1|true|yes)$/i.test(String(env.PMOS_NEXT_PROMPT_API || ''))) return null;
   try { return require('./anthropic-key.js').getKey(ctx.runtimeDir, env); } catch { return null; }
 }
+/* The API's health, per state folder, in memory: after a failed call PMOS stops calling the API for DOWN_MS and uses the background run,
+ * so a spent balance or a refused key does not fail every reply again. A server restart, or a new key saved, tries the API again. */
+const DOWN_MS = 15 * 60 * 1000;
+const apiDown = new Map();   // runtimeDir → { until, why, auth, key }
+function downOf(ctx, key) {
+  const d = apiDown.get(ctx.runtimeDir);
+  if (!d) return null;
+  if (d.until <= Date.now() || d.key !== keyId(key)) { apiDown.delete(ctx.runtimeDir); return null; }
+  return d;
+}
+const keyId = (k) => (k ? crypto.createHash('sha1').update(String(k)).digest('hex').slice(0, 12) : '');
 function prefs(ctx) {
-  const set = get(ctx, 'sharpen') || 'auto', api = !!apiKey(ctx), style = get(ctx, 'style') || 'engineer', rules = String(get(ctx, 'rules') || '');
-  return { next: get(ctx, 'next') !== false, sharpen: set === 'on' || (set === 'auto' && api), sharpenSet: set, style, rules: !!rules.trim(), rulesText: rules, api };
+  const set = get(ctx, 'sharpen') || 'auto', k = apiKey(ctx), down = k ? downOf(ctx, k) : null, api = !!k && !down;
+  const style = get(ctx, 'style') || 'engineer', rules = String(get(ctx, 'rules') || '');
+  return { next: get(ctx, 'next') !== false, sharpen: set !== 'off' && !(set === 'auto' && k && down), sharpenSet: set, style, rules: !!rules.trim(), rulesText: rules, api,
+    ...(down ? { apiDown: { why: down.why, auth: down.auth } } : {}) };
 }
 function offWhy(ctx, job) {
   const why = AG.off(job, { env: envOf(ctx), settingsDir: ctx.runtimeDir });
@@ -81,31 +97,55 @@ function offWhy(ctx, job) {
 
 /* ── the call ────────────────────────────────────────────────────────────────────────────── */
 
-async function viaApi(key, prompt, env) {
-  const Anthropic = require('@anthropic-ai/sdk');
-  const api = new Anthropic({ apiKey: key });
-  const res = await api.messages.create({ model: String(env.PMOS_NEXT_PROMPT_MODEL || '').trim() || DEFAULT_MODEL, max_tokens: 800, messages: [{ role: 'user', content: prompt }] });
-  return (res.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+// A model the account cannot use (404) tries the next one before the call counts as failed.
+const MODELS = ['claude-sonnet-5-5', 'claude-sonnet-5', 'claude-haiku-5-5'];
+async function viaApi(key, prompt, env, create = null) {
+  const make = create || ((o) => { const Anthropic = require('@anthropic-ai/sdk'); return new Anthropic({ apiKey: key }).messages.create(o); });
+  const want = String(env.PMOS_NEXT_PROMPT_MODEL || '').trim();
+  const models = want ? [want] : MODELS;
+  for (let i = 0; i < models.length; i++) {
+    try {
+      const res = await make({ model: models[i], max_tokens: 800, messages: [{ role: 'user', content: prompt }] });
+      return (res.content || []).filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+    } catch (e) { if (!(e && e.status === 404) || i === models.length - 1) throw e; }
+  }
+  return null;
 }
-function viaHeadless(ctx, prompt, origin) {
+/** A background read-only Claude run → its answer text, or null after `fail(why)` says why it gave none. */
+function viaHeadless(ctx, prompt, origin, fail = () => {}) {
   const headless = require('./headless.js');
-  if (typeof ctx.spawnSession !== 'function' || headless.kindFor({ agent: 'claude', origin }) !== 'ask') return Promise.resolve(null);
+  if (typeof ctx.spawnSession !== 'function') { fail('no background run here'); return Promise.resolve(null); }
+  if (headless.kindFor({ agent: 'claude', origin }) !== 'ask') { fail('the run would not be read-only'); return Promise.resolve(null); }
   return new Promise((resolve) => {
-    let settled = false; const done = (v) => { if (!settled) { settled = true; clearTimeout(t); resolve(v); } };
-    const t = setTimeout(() => done(null), TIMEOUT_MS);
+    let settled = false; const done = (v, why) => { if (settled) return; settled = true; clearTimeout(t); if (v == null) fail(why); resolve(v); };
+    const t = setTimeout(() => done(null, 'the run took longer than ' + Math.round(TIMEOUT_MS / 1000) + ' s'), TIMEOUT_MS);
     let s = null;
     try {
       s = ctx.spawnSession({ name: 'chat: next prompt', agent: 'claude', origin, initialInput: prompt,
-        onDone: (d) => { const r = d && d.result; done(r && r.ok && !r.isError ? String(r.text || '') : null); } });
-    } catch { s = null; }
-    if (!s || s.state === 'exited') done(null);
+        onDone: (d) => { const r = d && d.result; done(r && r.ok && !r.isError ? String(r.text || '') : null, 'the run ended without an answer' + (d && d.note ? ': ' + String(d.note).slice(0, 80) : '')); } });
+    } catch (e) { s = null; }
+    if (!s || s.state === 'exited') done(null, 'the run did not start' + (s && s.note ? ': ' + String(s.note).slice(0, 80) : ''));
   });
 }
-async function ask(ctx, prompt, { job, key }) {
+/** Why an API call failed, in words fit for the audit: the HTTP status and the error's type, never the prompt or the answer. */
+function apiWhy(e) {
+  const st = e && (e.status || (e.response && e.response.status));
+  const kind = e && ((e.error && e.error.error && e.error.error.type) || e.name || e.code);
+  return ['api', st ? String(st) : null, kind ? String(kind).slice(0, 60) : null].filter(Boolean).join(' ');
+}
+/* One short Claude call. With a key it goes to the API; when that call fails (a spent balance, a model the account cannot use, no network),
+ * it does not end in silence: the same prompt goes to a background read-only Claude run, and the audit records why the API failed
+ * (`pmos ai log next-prompt`); for 15 minutes after, PMOS goes straight to the background run. `ctx.createMessage` replaces the SDK in tests. */
+async function ask(ctx, prompt, { job, key, run }) {
   if (typeof ctx.askClaude === 'function') return ctx.askClaude(prompt, { job, key });
   const k = apiKey(ctx);
-  if (k) { try { return await viaApi(k, prompt, envOf(ctx)); } catch { return null; } }
-  return viaHeadless(ctx, prompt, `briefing-ask:next-prompt:${job}:${crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 10)}`);
+  if (k && !downOf(ctx, k)) {
+    const failed = (why, auth) => { apiDown.set(ctx.runtimeDir, { until: Date.now() + DOWN_MS, why, auth: !!auth, key: keyId(k) }); AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'api-error', error: why }); };
+    try { const t = await viaApi(k, prompt, envOf(ctx), ctx.createMessage || null); if (t && String(t).trim()) return t; failed('api empty answer', false); }
+    catch (e) { failed(apiWhy(e), e && (e.status === 401 || e.status === 403)); }
+  }
+  return viaHeadless(ctx, prompt, `briefing-ask:next-prompt:${job}:${crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 10)}`,
+    (why) => AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'run-error', error: String(why).slice(0, 160) }));
 }
 
 /* ── what a card cites ───────────────────────────────────────────────────────────────────── */
@@ -182,7 +222,7 @@ async function next(ctx, b) {
   const k = 'n:' + key + ':' + crypto.createHash('sha1').update(reply + '\n' + P.style + '\n' + P.rulesText).digest('hex');
   return once(k, async () => {
     AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'start' });
-    const answer = await ask(ctx, NP.nextPrompt({ pm: text(b.asked, 2000), reply, place, style: P.style, rules: P.rulesText, moves }), { job, key });
+    const answer = await ask(ctx, NP.nextPrompt({ pm: text(b.asked, 2000), reply, place, style: P.style, rules: P.rulesText, moves }), { job, key, run });
     const cards = NP.parseNext(answer, { moves, place });
     if (!cards.length) { AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'end', filed: 0, dropped: 0, ...(answer == null ? { error: 'no answer' } : {}) }); return { ok: true, on: true, cards: [] }; }
     const rel = keep(ctx.runtimeDir, 'reply', reply);
@@ -200,7 +240,7 @@ async function sharpen(ctx, b) {
   const k = 's:' + key + ':' + crypto.createHash('sha1').update(typed + '\n' + P.style + '\n' + P.rulesText).digest('hex');
   return once(k, async () => {
     AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'start' });
-    const answer = await ask(ctx, NP.sharpenPrompt({ text: typed, reply: text(b.reply, 3000), place: placeOf(b), style: P.style, rules: P.rulesText }), { job, key });
+    const answer = await ask(ctx, NP.sharpenPrompt({ text: typed, reply: text(b.reply, 3000), place: placeOf(b), style: P.style, rules: P.rulesText }), { job, key, run });
     const out = NP.parseSharpen(answer, typed);
     if (!out) { AG.audit(ctx.runtimeDir, { job, version: VERSION, run, event: 'end', filed: 0, dropped: 0, ...(answer == null ? { error: 'no answer' } : { same: true }) }); return { ok: true, on: true, text: null }; }
     const first = typed.split('\n')[0], rel = keep(ctx.runtimeDir, 'typed', typed);
@@ -227,7 +267,7 @@ async function handle(req, res, url, ctx) {
     if (req.method !== 'GET') return send(bad(405, 'GET or POST only'));
     const P = prefs(ctx), env = envOf(ctx);
     const next = P.next && !AG.off(NP.JOB_NEXT, { env, settingsDir: ctx.runtimeDir }), sh = P.sharpen && !AG.off(NP.JOB_SHARPEN, { env, settingsDir: ctx.runtimeDir });
-    return send({ status: 200, body: { ok: true, next, nextSet: P.next, sharpen: sh, sharpenSet: P.sharpenSet, style: P.style, rules: P.rules, rulesText: P.rulesText, api: P.api } });
+    return send({ status: 200, body: { ok: true, next, nextSet: P.next, sharpen: sh, sharpenSet: P.sharpenSet, style: P.style, rules: P.rules, rulesText: P.rulesText, api: P.api, ...(P.apiDown ? { apiDown: P.apiDown } : {}) } });
   }
   if (what !== 'next' && what !== 'sharpen') return send(bad(404, 'no such next-prompt route'));
   if (req.method !== 'POST') return send(bad(405, 'POST only'));
@@ -245,4 +285,4 @@ async function handle(req, res, url, ctx) {
   catch (e) { return send(bad(500, 'The suggestion failed: ' + String((e && e.message) || e).slice(0, 200))); }
 }
 
-module.exports = { prefixes: ['/api/next-prompt'], handle, VERSION, FIXTURE, prefs, setPref, lineRef, replayCases, next, sharpen };
+module.exports = { prefixes: ['/api/next-prompt'], handle, VERSION, FIXTURE, MODELS, prefs, setPref, lineRef, replayCases, next, sharpen };

package/workspace/lib/routes-sources.js

@@ -5,7 +5,8 @@
  *                                              lib/harness-health.js of(): { level, line, issues } or null; all is the last Refresh all
  *                                              (lib/refresh-run.js allState) or null; derived is the content built from stored reads
  *                                              (refresh-run derived: the brief, core documents, the scan, and the reads each was built from).
- *                                              Each source row has a group: 'machine' (read on this machine) or 'connector'
+ *                                              Each source row has a group: 'machine' (read on this machine) or 'connector',
+ *                                              and `heal` while Claude repairs it by itself or it needs the PM (lib/source-heal.js view())
  *   POST /api/sources/refresh { ws, source } → { ok, source, started: 'rebuild'|'session', session? }
  *   POST /api/sources/refresh-all { ws }     → { ok, joined, started, already, failed, all }   every source that is on, then the
  *                                              Briefing from those reads (briefing-source-flow, slice 3); a press while one runs joins it
@@ -18,6 +19,7 @@
  */
 const guard = require('./pm-guard.js');
 const freshness = require('./freshness.js');
+const heal_ = require('./source-heal.js');
 
 function wsOf(ctx, id) {
   const w = ctx.getWs(id || '');
@@ -33,7 +35,9 @@ async function handle(req, res, url, ctx) {
     if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
     const w = wsOf(ctx, url.searchParams.get('ws'));
     if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
-    const sources = F.sources({ id: w.id, root: w.root, repoStateDir: repoStateDir(ctx, w) });
+    let heal = {}; try { heal = ctx.runtimeDir ? heal_.viewAll(ctx.runtimeDir) : {}; } catch { heal = {}; }
+    // self-heal (lib/source-heal.js): a row Claude is repairing, or that needs the PM, carries its repair
+    const sources = F.sources({ id: w.id, root: w.root, repoStateDir: repoStateDir(ctx, w) }).map((r) => (heal[r.id] ? { ...r, heal: heal[r.id] } : r));
     let health = null; try { health = ctx.health ? ctx.health() : null; } catch { health = null; }
     let all = null; try { all = ctx.refreshAllState ? ctx.refreshAllState() : null; } catch { all = null; }
     let derived = []; try { derived = ctx.refreshDerived ? ctx.refreshDerived(w.id) : []; } catch { derived = []; }

package/workspace/lib/source-heal.js

@@ -0,0 +1,140 @@
+'use strict';
+/* source-heal.js — Claude repairs a source that is behind by itself, and asks the PM only when the PM must act
+ * (feedback batch 26 item 7, Wawan 2026-11-03: "any issue with connection should self diagnose and resolve unless necessary for
+ * the user to take action").
+ *
+ *   diagnose(error, { result }) → cause    why a read failed: one of CAUSES' keys
+ *   step(x) → { h, start?, note?, tell? }   one tick for one source: what to do now, and its new repair record
+ *   view(h, name) → { state, cause, why, tried, action, attempts, next_at } | null   what /api/sources shows on the row
+ *   MAX · BACKOFF_MIN · CAUSES
+ *
+ * THE REPAIR. A source that is on and behind (stale, failed or never read) is read again by Claude, without a press. Attempt 1 starts
+ * at once; the next ones wait BACKOFF_MIN minutes (longer after a rate limit). After each attempt the cause is diagnosed from the
+ * run's end (the log's error), and a read that ended "done" while the source is still behind counts as failed ("saved nothing new"):
+ * a source is fresh only when a read proved it. A cause the PM must fix (a connector that is not connected, a sign-in that still
+ * fails after one more try) stops the repair at once; any other cause stops after MAX attempts. Then the record is `needs-you`,
+ * with the one action and what Claude tried. The schedule keeps running all the time, so a source the PM fixed turns fresh on its
+ * next read and the record becomes `repaired`.
+ *
+ * A source that is off is left alone (the PM chose it). A source that is read only on a press has no schedule to be past, so its
+ * one action is the press.
+ *
+ * PURE but for viewAll(dir), which reads <state>/source-heal.json for /api/sources (any server, not only the one that runs the
+ * schedules). lib/refresh-run.js holds the records, starts the reads, and writes each attempt to the refresh log (trigger 'repair',
+ * with the attempt and the last cause in its note).
+ */
+
+const MAX = 5;
+const BACKOFF_MIN = Object.freeze([0, 2, 10, 30, 120]);        // minutes before attempt n+1, by the attempts made so far
+const RATE_MIN = Object.freeze([0, 15, 60, 120, 240]);         // the same after a rate limit
+const KEEP_REPAIRED_MS = 24 * 3600 * 1000;                     // a repaired record is kept this long, then dropped
+
+const CONNECTORS = 'https://claude.ai/settings/connectors';
+/* cause → why (the words after "because"), user: the PM must act, after: attempts before that is sure (1 = the first failure tells) */
+const CAUSES = Object.freeze({
+  'claude-signin': { why: 'Claude is signed out on this computer', user: true, after: 2 },
+  'connector-missing': { why: 'its connector is not connected', user: true, after: 1 },
+  'sign-in': { why: 'its sign-in has expired', user: true, after: 2 },
+  'rate-limit': { why: 'it asked Claude to slow down', user: false },
+  network: { why: 'the network or the proxy did not answer', user: false },
+  'connector-failed': { why: 'its connector did not start', user: false },
+  interrupted: { why: 'the read was stopped before it ended', user: false },
+  empty: { why: 'the read ended but saved nothing new', user: false },
+  skill: { why: 'the read stopped with an error', user: false },
+  manual: { why: 'it is read only when you press ↻', user: true, after: 0 },
+});
+
+/** Why a read failed, from the error its run ended with. The order matters: Claude's own sign-in first, then a missing connector. */
+function diagnose(error, { result } = {}) {
+  const e = String(error || '').toLowerCase();
+  if (result === 'done') return 'empty';
+  if (/claude is signed out|not logged in|please run \/login|type \/login|invalid api key/.test(e)) return 'claude-signin';
+  if (/not connected|connector (is )?(missing|not (found|installed|available|configured|enabled))|no (\w+ )?(connector|mcp server)|no such tool|tools? .{0,40}not (available|found)|mcp server .{0,40}not (found|configured)/.test(e)) return 'connector-missing';
+  if (/\b429\b|rate.?limit|too many requests|quota|throttl/.test(e)) return 'rate-limit';
+  if (/\b401\b|unauthori[sz]ed|token (has )?expired|expired (token|session|credentials)|re-?authori[sz]|re-?authenticat|sign.?in (has )?expired|reconnect|invalid[_ ]grant|oauth/.test(e)) return 'sign-in';
+  if (/econn|etimedout|enotfound|eai_again|network|proxy|socket hang up|tunnel|\b50[234]\b|unreachable|\bdns\b|fetch failed/.test(e)) return 'network';
+  if (/failed to connect|mcp.{0,40}(error|failed)|connector.{0,40}(failed|error)/.test(e)) return 'connector-failed';
+  if (result === 'interrupted' || /stopped by you|restarted|session was gone/.test(e)) return 'interrupted';
+  return 'skill';
+}
+
+const behindOf = (row) => !!row && ['stale', 'failed', 'never'].includes(row.state);
+const waitMin = (cause, n) => { const L = cause === 'rate-limit' ? RATE_MIN : BACKOFF_MIN; return L[Math.min(n, L.length - 1)]; };
+
+/**
+ * One tick for one source. Every field is plain data:
+ *   x { now, row (lib/freshness.js row), on, manual, busy (a run is going, or the schedule's own retry or a press waits),
+ *       last (the source's last run in the log: { start_at, end_at, result, error }), h (its repair record or null), canStart }
+ * → { h, start?: true, note?, tell?: { cause, why } }   h null drops the record
+ */
+function step(x) {
+  const { now, row } = x;
+  let h = x.h ? { ...x.h, attempts: (x.h.attempts || []).slice() } : null;
+  if (!row || !x.on) return { h: null };
+  if (!behindOf(row)) {
+    if (h && h.state !== 'repaired' && (h.attempts.length || h.state === 'needs-you')) return { h: { ...h, state: 'repaired', repaired_at: now, open: null, next_at: null } };
+    if (h && h.state === 'repaired' && now - (h.repaired_at || 0) < KEEP_REPAIRED_MS) return { h };
+    return { h: null };
+  }
+  if (x.manual) return { h: { state: 'needs-you', cause: 'manual', attempts: [], since: (h && h.since) || now } };
+  if (!h || h.state === 'repaired' || h.cause === 'manual') h = { state: 'repairing', since: now, attempts: [], open: null, cause: null, next_at: null };
+
+  // the attempt that is open ends when its run ends in the log
+  if (h.open) {
+    const l = x.last;
+    const ended = l && l.end_at && Date.parse(l.start_at || l.end_at) >= h.open.at - 1000;
+    if (!ended) {
+      if (now - h.open.at < 30 * 60000 || x.busy) return { h: { ...h, state: 'repairing' } };
+      h.attempts.push({ at: h.open.at, result: 'lost', cause: 'interrupted' });   // no run came of it in 30 minutes
+    } else {
+      const cause = diagnose(l.error, { result: l.result });
+      h.attempts.push({ at: h.open.at, result: l.result, cause, error: l.error ? String(l.error).slice(0, 300) : null });
+    }
+    h.open = null; h.cause = h.attempts[h.attempts.length - 1].cause;
+  }
+  if (x.busy) return { h: { ...h, state: h.state === 'needs-you' ? 'needs-you' : 'repairing' } };
+  if (h.state === 'needs-you') return { h };   // the schedule keeps reading; a good read makes it repaired
+
+  const n = h.attempts.length;
+  const c = h.cause && CAUSES[h.cause];
+  const same = n >= (c && c.after || 1) && h.attempts.slice(-(c && c.after || 1)).every((a) => a.cause === h.cause);
+  if ((c && c.user && same) || n >= MAX) {
+    return { h: { ...h, state: 'needs-you', next_at: null, told_at: h.told_at || now }, tell: h.told_at ? null : { cause: h.cause, why: c ? c.why : '' } };
+  }
+  const next = n ? h.attempts[n - 1].at + waitMin(h.cause, n) * 60000 : now;
+  if (now < next || !x.canStart) return { h: { ...h, state: 'repairing', next_at: Math.max(next, now) } };
+  h.open = { at: now };
+  return { h: { ...h, state: 'repairing', next_at: null }, start: true, note: `Repair ${n + 1} of ${MAX}` + (c ? `: the last read failed because ${c.why}` : `: ${row.state === 'never' ? 'never read' : row.state === 'failed' ? 'the last read failed' : 'past its schedule'}`) };
+}
+
+const hm = (ms) => { const d = new Date(ms); return String(d.getHours()).padStart(2, '0') + ':' + String(d.getMinutes()).padStart(2, '0'); };
+
+/** What the Sources row and the banner show. `name` is the source's name ('Jira'). */
+function view(h, name = 'It') {
+  if (!h) return null;
+  const c = h.cause ? CAUSES[h.cause] : null;
+  const n = (h.attempts || []).length;
+  const tried = n ? `Claude read it again ${n === 1 ? 'once' : n + ' times'} since ${hm(h.attempts[0].at)}${c ? `, and ${c.why}` : ''}.` : '';
+  let action = null;
+  if (h.state === 'needs-you') {
+    if (h.cause === 'claude-signin') action = { label: 'Sign in to Claude', how: 'Open Terminal, run claude, type /login and sign in.', sec: 'claude' };
+    else if (h.cause === 'connector-missing') action = { label: 'Connect ' + name, how: 'Turn on its connector in your Claude connectors.', href: CONNECTORS };
+    else if (h.cause === 'sign-in') action = { label: 'Reconnect ' + name, how: 'Sign in to its connector again in your Claude connectors.', href: CONNECTORS };
+    else action = { label: 'Read ' + name + ' again', how: h.cause === 'manual' ? 'You chose to read it only when you press ↻.' : 'Claude stopped after ' + n + ' tries.', read: true };
+  }
+  return { state: h.state, cause: h.cause || null, why: c ? c.why : '', tried, action, attempts: n, next_at: h.next_at ? new Date(h.next_at).toISOString() : null,
+    ...(h.repaired_at ? { repaired_at: new Date(h.repaired_at).toISOString() } : {}) };
+}
+
+const NAME = Object.freeze({ calendar: 'your calendar', jira: 'Jira', 'my-work': 'Jira', tracker: 'the tracker files', tools: 'your tools' });   // who the PM reconnects
+const FILE = 'source-heal.json';
+/** Every repair record as view() shows it, keyed by its lib/freshness.js id. A missing or torn file is no repair. */
+function viewAll(dir) {
+  let x = {};
+  try { x = JSON.parse(require('fs').readFileSync(require('path').join(dir, FILE), 'utf8')) || {}; } catch { return {}; }
+  const out = {};
+  for (const [id, h] of Object.entries(x)) if (h && typeof h === 'object') out[h.fresh || id] = view(h, NAME[h.fresh || id] || id);
+  return out;
+}
+
+module.exports = { viewAll, FILE, NAME, diagnose, step, view, MAX, BACKOFF_MIN, RATE_MIN, CAUSES, CONNECTORS };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.517.0",
+  "version": "0.519.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.517.0",
+      "version": "0.519.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^1.3.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.517.0",
+  "version": "0.519.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/bd-span.js

@@ -524,7 +524,7 @@ function scaled(rows, M, o) {
   const msO = { sp, reach: Math.max(1, Math.round(40 / pxDay)), mode: o.msMode || 'pinned', noLabel: !!(C && C.msOn) };   // a row's milestone ◇s closer than ~40 px merge (batch 11 item 3); the Filter's milestones (batch 13 item 4)
   const ov = overlay(W, X, now, sprint, rel), pxPct = (tpx * (W.fixed ? 1 : ratio)) / 100;
   const ra = rel && day(rel.iso), sa = sprint && day(sprint.start), sb = sprint && day(sprint.end);
-  // an undated program member's track says so beside today, where the view opens
+  // an undated initiative's track says so beside today, where the view opens
   const ND = `<span class="tg-nd" style="left:${P(Math.min(90, Math.max(0, X(now))))}">No dates</span>`;
   const askBtn = none.length ? `<a class="bd-chip tg-ask" id="askDates" href="${esc(o.askHref(none))}">${SV('M4 5h16v11h-9l-5 4v-4H4z')}Ask to propose dates</a>` : '';
   const ticks = W.ticks.map((k) => `<span style="left:${P(X(k.at))}" data-y="${k.y}" data-base="${esc(k.base)}"${k.plain ? ' data-plain' : ''}><b>${esc(k.label)}</b><small>${esc(k.sub)}</small></span>`).join('');
@@ -533,23 +533,19 @@ function scaled(rows, M, o) {
   const back = `<button type="button" class="tg-tback" data-today hidden aria-label="Back to today">${SV(CHL)}<span>Today</span>${SV(CHR)}</button>`;
   const attrs = `data-span="${sp}" data-from="${+W.from}" data-to="${+W.to}" data-ratio="${W.fixed ? 1 : ratio.toFixed(5)}" data-now="${+now}"${W.fixed ? ' data-fixed' : ''}`;
   const style = `--tw:${Math.round(tpx * (W.fixed ? 1 : ratio))}px`;
-  // a program keeps its undated initiatives as rows that say "No dates" (feedback batch 8 item 4: initiatives just moved into a program
-  // were missing under it); a product group keeps only the dated ones, and the foot names the rest
-  // by key, not by identity: By product copies a program's row ({ ...r, inProgram }), and that copy is never in `list` (batch 11 item 12: a
-  // program's initiatives were missing from their product on the timeline)
-  // By product, a program's undated initiative keeps its "No dates" row under its product too (batch 11 item 19: they disappeared once grouped by product)
-  const onList = new Set(list.map((r) => r.key));
-  // a product with no dated initiative keeps its head and its initiatives as "No dates" rows, so the product is not missing from the Board
-  // (batch 14 item 2: pmos-microsites, all undated outside its program, had no group at all); those rows leave the foot's names
-  const keepOf = (R) => { const k = R.filter((r) => onList.has(r.key) || r.inProgram); return k.length ? k : R.slice(); };
-  const shownNd = new Set(o.groups ? o.groups.filter((g) => g.kind !== 'program' && !g.rows.some((r) => onList.has(r.key) || r.inProgram)).flatMap((g) => g.rows.map((r) => r.key)) : []);
-  const footNone = none.filter((r) => !shownNd.has(r.key));
+  // every undated initiative is a row that says "No dates" beside today, in every grouping and in no program too (batch 26 item 8, Wawan:
+  // the foot alone hid them; this replaces batch 8 item 4's program-only rule and design B6). By product copies a program's row
+  // ({ ...r, inProgram }), so a row is matched by key, not by identity (batch 11 item 12)
+  const shownKeys = new Set(o.groups ? o.groups.flatMap((g) => (g.kind === 'program' ? g.products.flatMap((x) => x.rows) : g.rows).map((r) => r.key)) : rows.map((r) => r.key));
+  // the foot keeps the count and "Ask to propose dates"; it names only an undated initiative no group draws (none, as the Board groups today)
+  const footNone = none.filter((r) => !shownKeys.has(r.key));
   // a timeline reads in time (batch 11 item 22): each group's rows by start, then end; undated ones last. The health dot still says late or at risk
   const at = (r) => { const x = extentOf(r, now); return x ? [+x.a, +x.b] : [Infinity, Infinity]; };
   // a pressed column title sorts each group by that column instead (StsA8Board, as in the List)
   const byTime = (L) => (C && C.order ? L.slice().sort(C.order) : L.map((r) => [at(r), r]).sort((p, q) => p[0][0] - q[0][0] || p[0][1] - q[0][1]).map((x) => x[1]));
   list.splice(0, list.length, ...byTime(list));
-  const G = o.groups ? o.groups.map((g) => (g.kind === 'program' ? { ...g, products: g.products.filter((x) => x.rows.length).map((x) => ({ ...x, rows: byTime(x.rows) })) } : { ...g, rows: byTime(keepOf(g.rows)) })).filter((g) => g.rows.length || g.kind === 'program') : null;
+  const flat = list.concat(none);
+  const G = o.groups ? o.groups.map((g) => (g.kind === 'program' ? { ...g, products: g.products.filter((x) => x.rows.length).map((x) => ({ ...x, rows: byTime(x.rows) })) } : { ...g, rows: byTime(g.rows) })).filter((g) => g.rows.length || g.kind === 'program') : null;
   const empty = '<p class="tg-empty">No initiative on screen has a date on record.</p>';
   const ext = (r) => { const x = extentOf(r, now); return x ? ` data-a="${X(x.a).toFixed(3)}" data-b="${X(x.b).toFixed(3)}"` : ''; };
   // a product's head carries its lane from Quarter on (batch 11 item 17); Sprint on a phone, and a page that gives no head cell, keep the plain head
@@ -561,9 +557,9 @@ function scaled(rows, M, o) {
       if (g.kind !== 'program') return lane(g) + (o.folded(g.key) ? '' : g.rows.map(one).join(''));
       const st = o.progState(g.program), shut = o.folded(g.key), tr = shut ? rollUp(g.rows, progSpan(g), X, W, o, msO, pxPct, now) : '';
       return `<div class="tgq-r tg-pg${shut ? ' closed' : ''}" data-prow="${esc(g.program.id)}"><div class="tgq-n tg-pgn">${progName(g, st, o, shut ? offDots(g.rows, now) : '')}</div><div class="tg-p">${ov}${tr}</div></div>` + (shut ? '' : g.products.map((x) => x.rows.map(one).join('')).join(''));
-    }).join('') : list.map(one).join('');
+    }).join('') : flat.map(one).join('');
     const top = `<div class="tgq-h"><div class="tg-p">${ticks}${pill}</div></div>`;
-    const below = none.length ? `<div class="tg-none">${footNone.length ? `<span>${footNone.length} ${footNone.length === 1 ? 'has' : 'have'} no dates</span>` : ''}${askBtn}</div>` : '';
+    const below = none.length ? `<div class="tg-none"><span>${none.length} ${none.length === 1 ? 'has' : 'have'} no dates</span>${askBtn}</div>` : '';
     // the Deliveries lane (batch 13 item 4, XcalmA6Phone): a phone shows the next deliveries above the rows (o.lane draws it; none: nothing)
     const lanePh = o.lane ? o.lane({ W, X, rows: list, groups: G, now, phone: true, pxPct }) || '' : '';
     return { html: lanePh + `<div class="tg tg-s tgq" ${attrs}><div class="tg-scw"><div class="tg-sc" tabindex="0" role="group" aria-label="Timeline" style="${style}"><div class="tg-in">${top}<div class="tg-body">${body || empty}</div></div></div>${back}<i class="tg-fade l" aria-hidden="true"></i><i class="tg-fade r" aria-hidden="true"></i></div></div>${below}`, none };
@@ -581,11 +577,11 @@ function scaled(rows, M, o) {
     if (g.kind !== 'program') return lane(g) + (o.folded(g.key) ? '' : g.rows.map((r) => one(r, ' tg-gr')).join(''));
     const lp = g.products[g.products.length - 1], last = lp ? lp.rows[lp.rows.length - 1] : null;
     return progRow(g, o.progState(g.program), X, W, ov, o, msO, pxPct, now) + (o.folded(g.key) ? '' : g.products.map((x) => (g.products.length > 1 ? o.subHtml(x.name) : '') + x.rows.map((r) => one(r, ' tg-kid' + (r === last ? ' last' : ''))).join('')).join(''));
-  }).join('') : list.map((r) => one(r)).join('');
+  }).join('') : flat.map((r) => one(r)).join('');
   // the sprint band and the release keep their labels under the axis on Quarter, where a week is wide enough to read them
   const axl = sp === 'quarter' ? `${sa && sb && sb > W.from && sa < W.to ? `<span class="tg-axl sb" style="left:${P(X(sa))}">Jira ${esc(sprint.name.toLowerCase())} · ${esc(md(sa))} – ${esc(md(sb))}</span>` : ''}${ra && ra > W.from && ra < W.to ? `<span class="tg-axl rl" style="left:${P(X(ra))}">${SV(FLAG)}${esc(rel.name)} · ${esc(md(ra))}</span>` : ''}` : '';
   const axis = axl ? `<div class="tg-ax"><span class="tg-n"></span><div class="tg-p">${axl}</div></div>` : '';
-  const foot = none.length ? `<div class="tg-ft">${footNone.length ? `<span class="tg-none"><b>${footNone.length} ${footNone.length === 1 ? 'has' : 'have'} no dates:</b> <span>${esc(footNone.slice(0, 4).map((r) => r.title).join(', '))}${footNone.length > 4 ? ' and ' + (footNone.length - 4) + ' more' : ''}</span>${askBtn}</span>` : `<span class="tg-none">${askBtn}</span>`}</div>` : '';
+  const foot = none.length ? `<div class="tg-ft"><span class="tg-none"><b>${none.length} ${none.length === 1 ? 'has' : 'have'} no dates${footNone.length ? ':' : ''}</b>${footNone.length ? ` <span>${esc(footNone.slice(0, 4).map((r) => r.title).join(', '))}${footNone.length > 4 ? ' and ' + (footNone.length - 4) + ' more' : ''}</span>` : ''}${askBtn}</span></div>` : '';
   // the Deliveries lane (batch 13 item 4, XcalmA6Lane): one row under the axis, a list per column (o.lane draws it; none: nothing)
   const laneH = o.lane ? o.lane({ W, X, rows: list, groups: G, now, phone: false, pxPct }) || '' : '';
   // the columns' width is the name column's (--nw: the sticky block, the left fade and the Deliveries fold all read it)

package/workspace/public/pm/cozy-evmodel.js

@@ -4,6 +4,8 @@
  *   ago(iso, now)                 → '2 min ago' · '1 hour ago' · '5 days ago' · ''
  *   sourceName(row)               → the name a source shows: 'Jira', 'Calendar', 'Repository', …
  *   staleOf(sources, now)         → { id, name, text: 'Jira 5 days old', ago, state } | null   the source furthest behind (failed, then the oldest)
+ *   bannerOf(sources, now)        → { id, name, title: 'Reconnect Jira.', body, text, action } | null   the one source the PM must act on
+ *                                   (self-heal, feedback batch 26 item 7): null while Claude repairs a source by itself, or after it did
  *   sourceRows(sources, now)      → [{ id, name, sub, when, risk, act: 'read' | 'connect' | '' }]   the Sources table (EvSources)
  *   partsOf(id)                   → what may be out of date when that source is old ('Board and the Jira-linked initiatives')
  *   fabLabel(here, open, stale, news) → 'Open the menu. You are in Home. 3 new for you. Jira 5 days old' (the button says both dots, FmGrill 13)
@@ -44,11 +46,26 @@ export function staleOf(sources, now = Date.now()) {
   return { id: s.id, name, text, ago: ago(s.as_of, now), state: s.state };
 }
 
+/** The one source the PM must act on, or null. The server repairs a source that is behind by itself (lib/source-heal.js) and marks a
+ * row `heal.state: 'needs-you'` only when the PM must act; until then, and after a repair, there is no banner. The body says what is
+ * old and why, what it makes old, and what Claude already tried. It never says a source is fresh: only a read says that. */
+export function bannerOf(sources, now = Date.now()) {
+  const L = (sources || []).filter((s) => s && s.heal && s.heal.state === 'needs-you' && s.heal.action);
+  if (!L.length) return null;
+  const rank = (s) => (s.heal.action.read ? 1 : 0);   // a connection to fix leads a read to press
+  L.sort((a, b) => rank(a) - rank(b) || (Date.parse(a.as_of || '') || 0) - (Date.parse(b.as_of || '') || 0));
+  const s = L[0], h = s.heal, name = sourceName(s);
+  const when = s.as_of ? name + ' was last read ' + ago(s.as_of, now) : name + ' was never read';
+  const body = when + (h.why ? ' because ' + h.why : '') + '. ' + partsOf(s.id) + ' may be out of date.' + (h.tried ? ' ' + h.tried : '');
+  return { id: s.id, name, title: h.action.label + '.', body, text: h.action.label, action: h.action, cause: h.cause };
+}
+
 /** The Sources table: one row per source, in the order the server lists them. */
 export function sourceRows(sources, now = Date.now()) {
   return (sources || []).filter(Boolean).map((s) => {
     const behind = s.state === 'stale' || s.state === 'failed' || s.state === 'never';
-    const when = s.state === 'off' ? 'Not connected' : s.state === 'building' ? 'Reading now' : s.state === 'never' ? 'Never read'
+    const mend = behind && s.heal && s.heal.state === 'repairing';
+    const when = s.state === 'off' ? 'Not connected' : s.state === 'building' ? 'Reading now' : mend ? 'Reading again' : s.state === 'never' ? 'Never read'
       : s.state === 'failed' ? 'Could not be read' : s.id === 'repository' && s.state === 'fresh' ? 'Watching' : ago(s.as_of, now) || 'Never read';
     return { id: s.id, name: sourceName(s), sub: SRC_SUB[s.id] || s.label || '', when, risk: behind, act: s.state === 'off' ? 'connect' : behind && s.id !== 'repository' ? 'read' : '' };
   });

package/workspace/public/pm/cozy-nav.js

@@ -5,12 +5,12 @@
  * One button, bottom left on desktop and bottom right on a phone, opens the menu: the three places, Home, Board and Intelligence; then a
  * tray of three icons, Search (⌘K on a desk), Guide and Settings. It is the one way between places, and it holds nothing else: New for you is a fold
  * in Your day, Sources are Settings › Connectors, Theme is Settings › General, and More is gone (feedback batch 16 item 5).
- * The button keeps its two dots on every page: blue when something is new for you, amber when a source is stale. Open, the blue dot sits on
+ * The button keeps its two dots on every page: blue when something is new for you, amber when a source needs you (Claude repairs the rest by itself). Open, the blue dot sits on
  * the Home row (where Your day is) and the amber dot on the Settings icon; the button's own name says both ("Open the menu. 3 new for you.
  * Jira is stale.").
  *   Search       pm/cozy-search.js: across the repository and every worktree; Ctrl K (Cmd K) or "/" opens it from any page
  *   Guide        pm/premium-vw-guide.js: the user guide's Start here, in the Viewer of the page you are on (initiative guide-in-app)
- *   Settings     pm/cozy-settings.js; it opens at Connectors while a source is stale, so the stale one is the first thing there
+ *   Settings     pm/cozy-settings.js; it opens at Connectors while a source needs you, so that one is the first thing there
  * A page that passes opts.here() runs it when its own place is pressed, in place of a reload (Home: Menu > Home closes the page that is open).
  * The counts come from GET /api/news-for-you and GET /api/sources, read when the page opens and every two minutes while it is shown; each
  * read of New for you is passed on as the event 'cz:news-for-you' (detail: the answer), so Home's Your day and Good morning follow it.
@@ -20,7 +20,7 @@
  * call, the menu open, a desk, Settings > Adler not Full, or after Quiet after: no ears (zero is silence).
  */
 import { esc, svg, ICON, wsQ } from './cozy-evui.js';
-import { fabLabel, staleOf } from './cozy-evmodel.js';
+import { fabLabel, bannerOf } from './cozy-evmodel.js';
 import { mountToastFaces, loadPrefs, adlerPeek, asleep } from './cozy-adler.js';   // Adler (batch 16 item 2): every toast carries his S face; Settings > Adler is read once
 
 export const PLACES = [
@@ -134,7 +134,7 @@ export function mountNav(here, doc = document, opts = {}) {
     if (doc.hidden) return;
     const [n, s] = await Promise.all([getj('/api/news-for-you' + wsQ()), getj('/api/sources' + wsQ())]);
     if (n && n.ok) { N.news = n.count || 0; doc.dispatchEvent(new CustomEvent('cz:news-for-you', { detail: n })); }
-    if (s && s.ok) { N.stale = staleOf(s.sources); doc.dispatchEvent(new CustomEvent('cz:sources', { detail: s })); }   // Your day's failed source (AdP5)
+    if (s && s.ok) { N.stale = bannerOf(s.sources); doc.dispatchEvent(new CustomEvent('cz:sources', { detail: s })); }   // Your day's failed source (AdP5)
     if (menu.hidden || !menu.contains(doc.activeElement)) draw();
   };
   read();
@@ -143,6 +143,6 @@ export function mountNav(here, doc = document, opts = {}) {
   doc.addEventListener('cz:news', (e) => { if (e.detail && Number.isFinite(e.detail.count)) { N.news = e.detail.count; draw(); } else read(); });
   doc.addEventListener('cz:calls', (e) => { const n = e.detail && Number(e.detail.count); N.calls = Number.isFinite(n) && n > 0 ? n : 0; draw(); });
   doc.addEventListener('adler:prefs', () => { ears.innerHTML = ''; draw(); });
-  window.addEventListener('pm:sources', (e) => { const d = e.detail; if (d && d.ok) { N.stale = staleOf(d.sources); draw(); } });
+  window.addEventListener('pm:sources', (e) => { const d = e.detail; if (d && d.ok) { N.stale = bannerOf(d.sources); draw(); } });
   return w;
 }