create-pmos 0.123.0 → 0.125.0

package/workspace/lib/routes-doc-sheet.js

@@ -0,0 +1,169 @@
+'use strict';
+/* routes-doc-sheet.js — the document sheet's server side (console3 wave E1c).
+ *
+ *   GET  /api/doc-sheet/revisions?path=          → { ok, path, revisions: [{ rev, why, by, at, before_hash, after_hash }] }
+ *   GET  /api/doc-sheet/at?path=&rev=            → { ok, path, rev, text }      the fold of the revisions
+ *   POST /api/doc-sheet/edit   { path, text, why }          page press; human edit; an empty why is refused
+ *   POST /api/doc-sheet/propose { path, prompt, after, id? } agent session or PM; a proposal only, the file is NOT changed
+ *                                                            (an id revises a proposal: new hash, the old hash is void)
+ *   POST /api/doc-sheet/accept { path, id, hash }           page press, PM only; writes the file, records a revision, why = the prompt
+ *   POST /api/doc-sheet/change-note { path, downstream? }   a draft body only; nothing is sent
+ *
+ * Storage (append-only JSONL): <runtime>/doc-sheet/revisions.jsonl and proposals.jsonl.
+ * The write is the same one /api/doc/save makes: the path must resolve inside the repository root, only Markdown is
+ * written, and the why goes to the repository's doc-changes.jsonl as `note` with the before/after region
+ * (apply-change.changedRegion), the log /api/doc/save already keeps and /api/doc/changes already reads.
+ * Handlers are pure over (req, body, ctx) so a test needs no server.
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+const applyChange = require('./apply-change.js');
+const S = require('../../scripts/doc-sheet.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const fail = (status, error, extra) => ({ status, body: { ok: false, error, ...(extra || {}) } });
+const dirOf = (runtimeDir) => path.join(runtimeDir, 'doc-sheet');
+
+function readLines(file) {
+  let raw; try { raw = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const l of raw.split('\n')) { if (!l.trim()) continue; try { out.push(JSON.parse(l)); } catch { /* torn line */ } }
+  return out;
+}
+function append(runtimeDir, name, row) {
+  fs.mkdirSync(dirOf(runtimeDir), { recursive: true });
+  fs.appendFileSync(path.join(dirOf(runtimeDir), name), JSON.stringify(row) + '\n');
+}
+
+function inside(root, full) {
+  try { const r = fs.realpathSync(root), f = fs.realpathSync(full); return f === r || f.startsWith(r + path.sep); } catch { return false; }
+}
+// The same guard /api/doc/save uses: resolve under the root, markdown only, refuse anything outside.
+function resolveDoc(root, rel) {
+  if (typeof rel !== 'string' || !rel.trim() || rel.includes('\0')) return { error: fail(400, 'path is required') };
+  const full = path.resolve(root, rel);
+  if (!full.startsWith(path.resolve(root) + path.sep) || !inside(root, path.dirname(full))) return { error: fail(404, 'outside workspace') };
+  if (!/\.md$/i.test(full)) return { error: fail(400, 'only markdown documents are editable here') };
+  let text; try { if (!inside(root, full)) return { error: fail(404, 'outside workspace') }; text = fs.readFileSync(full, 'utf8'); } catch { return { error: fail(404, 'could not read the document') }; }
+  return { full, rel: path.relative(root, full), text };
+}
+
+const revsOf = (runtimeDir, rel) => S.revisions(readLines(path.join(dirOf(runtimeDir), 'revisions.jsonl')), rel);
+
+// Record the file's current text first when it moved outside this sheet (or was never seen), so the fold is complete.
+function syncBaseline(runtimeDir, rel, text, now) {
+  const revs = revsOf(runtimeDir, rel), last = revs[revs.length - 1];
+  if (last && last.after_hash === S.hashText(text)) return last.rev;
+  const rev = last ? last.rev + 1 : 1;
+  const ev = { ...S.editWithWhy(last ? last.text : text, text, last ? 'changed outside the sheet' : 'first seen by the sheet', 'baseline', { rev, path: rel, at: now.toISOString() }) };
+  append(runtimeDir, 'revisions.jsonl', ev);
+  return rev;
+}
+
+function logChange(ctx, w, rel, before, after, why, by, now) {
+  const dir = ctx && ctx.stateDirFor ? ctx.stateDirFor(w, { create: true }) : null;
+  if (!dir) return null;
+  const region = applyChange.changedRegion(before, after);
+  const rec = { file: rel, at: now.toISOString(), pm: by, via: 'doc-sheet', note: why.slice(0, 400),
+    at_line: region.at_line, added: region.added, removed: region.removed, before: region.before, after: region.after };
+  try { fs.mkdirSync(dir, { recursive: true }); fs.appendFileSync(path.join(dir, 'doc-changes.jsonl'), JSON.stringify(rec) + '\n'); return true; } catch { return null; }
+}
+
+function writeDoc(root, rel, before, after, why, runtimeDir, ctx, w, now) {
+  const r = resolveDoc(root, rel); if (r.error) return r.error;
+  if (r.text !== before) return fail(409, 'stale: the document changed since it was read');
+  syncBaseline(runtimeDir, r.rel, r.text, now);
+  const rev = revsOf(runtimeDir, r.rel).length + 1;
+  const ev = S.editWithWhy(before, after, why, 'pm', { rev, path: r.rel, at: now.toISOString() });
+  try { fs.writeFileSync(r.full, after); } catch { return fail(500, 'could not write the document — nothing was changed'); }
+  append(runtimeDir, 'revisions.jsonl', ev);
+  const logged = logChange(ctx, w, r.rel, before, after, why, 'pm', now);
+  return { status: 200, body: { ok: true, path: r.rel, rev, revision: { ...ev, text: undefined }, logged: !!logged } };
+}
+
+function revisionsRoute(root, q, runtimeDir) {
+  const r = resolveDoc(root, q.path); if (r.error) return r.error;
+  return { status: 200, body: { ok: true, path: r.rel, revisions: revsOf(runtimeDir, r.rel).map(({ text, ...rest }) => rest) } };
+}
+function atRoute(root, q, runtimeDir) {
+  const r = resolveDoc(root, q.path); if (r.error) return r.error;
+  const rev = Number(q.rev);
+  if (!Number.isInteger(rev) || rev < 1) return fail(400, 'rev must be a positive integer');
+  const text = S.foldAt(revsOf(runtimeDir, r.rel), rev);
+  if (text == null) return fail(404, 'no such revision');
+  return { status: 200, body: { ok: true, path: r.rel, rev, text } };
+}
+
+function edit(req, body, ctx, now = new Date()) {
+  const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
+  if (typeof body.why !== 'string' || !body.why.trim()) return fail(400, 'a why is required: say why the document changes');
+  if (typeof body.text !== 'string') return fail(400, 'text is required');
+  const w = ctx.w || null, root = ctx.root;
+  const r = resolveDoc(root, body.path); if (r.error) return r.error;
+  return writeDoc(root, body.path, r.text, body.text, body.why, ctx.runtimeDir, ctx, w, now);
+}
+
+const proposalsOf = (runtimeDir) => {
+  const by = new Map();
+  for (const e of readLines(path.join(dirOf(runtimeDir), 'proposals.jsonl'))) by.set(e.id, { ...(by.get(e.id) || {}), ...e });
+  return by;
+};
+
+function propose(req, body, ctx, now = new Date()) {
+  // An agent session or the PM may propose; nothing here touches the document.
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return fail(400, 'body must be an object');
+  if (typeof body.after !== 'string') return fail(400, 'after is required');
+  const r = resolveDoc(ctx.root, body.path); if (r.error) return r.error;
+  let p; try { p = S.askAgentProposal({ before: r.text, after: body.after, prompt: body.prompt }); } catch (e) { return fail(400, e.message); }
+  const id = typeof body.id === 'string' && proposalsOf(ctx.runtimeDir).has(body.id) ? body.id : 'prop-' + require('crypto').randomBytes(6).toString('hex');
+  const prior = proposalsOf(ctx.runtimeDir).get(id);
+  if (prior && prior.path !== r.rel) return fail(400, 'that proposal belongs to another document');
+  const row = { event: prior ? 'revised' : 'proposed', id, path: r.rel, at: now.toISOString(), state: 'proposed', prompt: p.prompt, before_hash: p.before_hash, before_text: r.text, after: p.after, hash: p.hash };
+  append(ctx.runtimeDir, 'proposals.jsonl', row);
+  return { status: 200, body: { ok: true, id, state: 'proposed', hash: p.hash, diff: p.diff, voided_hash: prior ? prior.hash : null } };
+}
+
+function accept(req, body, ctx, now = new Date()) {
+  const g = guard.requirePagePress(req, body); if (!g.ok) return fail(g.status, g.error);
+  const root = ctx.root;
+  const r = resolveDoc(root, body.path); if (r.error) return r.error;
+  const p = proposalsOf(ctx.runtimeDir).get(body.id);
+  if (!p || p.path !== r.rel) return fail(404, 'no such proposal');
+  const res = S.acceptProposal(p, { hash: body.hash, by: 'pm' });   // by is set here, never read from the body
+  if (!res.ok) return fail(409, res.reason, { reason: res.reason });
+  if (r.text !== p.before_text) return fail(409, 'stale: the document changed since this proposal was made', { reason: 'stale' });
+  const out = writeDoc(root, body.path, r.text, p.after, p.prompt, ctx.runtimeDir, ctx, ctx.w || null, now);
+  if (out.status === 200) append(ctx.runtimeDir, 'proposals.jsonl', { event: 'accepted', id: p.id, path: r.rel, at: now.toISOString(), state: 'accepted', hash: p.hash });
+  return out;
+}
+
+function changeNote(root, body, runtimeDir) {
+  const r = resolveDoc(root, body && body.path); if (r.error) return r.error;
+  const revs = revsOf(runtimeDir, r.rel);
+  const note = S.changeNote({ path: r.rel, rev: revs.length ? revs[revs.length - 1].rev : 1 }, Array.isArray(body.downstream) ? body.downstream : []);
+  return { status: 200, body: { ok: true, note } };
+}
+
+const respond = (ctx, res, r) => { ctx.json(res, r.body, r.status); return true; };
+
+module.exports = {
+  prefixes: ['/api/doc-sheet'],
+  resolveDoc, revisionsRoute, atRoute, edit, propose, accept, changeNote,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    const w = (url.searchParams.get('ws') && ctx.getWs) ? ctx.getWs(url.searchParams.get('ws')) : null;
+    const base = { root: w ? w.root : (ctx.root || ROOT), runtimeDir: ctx.runtimeDir, stateDirFor: ctx.stateDirFor, w };
+    if (req.method === 'GET' && p === '/api/doc-sheet/revisions') return respond(ctx, res, revisionsRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
+    if (req.method === 'GET' && p === '/api/doc-sheet/at') return respond(ctx, res, atRoute(base.root, Object.fromEntries(url.searchParams), base.runtimeDir));
+    const fn = req.method === 'POST' && { '/api/doc-sheet/edit': edit, '/api/doc-sheet/propose': propose, '/api/doc-sheet/accept': accept,
+      '/api/doc-sheet/change-note': (rq, b, c) => changeNote(c.root, b, c.runtimeDir) }[p];
+    if (!fn) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) return respond(ctx, res, fail(400, 'invalid JSON body'));
+    const body = got.body || {};
+    const bw = body.ws && ctx.getWs ? ctx.getWs(body.ws) : w;
+    if (body.ws && !bw) return respond(ctx, res, fail(404, 'no workspace'));
+    return respond(ctx, res, fn(req, body, { ...base, root: bw ? bw.root : base.root, w: bw }));
+  },
+};

