create-pmos 0.38.8 → 0.40.0

package/workspace/server.js

@@ -62,11 +62,22 @@ ensureSpawnHelperExecutable();
 
 const { checkSurface } = require('./lib/surface-contract');
 const { createSinkGuard } = require('./lib/sink.js');
+const tsSettings = require('./lib/typesafe-settings.js');
+const tsClient = require('./lib/typesafe.js');
+const validateLib = require('./lib/validate.js');
+const claimsLib = require('./lib/claims.js');
+const repoWatch = require('./lib/repo-watch.js');
+tsSettings.adoptEnv(process.env);   // D79 — take the env key into memory and delete it, before anything is spawned
 const scheduleLogic = require('./lib/schedule-logic');
 const { safeFirstInput } = require('./lib/prompt-input');
 const transcriptsLib = require('./lib/transcripts');
 const initiativeFiles = require('./lib/initiative-files');
 const { deriveNextSteps } = require('./lib/next-steps');
+const nextStepActions = require('./lib/next-step-actions');
+const sessionBudget = require('./lib/session-budget');
+const judgmentLib = require('./lib/judgment');
+const proactiveLib = require('./lib/proactive');
+const briefLib = require('./lib/brief');
 const harness = require('./lib/harness-parse');
 const transcript = require('./lib/transcript-read');
 const skillStore = require('./lib/skill-store');
@@ -260,6 +271,9 @@ function sessionEnv() {
   for (const k of INHERITED_SESSION_MARKERS) delete env[k];
   // also drop any other CLAUDE_CODE_* the CLI adds to mark a nested run
   for (const k of Object.keys(env)) if (/^CLAUDE_CODE_/.test(k)) delete env[k];
+  // D79 — the TypeSafe key is the workspace server's own credential. A terminal runs an agent that can
+  // print its environment, so the key is never handed to one, whether it came from settings or the shell.
+  delete env[tsSettings.ENV_NAME];
   return env;
 }
 
@@ -1167,19 +1181,37 @@ function searchFamily(w, query, limit, only) {
 }
 
 // Serve a TEXTUAL document — markdown (incl. .skill), plain-text/config source, or HTML source —
-// per-workspace-guarded. Images are NOT served here (they stream through /api/asset); anything
-// non-textual returns null so the reader shows it inert. A NUL byte ⇒ binary masquerading as text
-// ⇒ refused. Returns { kind, text } or null. The traversal + cross-workspace guard is unchanged
-// (insideRoot); what widened is the file KIND, never the reachable path set.
-function readTextDoc(root, rel) {
+// per-workspace-guarded. Images, PDF and workbooks are NOT served here (they stream through /api/asset).
+// file-viewer-any-text: a file whose extension is on no list is TRIED as text rather than refused for
+// being unlisted — unless its type is binary by nature, it is over MAX_READ_BYTES, it holds a NUL byte, or
+// it is not valid UTF-8. The traversal + cross-workspace guard is unchanged (insideRoot); what widened is
+// the file KIND, never the reachable path set. A refusal carries its reason (readTextDocWhy).
+const MAX_READ_BYTES = 2 * 1024 * 1024;
+function readTextDocWhy(root, rel) {
   const full = path.resolve(root, rel || '');
-  if (!insideRoot(root, full)) return null;                     // per-workspace guard (traversal + cross-ws)
-  const kind = preview.previewKind(path.basename(full));
-  if (kind !== 'markdown' && kind !== 'text' && kind !== 'html') return null;
+  if (!insideRoot(root, full)) return { ok: false, reason: 'not inside this workspace' };   // per-workspace guard (traversal + cross-ws)
+  const name = path.basename(full);
+  const kind = preview.previewKind(name);
+  if (kind === 'image' || kind === 'pdf' || kind === 'sheet') return { ok: false, reason: 'this kind of file is opened another way, not as text' };
+  const known = kind === 'markdown' || kind === 'text' || kind === 'html';
+  if (!known && preview.isKnownBinary(name)) return { ok: false, reason: 'this is a binary file (.' + preview.extOf(name) + ') and cannot be shown as text' };
+  let buf;
+  try {
+    const st = fs.statSync(full);
+    if (!st.isFile()) return { ok: false, reason: 'this is not a file' };
+    if (!known && st.size > MAX_READ_BYTES) return { ok: false, reason: 'the file is larger than 2 MB' };
+    buf = fs.readFileSync(full);
+  } catch { return { ok: false, reason: 'the file could not be read' }; }
+  if (buf.indexOf(0) !== -1) return { ok: false, reason: 'the file is binary (it holds a NUL byte)' };   // binary masquerading as text
   let text;
-  try { text = fs.readFileSync(full, 'utf8'); } catch { return null; }
-  if (text.indexOf(String.fromCharCode(0)) !== -1) return null;   // NUL byte => binary masquerading as text
-  return { kind, text };
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(buf); }
+  catch { if (!known) return { ok: false, reason: 'the file is not valid UTF-8 text' }; text = buf.toString('utf8'); }
+  return { ok: true, kind: known ? kind : 'text', text };
+}
+// Returns { kind, text } or null — the contract every earlier caller relies on.
+function readTextDoc(root, rel) {
+  const r = readTextDocWhy(root, rel);
+  return r.ok ? { kind: r.kind, text: r.text } : null;
 }
 
 // ── The initiative lens: the library grouped the way the PM thinks. ───────────────────
@@ -1646,6 +1678,13 @@ function readLifecycle(w) {
   }
   return latest;
 }
