create-pmos 0.38.8 → 0.39.0

package/workspace/public/pm/status-banner.js

@@ -0,0 +1,87 @@
+/**
+ * status-banner.js — status-clarity R2/R3/R4. The block at the top of an initiative that says where it stands.
+ *
+ * It states, from facts the server already derived: the group, why (the evidence behind it), who acts, the one
+ * thing to do next, how the status will change, and, for "needs you", each open item by its own words. It adds
+ * no fact of its own: the group text comes from lib/status-groups.js, the evidence from deriveState, the steps
+ * from lib/next-steps.js. A failed read says so and shows no group.
+ *
+ * The lifecycle control (hold, close, cancel, reopen) sits beside it with one sentence on what it does and the
+ * history of every change. Acceptance is the PM's and is recorded in a session, not by a button here (D12), so the
+ * banner says how and offers the list of what is waiting.
+ */
+import { el } from './dom.js';
+import { state, setState, FIXTURE } from './state.js';
+
+const SG = () => (typeof window !== 'undefined' ? window.PMOSStatusGroups : null);
+const LAB = 'font-family:var(--mono);font-size:9.5px;letter-spacing:.12em;text-transform:uppercase;color:var(--muted-foreground)';
+const TONE = { 'needs-you': 'var(--destructive)', 'in-progress': 'var(--brand)', 'awaiting-acceptance': 'var(--foreground)', unknown: 'var(--destructive)' };
+const WHO = { pm: 'you', agent: 'the agent', system: 'nobody — it is derived' };
+const iv = (t) => el('span', null, t == null ? '' : String(t));
+
+function line(label, value, attr) {
+  return el('div', { style: 'display:grid;grid-template-columns:78px 1fr;gap:8px;padding:2px 0' },
+    el('span', { style: LAB + ';padding-top:2px' }, label),
+    el('span', { 'data-r18': attr, style: 'font-size:12px;line-height:1.5;color:var(--foreground);overflow-wrap:anywhere' }, iv(value)));
+}
+
+/** @returns {HTMLElement|null} null in fixture mode (the prototype has no such block). */
+export function statusBanner(product, slug, rec) {
+  const sg = SG();
+  if (FIXTURE || !sg || !slug) return null;
+  const err = state.statusErrors && state.statusErrors[product];
+  const row = state.statuses && state.statuses[product] && state.statuses[product][slug];
+  if (err || !row) {
+    return el('div', { 'data-r18': 'status-banner', 'data-key': 'unreadable', style: 'padding:8px 14px;border-bottom:1px solid var(--border)' },
+      el('span', { style: LAB }, 'status'),
+      el('div', { 'data-r18': 'status-error', style: 'font-size:12px;color:var(--destructive);line-height:1.5' },
+        'The status could not be read — ' + (err || 'the server returned no status for this initiative') + '. No group is shown because none can be derived.'));
+  }
+  const key = sg.keyOf(row);
+  const g = sg.BY_KEY[key];
+  const items = (rec && rec.nextSteps && rec.nextSteps.items) || [];
+  const waiting = items.filter((i) => i.kind === 'needs' || i.kind === 'returned');
+  // The one thing to do next: the engine's first item, unless it is not yours and something is waiting on you.
+  const mine = items.filter((i) => i.owner === 'pm' && !i.held);
+  const first = items.find((i) => i.first) || items[0] || null;
+  const next = g.owner === 'pm' ? (mine[0] || first) : first;
+  const nextText = next ? next.text + ' — ' + next.action : (g.key === 'accepted' ? 'Nothing remains.' : 'No step is outstanding.');
+
+  const kids = [
+    el('div', { style: 'display:flex;gap:8px;align-items:baseline;flex-wrap:wrap' },
+      el('span', { style: LAB }, 'status'),
+      el('span', { 'data-r18': 'status-group', style: 'font-size:13px;font-weight:600;color:' + (TONE[key] || 'var(--foreground)') }, g.label),
+      el('span', { style: 'font-family:var(--mono);font-size:9.5px;letter-spacing:.1em;text-transform:uppercase;color:var(--muted-foreground)' }, 'derived, not typed')),
+    line('why', row.statusText ? row.statusText + '. ' + g.meaning : g.meaning, 'status-why'),
+    line('acts now', WHO[g.owner] || g.owner, 'status-owner'),
+    line('next', nextText, 'status-next'),
+    line('changes when', g.moves, 'status-moves'),
+  ];
+  if (waiting.length) {
+    kids.push(el('div', { 'data-r18': 'needs-items', style: 'display:flex;flex-direction:column;gap:2px;padding-top:4px' },
+      el('span', { style: LAB }, 'waiting on you · ' + waiting.length),
+      waiting.map((w) => el('div', { 'data-r18': 'needs-item', style: 'font-size:12px;line-height:1.5;color:var(--foreground);padding-left:10px;border-left:2px solid var(--destructive)' },
+        iv(w.text + (w.action ? ' — ' + w.action : ''))))));
+  }
+  if (key === 'awaiting-acceptance' || key === 'needs-you') {
+    kids.push(el('div', { 'data-r18': 'acceptance-note', style: 'font-size:11px;line-height:1.5;color:var(--muted-foreground);padding-top:4px' },
+      'Acceptance is yours and cannot be delegated (D12). Tell the session that holds this initiative to record it, or run scripts/record-acceptance.js. The workspace never records one for you.'),
+      el('button', { 'data-r18': 'see-waiting', onClick: () => setState({ mode: 'focus', settingsOpen: false, col1: true }),
+        style: 'align-self:flex-start;font-family:var(--mono);font-size:10px;padding:2px 7px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground);margin-top:4px' },
+        'see everything waiting on you'));
+  }
+  return el('div', { 'data-r18': 'status-banner', 'data-key': key, style: 'display:flex;flex-direction:column;gap:2px;padding:8px 14px;border-bottom:1px solid var(--border)' }, kids);
+}
+
+/** What the lifecycle control does, and every change made with it. Sits under the control row. */
+export function lifecycleNotes(rec) {
+  if (FIXTURE) return null;
+  const hist = (rec && rec.lcHistory) || [];
+  return el('div', { 'data-r18': 'lifecycle-notes', style: 'display:flex;flex-direction:column;gap:2px;padding:4px 14px 6px;border-bottom:1px solid var(--border)' },
+    el('span', { 'data-r18': 'lifecycle-explain', style: 'font-size:10.5px;line-height:1.5;color:var(--muted-foreground)' },
+      'Hold, close and cancel take this initiative off the board and stop it gating; reopen puts it back. They are the only statuses you set by hand. Every other status is read from git and the ledgers, so it cannot be edited here.'),
+    hist.length ? el('div', { 'data-r18': 'lifecycle-history', style: 'display:flex;flex-direction:column;gap:1px' },
+      el('span', { style: LAB + ';padding-top:2px' }, 'lifecycle history · ' + hist.length),
+      hist.map((h) => el('span', { style: 'font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' },
+        iv(String(h.at || '').slice(0, 10) + ' · ' + h.state + (h.reason ? ' — ' + h.reason : ''))))) : null);
+}

