create-pmos 0.517.0 → 0.518.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.517.0",
+  "version": "0.518.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {
@@ -32,6 +32,19 @@
     "audit"
   ],
   "pmosChanges": [
+    {
+      "v": "0.518.0",
+      "at": "2026-11-04T00:33:13.219Z",
+      "f": 4,
+      "prs": [
+        {
+          "n": 1211,
+          "t": "Claude repairs a source that is behind by itself; the banner shows only when you must act",
+          "s": "Claude repairs a source that is behind by itself; the banner shows only when you must act",
+          "k": "new"
+        }
+      ]
+    },
     {
       "v": "0.517.0",
       "at": "2026-11-04T00:17:56.633Z",
@@ -391,47 +404,6 @@
           "d": "The sign-in check could fail a user who was signed in, and the picker showed one login twice. Now it checks the real login and lists each one once."
         }
       ]
-    },
-    {
-      "v": "0.498.0",
-      "at": "2026-11-03T02:56:03.824Z",
-      "f": 4,
-      "prs": [
-        {
-          "n": 1176,
-          "t": "Commit as the repo's own git identity; ask the PM once when it has none",
-          "s": "Commit as the repo's own git identity; ask the PM once when it has none",
-          "k": "fix",
-          "h": "Commits use the right name",
-          "d": "PMOS could commit under a guessed name and email. Now it uses the repo's own identity, and asks you once when there is none."
-        },
-        {
-          "n": 1178,
-          "t": "Full task names wrap; add-task chips for stage, type, dates, owner",
-          "s": "Full task names wrap; add-task chips for stage, type, dates, owner",
-          "k": "new",
-          "h": "Full task names, quicker new tasks",
-          "d": "Long task names were cut off. Now they wrap in full, and a new task has chips for its stage, type, dates and owner.",
-          "top": "Board and Timeline show full task names, and a new task takes its stage, dates and owner in one go."
-        },
-        {
-          "n": 1179,
-          "t": "Each product repo pushes with its own GitHub login",
-          "s": "Each product repo pushes with its own GitHub login",
-          "k": "new",
-          "h": "Each repo pushes as you",
-          "d": "Every product repo pushed with the same GitHub login. Now each one pushes with its own login.",
-          "top": "Setup is steadier: each repo pushes with its own GitHub login and commits with its own git identity."
-        },
-        {
-          "n": 1177,
-          "t": "A workflow routes the initiative; blocked steps ask only as ✦ proposals",
-          "s": "A workflow routes the initiative; blocked steps ask only as ✦ proposals",
-          "k": "fix",
-          "h": "Workflows guide the work",
-          "d": "A blocked step could interrupt you with a question. Now the initiative's workflow decides the next step, and a blocked one shows up only as a ✦ proposal."
-        }
-      ]
     }
   ]
 }

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@2580bd8d
+kernel-source: pmos@ed082f08
 assembled: 2026-11-04
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-11-04T00:17:54Z"}
+generated: {by: process:create-pmos, at: "2026-11-04T00:33:09Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-11-04T00:17:54Z"}
+generated: {by: process:create-pmos, at: "2026-11-04T00:33:09Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-11-04T00:17:54Z"}
+generated: {by: process:create-pmos, at: "2026-11-04T00:33:09Z"}
 status: stable
 ---
 

package/workspace/changelog.json