package/workspace/lib/routes-forecast.js

@@ -0,0 +1,85 @@
+'use strict';
+/* routes-forecast.js — console3 wave B5: the forecast, critical path, capacity and time machine of the Timeline. READ ONLY.
+ *
+ *   GET /api/forecast?initiative=<id>[&ws=<id>]        → { ok, initiative, today, items:[item + forecast], critical, problems, capacity, proposal }
+ *   GET /api/forecast/at?initiative=<id>&date=YYYY-MM-DD → { ok, date, items }     the plan as the fold of work events up to that day
+ *   GET /api/forecast/events?initiative=<id>           → { ok, events }           the events the slider replays (from > the item history)
+ *
+ * Items are read as routes-timeline.js reads them: plan-items.readFold(root), the live (not proposed) items of one initiative.
+ * Dependencies are each item's `after` list. routes-timeline.js exports no reader, so this file does the same two lines.
+ * People and points come from <runtime>/people.json ({ people: [{ id, points_per_week, skills }] }) when it exists; an owner
+ * with no entry gets 5 points a week. Item `points` and `skill` are used when the item has them (default 1 point).
+ * LIMIT: the plan-items fold keeps only the current start and due, so the time machine shows an item's CURRENT dates from the
+ * day it was planned, and its state and later field changes from the day they happened. No write route exists.
+ */
+const fs = require('fs');
+const path = require('path');
+const planItems = require('./plan-items.js');
+const F = require('../../scripts/plan-forecast.js');
+
+const DEFAULT_PPW = 5;
+const localYmd = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+
+function liveItems(root, initiative, now) {
+  const fold = planItems.readFold(root, { now });
+  return Object.values(fold.items).filter((it) => it.initiative === initiative && !it.proposed);
+}
+function readPeople(ctx, items) {
+  let listed = [];
+  try { listed = JSON.parse(fs.readFileSync(path.join(ctx.runtimeDir, 'people.json'), 'utf8')).people || []; } catch { /* none */ }
+  const known = new Map(listed.filter((p) => p && p.id).map((p) => [p.id, { skills: [], ...p, points_per_week: Number(p.points_per_week) || DEFAULT_PPW }]));
+  for (const it of items) if (it.owner && !known.has(it.owner)) known.set(it.owner, { id: it.owner, points_per_week: DEFAULT_PPW, skills: [] });
+  return [...known.values()];
+}
+const shape = (it) => ({ id: it.id, title: it.title, start: it.start, due: it.due, state: it.state, after: it.after || [], owner: it.owner || null,
+  points: it.points, skill: it.skill, doneAt: it.doneAt ? String(it.doneAt).slice(0, 10) : null });
+
+/** The work events of items: planned, then each set, moved. */
+function eventsOf(items) {
+  const out = [];
+  for (const it of items) {
+    out.push({ at: it.createdAt, id: it.id, op: 'add', fields: { ...shape(it), state: 'todo', doneAt: null } });
+    for (const h of it.history || []) {
+      if (h.ev === 'set') out.push({ at: h.at, id: it.id, op: 'set', fields: h.fields });
+      else if (h.ev === 'moved') out.push({ at: h.at, id: it.id, op: 'set', fields: { state: h.to, doneAt: h.to === 'done' ? String(h.at).slice(0, 10) : null } });
+    }
+  }
+  return out;
+}
+
+function build(w, ctx, initiative, now) {
+  const today = localYmd(new Date(now));
+  const items = liveItems(w.root, initiative, now).map(shape);
+  const f = F.forecast(items, null, today);
+  const cp = F.criticalPath(items, null);
+  const merged = items.map((it, i) => ({ ...it, forecast: f.rows[i] }));
+  const flat = merged.map((m) => ({ ...m, start: m.forecast.start, end: m.forecast.end }));
+  const capacity = F.capacityLoad(flat, readPeople(ctx, items), F.weeksFrom(today, 2));
+  return { ok: true, initiative, today, items: merged, critical: cp.ids, critical_days: cp.days, problems: f.problems, capacity, proposal: F.rebalanceProposal(capacity) };
+}
+
+module.exports = {
+  prefixes: ['/api/forecast'],
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p !== '/api/forecast' && p !== '/api/forecast/at' && p !== '/api/forecast/events') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only: the forecast is derived, and plan changes go through the plan-items writer' }, 405); return true; }
+    const initiative = String(url.searchParams.get('initiative') || '');
+    if (!initiative) { ctx.json(res, { ok: false, error: 'initiative is required' }, 400); return true; }
+    const w = ctx.getWs(String(url.searchParams.get('ws') || ''));
+    if (!w || !w.root) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    let out;
+    try {
+      const now = Date.now();
+      if (p === '/api/forecast') out = build(w, ctx, initiative, now);
+      else if (p === '/api/forecast/events') out = { ok: true, events: eventsOf(liveItems(w.root, initiative, now)) };
+      else {
+        const date = String(url.searchParams.get('date') || '');
+        if (!/^\d{4}-\d\d-\d\d$/.test(date)) out = { ok: false, status: 400, error: 'date must be YYYY-MM-DD' };
+        else out = { ok: true, initiative, date, items: F.stateAt(eventsOf(liveItems(w.root, initiative, now)), date) };
+      }
+    } catch (e) { out = { ok: false, status: 500, error: 'the forecast could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }; }
+    ctx.json(res, out, out.ok ? 200 : out.status || 500);
+    return true;
+  },
+};