+// The whole lifecycle history of one initiative, oldest first, so the detail can say how it got where it is.
+function lifecycleHistory(w, id) {
+  return readLedger(w, 'lifecycle.jsonl')
+    .filter((r) => r && r.initiative_id === id && (r.state === 'active' || STOPPED_STATES.includes(r.state)))
+    .map((r) => ({ state: r.state, reason: r.reason || '', pm: r.pm || '', at: r.at || '' }))
+    .sort((a, b) => String(a.at).localeCompare(String(b.at))).slice(-20);
+}
 function readAcceptances(w) {
   const acc = new Map();   // initiative_id -> { action, at }
   for (const r of readLedger(w, 'acceptances.jsonl')) {
@@ -2032,6 +2071,7 @@ function taskById(id, root) { return loadTasks(root).find((t) => t.id === id ||
 // D71 — the recommended schedules, one set per purpose. Times are host-local, like every schedule.
 const SEED_SETS = {
   requirements: [{ name: 'Daily requirement gathering', skill: 'gather-requirements', cadence: 'daily', time: '07:30' }],
+  brief: [{ name: 'Morning brief', skill: 'morning-brief', cadence: 'daily', time: '06:45' }],
   memory: [{ name: 'Weekly memory grooming', skill: 'memory-groom', cadence: 'weekly', day: 'Mon', time: '08:00' }],
   skills: [{ name: 'Weekly skill discovery', skill: 'skill-discover', cadence: 'weekly', day: 'Wed', time: '09:00' }],
   reports: [
@@ -2148,7 +2188,7 @@ function checkDueSchedules() {
   return fired;
 }
 // the tick — the persistent server checks on an interval; unref'd so it never blocks exit
-try { const _tick = setInterval(checkDueSchedules, 60000); if (_tick.unref) _tick.unref(); } catch {}
+try { const _tick = setInterval(() => { checkDueSchedules(); proactiveTick(); }, 60000); if (_tick.unref) _tick.unref(); } catch {}
 
 // ── Sessions: real PTYs, owned by the server, with disk-backed scrollback + metadata. ──
 /** @type {Map<string, {id,ws,name,agent,cwd,state,note,created,pty,buf,cols,rows,clients:Set}>} */
@@ -3039,7 +3079,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
 // A FAILED git operation in a real repo must never spawn a session on the wrong branch (rubric
 // hard floor): we return {ok:false} and spawn nothing. Kept as its own function so the
 // git-then-maybe-spawn contract is unit-testable without a WS client.
-function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative, modelAsk }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative, modelAsk, origin, initialInput }) {
   const w = getWs(ws);
   if (!w) return { ok: false, error: 'no workspace' };
   // The profile is checked BEFORE any git operation. A composer that picked a profile PMOS cannot
@@ -3086,7 +3126,7 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
       broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
     }
   }
-  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative, modelAsk });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative, modelAsk, origin, initialInput });
   // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
   // block above. The isolate default already computes that other sessions would be disturbed — and
   // then the whole git block is skipped when no branch was picked, which is the common path and the
