create-pmos 0.16.0 → 0.17.0

package/workspace/server.js

@@ -121,7 +121,11 @@ const CLONE_DIR = path.join(STATE, 'clones');
 // PMOS's OWN memory of which profile to preselect per agent binary (profiles R8.2). It is a
 // workspace preference, not an agent attribute — the file lives here for exactly that reason.
 const PREFS_FILE = path.join(STATE, 'prefs.json');
-const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+const discovery = require('./lib/server-discovery');    // how a launcher FINDS a running server
+const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : discovery.DEFAULT_PORT;
+// Written on listen, removed on shutdown. This is the server's answer to "where am I?" — see
+// lib/server-discovery.js for why a launcher must ask rather than assume.
+const PID_FILE = path.join(STATE, discovery.pidFileName(PORT));
 const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
 const layoutModel = require('./lib/layout');           // the arrangement model — validated on BOTH sides
 // Bind + token policy (D62). DEFAULT = loopback only, no token (unchanged). The opt-in remote flag
@@ -519,6 +523,10 @@ const ROLE_BY_DIR = {
   prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
   okrs: 'OKR', radar: 'radar', gtm: 'gtm', 'out-of-scope': 'rejected', 'harness-refine': 'harness',
   'design-export': 'design', explainers: 'explainer', fixtures: 'fixture',
+  // The initiative RECORD (planning/initiatives/<id>.md) is the canonical anchor+lane carrier and
+  // the only artifact that exists for work backfilled from a merge. Before it was a role, a record
+  // with no sibling PRD landed in `ungrouped` and the initiative was invisible here.
+  initiatives: 'record',
 };
 // ── D60 specimens: prototype/<id>/, deliberately OUTSIDE planning/ ───────────────────────────
 // The planning walk cannot reach them (planningRoots only finds `planning`), so a prototype leg was
