create-pmos 0.38.7 → 0.39.0

package/workspace/server.js

@@ -62,7 +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');
@@ -256,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;
 }
 
@@ -1642,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')) {
@@ -2040,6 +2061,13 @@ const SEED_SETS = {
 function readSchedules() {
   try { const a = JSON.parse(fs.readFileSync(schedFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
 }
+// R5 — count a fire against the schedule's own limits. A schedule that has run `max_runs` times, or whose `until`
+// day is over, turns itself off and says why; nothing about a schedule without either changes.
+function countRun(cur, now = new Date()) {
+  cur.runs = (+cur.runs || 0) + 1;
+  const why = scheduleLogic.finishReason(cur, now);
+  if (why) { cur.enabled = false; cur.endedReason = why; cur.nextRun = null; }
+}
 function writeSchedules(list) {
   try { fs.writeFileSync(schedFile(), JSON.stringify(list)); }
   catch (e) { warnWriteFail('schedules.json (scheduled tasks)', e); }
@@ -2088,7 +2116,7 @@ function fireSchedule(sched) {
       modelAsk: { scheduleTier: sched.tier || null, skillTier: task.tier || null, skill: task.skill } });
     const list = readSchedules(); const cur = list.find((x) => x.id === sched.id);
     const started = s.state !== 'exited';
-    if (cur) { cur.lastRun = nowISO(); cur.lastStatus = started ? 'started' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); if (cur.cadence === 'once') cur.enabled = false; writeSchedules(list); }
+    if (cur) { cur.lastRun = nowISO(); cur.lastStatus = started ? 'started' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); if (cur.cadence === 'once') cur.enabled = false; countRun(cur); writeSchedules(list); }
     // A run that started WITHOUT the profile it recorded is reported as such rather than as a
     // clean start: the session is real, the environment is not the one the schedule declared.
     return { ok: started, kind: 'agent', sessionId: s.id,
@@ -2110,7 +2138,7 @@ function fireSchedule(sched) {
   // stamp lastRun/lastStatus/nextRun via the pure module
   const list = readSchedules();
   const cur = list.find((s) => s.id === sched.id);
-  if (cur) { cur.lastRun = nowISO(); cur.lastStatus = ok ? 'ok' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); writeSchedules(list); }
+  if (cur) { cur.lastRun = nowISO(); cur.lastStatus = ok ? 'ok' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); countRun(cur); writeSchedules(list); }
   // surface it — the finished run reaches the PM through needs-you (R5), honest on failure
   try {
     const nf = needsFileFor(w);
@@ -2131,6 +2159,7 @@ function checkDueSchedules() {
   try {
     const list = readSchedules(); let changed = false;
     for (const s of list) if (scheduleLogic.isMissed(s)) { s.enabled = false; s.lastStatus = 'missed'; s.nextRun = null; changed = true; }
+    for (const s of list) { const why = s.enabled && scheduleLogic.finishReason(s); if (why) { s.enabled = false; s.endedReason = why; s.nextRun = null; changed = true; } }
     if (changed) writeSchedules(list);
   } catch {}
   return fired;
@@ -2145,7 +2174,29 @@ const sessions = new Map();
 const allClients = new Set();
 let seq = 0;
 
+// The initiative a session belongs to, for the conversation record: the PM's or spawn's explicit word first,
+// else the `initiative/<id>` branch its working tree is on (the same join the initiative detail makes).
+function initiativeOfSession(s) {
+  if (s && s.initiative) return String(s.initiative);
+  try {
+    const w = wsList().find((x) => x.id === (s && s.ws));
+    const m = w && w.branch ? /^initiative\/(.+)$/.exec(String(w.branch)) : null;
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+// Save the conversation of a session that belongs to an initiative, so ending or removing it no longer erases it.
+// Runtime state only, never the repository (PM ruling 2026-10-03). Quiet when the session is on no initiative.
+function recordConversation(s) {
+  const initiative = initiativeOfSession(s);
+  if (!initiative) return { ok: false, skipped: true };
+  const r = transcriptsLib.save(STATE, { id: s.id, name: s.name, agent: s.agent, ws: s.ws, initiative,
+    state: s.state, started: s.created ? new Date(s.created).toISOString() : null, text: s.buf });
+  if (!r.ok) warnWriteFail('transcripts (conversation record)', new Error(r.error));
+  return r;
+}
 function persist(s) {
+  if (s.state === 'exited' && !s._txSaved) { s._txSaved = true; try { recordConversation(s); } catch {} }
+  else if (s.state !== 'exited') s._txSaved = false;
   // note IS persisted — a restored session must still say why it exited. `root` is persisted
   // so a session survives even if the workspace registry is lost (it re-registers its root).
   const meta = { id: s.id, ws: s.ws, root: s.root, name: s.name, agent: s.agent, cwd: s.cwd,
@@ -2872,7 +2923,8 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
   try { memoryLib.renderFor(root); } catch { /* memory is never a reason a session fails to start */ }
   // a scheduled run tags the session with its origin, and feeds the skill invocation as first input
   const tag = origin || null;
-  const feed = (s) => { if (initialInput && s && s.pty) { try { setTimeout(() => { try { s.pty.write(initialInput); } catch {} }, 700); } catch {} } };
+  // safeFirstInput: a first input that begins with `/` is read by the agent as a slash command, not as the task.
+  const feed = (s) => { if (initialInput && s && s.pty) { try { setTimeout(() => { try { s.pty.write(safeFirstInput(initialInput)); } catch {} }, 700); } catch {} } };
   // shell gets a real fallback to `sh`; agent CLIs run as-is (harness untouched), NO fallback —
   // falling back from `claude` to `sh` would be a lie.
   const cmd = isShell ? (commandExists(SHELL) ? SHELL : 'sh') : agent;
@@ -3004,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
@@ -3051,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
@@ -3154,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);
@@ -3177,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
@@ -3302,6 +3454,7 @@ function removeSession(id) {
   const s = sessions.get(id);
   if (!s || s.pty) return false;
   if (s.tmux) tmuxKillSession(s.tmux);   // best-effort: never orphan a detached tmux session
+  try { recordConversation(s); } catch {}   // the conversation outlives the session (surface-batch R5)
   forgetScratchpad(s);                   // the tab's staging text goes with the tab
   // Drop a claim this session held. Correctness does not depend on this — treeShare.writerOf only
   // believes a claim whose holder is still live, so a stale entry already reads as vacant — but a
@@ -4199,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)); });
 }
@@ -4229,6 +4404,7 @@ async function handleRequest(req, res) {
   // is the same two-hopper lib/four-panel.js makes per initiative on the server; the board makes it
   // once over every session, from this module, so 178 rows cost no requests.
   if (p === '/lib/working-set.js') return serveFile(res, path.join(__dirname, 'lib', 'working-set.js'));
+  if (p === '/lib/status-groups.js') return serveFile(res, path.join(__dirname, 'lib', 'status-groups.js'));
   // The editor computes its live diff with the SAME module the server saves through, so what the PM
   // sees while typing and what gets written cannot disagree. NB: /lib/ is an explicit allowlist, not
   // a directory route — a <script src> for a file missing from this list 404s silently, and the
@@ -4840,6 +5016,29 @@ async function handleRequest(req, res) {
     if (err) return json(res, { ok: false, error: err }, 500);
     return json(res, { ok: true, prefs });
   }
+  // One recorded conversation (R5): the live session's text, or the saved record once it has ended. Read-only.
+  if (p === '/api/transcript' && req.method === 'GET') {
+    const id = String(url.searchParams.get('id') || '');
+    const live = sessions.get(id);
+    if (live) {
+      const initiative = initiativeOfSession(live);
+      return json(res, { ok: true, id, name: live.name, initiative, state: live.state, live: live.state !== 'exited',
+        stored: 'the runtime state directory — not the repository, and never sent anywhere',
+        text: transcriptsLib.stripAnsi(live.buf).slice(-transcriptsLib.MAX_CHARS) });
+    }
+    const rec = transcriptsLib.read(STATE, id);
+    if (!rec) return json(res, { ok: false, error: 'no recorded conversation with that id' }, 404);
+    return json(res, { ok: true, ...rec, live: false, stored: 'the runtime state directory — not the repository, and never sent anywhere' });
+  }
+  // The tail of one session's terminal text, escape codes stripped, so a CLI can turn "what I just did" into a skill.
+  // Read-only, local, and capped; it names the session it read or says there is none.
+  if (p === '/api/sessions/transcript' && req.method === 'GET') {
+    const sess = sessions.get(String(url.searchParams.get('id') || ''));
+    if (!sess) return json(res, { ok: false, error: 'no such session' }, 404);
+    const max = Math.min(60000, Math.max(500, +url.searchParams.get('max') || 20000));
+    const text = transcriptsLib.stripAnsi(sess.buf).slice(-max);
+    return json(res, { ok: true, id: sess.id, name: sess.name, chars: text.length, text });
+  }
   if (p === '/api/schedules' && req.method === 'GET') {
     // `all=1` (overhaul-r4 D1): every repository's schedules — the drawer lists `scheduled` under "all
     // repositories", so filtering to the home workspace there would hide the PM's other schedules
@@ -4905,8 +5104,32 @@ async function handleRequest(req, res) {
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
     const list = readSchedules(); const s = list.find((x) => x.id === body.id);
     if (!s) return json(res, { ok: false, error: 'no such schedule' }, 404);
-    if (typeof body.enabled === 'boolean') s.enabled = body.enabled;
+    // R5 — `until` and `max_runs` are validated by the same rules a new schedule is, and null/'' clears one. A refused value
+    // returns BEFORE anything is changed, so a bad edit leaves the record as it was.
+    const lim = {};
+    for (const k of ['until', 'max_runs']) if (k in body) lim[k] = body[k];
+    if (Object.keys(lim).length) {
+      const chk = scheduleLogic.normalizeSchedule({ name: s.name, cadence: s.cadence === 'once' ? 'daily' : s.cadence, skill: s.skill, ...lim });
+      if (!chk.ok) return json(res, { ok: false, error: chk.error }, 400);
+      for (const k of Object.keys(lim)) { if (lim[k] == null || lim[k] === '') delete s[k]; else s[k] = chk.schedule[k]; }
+    }
+    if (typeof body.enabled === 'boolean') { s.enabled = body.enabled; if (body.enabled) delete s.endedReason; }
+    // Every field an edit may set is checked BEFORE any is applied (R2): a refused edit names the allowed values and
+    // leaves the record untouched. `skill` must be one that loads for this schedule's repository.
+    const bad = (m) => json(res, { ok: false, error: m }, 400);
+    if (body.cadence != null && !scheduleLogic.CADENCES.includes(body.cadence)) return bad(`cadence must be one of ${scheduleLogic.CADENCES.join(', ')}`);
+    if (body.day != null && !['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'].includes(body.day)) return bad('day must be one of Mon, Tue, Wed, Thu, Fri, Sat, Sun');
+    if (body.dayOfMonth != null && !(Number.isInteger(+body.dayOfMonth) && +body.dayOfMonth >= 1 && +body.dayOfMonth <= 28)) return bad('dayOfMonth must be a whole number from 1 to 28');
+    if (body.time != null && !/^([01]?\d|2[0-3]):[0-5]\d$/.test(String(body.time))) return bad('time must be HH:MM, 24-hour, this machine\'s clock');
+    if (body.date != null && !/^\d{4}-\d{2}-\d{2}$/.test(String(body.date))) return bad('date must be YYYY-MM-DD');
+    if (body.name != null && !String(body.name).trim()) return bad('name cannot be empty');
+    if (body.args != null && String(body.args).length > 2000) return bad('args is limited to 2000 characters');
+    for (const k of ['skill', 'task']) if (body[k] != null) {
+      const ws0 = workspaces.get(s.ws);
+      if (!taskById(body[k], ws0 ? ws0.root : null)) return bad(`no skill named "${body[k]}" is available to this schedule`);
+    }
     for (const k of ['name', 'cadence', 'day', 'dayOfMonth', 'time', 'task', 'skill', 'date', 'args']) if (body[k] != null) s[k] = body[k];
+    if ('args' in body && (body.args === null || body.args === '')) delete s.args;
     if ('tier' in body) { if (body.tier === null || body.tier === '') delete s.tier; else if (/^(fast|balanced|deep)$/.test(String(body.tier))) s.tier = String(body.tier); else return json(res, { ok: false, error: 'tier must be fast, balanced or deep' }, 400); }
     // `profile` is settable to null (clear it) as well as to an id, so it is checked for PRESENCE
     // of the key rather than for a non-null value — the other fields above cannot be cleared.
@@ -5052,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.
@@ -5189,7 +5443,35 @@ async function handleRequest(req, res) {
     // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
     let lanes = null;
     try { if (typeof engine.engine.lanesFor === 'function') lanes = engine.engine.lanesFor(root); } catch { lanes = null; }
-    return json(res, { ws: w ? w.id : null, ...out, lanes });
+    // R4/R5/R6 — what remains to reach acceptance, the conversations that belong to this initiative, and the
+    // files git says were changed for it. Each is read, never guessed; a failed read says so.
+    const sessRows = sessionList();
+    const liveConv = sessRows.filter((x) => initiativeOfSession(sessions.get(x.id)) === id)
+      .map((x) => ({ id: x.id, name: x.name, state: x.state === 'exited' ? 'exited' : 'live', live: x.state !== 'exited', ws: x.ws }));
+    const savedConv = transcriptsLib.listFor(STATE, id).filter((c) => !liveConv.some((l) => l.id === c.id))
+      .map((c) => ({ id: c.id, name: c.name, state: 'ended', live: false, ws: c.ws, saved: c.saved, chars: c.chars, cut: c.cut }));
+    const conversations = [...liveConv, ...savedConv];
+    const listed = new Set(((out && out.artifacts) || []).map((a) => a && a.path).filter(Boolean));
+    let files;
+    try { files = initiativeFiles.filesFor(root, id, { exclude: listed }); }
+    catch (e) { files = { ok: false, reason: 'the files could not be read — ' + String((e && e.message) || 'error').slice(0, 120) }; }
+    let nextSteps = null;
+    try {
+      const acc = readAcceptances(w).get(id) || {};
+      const lc = readLifecycle(w).get(id) || null;
+      nextSteps = 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) || 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: [] }; }
+    // 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
@@ -5568,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.