@@ -3189,7 +3229,7 @@ function startPreview({ initiative, repoKey, ws }) {
 // One click. Resolves the policy, then hands the SAME seam spawnWithBranch already exposes the
 // branch/isolate decision it made — so the inherited hard floor (a failed git operation spawns
 // nothing) is enforced in exactly one place and is not re-implemented here.
-function startWork({ initiative, repoKey, ws, agent, name, profile }) {
+function startWork({ initiative, repoKey, ws, agent, name, profile, origin, initialInput }) {
   const key = repoKeyFor({ repoKey, ws });
   if (!key) return { ok: false, error: 'no repository selected' };
   const trees = treesOfRepo(key);
@@ -3212,11 +3252,193 @@ function startWork({ initiative, repoKey, ws, agent, name, profile }) {
     // arrived here, decided the branch and supplied a fallback display name, and was then dropped
     // — so the one start path DESIGNED to know what it was starting work on never told the session.
     initiative,
+    // next-step-actions: a session started from a next step carries its origin (so the budget can count it) and its
+    // prompt. Only the /api/next-step/go route passes either; the socket's `start` message never does.
+    origin, initialInput,
   });
   if (!r.ok) return r;
   return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
 }
 
+// ── Next-step actions (initiative next-step-actions) ─────────────────────────────────────────────────────────────
+// A next step can be PREPARED (a read-only plan: branch, tree, prompt, sources, budget — nothing is created) and then
+// STARTED by the PM's press, with exactly the prompt they were shown. The session proposes only (lib/next-step-actions
+// RULES). Records live in the runtime state directory: what was started, and the PM's verdict on it.
+const NS_RUNS = () => path.join(STATE, 'next-step-runs.jsonl');
+const NS_REVIEWS = () => path.join(STATE, 'step-reviews.jsonl');
+const NS_SETTINGS = () => path.join(STATE, 'next-step-settings.json');
+function nsRead(file) {
+  let text = ''; try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) { if (!line.trim()) continue; try { out.push(JSON.parse(line)); } catch { /* a torn line is skipped */ } }
+  return out;
+}
+function nsAppend(file, rec, what) {
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); createSinkGuard({ sink: file, what }).appendLine(file, rec); return { ok: true }; }
+  catch (e) { warnWriteFail(path.basename(file), e); return { ok: false, error: 'could not record — nothing was saved' }; }
+}
+function nsLimits() {
+  try { const v = JSON.parse(fs.readFileSync(NS_SETTINGS(), 'utf8')); const n = sessionBudget.normalizeLimits(v && v.budget); if (n.ok) return n.limits; } catch { /* defaults */ }
+  return { ...sessionBudget.DEFAULTS };
+}
+function nsBudget() {
+  const today = new Date().toDateString();
+  const startedToday = nsRead(NS_RUNS()).filter((r) => r && r.at && new Date(r.at).toDateString() === today).length;
+  const running = sessionList().filter((x) => x.origin === 'next-step' && x.state !== 'exited').length;
+  return sessionBudget.check({ running, startedToday, limits: nsLimits() });
+}
+// The first repository file a step's own text names (planning/… .md or .jsonl) that exists in this repository.
+function nextStepPathOf(root, it) {
+  const m = /(planning\/[\w\-./]+\.(?:md|jsonl))/.exec(`${it.why || ''} ${it.action || ''}`);
+  if (!m) return null;
+  const full = path.resolve(root, m[1]);
+  return insideRoot(root, full) && fs.existsSync(full) ? m[1] : null;
+}
+// The latest run started from each item, and the PM's latest verdict on it.
+function attachRuns(ns, initiativeId) {
+  if (!ns || !Array.isArray(ns.items)) return;
+  const runs = nsRead(NS_RUNS()).filter((r) => r && r.initiative_id === initiativeId);
+  const reviews = nsRead(NS_REVIEWS()).filter((r) => r && r.initiative_id === initiativeId);
+  for (const it of ns.items) {
+    const run = runs.filter((r) => r.item_id === it.id).pop();
+    if (!run) continue;
+    const s = sessions.get(run.session_id);
+    const rv = reviews.filter((r) => r.session_id === run.session_id).pop() || null;
+    it.run = { session_id: run.session_id, at: run.at, branch: run.branch || null, state: s ? (s.state === 'exited' ? 'ended' : 'live') : 'ended',
+      review: rv ? { verdict: rv.verdict, note: rv.note || '', at: rv.at } : null };
+  }
+}
+function nextStepsFor(w, id) {
+  const root = w ? w.root : SELF_ROOT;
+  const engine = consoleState.loadEngine();
+  if (!engine.ok) return { ok: false, error: engine.error };
+  const L = engine.engine.layout(root);
+  const rec = fourPanel.readRecord({ root, dir: L.initiatives, id, parse: engine.engine.parseLeadingFrontmatter });
+  if (!rec.ok || rec.absent) return { ok: false, error: `no initiative record "${id}" in ${w ? w.name : 'this repository'}`, status: 404 };
+  let ladder;
+  try { ladder = consoleState.ladder({ root, id }); } catch (e) { ladder = { ok: false, error: 'the ladder could not be derived: ' + String((e && e.message) || 'error').slice(0, 140) }; }
+  const sessRows = sessionList();
+  const liveIds = new Set(sessRows.filter((x) => x.state !== 'exited' && initiativeOfSession(sessions.get(x.id)) === id).map((x) => x.id));
+  const acc = readAcceptances(w).get(id) || {};
+  const lc = readLifecycle(w).get(id) || null;
+  const ns = deriveNextSteps({ id, accepted: acc.action === 'accept', returned: acc.action === 'return',
+    lifecycle: lc && lc.state !== 'active' ? lc : null, ladder, needs: (readNeeds(w) || []).filter((n) => n && n.initiative_id === id),
+    sessions: sessRows.filter((x) => x.initiative === id || liveIds.has(x.id)) });
+  nextStepActions.annotate(ns, (it) => nextStepPathOf(root, it));
+  attachRuns(ns, id);
+  return { ok: true, ns, title: (rec.frontmatter && rec.frontmatter.title) || id };
+}
+// Everything a prepare shows, computed WITHOUT creating or writing anything. `go` recomputes it and compares the hash.
+function prepareNextStep(body) {
+  const w = getWs(body.ws);
+  if (!w) return { ok: false, status: 400, error: 'no workspace' };
+  const id = String(body.initiative_id || '');
+  if (!fourPanel.validId(id)) return { ok: false, status: 400, error: 'an initiative id is required, and it must be a record name' };
+  const got = nextStepsFor(w, id);
+  if (!got.ok) return { ok: false, status: got.status || 500, error: got.error };
+  const item = got.ns.items.find((x) => x.id === String(body.item_id || ''));
+  if (!item) return { ok: false, status: 404, error: 'no such step — the list may have changed; reload the initiative' };
+  const agent = body.agent === 'shell' ? 'shell' : 'claude';
+  const judgmentOn = body.judgment === true;
+  const budget = nsBudget();
+  const head = { ok: true, ws: w.id, initiative_id: id, agent, item: { id: item.id, key: item.key, kind: item.kind, text: item.text, owner: item.owner, act: item.act }, budget,
+    existing_sessions: sessionList().filter((x) => x.state !== 'exited' && initiativeOfSession(sessions.get(x.id)) === id).map((x) => ({ id: x.id, name: x.name, origin: x.origin || null })) };
+  const ref = nextStepActions.refusal(item, got.ns);
+  if (ref) return { ...head, refused: ref, plan: null, prompt: null, prompt_sha: null, sources: [], judgment: { on: judgmentOn } };
+  const preview = startPreview({ initiative: id, ws: w.id });
+  if (!preview.ok) return { ...head, refused: { code: 'no-plan', why: preview.error || 'no branch and tree could be chosen' }, plan: null, prompt: null, prompt_sha: null, sources: [], judgment: { on: judgmentOn } };
+  let mcp = [];
+  if (body.profile) { try { const rp = require('./lib/profiles').readProfiles(os.homedir()); const pr = rp.ok && (rp.profiles || []).find((x) => x.id === body.profile); if (pr && Array.isArray(pr.mcp)) mcp = pr.mcp; } catch { mcp = []; } }
+  const sources = nextStepActions.sourcesFor(item, mcp);
+  const prompt = nextStepActions.buildPrompt({ initiative: id, title: got.title, item, branch: preview.branch || null, sources, judgment: judgmentLib.fragment(judgmentOn) });
+  const sha = nextStepActions.planHash({ prompt, branch: preview.branch, wsId: preview.wsId, plan: preview.plan, judgment: judgmentOn });
+  return { ...head, refused: null, plan: { plan: preview.plan, why: preview.why, dir: preview.dir, branch: preview.branch, wsId: preview.wsId }, prompt, prompt_sha: sha, sources,
+    profile: body.profile || null,
+    judgment: { on: judgmentOn, outside_service: judgmentOn, needs_key: judgmentOn, note: judgmentOn ? 'The question text leaves this machine for the Typesafe service. It needs TYPESAFE_API_KEY in the session.' : 'No outside service is used.' } };
+}
+
+// ── Proactive engine, slice D1 (initiative proactive-engine) ─────────────────────────────────────────────────────
+// A scan reads ledgers and git for five conditions and appends each new one to signals.jsonl; Today is computed from what
+// is true now. No model call, no network call, no write into any repository, no session started (lib/proactive.js is
+// pure). Records live in the runtime state directory, never in a repository.
+const PRO_SIGNALS = () => path.join(STATE, 'signals.jsonl');
+const PRO_FEEDBACK = () => path.join(STATE, 'proactive-feedback.jsonl');
+const PRO_SETTINGS = () => path.join(STATE, 'proactive-settings.json');
+let proLastScan = 0;
+const PRO_SCAN_EVERY_MS = 10 * 60 * 1000;
+function proSettings() {
+  try { const n = proactiveLib.normalizeSettings(JSON.parse(fs.readFileSync(PRO_SETTINGS(), 'utf8'))); if (n.ok) return n.settings; } catch { /* defaults */ }
+  return proactiveLib.normalizeSettings({}).settings;
+}
+function proactiveCtx(now, settings) {
+  const repos = [];
+  const allSchedules = readSchedules();
+  // The same read the portfolio list uses: every initiative of every registered repository, from the cached boards.
+  const pf = portfolio();
+  for (const r of repoLeads()) {
+    const entry = { name: r.name, ws: r.ws, initiatives: [], needs: [], returned: [], schedules: [] };
+    repos.push(entry);
+    try {
+      const w = getWs(r.ws);
+      const pr = pf.repos.find((x) => x.ws === r.ws);
+      if (pr && pr.error) { entry.error = pr.error; continue; }
+      if (pr && pr.pending) { entry.error = 'the board is still being read — try again in a few seconds'; continue; }
+      const life = readLifecycle(w); const acc = readAcceptances(w);
+      const lastRun = new Map(); const hasRuns = new Set();
+      for (const x of readLedger(w, 'agent-runs.jsonl')) {
+        const id = x && x.initiative_id; if (!id) continue;
+        hasRuns.add(id);
+        const t = Date.parse(x.recorded_at || x.created_at);
+        if (Number.isFinite(t)) lastRun.set(id, Math.max(lastRun.get(id) || 0, t));
+      }
+      for (const b of pf.rows.filter((x) => x.ws === r.ws)) {
+        if (!b || !b.id) continue;
+        const lc = life.get(b.id); const stopped = !!(lc && lc.state !== 'active');
+        entry.initiatives.push({ id: b.id, title: b.title || b.id, active: !b.accepted && !stopped, lastRun: lastRun.has(b.id) ? lastRun.get(b.id) : null, hasRuns: hasRuns.has(b.id) });
+      }
+      entry.needs = (readNeeds(w) || []).filter((n) => n).map((n) => ({ initiative_id: n.initiative_id || null, question: n.question || '', run_id: n.run_id || null }));
+      for (const [id, a] of acc) if (a && a.action === 'return') entry.returned.push({ initiative_id: id, note: 'returned at the Acceptance Gate', at: a.at });
+      entry.schedules = allSchedules.filter((x) => r.ids.has(x.ws)).map((x) => ({ id: x.id, name: x.name || x.label || x.skill || x.id, lastStatus: x.lastStatus || null, lastRun: x.lastRun || null }));
+    } catch (e) { entry.error = 'the repository could not be read — ' + String((e && e.message) || 'error').slice(0, 120); }
+  }
+  const reviews = new Set(nsRead(NS_REVIEWS()).filter((x) => x && x.session_id).map((x) => x.session_id));
+  const nextStepRuns = nsRead(NS_RUNS()).filter((x) => x && x.session_id).map((x) => {
+    const s = sessions.get(x.session_id);
+    return { session_id: x.session_id, initiative_id: x.initiative_id, ws: x.ws, key: x.key, ended: !s || s.state === 'exited', reviewed: reviews.has(x.session_id), at: x.at };
+  });
+  return { now, settings, repos, nextStepRuns };
+}
+function proactiveToday(now) {
+  const settings = proSettings();
+  const ctx = proactiveCtx(now, settings);
+  const d = proactiveLib.detect(ctx);
+  const dismissed = proactiveLib.dismissedIds(nsRead(PRO_FEEDBACK()), now);
+  const live = d.candidates.filter((c) => !dismissed.has(c.id));
+  return { settings, unreadable: d.unreadable, dismissed: d.candidates.length - live.length, candidates: settings.enabled ? proactiveLib.rank(live, now) : [], off: !settings.enabled };
+}
+function proactiveScan({ manual }) {
+  const now = Date.now();
+  const settings = proSettings();
+  if (!manual && !settings.enabled) return { ok: true, skipped: 'the engine is off', appended: 0 };
+  if (!manual && proactiveLib.inQuietHours(now, settings.quiet)) return { ok: true, skipped: 'quiet hours', appended: 0 };
+  const ctx = proactiveCtx(now, settings);
+  const d = proactiveLib.detect(ctx);
+  const recent = nsRead(PRO_SIGNALS()).slice(-2000);
+  const fresh = proactiveLib.newSignals(d.candidates, recent, now);
+  let wrote = 0;
+  for (const c of fresh) {
+    const w = nsAppend(PRO_SIGNALS(), { at: new Date(now).toISOString(), key: c.key, id: c.id, kind: c.kind, initiative_id: c.initiative_id, ws: c.ws, why: c.why, evidence: c.evidence, confidence: c.confidence, manual: !!manual }, 'proactive signal');
+    if (w.ok) wrote++;
+  }
+  return { ok: true, skipped: null, appended: wrote, found: d.candidates.length, unreadable: d.unreadable };
+}
+function proactiveTick() {
+  const now = Date.now();
+  if (now - proLastScan < PRO_SCAN_EVERY_MS) return;
+  proLastScan = now;
+  try { proactiveScan({ manual: false }); } catch (e) { warnWriteFail('proactive scan', e); }
+}
+
 // ── Worktree housekeeping: the app that creates the folders shows and clears them ──────────────
 // Isolation buys "your other sessions keep running" at the price of a directory per branch. That
 // price is only fair if the PM can see the folders and reclaim them without leaving the workspace