@@ -1,4 +1,17 @@
 [
+ {
+  "v": "0.518.0",
+  "at": "2026-11-04T00:33:13.219Z",
+  "f": 4,
+  "prs": [
+   {
+    "n": 1211,
+    "t": "Claude repairs a source that is behind by itself; the banner shows only when you must act",
+    "s": "Claude repairs a source that is behind by itself; the banner shows only when you must act",
+    "k": "new"
+   }
+  ]
+ },
  {
   "v": "0.517.0",
   "at": "2026-11-04T00:17:56.633Z",

package/workspace/guide/data-freshness.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Data freshness: how the workspace keeps up to date, and how old each source is"
-timestamp: 2026-11-03
+timestamp: 2026-11-04
 ---
 
 # Data freshness
@@ -55,7 +55,29 @@ The Sources list shows them as one row, **Your tools**. Its time is the oldest r
 
 ## Refresh all: the sources first, then the Briefing
 
-On Home, the Board and Intelligence, the sources list is in **Settings › Connectors**. There is no Sources card in the place menu. Each source shows when PMOS last read it. A source that is old or failed has an amber dot and ↻: press ↻ to read it again. ↻ in the Connectors header is **Refresh all**. While a source is old, an amber box at the top of Settings names it, and the place menu opens Settings at Connectors.
+On Home, the Board and Intelligence, the sources list is in **Settings › Connectors**. There is no Sources card in the place menu. Each source shows when PMOS last read it. A source that is old or failed has an amber dot and ↻: press ↻ to read it again. ↻ in the Connectors header is **Refresh all**. When a source needs you, an amber box at the top of Settings names it, and the place menu opens Settings at Connectors. Claude repairs the other problems by itself, so you do not see a box for them (see below).
+
+## When a source cannot be read: Claude repairs it first
+
+You do not need to watch the sources. When a source that is on is past its limit, never read, or its last read failed, Claude reads it again by itself, without a press. Calendar, Jira, My work, tracker items and Your tools are each repaired this way.
+
+1. The first repair starts at once. The next ones wait 2, 10, 30 and 120 minutes. After a rate limit they wait 15, 60, 120 and 240 minutes. Claude tries at most 5 times. A repair waits while a read of that source is already going, in your quiet hours, and while the run limit is reached.
+2. After each try, Claude finds why the read failed: the sign-in of the connector expired, the connector is not connected or did not start, the network or the proxy did not answer, the tool asked to slow down (rate limit), Claude is signed out on this computer, or the skill stopped with an error. A read that ends but saves nothing new also counts as a failure.
+3. Each try is a line in the refresh log, with the trigger **repair** and a note such as "Repair 2 of 5: the last read failed because the network or the proxy did not answer".
+
+While Claude repairs a source, the source row says **Reading again** with its amber dot, because its data is still old. There is no amber box. When a read proves that the source is up to date, the row shows its new time. PMOS says a source is up to date only when a read proved it.
+
+The amber box shows only when you must act. It names the one action, links to the place where you do it, and says what Claude already tried. For example: **Reconnect Jira.** Jira was last read 3 days ago because its sign-in has expired. Board and the Jira-linked initiatives may be out of date. Claude read it again 2 times since 07:02.
+
+| Why | When the box shows | The action |
+|---|---|---|
+| The connector is not connected | after the first try | **Connect** the source in your Claude connectors (claude.ai/settings/connectors) |
+| The sign-in of the connector expired | after the same failure twice | **Reconnect** the source in your Claude connectors |
+| Claude is signed out on this computer | after the same failure twice | **Sign in to Claude** in Settings › Claude (Terminal: run `claude`, type /login) |
+| The network, a rate limit, a connector that did not start, or a skill error | after 5 tries | ↻ **Read it again** |
+| The source is read only when you press Refresh | at once | ↻ **Read it again** |
+
+The box also adds one item to Needs you, once. The schedule keeps running while the box shows, so after you fix the connection the next read clears the box. A source that you switched off is not repaired and shows no box. Its row still says how old it is.
 
 **Refresh all** in Sources is one run, in a fixed order:
 
@@ -106,7 +128,7 @@ A refresh waits for the sources it uses. The briefing waits for work assigned to
 
 - **Catch up**: a refresh missed while PMOS was closed runs once when PMOS starts. Off, the missed slot is skipped and written to the log.
 - **Retry**: a failed scheduled refresh is tried once more after 15 or 60 minutes.
-- **Tell me**: a failed scheduled refresh adds one item to Needs you on the Briefing.
+- **Tell me**: a failed scheduled refresh adds one item to Needs you on the Briefing. While Claude repairs that source, the repair adds the item instead, once, and only when you must act.
 - **Runs at once**: at most this many scheduled refreshes run together. A refresh you press is never held.
 - No scheduled refresh starts in your quiet hours; the background jobs keep to the day check's working hours.
 - **Deep work runs at night or when you step away.** Your impact, metric drafts and reads, Claude's morning checks of initiatives, and core document drafts run between 01:00 and 05:00. If PMOS was not running then, they run when you have not pressed anything or typed in a terminal for 30 minutes. Quiet hours hold them too. Each one still runs at most once a day.
@@ -120,4 +142,4 @@ A refresh waits for the sources it uses. The briefing waits for work assigned to
 
 ### The refresh log
 
-Every background run is written to `refresh-log.jsonl` in your runtime folder on this computer: a start line and an end line with the result, the time it took, what it got and the error. A skipped slot writes a line with the reason. The start line records each input's state and when it last refreshed. A done refresh of Jira or of work assigned to you keeps a copy of what it read, so you can see what PMOS knew at any time. Lines and copies older than the keep setting (30, 90 or 365 days, or forever; 90 by default) are removed once a day. The log view filters by source and result, and **Export** downloads it as CSV.
+Every background run is written to `refresh-log.jsonl` in your runtime folder on this computer: a start line and an end line with the result, the time it took, what it got and the error. A skipped slot writes a line with the reason. The start line records each input's state and when it last refreshed. A done refresh of Jira or of work assigned to you keeps a copy of what it read, so you can see what PMOS knew at any time. Lines and copies older than the keep setting (30, 90 or 365 days, or forever; 90 by default) are removed once a day. The repair of each source is kept in `source-heal.json` next to the log: each try, its time and why it failed. The log view filters by source and result, and **Export** downloads it as CSV.

package/workspace/lib/refresh-run.js

@@ -13,6 +13,8 @@
  *   run.refreshAll(ws) · run.allState()  Refresh all (briefing-source-flow, slice 3): read every source that is on, then write the
  *                                       Briefing from those reads. One run at a time: a second press joins the run that is going.
  *   run.rows(ws) · run.setSource(id, patch) · run.setRules(patch) · run.ensureOn(id, ws) · run.settings() · run.log()
+ *   run.heal()                          the repair of each source that is behind (lib/source-heal.js), by its lib/freshness.js id:
+ *                                       { jira: { state: 'repairing'|'needs-you'|'repaired', cause, why, tried, action, … } }
  *
  * lib/refresh.js decides; this file holds the state between minutes and calls the host. The host is server.js:
  *   { stateDir, now?, homeWs(), proactive() → { quiet, dayCheck: { start, end, every } }, schedules: { read, write },
@@ -24,6 +26,7 @@
 const fs = require('fs');
 const path = require('path');
 const R = require('./refresh.js');
+const H = require('./source-heal.js');
 
 const PRUNE_EVERY_MS = 24 * 3600 * 1000;
 const LOST_MS = 6 * 3600 * 1000;   // a run with no live session and no end after this long is written as interrupted
@@ -66,6 +69,11 @@ function create(host) {
   const win = () => { const d = (host.proactive() || {}).dayCheck || {}; return { start: d.start || '08:00', end: d.end || '18:00' }; };
   const quiet = () => { const q = (host.proactive() || {}).quiet; return q && q.start && q.end ? q : null; };
   const log = () => R.foldLog(R.readLog(dir));
+  /* self-heal (feedback batch 26 item 7): one repair record per skill source that reads a tool, in <state>/source-heal.json */
+  const healFile = () => path.join(dir, H.FILE);
+  const readHeal = () => { try { const x = JSON.parse(fs.readFileSync(healFile(), 'utf8')); return x && typeof x === 'object' ? x : {}; } catch { return {}; } };
+  function writeHeal(x) { try { fs.mkdirSync(dir, { recursive: true }); const tmp = `${healFile()}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(x) + '\n'); fs.renameSync(tmp, healFile()); } catch (e) { warn('source repair state', e); } }
+  const healing = (id) => { const h = readHeal()[id]; return !!h && h.state !== 'repaired'; };
 
   /* ── the state of each source between minutes ── */
   const openOf = (st) => (st && st.open && typeof st.open === 'object' ? st.open : {});
@@ -143,7 +151,8 @@ function create(host) {
     R.append(dir, { source: id, ws: s.ws || null, ev: 'end', run: o.run, result, took_ms: t - o.at, got, error, ...(copy ? { copy } : {}) }, t);
     // popup context slice 3b: a read of the tools that ends well is followed by one leads session, once no other read is going
     if (result === 'done' && src && src.group === 'tools') afterRead(s.ws || null);
-    if (result === 'failed' && scheduled && rules.tell === 'brief' && !next.retry_at) {
+    // a source under repair is told once by the repair, when the PM must act (lib/source-heal.js), not on each failed read
+    if (result === 'failed' && scheduled && rules.tell === 'brief' && !next.retry_at && !healing(id)) {
       try { host.tell({ source: id, label: src ? src.label : id, error: error || 'it failed', ws: s.ws || null }); } catch (e) { warn('refresh failure note', e); }
     }
   }
@@ -227,11 +236,39 @@ function create(host) {
       }
       start(src, ws, { trigger: d.trigger, slot: d.slot, note: d.note });
     }
+    try { healTick(t, set); } catch (e) { warn('source repair', e); }
     if (t - lastPrune > PRUNE_EVERY_MS) {
       lastPrune = t;
       try { const p = R.prune(dir, rules.keep, t); if (p.lines || p.copies) warn('refresh log', { message: `removed ${p.lines} lines and ${p.copies} copies older than ${rules.keep} days` }); } catch (e) { warn('refresh log prune', e); }
     }
   }
+  /** Read again, by itself, each source that is on and behind; diagnose each failed read; ask the PM only when the PM must act. */
+  function healTick(t, set) {
+    const heal = readHeal(); const before = JSON.stringify(heal);
+    const rowsByWs = new Map();
+    const rowOf = (ws, fid) => { if (!rowsByWs.has(ws)) { let r = []; try { r = host.freshRows(ws) || []; } catch (e) { warn('source repair rows', e); } rowsByWs.set(ws, r); } return rowsByWs.get(ws).find((x) => x.id === fid) || null; };
+    const f = log();
+    for (const src of R.SOURCES.filter((x) => x.run === 'skill' && x.fresh)) {
+      const x = set.sources[src.id] || {}; const cur = R.readState(dir); const st = cur[src.id] || {};
+      const ws = x.ws || host.homeWs();
+      const busy = running(st) || !!st.pending || !!st.waiting_since || (!!st.retry_at && st.retry_at > t);
+      const canStart = runningCount(cur) < Number(set.rules.max || 3) && !R.inQuiet(t, quiet());
+      const r = H.step({ now: t, row: rowOf(ws, src.fresh), on: !!x.on, manual: !!(x.s && x.s.kind === 'manual'), busy, last: f.lastRun(src.id), h: heal[src.id] || null, canStart });
+      if (r.h) heal[src.id] = { ...r.h, fresh: src.fresh }; else delete heal[src.id];
+      if (r.start) {
+        writeHeal(heal);
+        const s0 = start(src, ws, { trigger: 'repair', note: r.note });
+        if (!s0.ok) warn('source repair', { message: `${src.label} could not start: ${s0.error || 'no session'}` });
+      }
+      if (r.tell) {
+        const v = H.view(heal[src.id], H.NAME[src.fresh] || src.label);
+        try { host.tell({ source: src.id, label: src.label, error: `${v.why}. ${v.tried} ${v.action ? v.action.label + ': ' + v.action.how : ''}`.trim(), ws }); } catch (e) { warn('source repair note', e); }
+      }
+    }
+    if (JSON.stringify(heal) !== before) writeHeal(heal);
+  }
+  /** What /api/sources shows per source: the repair view, keyed by the lib/freshness.js id. */
+  const healView = () => H.viewAll(dir);
   function start(src, ws, { trigger, slot, note }) {
     expect.set(src.id, { trigger, slot, note });
     let r;
@@ -415,7 +452,7 @@ function create(host) {
       last_run: l ? l.start_at : null, last_status: l ? (l.result === 'failed' ? 'fail' : l.result === 'done' ? 'ok' : 'started') : st.last_result || null };
   }
 
-  return { tick, started, ended, briefDone, codeRun, jobGate, runNow, refreshAll, allState, derived, setSource, setRules, ensureOn, rows, settings, log, scheduleOfSkill, managedSkill: (skill) => R.SKILL_OF.get(skill) || null };
+  return { heal: healView, tick, started, ended, briefDone, codeRun, jobGate, runNow, refreshAll, allState, derived, setSource, setRules, ensureOn, rows, settings, log, scheduleOfSkill, managedSkill: (skill) => R.SKILL_OF.get(skill) || null };
 }
 
 module.exports = { create };

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.518.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.517.0",
+      "version": "0.518.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.518.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

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;
 }

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

@@ -25,15 +25,15 @@
  * Adler's moments (batch 17 item 4-B, AdM4): one face per section, where Claude speaks. Updates: glasses while it checks or installs,
  * holding the card when a version is ready, calm when up to date. General: holding the update card, else the Jira promise (only after
  * Commit). A failure in the status line takes the honest face, and then the section's face steps back (one Adler per screen).
- * The card at the bottom of General says when an update is ready. While a source is stale, an amber box at the top of every section names
- * it with ↻ Read again, and the place menu opens Settings at Connectors. Every write is the PM's press (pmPost carries the launch nonce).
+ * The card at the bottom of General says when an update is ready. While a source needs you (lib/source-heal.js), an amber box at the top of every section names
+ * it with its one action and what Claude tried, and the place menu opens Settings at Connectors. Every write is the PM's press (pmPost carries the launch nonce).
  * PMOS reads the sources and never posts to them.
  *   openSettings(section?) */
 import { mountClaudeSetup } from './cozy-claude-setup.js';
 import * as JL from './cozy-jl.js';
 import { pmGet, pmPost, pressFetch } from './http.js';
 import { esc, svg, ICON, toast, wsParam, wsQ } from './cozy-evui.js';
-import { sourceRows, staleOf, partsOf } from './cozy-evmodel.js';
+import { sourceRows, bannerOf } from './cozy-evmodel.js';
 import * as AD from './cozy-adler.js';
 import * as SE from './cozy-seasons.js';
 import { weeksOf, lineOf, storiesOf } from './upd-weeks.js';
@@ -182,11 +182,16 @@ function readsHtml() {
   const L = T.lines ? [['Today', T.lines.readLine(s, ['calendar'])], ['Needs you', T.lines.readLine(s, ['initiatives', 'my-work', 'd:brief'])]].filter((x) => x[1]) : [];
   return `${health}<div class="ev-reads">${rows}</div>${L.map(([k, v]) => `<p class="ev-small ev-mut ev-rl" data-reads="${esc(k)}"><b>${esc(k)}:</b> ${esc(v)}</p>`).join('')}`;
 }
-/** The amber box at the top of Settings while a source is stale (FmA3Settings): what is old, what it makes old, and ↻ Read again. */
+/** The amber box at the top of Settings, only when the PM must act on a source (self-heal, feedback batch 26 item 7). While Claude
+ * reads a source again by itself, or after it did, there is no box. The box names the one action and links to the exact place:
+ * the Claude connectors, Settings › Claude, or ↻ when only a press reads it. It says what Claude already tried. */
 function staleHtml() {
-  const st = T.fresh && T.fresh.ok ? staleOf(T.fresh.sources) : null;
-  if (!st) return '';
-  return `<div class="ev-warn ev-line ev-st-warn" id="srcWarn"><i class="ev-dot risk" aria-hidden="true"></i><p class="ev-grow"><b>${esc(st.state === 'stale' ? st.name + ' was last read ' + st.ago + '.' : st.text + '.')}</b> ${esc(partsOf(st.id))} may be out of date.</p>${readBtn(st.id, 'Read ' + st.name + ' again', 'ev-ib ev-ib-card')}</div>`;
+  const b = T.fresh && T.fresh.ok ? bannerOf(T.fresh.sources) : null;
+  if (!b) return '';
+  const a = b.action;
+  const act = a.read ? readBtn(b.id, a.label, 'ev-ib ev-ib-card')
+    : `<a class="ev-ib ev-ib-card" href="${esc(a.href || '#' + a.sec)}"${a.href ? ' target="_blank" rel="noopener"' : ` data-ev-sec="${esc(a.sec)}"`} aria-label="${esc(a.label)}" title="${esc(a.label)}">${svg(ICON.open, 18)}</a>`;
+  return `<div class="ev-warn ev-line ev-st-warn" id="srcWarn" data-cause="${esc(b.cause || '')}"><i class="ev-dot risk" aria-hidden="true"></i><p class="ev-grow"><b>${esc(b.title)}</b> ${esc(b.body)}${a.read ? '' : ' ' + esc(a.how)}</p>${act}</div>`;
 }
 function connectors() {
   if (T.src === null) return readsHtml() + '<p class="ev-small ev-mut">Reading the connectors.</p>';
@@ -315,8 +320,8 @@ function draw() {
   // a redraw replaces the nodes: keep focus on the same control (by its data-ev-* key), else on the open section, never on the body
   const ae = document.activeElement, had = ae && el.contains(ae), key = had ? [...ae.attributes].find((a) => a.name.startsWith('data-ev-')) : null;
   const n = { connectors: T.src === null ? '' : Object.keys(SRC).filter((k) => T.src[k]).length + T.conn.filter((c) => !c.source && T.con[c.name]).length, workspaces: T.ws ? T.ws.filter((x) => !x.linked).length : '', updates: ready() ? '<span class="ev-pill y">1</span>' : '' };
-  const stale = T.fresh && T.fresh.ok ? staleOf(T.fresh.sources) : null;
-  el.querySelector('.ev-st-nav').innerHTML = '<h2 class="ev-h2">Settings</h2>' + SECTIONS.map(([k, l]) => PAGE_LINKS[k] ? `<a href="${PAGE_LINKS[k]}" class="ev-mi">${esc(l)}</a>` : `<a href="#${k}" class="ev-mi" data-ev-sec="${k}"${T.sec === k ? ' aria-current="page"' : ''}>${esc(l)}${k === 'connectors' && stale ? '<i class="ev-dot risk" aria-label="A source is stale" role="img"></i>' : ''}${n[k] !== undefined && n[k] !== '' ? `<span class="ev-k">${typeof n[k] === 'number' ? n[k] : n[k]}</span>` : ''}</a>`).join('');
+  const stale = T.fresh && T.fresh.ok ? bannerOf(T.fresh.sources) : null;
+  el.querySelector('.ev-st-nav').innerHTML = '<h2 class="ev-h2">Settings</h2>' + SECTIONS.map(([k, l]) => PAGE_LINKS[k] ? `<a href="${PAGE_LINKS[k]}" class="ev-mi">${esc(l)}</a>` : `<a href="#${k}" class="ev-mi" data-ev-sec="${k}"${T.sec === k ? ' aria-current="page"' : ''}>${esc(l)}${k === 'connectors' && stale ? '<i class="ev-dot risk" aria-label="A source needs you" role="img"></i>' : ''}${n[k] !== undefined && n[k] !== '' ? `<span class="ev-k">${typeof n[k] === 'number' ? n[k] : n[k]}</span>` : ''}</a>`).join('');
   const label = (SECTIONS.find((x) => x[0] === T.sec) || SECTIONS[0])[1];
   const all = T.sec === 'connectors' ? `<button type="button" class="ev-ib" data-ev-readall aria-label="Read every source again" title="Read all again"${T.reading ? ' disabled' : ''}>${svg(RD, 18)}</button>` : '';
   el.querySelector('.ev-st-main').innerHTML = staleHtml() + `<div class="ev-top"><h3 class="ev-h2" id="evStTitle">${esc(label)}</h3>${all}<button type="button" class="ev-ib" data-ev-close aria-label="Close settings" title="Close settings">${svg(ICON.close, 18)}</button></div>`
@@ -512,6 +517,7 @@ async function load() {
 export function openSettings(section) {
   const el = mount();
   if (section === 'dress') { T.sec = 'adler'; T.dress = true; } else if (section && BODY[section]) { T.sec = section; T.dress = false; }
+  else if (el.hidden) { T.sec = 'general'; T.dress = false; }   // a fresh open with no section opens on General (R2), not on the section of the last visit
   if (el.hidden) { const ae = document.activeElement; T.back = ae && ae !== document.body ? ae : null; T.ws = null; T.src = null; T.msg = ''; T.phase = ''; T.auto = false; T.wkOpen = new Set(); T.wkMore = new Set(); T.arc = false; T.fresh = null; T.note = {}; T.dset = {}; T.cl = null; T.gr = null; T.np = null; JL.reset(); }
   el.hidden = false; document.getElementById('evStScrim').hidden = false; el.setAttribute('data-esc-layer', '');
   draw();