package/workspace/lib/routes-hooks.js

@@ -0,0 +1,121 @@
+'use strict';
+/* routes-hooks.js — the CLI hook endpoints. The policy is the PM's reply contract (scripts/reply-contract/reply-contract.js):
+ * permissionPolicy decides a permission request, stopDecision a Stop, askFromTool/askToolReply the CLI's question tool,
+ * planRequest/planReply a plan approval, sessionStartContext the first prompt, sessionSettings the per-session --settings.
+ *
+ *   POST /api/hooks/<SessionStart|PreToolUse|PermissionRequest|Stop|Notification|SessionEnd>   (also /api/hook/<pre-tool|permission-request|stop|notification|session-end>)
+ *
+ * The session token comes from the x-pmos-session header; the run is the session it names. Each call appends the event
+ * to <runtimeDir>/hooks/<session>.jsonl, and the contract's own hook event (src: "hook") to <runtimeDir>/replies/<session>.jsonl,
+ * where the fold reads it. A request the policy does not settle is denied "waiting for the PM" until the PM has answered it
+ * (lib/run-answers.js); then the answer decides. The policy's own denials are final.
+ */
+const fs = require('fs');
+const path = require('path');
+const actor = require('./actor.js');
+const runAnswers = require('./run-answers.js');
+const C = require('../../scripts/reply-contract/reply-contract.js');
+const R = require('../../scripts/replies.js');
+
+const EVENTS = ['SessionStart', 'PreToolUse', 'PermissionRequest', 'Stop', 'Notification', 'SessionEnd'];
+const ALIASES = { 'session-start': 'SessionStart', 'pre-tool': 'PreToolUse', 'permission-request': 'PermissionRequest', stop: 'Stop', notification: 'Notification', 'session-end': 'SessionEnd' };
+const WAIT = 'waiting for the PM';
+const ASK_TOOL = 'AskUserQuestion';
+const PLAN_TOOL = 'ExitPlanMode';
+
+const permit = (decision) => ({ status: 200, body: { hookSpecificOutput: { hookEventName: 'PermissionRequest', decision } } });
+const whatOf = (inp) => String((inp && (inp.command || inp.file_path || inp.path || inp.pattern)) || '').slice(0, 300);
+
+// The contract's hook event for what the CLI just told us. The workspace observed it, so it carries src "hook".
+function eventFor(event, b, id) {
+  const inp = b.tool_input && typeof b.tool_input === 'object' ? b.tool_input : {};
+  switch (event) {
+    case 'SessionStart': return { kind: 'start' };
+    case 'PreToolUse': return { kind: 'tool', tool: b.tool_name || '', what: whatOf(inp) };
+    case 'PermissionRequest': return { kind: 'permission', id, tool: b.tool_name || '', command: whatOf(inp), cwd: b.cwd || '', why: '' };
+    case 'Stop': return { kind: 'stop', last_assistant_message: b.last_assistant_message || '' };
+    case 'Notification': return { kind: 'notify', ntype: b.notification_type || '', message: b.message || '' };
+    case 'SessionEnd': return { kind: 'end', exit: 0 };
+    default: return null;
+  }
+}
+
+function handleHook(eventIn, body, token, { sessDir, hooksDir, repliesDir, answersFile, rules, now = new Date() } = {}) {
+  const event = ALIASES[eventIn] || eventIn;
+  if (!EVENTS.includes(event)) return { status: 404, body: { ok: false, error: 'unknown hook event' } };
+  const who = actor.sessionForToken(token, { sessDir });
+  if (!who) return { status: 401, body: { ok: false, error: 'no valid session token' } };
+  const b = body && typeof body === 'object' ? body : {};
+  const run = R.runFor(who);
+  const file = path.join(hooksDir, who.session + '.jsonl');
+  const repliesFile = path.join(repliesDir || path.join(hooksDir, '..', 'replies'), who.session + '.jsonl');
+  const reqId = runAnswers.requestIdOf(b);
+  const answers = answersFile ? runAnswers.readAnswers(answersFile) : [];
+  const answer = answersFile ? runAnswers.answerFor(who.session, reqId, answers) : null;
+  const prior = R.readLines(file);
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const logged = { event, session: who.session, initiative: who.initiative, at: now.toISOString(), body: b };
+
+  let out = { status: 200, body: { ok: true } };
+  if (event === 'PermissionRequest') {
+    const inp = b.tool_input && typeof b.tool_input === 'object' ? b.tool_input : {};
+    if (b.tool_name === PLAN_TOOL) {
+      const plan = C.planRequest({ tool: PLAN_TOOL, input: inp });
+      if (answer && answer.behavior === 'allow') out = { status: 200, body: C.planReply('approve') };
+      else if (answer && answer.behavior === 'deny') out = { status: 200, body: C.planReply('reject', answer.message) };
+      else out = permit({ behavior: 'deny', message: WAIT });
+      logged.plan = plan.plan || null;
+    } else {
+      const pol = C.permissionPolicy({ tool: b.tool_name, command: String(inp.command || ''), cwd: b.cwd || '' }, run, rules);
+      logged.policy = pol;
+      if (pol.act === 'deny') out = permit({ behavior: 'deny', message: pol.why });
+      else if (pol.act === 'allow') out = permit({ behavior: 'allow' });
+      else if (answer && (answer.behavior === 'allow' || answer.behavior === 'deny')) out = permit(answer.behavior === 'allow' ? { behavior: 'allow' } : { behavior: 'deny', message: answer.message || 'the PM denied this' });
+      else out = permit({ behavior: 'deny', message: WAIT });
+    }
+  } else if (event === 'PreToolUse' && b.tool_name === ASK_TOOL) {
+    const asked = C.askFromTool(b.tool_input);
+    if (!asked.error && answer && answer.behavior === 'answer') out = { status: 200, body: C.askToolReply([{ q: asked.asks[0].q, a: answer.message }]) };
+    else if (!asked.error) out = { status: 200, body: { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: WAIT } } };
+  } else if (event === 'SessionStart') {
+    const ctx = C.sessionStartContext(run, b.source);
+    if (ctx.hookSpecificOutput) out = { status: 200, body: ctx };
+  } else if (event === 'Stop') {
+    const vm = R.foldReplies(R.readLines(repliesFile), run);
+    const tries = prior.filter((l) => l && l.event === 'Stop' && l.blocked).length;
+    const d = C.stopDecision(vm, tries);
+    if (d.decision) { logged.blocked = true; out = { status: 200, body: d }; }
+  }
+
+  fs.appendFileSync(file, JSON.stringify(logged) + '\n');
+  const ev = eventFor(event, b, reqId);
+  if (ev) R.appendReply(repliesFile, { v: C.CUR_V, ...ev, run: run.id, session: run.session, src: 'hook' }, now);
+  return out;
+}
+
+const prefixes = ['/api/hooks', '/api/hook'];
+
+async function handle(req, res, url, ctx) {
+  const m = /^\/api\/hooks?\/([A-Za-z-]+)$/.exec(url.pathname);
+  if (!m) return false;
+  if (req.method !== 'POST') { ctx.json(res, { ok: false, error: 'POST only' }, 405); return true; }
+  const parsed = await ctx.readJson(req);
+  if (!parsed.ok) { ctx.json(res, { ok: false, error: 'body must be JSON' }, 400); return true; }
+  const token = req.headers['x-pmos-session'];
+  const r = handleHook(m[1], parsed.body, Array.isArray(token) ? token[0] : token, {
+    sessDir: ctx.sessDir || path.join(ctx.runtimeDir, 'sessions'),
+    hooksDir: path.join(ctx.runtimeDir, 'hooks'),
+    repliesDir: path.join(ctx.runtimeDir, 'replies'),
+    answersFile: runAnswers.answersFile(ctx.runtimeDir),
+  });
+  ctx.json(res, r.body, r.status);
+  return true;
+}
+
+// The JSON for `claude --settings <json>` on one session: hooks post to this workspace, the token goes in a header.
+// `port` is the workspace's listening port. Call it where the workspace builds an agent session's launch command.
+function settingsFor(port, host = '127.0.0.1') {
+  return C.sessionSettings('http://' + host + ':' + port + '/api');
+}
+
+module.exports = { prefixes, handle, handleHook, settingsFor, EVENTS };