@@ -4235,6 +4457,62 @@ function serveFile(res, file, type, noCache) {
     res.end(buf);
   });
 }
+// claims-ledger — the claims ledger and its local checks. Local only: no key, no network. The ledger is file-mode
+// state beside the repository's other ledgers; the caches (stamps, per-document index) live in the per-user runtime
+// directory, outside every repository.
+const claimsRunning = new Set();
+function claimsKey(w) { return require('crypto').createHash('sha1').update(w.root).digest('hex').slice(0, 12); }
+function claimsPaths(w) {
+  const cacheDir = path.join(STATE, 'claims', claimsKey(w));
+  let dir = null;
+  if (isDir(path.join(w.root, 'planning', 'initiatives'))) dir = path.join(w.root, 'planning', 'runs');
+  else if (isDir(path.join(w.root, 'pmos', 'state'))) dir = path.join(w.root, 'pmos', 'state');
+  else dir = cacheDir;
+  return { cacheDir, ledgerFile: path.join(dir, 'claims.jsonl'), ledgerDir: dir };
+}
+async function runClaims(w, { sweep = false } = {}) {
+  if (claimsRunning.has(w.root)) return { ok: false, busy: true, error: 'a check is already running for this repository' };
+  claimsRunning.add(w.root);
+  try {
+    const { cacheDir, ledgerFile, ledgerDir } = claimsPaths(w);
+    try { fs.mkdirSync(ledgerDir, { recursive: true }); fs.mkdirSync(cacheDir, { recursive: true }); } catch { /* the writers report it */ }
+    return await claimsLib.check({ root: w.root, cacheDir, ledgerFile, sweep });
+  } finally { claimsRunning.delete(w.root); }
+}
+const claimsLast = new Map();      // root → { at, run, error }
+const claimsWatcher = repoWatch.createWatcher({
+  repos: () => Array.from(workspaces.values()).map((w) => ({ id: w.id, root: w.root })),
+  enabled: (root) => tsSettings.getRepo(STATE, root).watch === true,
+  listFiles: claimsLib.listScope,
+  check: async ({ root, sweep }) => { const w = Array.from(workspaces.values()).find((x) => x.root === root); return w ? runClaims(w, { sweep }) : { ok: false }; },
+  // Timing only (a test shortens them); nothing here names a host or a path.
+  pollMs: Math.max(250, Number(process.env.PMOS_CLAIMS_POLL_MS) || 10000),
+  stableMs: Math.max(250, Number(process.env.PMOS_CLAIMS_STABLE_MS) || 8000),
+  onResult: ({ root, ok, result, error, sweep }) => { claimsLast.set(root, { at: new Date().toISOString(), ok, sweep, run: result && result.run ? result.run : null, error: error || (result && result.error) || null }); },
+});
+if (!REQUIRED_AS_LIBRARY) claimsWatcher.start();
+// D79 — why a validation may not start, or null. The same words on the plan and the run, so the browser
+// never has to guess. No key means no request; no consent means this repository is never sent.
+const validating = new Set();
+function validationRefusal(w) {
+  if (!tsSettings.status(STATE).present) return 'No TypeSafe key is set. Add one in Settings; without a key nothing is sent.';
+  if (!tsSettings.getRepo(STATE, w.root).consent) return 'Validation is off for this repository. Switch it on first; until then nothing from it is sent.';
+  return null;
+}
+// Findings are file-mode state: a PMOS-shaped repository keeps them beside its other ledgers, so they travel
+// with it. Any other repository keeps them in the per-user runtime directory, never inside the repository.
+function validationFindingsFile(w) {
+  let d = null;
+  if (isDir(path.join(w.root, 'planning', 'initiatives'))) d = path.join(w.root, 'planning', 'runs');
+  else if (isDir(path.join(w.root, 'pmos', 'state'))) d = path.join(w.root, 'pmos', 'state');
+  else {
+    d = path.join(STATE, 'validation');
+    try { fs.mkdirSync(d, { recursive: true }); } catch { /* the sink guard reports it */ }
+    return path.join(d, require('crypto').createHash('sha1').update(w.root).digest('hex').slice(0, 12) + '.jsonl');
+  }
+  try { fs.mkdirSync(d, { recursive: true }); } catch { /* the sink guard reports it */ }
+  return path.join(d, 'validation-findings.jsonl');
+}
 function readBody(req) {
   return new Promise((resolve) => { let b = ''; req.on('data', (c) => (b += c)); req.on('end', () => resolve(b)); });
 }