@@ -571,17 +579,23 @@ function parseHead(full) {
     head = buf.slice(0, n).toString('utf8');
   } catch { return {}; }
   const id = head.match(/^\s*[-*]?\s*initiative_id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
+  // An initiative RECORD names itself with `id:`, not `initiative_id:`. Only the record role reads
+  // this (see docMeta) — a bare `id:` on any other document must not invent an initiative.
+  const rid = head.match(/^\s*id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
   const h1 = head.match(/^#\s+(.+)$/m);
-  // status/stage/anchor ride the PRD's identity block — the only initiative signal that lives on
-  // disk today. RICE/effort/milestones/progress do NOT (net-new state) and are never invented.
+  // The anchor and the lane are DECLARED state and are read as such — they say what the work is
+  // pointed at, never how far along it is. `status:`/`stage:` are deliberately NOT read: they were
+  // hand-typed free text (23 distinct values in this repo, 33 absent, several truncated mid-YAML)
+  // funnelled through a regex, so `build complete, PR #138` rendered as `building`. Position is
+  // derived from evidence in deliveryIndex/deriveState instead — see the surface explainer.
   const clean = (m) => m ? m[1].replace(/\*\*/g, '').split(/\s+[—–-]\s|\(/)[0].trim().slice(0, 48) : null;
-  const status = head.match(/^\s*[-*]?\s*status\s*:\s*(.+?)\s*$/mi);
-  const stage = head.match(/^\s*[-*]?\s*stage\s*:\s*(.+?)\s*$/mi);
   const kr = head.match(/^\s*[-*]?\s*parent[_-]?kr\s*:\s*(.+?)\s*$/mi);
+  const lane = head.match(/^\s*[-*]?\s*lane\s*:\s*(.+?)\s*$/mi);
   return {
     initiative: id ? id[1] : null,
+    recordId: rid ? rid[1] : null,
     title: h1 ? h1[1].replace(/^(PRD|Eval Rubric|Design Brief)\s*:\s*/i, '').trim() : null,
-    status: clean(status), stage: clean(stage), kr: clean(kr),
+    kr: clean(kr), lane: clean(lane),
   };
 }
 function roleAndStem(rel, base) {
@@ -604,8 +618,9 @@ function docMeta(root, full) {
   const meta = {
     mtimeMs: st.mtimeMs, path: rel, name: base, role,
     // frontmatter wins; the filename convention is the fallback, never the override
-    initiative: head.initiative || null, stem, title: head.title || null,
-    status: head.status || null, stage: head.stage || null, kr: head.kr || null,
+    initiative: head.initiative || (role === 'record' ? head.recordId : null) || null,
+    stem, title: head.title || null,
+    kr: head.kr || null, lane: head.lane || null,
   };
   metaCache.set(full, meta);
   return meta;
@@ -646,17 +661,17 @@ function initiativeIndex(root) {
     const k = keyFor(m);
     const art = { name: m.name, path: m.path, role: m.role, title: m.title };
     if (!k) { ungrouped.push(art); continue; }
-    if (!groups.has(k)) groups.set(k, { id: k, title: null, status: null, stage: null, kr: null, artifacts: [] });
+    if (!groups.has(k)) groups.set(k, { id: k, title: null, kr: null, lane: null, artifacts: [] });
     const g = groups.get(k);
     g.artifacts.push(art);
     if (m.role === 'PRD' && m.title) g.title = m.title;      // the PRD names the initiative
     else if (!g.title && m.title) g.title = m.title;
-    // status/stage/anchor: the PRD is authoritative; any artifact fills a gap, never overrides it
-    if (m.status && (m.role === 'PRD' || !g.status)) g.status = m.status;
-    if (m.stage && (m.role === 'PRD' || !g.stage)) g.stage = m.stage;
-    if (m.kr && (m.role === 'PRD' || !g.kr)) g.kr = m.kr;
+    // The anchor and lane are the RECORD's to declare (D56/D59 — it is what the gates read); the
+    // PRD fills a gap for legacy initiatives that predate repo-native records, never overrides it.
+    if (m.kr && (m.role === 'record' || !g.kr)) g.kr = m.kr;
+    if (m.lane && (m.role === 'record' || !g.lane)) g.lane = m.lane;
   }
-  const ROLE_ORDER = ['PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
+  const ROLE_ORDER = ['record', 'PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
   const initiatives = [...groups.values()].map((g) => {
     g.artifacts.sort((a, b) => {
       const ia = ROLE_ORDER.indexOf(a.role), ib = ROLE_ORDER.indexOf(b.role);
@@ -691,57 +706,207 @@ function library(root) {
 // client renders it; a surface that can't be produced returns ok:false and the client shows an
 // honest can't-produce state. RICE/effort/milestones/progress are NET-NEW state → emitted as null
 // ("— not tracked"), never invented (D14/D40 honesty).
-const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', landed: 'report' };
-function statusKey(raw) {
-  const s = String(raw || '').toLowerCase();
-  if (/block/.test(s)) return 'blocked';
-  if (/ship|merg|accept|closed|done|live/.test(s)) return 'landed';
-  if (/build|progress|in build|dogfood/.test(s)) return 'building';
-  if (/intake|spec|plan|draft|propos/.test(s)) return 'planning';
+const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', delivered: 'report', accepted: 'report', unknown: 'plan' };
+
+// ── Delivery evidence (board-delivery-truth R-2/R-3). ──────────────────────────────────────────
+// "Has this shipped?" answered from the trunk's own history rather than from anything anyone typed.
+//
+// ONE `git log` per trunk head, memoised on that sha — ~0.3s and ~800 KB on this repo's 1,214
+// commits, paid once and reused by every surface until the trunk moves. Local only: git reads the
+// object store on disk, so the suite's "no network" guarantee (K. Surfaces) is untouched.
+//
+// TWO signals, because one is not enough. The branch convention (`initiative/<id>`) is precise but
+// incomplete: 31% of this repo's merged PRs shipped on `claude/*` branches, which match no id. So a
+// commit that MENTIONS the id and TOUCHES a build path counts too. The build-path requirement is
+// what keeps the mention signal honest — `feat(planning): add <id> PRD` mentions the id while
+// delivering nothing, and without the path test every specified initiative would read as shipped.
+const BUILD_EXCLUDE = /^(planning|okf|prototype)\//;
+function isDeliveryPath(f) {
+  if (!f) return false;
+  if (BUILD_EXCLUDE.test(f)) return false;
+  return !/^[^/]+\.md$/.test(f);      // root governance prose (DECISIONS.md, CLAUDE.md…) is not a build
+}
+const deliveryCache = new Map();      // root -> { head, index }
+function trunkRef(root) {
+  for (const c of ['origin/main', 'main', 'origin/master', 'master']) {
+    const r = gitCap(root, ['rev-parse', '--verify', '--quiet', c]);
+    if (r.ok && r.out.trim()) return { ref: c, head: r.out.trim() };
+  }
   return null;
 }
-function statusFrom(g) {
-  return statusKey(g.status) || statusKey(g.stage) || 'planning';
+function gitCap(root, args) {
+  try {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status !== 0) return { ok: false, out: '', err: (r.stderr || (r.error && r.error.message) || '').trim() };
+    return { ok: true, out: r.stdout || '' };
+  } catch (e) { return { ok: false, out: '', err: String((e && e.message) || e) }; }
+}
+/**
+ * → { ok, reason?, byBranch:Set<id>, byMention:Set<id> }
+ * `ok:false` is a REAL answer and never degrades into "nothing was delivered" — the caller renders
+ * it red and marks every initiative's delivery `unknown` (R-3). A board that cannot read the
+ * history must say so; silently reporting `planning` for 110 shipped initiatives is the failure
+ * this whole initiative exists to remove.
+ */
+function deliveryIndex(root, ids) {
+  const t = trunkRef(root);
+  if (!t) return { ok: false, reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived', byBranch: new Set(), byMention: new Set() };
+  const hit = deliveryCache.get(root);
+  if (hit && hit.head === t.head) return hit.index;
+
+  // %x1e separates commits, %x1f separates the message from --name-only's file list.
+  const r = gitCap(root, ['log', '--format=%x1e%s %b%x1f', '--name-only', t.head]);
+  if (!r.ok) {
+    return { ok: false, reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`, byBranch: new Set(), byMention: new Set() };
+  }
+  const byBranch = new Set(), byMention = new Set();
+  const known = Array.isArray(ids) ? ids : [...ids];
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const msg = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    for (const m of msg.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) byBranch.add(m[1]);
+    if (!files.some(isDeliveryPath)) continue;
+    for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
+  }
+  const index = { ok: true, byBranch, byMention };
+  deliveryCache.set(root, { head: t.head, index });
+  return index;
+}
+/**
+ * The five states, in precedence order. Every one of them names the artifact it was read from, so
+ * the surface can show its own evidence instead of asking to be trusted.
+ *
+ * `blocked` deliberately outranks `delivered`: work the PM RETURNED is work that needs them, and
+ * hiding that behind a delivery glyph would reproduce, in a new place, the exact failure of a board
+ * that reports green over a red underneath. (The PRD's R-1 table lists delivered first; this is the
+ * one ordering departure, made because the alternative buries a returned initiative.)
+ */
+function deriveState(ev) {
+  if (ev.accepted) return { state: 'accepted', why: `accepted by the PM${ev.acceptedAt ? ` on ${String(ev.acceptedAt).slice(0, 10)}` : ''}` };
+  if (ev.returned) return { state: 'blocked', why: 'the PM returned this at the Acceptance Gate' };
+  if (ev.needs) return { state: 'blocked', why: `${ev.needs} open item${ev.needs > 1 ? 's' : ''} in needs.json` };
+  // Not `planning`. An unreadable history means the evidence for the delivery states is missing,
+  // and `planning` is itself a claim ("nothing has happened") that the missing evidence cannot
+  // support. `unknown` is the only honest answer, and it is visibly not a resting state.
+  if (ev.delivery === 'unknown') return { state: 'unknown', why: 'the trunk history could not be read — delivery cannot be derived here' };
+  if (ev.deliveredBy) return { state: 'delivered', why: ev.deliveredBy === 'branch' ? 'an initiative/<id> branch merged to the trunk' : 'a commit on the trunk names this initiative and changes build files' };
+  if (ev.runs) return { state: 'building', why: `${ev.runs} run${ev.runs > 1 ? 's' : ''} logged, nothing merged yet` };
+  return { state: 'planning', why: 'no run, no merge, no acceptance — nothing has happened yet' };
+}
+// BOTH acceptance ledgers, oldest-wins-never: the workspace writes to its state dir, while the
+// ladder and every hand-recorded acceptance in pmos-self live in planning/runs/. Reading only the
+// state dir is why this surface reported 0 accepted against 23 real acceptance rows — the same
+// "one field, several readers, none agreeing" defect the anchor resolver was built to end.
+function acceptanceFilesFor(w) {
+  const out = [];
+  const d = stateDirFor(w);
+  if (d) out.push(path.join(d, 'acceptances.jsonl'));
+  if (w && w.root) out.push(path.join(w.root, 'planning', 'runs', 'acceptances.jsonl'));
+  return out;
 }
 function readAcceptances(w) {
-  const acc = new Map();   // initiative_id -> last action (accept | approve | return)
-  const f = acceptancesFileFor(w);
-  if (!f) return acc;
-  try {
-    for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+  const acc = new Map();   // initiative_id -> { action, at }
+  for (const f of acceptanceFilesFor(w)) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
       if (!line.trim()) continue;
       // Tolerate both shapes: this server's {action} and the kit's {accepted} (D54 adapter).
+      // THE BOOLEAN OUTRANKS THE LABEL. `action` is an open vocabulary describing what the PM did
+      // — this corpus holds accept, merge, publish, return — while `accepted` is the D12 verdict
+      // itself. Reading `action` first (the previous behaviour) meant every row labelled `merge` or
+      // `publish` carried `accepted: true` and was still not counted: 7 of 16 real acceptances went
+      // missing, and the surface reported those initiatives as merely `building`.
       try {
         const r = JSON.parse(line);
         if (!r.initiative_id) continue;
-        acc.set(r.initiative_id, r.action || (r.accepted === true ? 'accept' : r.accepted === false ? 'return' : null));
+        const label = String(r.action || '').toLowerCase();
+        const action = r.accepted === true ? 'accept'
+          : r.accepted === false ? 'return'
+            : label === 'return' ? 'return'
+              : ['accept', 'approve', 'merge', 'publish'].includes(label) ? 'accept'
+                : null;
+        const at = r.at || r.date || null;
+        // Last write wins, but a row with no timestamp never displaces a dated one.
+        const prev = acc.get(r.initiative_id);
+        if (prev && prev.at && !at) continue;
+        acc.set(r.initiative_id, { action, at });
       } catch {}
     }
-  } catch {}
+  }
   return acc;
 }
+// How many runs each initiative has logged — evidence that work STARTED, which is the only thing
+// separating `building` from `planning`. The file is the same one the ladder reads.
+function readRunCounts(w) {
+  const counts = new Map();
+  const d = stateDirFor(w);
+  const files = [];
+  if (d) files.push(path.join(d, 'agent-runs.jsonl'));
+  if (w && w.root) files.push(path.join(w.root, 'planning', 'runs', 'agent-runs.jsonl'));
+  for (const f of files) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const r = JSON.parse(line);
+        if (r && r.initiative_id) counts.set(r.initiative_id, (counts.get(r.initiative_id) || 0) + 1);
+      } catch {}
+    }
+  }
+  return counts;
+}
 function surfaceInitiatives(root, w) {
   const { initiatives } = initiativeIndex(root);
   const acc = readAcceptances(w);
+  const runs = readRunCounts(w);
+  const needsRaw = readNeeds(w) || [];
+  const needsBy = new Map();
+  for (const n of needsRaw) if (n && n.initiative_id) needsBy.set(n.initiative_id, (needsBy.get(n.initiative_id) || 0) + 1);
+
+  const del = deliveryIndex(root, initiatives.map((g) => g.id));
   const items = initiatives.map((g) => {
-    const sk = statusFrom(g);
+    const a = acc.get(g.id) || {};
+    const deliveredBy = !del.ok ? null : del.byBranch.has(g.id) ? 'branch' : del.byMention.has(g.id) ? 'mention' : null;
+    const { state, why } = deriveState({
+      accepted: a.action === 'accept' || a.action === 'approve', acceptedAt: a.at,
+      returned: a.action === 'return',
+      needs: needsBy.get(g.id) || 0,
+      delivery: del.ok ? 'known' : 'unknown',
+      deliveredBy,
+      runs: runs.get(g.id) || 0,
+    });
     return {
       id: g.id, title: g.title || null,
-      status: sk, statusText: g.status || g.stage || sk, phase: PHASE_OF[sk] || 'plan',
-      stage: g.stage || null, kr: g.kr || null,
-      accepted: acc.get(g.id) === 'accept',
-      artifacts: g.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path })),
+      status: state, statusText: why, phase: PHASE_OF[state] || 'plan',
+      // `stage` was the declared field this surface used to trust. It is gone, not renamed —
+      // the client renders `statusText`, which always names the artifact the state was read from.
+      stage: null, kr: g.kr || null, lane: g.lane || null,
+      accepted: state === 'accepted',
+      delivered: state === 'accepted' || state === 'delivered',
+      delivery_evidence: deliveredBy,
+      artifacts: g.artifacts.map((a2) => ({ role: a2.role, name: a2.name, path: a2.path })),
       // NET-NEW state — not on disk yet, so null (the surface renders "— not tracked", never a guess)
       rice: null, effort: null, milestones: null, progress: null, tracked: false,
     };
   });
   const by = (k) => items.filter((i) => i.status === k).length;
-  const needs = (readNeeds(w) || []).map((n) => ({
+  const needs = needsRaw.map((n) => ({
     t: n.question || '(unstated)', kind: n.kind || 'question', initiative_id: n.initiative_id || null,
   }));
   return {
     initiatives: items,
-    pulse: { total: items.length, planning: by('planning'), building: by('building'), blocked: by('blocked'), landed: by('landed') },
+    pulse: {
+      total: items.length, planning: by('planning'), building: by('building'),
+      blocked: by('blocked'), delivered: by('delivered'), accepted: by('accepted'),
+      unknown: by('unknown'),
+    },
+    // R-3: a failed read is reported, never absorbed. The client renders this RED above the list
+    // rather than letting 110 shipped initiatives quietly read `planning`.
+    delivery_read: del.ok ? null : (del.reason || 'the trunk history could not be read'),
     needs,
   };
 }
@@ -751,7 +916,7 @@ function surfaceRoadmap(root, w) {
     label, dates_tracked: false,
     items: items.filter((i) => keys.includes(i.status)).map((i) => ({ id: i.id, status: i.status, phase: i.phase, progress: i.progress })),
   });
-  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['landed'])]
+  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['delivered', 'accepted'])]
     .filter((g) => g.items.length);
   return { groups, note: 'dates are net-new state — grouped by status until a timeline is tracked' };
 }
@@ -928,12 +1093,16 @@ function surfaceReport(root, w) {
   const s = surfaceInitiatives(root, w);
   const line = (i) => `${i.id}${i.title ? ' — ' + i.title : ''}`;
   const inflight = s.initiatives.filter((i) => i.status === 'building' || i.status === 'blocked');
-  const landed = s.initiatives.filter((i) => i.status === 'landed');
+  // Delivered and accepted are reported SEPARATELY, not summed into one "landed" heading. The gap
+  // between them is the D12 Acceptance Gate's backlog — the number this report exists to surface.
+  const delivered = s.initiatives.filter((i) => i.status === 'delivered');
+  const accepted = s.initiatives.filter((i) => i.status === 'accepted');
   const sections = [
     { heading: 'In flight', items: inflight.map(line) },
-    { heading: 'Landed', items: landed.map(line) },
+    { heading: 'Delivered — acceptance not recorded', items: delivered.map(line) },
+    { heading: 'Accepted', items: accepted.map(line) },
     { heading: 'Needs you', items: s.needs.map((n) => n.t) },
-    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.landed} landed`] },
+    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.delivered} delivered · ${s.pulse.accepted} accepted`] },
   ];
   return { cadence: 'weekly', sections };
 }
@@ -3604,10 +3773,27 @@ async function handleRequest(req, res) {
       'and useful answer.',
     ].filter((l) => l !== '').join('\n');
 
+    // NOT typed blind into the PTY. An agent CLI opening a folder it has never seen shows a
+    // trust prompt first — and a fresh tenant repo is by definition such a folder, so the case this
+    // feature exists for is the exact case where blind input is swallowed by a security dialog and
+    // the drafting silently never happens. Found by installing the published kit and watching a real
+    // session sit at "Is this a project you trust?" with the prompt already gone.
+    //
+    // Auto-answering that dialog is not on the table: it is the PM's decision, not ours. So the
+    // prompt is PERSISTED and STAGED instead — it cannot be lost, and the PM sends it once the agent
+    // is actually at its input.
+    const promptFile = path.join(adir, 'prompt-' + Date.now() + '.md');
+    try { fs.writeFileSync(promptFile, prompt + '\n'); }
+    catch (e) { warnWriteFail('alignment prompt', e); return json(res, { ok: false, error: 'could not stage the drafting prompt' }, 500); }
+
     const s = spawnSession({ name: 'align: ' + path.basename(rel), agent: 'claude', ws: w.id,
-      origin: 'align:' + rel, initialInput: prompt + '\r' });
+      origin: 'align:' + rel });
     const started = !!(s && s.pty);
+    let staged = false;
+    if (started) { try { writeScratchpad(w, s.id, prompt); staged = true; } catch {} }
     return json(res, { ok: started, sessionId: s && s.id, targets, sink: adir,
+      prompt_file: promptFile, staged,
+      next: started ? 'the drafting prompt is staged in this session\'s scratchpad — answer any trust prompt the agent shows, then send it' : undefined,
       error: started ? undefined : ((s && s.note) || 'could not start the session') });
   }
   if (p === '/api/align/drafts') {
@@ -3622,8 +3808,19 @@ async function handleRequest(req, res) {
     let doc;
     try { doc = JSON.parse(fs.readFileSync(path.join(adir, pick), 'utf8')); }
     catch { return json(res, { ok: false, error: `the draft file '${pick}' is unreadable or not valid JSON` }, 500); }
-    const drafts = Array.isArray(doc.drafts) ? doc.drafts.filter((d) => d && typeof d.file === 'string') : [];
-    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts });
+    // A malformed draft is REFUSED at read, not half-rendered (contract crit 4). Silently dropping a
+    // bad draft would let the agent's mistake reach the PM as a shorter, unexplained list — the same
+    // "looks fine, is wrong" failure the anchored write guard exists to stop. An empty `drafts` array
+    // is valid and calm (crit 3): the agent looked and found nothing to realign.
+    if (!Array.isArray(doc.drafts)) {
+      return json(res, { ok: false, error: `the draft file '${pick}' has no drafts array — the agent did not produce the documented shape` }, 422);
+    }
+    for (const d of doc.drafts) {
+      if (!d || typeof d.file !== 'string' || typeof d.after !== 'string' || (d.before != null && typeof d.before !== 'string')) {
+        return json(res, { ok: false, error: `a draft in '${pick}' is missing a file or an after — refusing to render a partial set (crit 4)` }, 422);
+      }
+    }
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts: doc.drafts });
   }
   if (p === '/api/align/apply' && req.method === 'POST') {
     // Apply ONE drafted realignment. Same anchored guard as everything else that writes here: the
@@ -3909,6 +4106,7 @@ if (require.main === module) {
     if (shuttingDown) return; shuttingDown = true;
     for (const s of sessions.values()) if (s.pty) { try { persist(s); } catch {} }
     for (const l of listeners) { try { l.close(); } catch {} }
+    try { fs.unlinkSync(PID_FILE); } catch {}   // stop being discoverable the moment we stop serving
     process.exit(0);
   };
   process.on('SIGTERM', shutdown);
@@ -3916,7 +4114,9 @@ if (require.main === module) {
   const onError = (e) => {
     if (e.code === 'EADDRINUSE') {
       console.error(`✗ port ${PORT} is already in use (another workspace server running?).`);
-      console.error(`  Stop it, or start on another port:  PMOS_WS_PORT=7500 npm start`);
+      console.error(`  \`pmos\` finds a running workspace on any port and reuses it, and picks a free`);
+      console.error(`  port when something else holds this one. \`pmos stop\` shuts running ones down.`);
+      console.error(`  To pin a port by hand:  PMOS_WS_PORT=7500 npm start`);
       process.exit(1);
     }
     if (e.code === 'EADDRNOTAVAIL') {
@@ -3931,7 +4131,13 @@ if (require.main === module) {
     l.on('error', onError);
     l.listen(PORT, addr, () => {
       // stdout only — no request/header logging (D08). Banner (incl. any generated token) printed once.
-      if (++up === BIND.binds.length) for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
+      if (++up !== BIND.binds.length) return;
+      // Record the port WE are serving, whoever started us. The launcher discovers a running
+      // workspace from these files, so a server started by `npm start` (which is exactly what the
+      // old EADDRINUSE advice told the PM to do, on another port) has to leave the same trace as
+      // one started by `pmos` — otherwise the next `pmos` cannot see it and starts a second server.
+      try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(PID_FILE, String(process.pid)); } catch {}
+      for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
     });
   });
 }
@@ -3956,4 +4162,9 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // where the anchor resolver is looked for — exported so the suite can assert the INSTALL
   // location is in the list. A dev checkout satisfies entry 1 and would hide the loss of entry 2
   // exactly as it hid the workflow engine's absence for four releases (PKG4).
-  ANCHOR_LIB_PATHS };
+  ANCHOR_LIB_PATHS,
+  // the delivery derivation (board-delivery-truth), exported so the suite can assert the three
+  // things that matter independently of a rendered page: that no declared field reaches a status,
+  // that an unreadable history reports rather than degrades, and that a planning-only commit does
+  // not count as delivery.
+  surfaceInitiatives, deliveryIndex, deriveState, isDeliveryPath };