package/workspace/lib/routes-initiatives.js

@@ -57,6 +57,7 @@ const tidy = require('./tidy-documents.js');
 const jevDocs = require('./jev-documents.js');
 const tsSettings = require('./typesafe-settings');
 const docCatCorrections = require('./doc-category-corrections');
+const { nineStages } = require('../../scripts/nine-stages.js');   // pure label layer; never workflow-state.js (it runs its CLI on require)
 
 const HORIZON_RANK = { now: 0, next: 1, later: 2 };
 const FILE_KEYS = [['brief_path', 'brief', 'Brief'], ['prd_path', 'prd', 'PRD'], ['rubric_path', 'rubric', 'Rubric'], ['doc_path', 'doc', 'Document']];
@@ -178,6 +179,8 @@ function rowOf(F, rec) {
     progress: { done: pr.done, total: pr.total, label: pr.label },
     next_due: nextDue(F, id),
     last_activity: rec.last_activity || null,
+    // The nine stage names over the engine's rung (scripts/nine-stages.js); on every row so Roadmap, List and sheet share one key set.
+    nine_stages: nineStages(rec.lane, { stage: rec.stage, steps: Array.isArray(rec.steps) ? rec.steps : [] }),
   };
 }
 

package/workspace/lib/routes-intake.js