@@ -5136,10 +5414,42 @@ async function handleRequest(req, res) {
     const doc = readLayouts(w);
     return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId, stored: doc.stored });
   }
+  if (p === '/api/guide' && req.method === 'GET') {
+    // The user guide ships with the app (workspace/guide/*.md), so it is read from the app directory, not from a
+    // registered repository. A page name is a bare token, never a path. Read-only.
+    const gdir = path.join(__dirname, 'guide');
+    const page = url.searchParams.get('page');
+    if (page) {
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(page)) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end('no such guide page'); }
+      try { const text = fs.readFileSync(path.join(gdir, page + '.md'), 'utf8'); res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8', 'X-Doc-Kind': 'markdown' }); return res.end(text); }
+      catch { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end('no such guide page'); }
+    }
+    let names = [];
+    try { names = fs.readdirSync(gdir).filter((n) => /^[a-z0-9][a-z0-9-]*\.md$/.test(n)).map((n) => n.slice(0, -3)); }
+    catch (e) { return json(res, { ok: false, error: 'the guide could not be read — ' + String((e && e.message) || 'error').slice(0, 120) }); }
+    const order = ['index', 'layout', 'statuses', 'initiatives-and-next-steps', 'scheduled-tasks-and-cli'];
+    names.sort((a, b) => (order.indexOf(a) < 0 ? 99 : order.indexOf(a)) - (order.indexOf(b) < 0 ? 99 : order.indexOf(b)) || a.localeCompare(b));
+    const pages = names.map((n) => {
+      let title = n;
+      try { const m = /^title:\s*"?([^"\n]+)"?/m.exec(fs.readFileSync(path.join(gdir, n + '.md'), 'utf8').slice(0, 600)); if (m) title = m[1].trim(); } catch { /* keep the name */ }
+      return { page: n, title };
+    });
+    return json(res, { ok: true, pages });
+  }
   if (p === '/api/doc') {
     const w = getWs(url.searchParams.get('ws'));
-    const doc = w ? readTextDoc(w.root, url.searchParams.get('path') || '') : null;
-    if (doc == null) { res.writeHead(404); return res.end('not a readable text document in this workspace'); }
+    // `ref` — a file that exists only on an initiative's own branch (status-clarity R5). Read through git, never the
+    // working tree, and only from an initiative branch; the reason for a refusal travels in the body.
+    const ref = url.searchParams.get('ref');
+    if (ref && w) {
+      const at = initiativeFiles.readAtRef(w.root, ref, url.searchParams.get('path') || '');
+      if (!at.ok) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end(at.reason); }
+      res.writeHead(200, { 'Content-Type': at.kind === 'markdown' ? 'text/markdown; charset=utf-8' : 'text/plain; charset=utf-8', 'X-Doc-Kind': at.kind });
+      return res.end(at.text);
+    }
+    const got = w ? readTextDocWhy(w.root, url.searchParams.get('path') || '') : { ok: false, reason: 'no such workspace' };
+    if (!got.ok) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end(got.reason); }
+    const doc = got;
     // HTML is served as text/plain — the client renders it sandboxed on demand, never as live markup.
     const ctype = doc.kind === 'markdown' ? 'text/markdown; charset=utf-8' : 'text/plain; charset=utf-8';
     res.writeHead(200, { 'Content-Type': ctype, 'X-Doc-Kind': doc.kind }); return res.end(doc.text);