package/workspace/public/pm/tab-doc.js

@@ -60,7 +60,7 @@ const wsId = () => state.wsId || state.ws || state.product || '';
  * `ws`, and is read from and saved to THAT tree. Two trees can hold the same path with different
  * content, so every per-document cache keys on tree + path; a main-tree tab keys on path alone,
  * exactly as before. */
-const docKey = (tab) => (tab && tab.ws ? tab.ws + '\u241f' : '') + (tab ? tab.path : '');
+const docKey = (tab) => (tab && tab.guide ? 'guide\u241f' : '') + (tab && tab.ws ? tab.ws + '\u241f' : '') + (tab && tab.ref ? tab.ref + '\u241f' : '') + (tab ? tab.path : '');
 const wsOf = (tab) => (tab && tab.ws) || wsId();
 
 /* A REFERENCE is not a file. Panel 3's links section files `jira://ATL-501`, `confluence://PM/x`,
@@ -97,9 +97,12 @@ function requestDoc(tab) {
   if (pending.has(path)) return;
   pending.add(path);
   const done = (text) => { pending.delete(path); disk.set(path, text); setState({}); };
-  const load = (dataMod && typeof dataMod.readDoc === 'function')
-    ? dataMod.readDoc(tab.path, tab.ws)
-    : fetch('/api/doc?ws=' + encodeURIComponent(wsOf(tab)) + '&path=' + encodeURIComponent(tab.path))
+  // A guide page ships with the app and is read from it, not from the repository (status-clarity R6).
+  const load = tab.guide
+    ? fetch('/api/guide?page=' + encodeURIComponent(tab.path)).then((r) => (r.ok ? r.text() : Promise.reject(new Error('no such guide page'))))
+    : (dataMod && typeof dataMod.readDoc === 'function')
+    ? dataMod.readDoc(tab.path, tab.ws, tab.ref)
+    : fetch('/api/doc?ws=' + encodeURIComponent(wsOf(tab)) + '&path=' + encodeURIComponent(tab.path) + (tab.ref ? '&ref=' + encodeURIComponent(tab.ref) : ''))
       .then((r) => (r.ok ? r.text() : Promise.reject(new Error('HTTP ' + r.status))));
   Promise.resolve(load).then(
     (text) => { unread.delete(path); done(typeof text === 'string' ? text : String(text == null ? '' : text)); },
@@ -478,11 +481,13 @@ export function mountDoc(host, tab) {
   if (!FIXTURE && extOfPath(tab.path) === 'xlsx') { setChildren(host, [sheetBody(tab)]); return; }
   const raw = docText(tab);
   const text = state.docEdits[docKey(tab)] ?? raw;
-  const dm = state.docModes[tab.id] ?? 'view';
+  const dm = (tab.readonly && (state.docModes[tab.id] === 'edit' || state.docModes[tab.id] === 'diff')) ? 'view' : (state.docModes[tab.id] ?? 'view');
   const dirty = text !== raw;
   const err = saveErr.get(docKey(tab));
 
-  const modeBtns = ['view', 'raw', 'edit', 'diff'].map((mm) => el('button', {
+  // A file opened from the initiative's git files is evidence of what changed: it is read, never edited or saved here.
+  const readonly = !!tab.readonly;
+  const modeBtns = ['view', 'raw', 'edit', 'diff'].filter((mm) => !(readonly && (mm === 'edit' || mm === 'diff'))).map((mm) => el('button', {
     onClick: () => setState((s) => ({ docModes: { ...s.docModes, [tab.id]: mm } })),
     style: 'font-family:var(--mono);font-size:10.5px;padding:4px 10px;min-height:26px;background:'
       + (dm === mm ? 'var(--secondary)' : 'transparent')

package/workspace/server.js

@@ -62,11 +62,18 @@ 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');
+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 harness = require('./lib/harness-parse');
 const transcript = require('./lib/transcript-read');
 const skillStore = require('./lib/skill-store');
@@ -260,6 +267,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;
 }
 
@@ -1646,6 +1656,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')) {
@@ -3039,7 +3056,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 +3103,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 +3206,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 +3229,111 @@ 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.' } };
+}
+
 // ── 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 +4352,28 @@ function serveFile(res, file, type, noCache) {
     res.end(buf);
   });
 }
+// 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,8 +5275,39 @@ 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'));
+    // `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 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'); }
     // HTML is served as text/plain — the client renders it sandboxed on demand, never as live markup.
@@ -5296,7 +5466,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 +5850,150 @@ 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() });
+    }
+  }
+  // ── 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)) });
+  }
   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.