@@ -0,0 +1,24 @@
+'use strict';
+/* routes-intake.js — planning-flows run 4: the one-line intake draft.
+ *   POST /api/intake/draft { line, acknowledged? } → { ok, draft }
+ * Drafts only. Creating the initiative stays with createInitiative, which refuses an unanchored create. */
+const path = require('path');
+const guard = require('./pm-guard.js');
+const intake = require('../../scripts/intake.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+module.exports = {
+  prefixes: ['/api/intake'],
+  handle: async (req, res, url, ctx) => {
+    if (req.method !== 'POST' || url.pathname !== '/api/intake/draft') return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const body = got.body || {};
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+    if (typeof body.line !== 'string' || !body.line.trim()) { ctx.json(res, { ok: false, error: 'line is required' }, 400); return true; }
+    ctx.json(res, { ok: true, draft: intake.intakeDraft({ line: body.line, root: ctx.root || ROOT, acknowledged: body.acknowledged === true }) });
+    return true;
+  },
+};

package/workspace/lib/routes-outbox.js

@@ -0,0 +1,97 @@
+'use strict';
+/* routes-outbox.js — the outbox queue (console3 wave B3). This wave sends NOTHING; no channel is connected.
+ *
+ *   GET  /api/outbox                       → { ok, entries: [{ id, channel, recipient, body, origin, state, hash,
+ *                                              claims: { ok, refused: [line] }, last_result }], channels }
+ *   POST /api/outbox/draft   { channel, recipient, subject?, body } → { ok, entry }   origin is 'pm' (a page press)
+ *   POST /api/outbox/edit    { id, body }                 → { ok, entry }   a new hash; the old hash is void
+ *   POST /api/outbox/confirm { id, hash, reason? }        → { ok:false, reason:'no channel connected' }  entry stays queued
+ *                                                          → 422 { ok:false, state:'blocked', refused } when a claim fails the trust rules
+ *                                                            and no written reason is given; with a reason it is an override (recorded)
+ *
+ * The hash, the claim rules, the PM-only confirm and the send all come from scripts/trust (the PM's sample).
+ *
+ * WHO WRITES. Every POST passes pm-guard. pm-guard's PM_ONLY_ACTS has no 'confirm' act, so every POST here uses
+ * requirePagePress (body, Origin and nonce checks): an agent session has no Origin and no nonce and is refused. The
+ * writer sets by:'pm'; no body field can. Registering a 'confirm' act needs a pm-guard edit, which this wave does not own.
+ * The handlers are pure over (req, body, runtimeDir) so a test needs no server.
+ */
+const guard = require('./pm-guard.js');
+const outbox = require('../../scripts/outbox.js');
+const store = require('./outbox-store.js');
+const crypto = require('crypto');
+
+const fail = (status, error, extra) => ({ status, body: { ok: false, error, ...(extra || {}) } });
+
+const claimCheck = outbox.claimCheck;   // the trust.js claim rules over the body's claim lines
+
+const view = (entry) => { const c = claimCheck(entry); return { ...entry, claims: { ok: c.ok, refused: c.refused } }; };
+
+function list(runtimeDir) {
+  return { status: 200, body: { ok: true, entries: store.readOutbox(runtimeDir).map(view), channels: outbox.CHANNELS } };
+}
+
+function guarded(req, body) {
+  const g = guard.requirePagePress(req, body);
+  return g.ok ? null : fail(g.status, g.error);
+}
+
+function draft(req, body, runtimeDir, now = new Date()) {
+  const bad = guarded(req, body); if (bad) return bad;
+  let e;
+  try { e = outbox.draftOutbox({ channel: body.channel, recipient: body.recipient, subject: body.subject, body: body.body, origin: 'pm' }); }
+  catch (err) { return fail(400, err.message); }
+  const entry = { id: 'out-' + crypto.randomBytes(6).toString('hex'), ...e };
+  store.appendEvent(runtimeDir, { event: 'queued', ...entry }, now);
+  return { status: 200, body: { ok: true, entry: view({ ...entry, last_result: null }) } };
+}
+
+function edit(req, body, runtimeDir, now = new Date()) {
+  const bad = guarded(req, body); if (bad) return bad;
+  const cur = store.readOutbox(runtimeDir).find((e) => e.id === body.id);
+  if (!cur) return fail(404, 'no such outbox entry');
+  let e;
+  try { e = outbox.editOutbox(cur, { body: body.body }); } catch (err) { return fail(400, err.message); }
+  const { last_result, refused, created_at, ...rest } = e;
+  store.appendEvent(runtimeDir, { event: 'edited', ...rest }, now);
+  return { status: 200, body: { ok: true, entry: view({ ...e, last_result: null }), voided_hash: cur.hash } };
+}
+
+function confirm(req, body, runtimeDir, now = new Date(), senders) {
+  const bad = guarded(req, body); if (bad) return bad;
+  const cur = store.readOutbox(runtimeDir).find((e) => e.id === body.id);
+  if (!cur) return fail(404, 'no such outbox entry');
+  if (body.hash !== cur.hash) return fail(409, 'hash does not match the content', { reason: 'hash does not match the content' });
+  const claims = claimCheck(cur);
+  const reason = typeof body.reason === 'string' ? body.reason : '';
+  if (!claims.ok && !reason.trim()) {
+    return { status: 422, body: { ok: false, state: 'blocked', reason: 'unlabelled claim', refused: claims.refused } };
+  }
+  const { state, last_result, refused, created_at, claims: _c, ...content } = cur;
+  const r = senders ? outbox.confirmOutbox(content, { hash: body.hash, by: 'pm', reason }, senders) : outbox.confirmOutbox(content, { hash: body.hash, by: 'pm', reason });
+  if (!r.ok) {
+    if (r.reason === 'no channel connected') store.appendEvent(runtimeDir, { event: 'pressed', id: cur.id, hash: cur.hash, reason: r.reason, override: !claims.ok, override_reason: reason || null }, now);
+    return { status: r.reason === 'no channel connected' ? 200 : 409, body: { ok: false, reason: r.reason, state: 'queued' } };
+  }
+  // A sender is registered only in a later wave. The send is scripts/trust/outbox.js: queue, PM confirm bound to the hash, server execute.
+  store.executeSend(runtimeDir, cur, { reason: r.reason, claimsSend: claims.send }, senders[cur.channel], now);
+  return { status: 200, body: { ok: true, hash: r.hash, override: r.override, state: 'sent' } };
+}
+
+const ROUTES = { 'POST /api/outbox/draft': draft, 'POST /api/outbox/edit': edit, 'POST /api/outbox/confirm': confirm };
+
+module.exports = {
+  prefixes: ['/api/outbox'],
+  claimCheck, list, draft, edit, confirm, ROUTES,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p === '/api/outbox' && req.method === 'GET') { const r = list(ctx.runtimeDir); ctx.json(res, r.body, r.status); return true; }
+    const fn = ROUTES[`${req.method} ${p}`];
+    if (!fn) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const r = fn(req, got.body || {}, ctx.runtimeDir);
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};