@@ -5296,7 +5606,12 @@ async function handleRequest(req, res) {
         sessions: sessRows.filter((x) => (x.initiative === id) || conversations.some((c) => c.id === x.id && c.live)),
       });
     } catch (e) { nextSteps = { state: 'unreadable', summary: 'The next steps could not be derived — ' + String((e && e.message) || 'error').slice(0, 120), items: [] }; }
-    return json(res, { ws: w ? w.id : null, ...out, lanes, conversations, files, next_steps: nextSteps });
+    // next-step-actions: each item says what it can do (`act`), names the repository file it points at when there is one, and
+    // carries the run started from it and the PM's verdict on that run.
+    try { nextStepActions.annotate(nextSteps, (it) => nextStepPathOf(root, it)); attachRuns(nextSteps, id); } catch (e) { void e; }
+    let lcHistory = [];
+    try { lcHistory = lifecycleHistory(w, id); } catch { lcHistory = []; }
+    return json(res, { ws: w ? w.id : null, ...out, lanes, conversations, files, next_steps: nextSteps, lifecycle_history: lcHistory });
   }
   if (p === '/api/audit' && req.method === 'GET') {
     /* The workflow audit (D77): the sweep run on one repository, read-only. It reports state that contradicts
@@ -5675,6 +5990,235 @@ async function handleRequest(req, res) {
       return json(res, { ws: w.id, name: w.name, ...out });
     } finally { syncing.delete(w.root); }
   }
+  /* ── next-step actions: prepare is read-only; go starts exactly what was shown; review records the PM's word ── */
+  if (p === '/api/next-step/prepare' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const r = prepareNextStep(body);
+    return json(res, r, r.ok ? 200 : (r.status || 400));
+  }
+  if (p === '/api/next-step/go' && req.method === 'POST') {
+    // Only reached by the PM's press. It re-prepares, and starts a session only when the PM confirmed AND the prompt and plan
+    // are the ones they were shown (the hash). Anything else starts nothing.
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    if (body.confirm !== true) return json(res, { ok: false, error: 'confirm is required: this starts a session' }, 400);
+    const r = prepareNextStep(body);
+    if (!r.ok) return json(res, r, r.status || 400);
+    if (r.refused) return json(res, { ok: false, refused: r.refused, error: r.refused.why }, 409);
+    if (!body.prompt_sha || body.prompt_sha !== r.prompt_sha) return json(res, { ok: false, error: 'the plan changed since you reviewed it — prepare it again', prompt_sha: r.prompt_sha }, 409);
+    if (!r.budget.allowed) return json(res, { ok: false, error: r.budget.reason, budget: r.budget }, 409);
+    const started = startWork({ initiative: r.initiative_id, ws: r.ws, agent: r.agent, name: `${r.item.key} · ${r.initiative_id}`, profile: r.profile || undefined,
+      origin: 'next-step', initialInput: r.prompt + '\r' });
+    if (!started.ok) return json(res, { ok: false, error: started.error }, 409);
+    const rec = { id: 'nsr-' + Date.now().toString(36), at: nowISO(), ws: r.ws, initiative_id: r.initiative_id, item_id: r.item.id, key: r.item.key, session_id: started.session.id,
+      branch: r.plan.branch || null, plan: r.plan.plan, prompt_sha: r.prompt_sha, judgment: r.judgment.on, profile: r.profile || null };
+    const wrote = nsAppend(NS_RUNS(), rec, 'next-step run');
+    return json(res, { ok: true, session: { id: started.session.id, name: started.session.name }, notice: started.notice || null, plan: r.plan, run: wrote.ok ? rec.id : null, recorded: wrote.ok });
+  }
+  if (p === '/api/next-step/summary' && req.method === 'GET') {
+    // What an ended (or running) next-step session did: the files git shows on its branch against trunk, the end of the
+    // conversation, and every JUDGMENT line checked against its shape. Read-only.
+    const sid = String(url.searchParams.get('session') || '');
+    const run = nsRead(NS_RUNS()).filter((x) => x && x.session_id === sid).pop();
+    if (!run) return json(res, { ok: false, error: 'that session was not started from a next step' }, 404);
+    const live = sessions.get(sid);
+    let text = '';
+    if (live) text = transcriptsLib.stripAnsi(live.buf);
+    else { const rec = transcriptsLib.read(STATE, sid); text = rec && rec.text ? String(rec.text) : ''; }
+    const w = getWs(run.ws);
+    let files = []; let filesError = null;
+    if (w && gitInfo.isRepo(w.root)) {
+      const trunk = ['origin/main', 'main', 'origin/master', 'master'].find((b) => spawnSync('git', ['-C', w.root, 'rev-parse', '--verify', '--quiet', b], { encoding: 'utf8' }).status === 0);
+      const tree = live && live.root ? live.root : w.root;
+      const branch = run.branch && spawnSync('git', ['-C', tree, 'rev-parse', '--verify', '--quiet', run.branch], { encoding: 'utf8' }).status === 0 ? run.branch : 'HEAD';
+      if (trunk) {
+        const d = spawnSync('git', ['-C', tree, 'diff', '--name-status', `${trunk}...${branch}`], { encoding: 'utf8', timeout: 20000 });
+        if (d.status === 0) files = d.stdout.split('\n').filter(Boolean).slice(0, 100).map((l) => { const [st, ...rest] = l.split('\t'); return { status: st, path: rest.join('\t') }; });
+        else filesError = 'git could not compare the branch with trunk';
+      } else filesError = 'no trunk branch to compare against';
+    } else filesError = 'the repository could not be read';
+    const j = judgmentLib.extract(text);
+    const reviews = nsRead(NS_REVIEWS()).filter((x) => x && x.session_id === sid);
+    return json(res, { ok: true, session_id: sid, state: live ? (live.state === 'exited' ? 'ended' : 'live') : 'ended', branch: run.branch || null,
+      files, files_error: filesError, tail: text.slice(-3000), judgments: j, review: reviews.pop() || null });
+  }
+  if (p === '/api/next-step/review' && req.method === 'POST') {
+    // The PM's verdict on one step's run. It accepts or sends back THE STEP. It never records an acceptance of the
+    // initiative, never changes a status and never touches a lifecycle line.
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const verdict = body.verdict === 'accept' ? 'accept' : body.verdict === 'send-back' ? 'send-back' : null;
+    if (!verdict) return json(res, { ok: false, error: 'verdict must be accept or send-back' }, 400);
+    const note = String(body.note || '').trim().slice(0, 500);
+    if (verdict === 'send-back' && !note) return json(res, { ok: false, error: 'say what to change: a send-back needs a note' }, 400);
+    const sid = String(body.session_id || '');
+    const run = nsRead(NS_RUNS()).filter((x) => x && x.session_id === sid).pop();
+    if (!run) return json(res, { ok: false, error: 'that session was not started from a next step' }, 404);
+    const live = sessions.get(sid);
+    if (live && live.state !== 'exited') return json(res, { ok: false, error: 'the session is still running — review it when it has ended' }, 409);
+    const rec = { at: nowISO(), initiative_id: run.initiative_id, item_id: run.item_id, key: run.key, session_id: sid, verdict, note, pm: 'wawan' };
+    const wrote = nsAppend(NS_REVIEWS(), rec, 'step review');
+    if (!wrote.ok) return json(res, { ok: false, error: wrote.error }, 500);
+    return json(res, { ok: true, recorded: rec });
+  }
+  if (p === '/api/next-step/settings') {
+    if (req.method === 'GET') return json(res, { ok: true, budget: nsBudget() });
+    if (req.method === 'POST') {
+      let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+      const n = sessionBudget.normalizeLimits({ ...nsLimits(), ...(body.budget || {}) });
+      if (!n.ok) return json(res, { ok: false, error: n.error }, 400);
+      try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(NS_SETTINGS(), JSON.stringify({ budget: n.limits }) + '\n'); }
+      catch (e) { warnWriteFail('next-step-settings.json', e); return json(res, { ok: false, error: 'could not save — nothing changed' }, 500); }
+      return json(res, { ok: true, budget: nsBudget() });
+    }
+  }
+  // ── claims-ledger — the local checks, on a press or on a watch the PM switched on ────────────────────────────
+  if (p === '/api/claims' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const { cacheDir, ledgerFile } = claimsPaths(w);
+    const last = claimsLast.get(w.root) || null;
+    return json(res, { ok: true, ws: w.id, name: w.name, ...claimsLib.readView({ cacheDir, ledgerFile }),
+      watching: tsSettings.getRepo(STATE, w.root).watch === true, checking: claimsRunning.has(w.root), last_run: last,
+      // the record's path, only when it is inside the repository AND something has been written to it
+      ledger: (path.relative(w.root, ledgerFile).startsWith('..') || !fs.existsSync(ledgerFile)) ? null : path.relative(w.root, ledgerFile).split(path.sep).join('/') });
+  }
+  if (p === '/api/claims/check' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const out = await runClaims(w, { sweep: body.sweep === true });
+    if (out.ok) claimsLast.set(w.root, { at: new Date().toISOString(), ok: true, sweep: body.sweep === true, run: out.run, error: null });
+    return json(res, { ws: w.id, name: w.name, ...out }, out.ok ? 200 : (out.busy ? 409 : 500));
+  }
+  if (p === '/api/claims/watch' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    if (typeof body.watch !== 'boolean') return json(res, { ok: false, error: 'watch must be true or false' }, 400);
+    const out = tsSettings.setRepo(STATE, w.root, { watch: body.watch });
+    if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
+    return json(res, { ok: true, ws: w.id, watching: tsSettings.getRepo(STATE, w.root).watch === true });
+  }
+  // ── D79 — repository validation through TypeSafe ──────────────────────────────────────────────────
+  // The ONLY routes that lead to an outbound request, and only through lib/typesafe.js. The key is never
+  // in a response: `status` says present or absent. Nothing here edits a repository file.
+  if (p === '/api/typesafe' && req.method === 'GET') {
+    return json(res, { ok: true, key: tsSettings.status(STATE), host: tsClient.HOST });
+  }
+  if (p === '/api/typesafe/key' && (req.method === 'PUT' || req.method === 'DELETE')) {
+    let body = {};
+    if (req.method === 'PUT') {
+      try { body = JSON.parse((await readBody(req)) || '{}'); }
+      catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    }
+    const out = req.method === 'PUT' ? tsSettings.setKey(STATE, body.key) : tsSettings.clearKey(STATE);
+    if (!out.ok) return json(res, { ok: false, error: out.error }, req.method === 'PUT' && /look like a key/.test(out.error) ? 400 : 500);
+    return json(res, { ok: true, key: tsSettings.status(STATE) });
+  }
+  if (p === '/api/validate/repo' && (req.method === 'GET' || req.method === 'POST')) {
+    let body = {};
+    if (req.method === 'POST') {
+      try { body = JSON.parse((await readBody(req)) || '{}'); }
+      catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    }
+    const w = getWs(req.method === 'POST' ? body.ws : url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    if (req.method === 'POST') {
+      const out = tsSettings.setRepo(STATE, w.root, { consent: body.consent, exclude: body.exclude });
+      if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
+    }
+    return json(res, { ok: true, ws: w.id, name: w.name, ...tsSettings.getRepo(STATE, w.root), key: tsSettings.status(STATE) });
+  }
+  if (p === '/api/validate/plan' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const refused = validationRefusal(w);
+    if (refused) return json(res, { ok: false, error: refused }, 409);
+    return json(res, { ok: true, ws: w.id, name: w.name, plan: validateLib.plan({ root: w.root, exclude: tsSettings.getRepo(STATE, w.root).exclude }) });
+  }
+  if (p === '/api/validate/run' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const refused = validationRefusal(w);
+    if (refused) return json(res, { ok: false, error: refused }, 409);
+    if (validating.has(w.root)) return json(res, { ok: false, error: 'a validation is already running for this repository' }, 409);
+    const file = validationFindingsFile(w);
+    validating.add(w.root);
+    try {
+      const out = await validateLib.run({
+        root: w.root, exclude: tsSettings.getRepo(STATE, w.root).exclude,
+        key: tsSettings.getKey(STATE), findingsFile: file, expectRequests: body.expect_requests,
+      });
+      return json(res, { ws: w.id, name: w.name, ...out }, out.ok ? 200 : (out.conflict ? 409 : 500));
+    } finally { validating.delete(w.root); }
+  }
+  if (p === '/api/validate/findings' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    return json(res, { ok: true, ws: w.id, name: w.name, ...validateLib.readFindings(validationFindingsFile(w)) });
+  }
+  /* ── proactive engine (D1): Today is computed, feedback is recorded, nothing is sent, started or changed ── */
+  if (p === '/api/proactive/today' && req.method === 'GET') {
+    const now = Date.now();
+    const t = proactiveToday(now);
+    return json(res, { ok: true, as_of: new Date(now).toISOString(), ...t, quiet: proactiveLib.inQuietHours(now, t.settings.quiet), empty: !t.off && t.candidates.length === 0 && t.unreadable.length === 0,
+      note: 'Derived from the ledgers and git on this computer, only while the workspace server runs. It does not read your mail or calendar.' });
+  }
+  if (p === '/api/proactive/scan' && req.method === 'POST') {
+    const r = proactiveScan({ manual: true });
+    return json(res, r);
+  }
+  if (p === '/api/proactive/feedback' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const v = proactiveLib.validateFeedback(body);
+    if (!v.ok) return json(res, { ok: false, error: v.error }, 400);
+    const rec = { at: nowISO(), id: 'pf-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5), pm: 'wawan', ...v.record };
+    const w = nsAppend(PRO_FEEDBACK(), rec, 'proactive feedback');
+    if (!w.ok) return json(res, { ok: false, error: w.error }, 500);
+    return json(res, { ok: true, recorded: rec });
+  }
+  if (p === '/api/proactive/brief') {
+    // The brief is submitted by a scheduled skill in an agent session and only CHECKED and stored here. One file per day;
+    // a second submission for the same day replaces the first. Nothing is sent, started or changed.
+    const dir = path.join(STATE, 'briefs');
+    if (req.method === 'POST') {
+      let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+      const v = briefLib.validateBrief(body, { now: Date.now(), settings: proSettings() });
+      if (!v.ok) return json(res, { ok: false, error: v.error }, 400);
+      try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, v.brief.date + '.json'), JSON.stringify(v.brief) + '\n'); }
+      catch (e) { warnWriteFail('briefs', e); return json(res, { ok: false, error: 'could not save — nothing changed' }, 500); }
+      return json(res, { ok: true, brief: v.brief });
+    }
+    if (req.method === 'GET') {
+      const now = Date.now(); const st = proSettings();
+      let latest = null;
+      try { const f = fs.readdirSync(dir).filter((n) => /^\d{4}-\d{2}-\d{2}\.json$/.test(n)).sort().pop(); if (f) latest = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { /* none yet */ }
+      const sched = readSchedules().filter((x) => x.skill === 'morning-brief').map((x) => ({ id: x.id, ws: x.ws, time: x.time, enabled: x.enabled !== false, lastRun: x.lastRun, lastStatus: x.lastStatus }));
+      return json(res, { ok: true, greeting: briefLib.greeting(now, st.name), today: briefLib.localDate(now), brief: latest, stale: !!latest && latest.date !== briefLib.localDate(now), scheduled: sched,
+        note: 'A session reads your calendar and other sources and submits the brief. This server only checks and stores it.' });
+    }
+  }
+  if (p === '/api/proactive/settings') {
+    if (req.method === 'GET') return json(res, { ok: true, settings: proSettings() });
+    if (req.method === 'POST') {
+      let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+      const cur = proSettings();
+      const n = proactiveLib.normalizeSettings({ ...cur, ...body, triggers: { ...cur.triggers, ...(body.triggers || {}) }, briefSources: { ...cur.briefSources, ...(body.briefSources || {}) } });
+      if (!n.ok) return json(res, { ok: false, error: n.error }, 400);
+      try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(PRO_SETTINGS(), JSON.stringify(n.settings) + '\n'); }
+      catch (e) { warnWriteFail('proactive-settings.json', e); return json(res, { ok: false, error: 'could not save — nothing changed' }, 500); }
+      return json(res, { ok: true, settings: n.settings });
+    }
+  }
   if (p === '/api/lifecycle' && req.method === 'POST') {
     // D70 — close, hold, cancel or reopen an initiative. Only reached by an explicit PM press. It
     // appends ONE line to lifecycle.jsonl and never writes an acceptance.