create-pmos 0.133.0 → 0.135.0

package/workspace/lib/vendor/workspace/lib/plan-items.js

@@ -1,922 +0,0 @@
-'use strict';
-/* plan-items.js — THE ONE WRITER and THE ONE FOLD of an initiative's breakdown (pm-os-absorb Run 1, PRD R24).
- *
- * The ledger is `plan-items.jsonl` in the repository's runs directory (`planning/runs/` for PMOS-self,
- * `pmos/state/` in a kit repository). It is control graph (pmos/graph-membership.json): Keep is the PM's
- * disposition of an agent batch, and an item's state feeds the PM's view of a gate.
- *
- * THREE CALLERS, AND NO OTHER: the workspace route (server.js), `pmos item` (lib/item-cli.js) and the
- * read-only checker (scripts/check-plan-items.js). Agents reach this module only through `pmos item`. Every
- * require of this file is spelled with `.js` so scripts/check-separation.js lists each caller by name.
- *
- * ATTRIBUTION IS SET BY THE CALL PATH, NEVER BY A FIELD. `appendFromUi` writes `pm:wawan` / `ui`;
- * `appendFromCli` writes `pm:wawan` only at an interactive terminal, `agent:<PMOS_SESSION>` from a bound
- * session, and `agent:unknown` otherwise. A caller that sends `by`, `via`, `at`, `eid`, `v` or `override`
- * is refused — accepting one, even an identical one, would make the field something a caller chooses.
- *
- * WHO IS WHO COMES FROM lib/actor.js (Run 2, slice 2A). The server route runs lib/pm-guard.js first (Origin, the
- * per-launch nonce, writer fields; act `keep` when the call carries a Keep) and passes the guard's actor on;
- * `pmos item` takes actor.fromCli. R23 (X35): an agent does not change the PM's items. A set or a flag by an agent on
- * an item whose owner is `you` is refused with 403, and so is a withdraw of an item it did not plan; the agent asks the
- * PM instead. A move of one of the PM's items is open only to the session the PM handed that item to (Hand to agent:
- * the session meta's `plan_item`, read through actor.sessionForToken), so it can take it through Doing to Done with
- * evidence (R23 "finishes"). Item-change proposals are not built (deferred, named in the run PR).
- *
- * HONEST LIMIT (rubric anti-optimism). A process that runs as the PM's own user can still read the nonce from the
- * page, or fake a terminal with no PMOS_SESSION, and be recorded as the PM. The fold flags a `kept` line whose `via`
- * is not `ui`; it cannot tell a forged `ui` line from a real one. `agent:unknown` is one shared identity, so two
- * unbound processes can withdraw each other's items, and a withdraw line appended by hand is not flagged.
- *
- * NOTHING IS CACHED (D33). Every read folds the whole ledger again; the ledger is small and append-only.
- */
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { createSinkGuard } = require('./sink.js');
-const planTree = require('./plan-tree.js');
-const consoleState = require('./console-state');
-const actorLib = require('./actor.js');
-const stateRoot = require('./state-root');
-
-const LEDGER = 'plan-items.jsonl';
-const EVENTS = ['planned', 'set', 'moved', 'flagged', 'withdrawn', 'kept'];
-const STATES = ['todo', 'doing', 'review', 'done'];
-const PM_SLUG = 'wawan';
-const ID_RE = /^(.+)\.([0-9a-z]{10})$/;
-const INIT_RE = planTree.INIT_RE;
-const SESSION_RE = /^sess-\d+\.[0-9a-f]{8}$/;
-const EID_RE = /^[0-9a-z]{12}$/;
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-const AT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
-const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
-const MAX_LINES = 50;
-const SET_FIELDS = ['title', 'stage', 'order', 'owner', 'after', 'start', 'due', 'milestone', 'note'];
-const WRITER_FIELDS = ['v', 'eid', 'by', 'via', 'at', 'override'];
-const EVIDENCE_KINDS = ['commit', 'pr', 'file', 'session', 'note'];
-const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done' };
-const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
-
-// ── paths ─────────────────────────────────────────────────────────────────────────────────────────
-/** One ledger per repository, whichever worktree writes: the main working tree of `root`. */
-function ledgerRoot(root) { return planTree.mainTree(path.resolve(root)); }
-function engine() {
-  const loaded = consoleState.loadEngine();
-  if (!loaded.ok) throw new Error(loaded.error);
-  return loaded.engine;
-}
-function ledgerPath(root) { return path.join(engine().layout(ledgerRoot(root)).runsDir, LEDGER); }
-
-// ── ids ───────────────────────────────────────────────────────────────────────────────────────────
-/** n characters of [0-9a-z] from crypto.randomBytes, by rejection so every character is equally likely. */
-function randomChars(n) {
-  let out = '';
-  while (out.length < n) {
-    for (const b of crypto.randomBytes(n * 2)) {
-      if (b >= 252) continue;                    // 252 = 7 × 36: keep the modulo unbiased
-      out += ALPHABET[b % 36];
-      if (out.length === n) break;
-    }
-  }
-  return out;
-}
-function newEventId() { return randomChars(12); }
-/** `<initiative>.<10 × [0-9a-z]>`, retried until it is unused in `taken` (a Set or a predicate). */
-function newItemId(initiative, taken) {
-  const used = typeof taken === 'function' ? taken : (id) => !!(taken && taken.has && taken.has(id));
-  for (;;) {
-    const id = `${initiative}.${randomChars(10)}`;
-    if (!used(id)) return id;
-  }
-}
-/** The initiative an item id belongs to: everything before the LAST dot (initiative ids may hold dots). */
-function initiativeOf(id) { const m = ID_RE.exec(String(id || '')); return m ? m[1] : null; }
-
-// ── labels ────────────────────────────────────────────────────────────────────────────────────────
-const label = planTree.byLabel;
-
-// ── what the page is sent: an agent's actor without its session token ─────────────────────────────────
-/* An agent writes as `agent:<PMOS_SESSION>`, and the token is `sess-<n>.<8 hex>`. The ledger keeps the token whole: it is
- * the attribution, the file is committed, and the writer and the checker match on it. The routes the page reads (the
- * Breakdown layout through readLayout, the needs-you rows through needsFor) send `agent:sess-<n>`, which is all the page
- * shows ("agent · sess-3"). A batch is named the same way, with `#2`, `#3` on a later batch whose actor reads the same on
- * one initiative (another machine, or a server whose saved sessions are gone, counts from sess-0 again), so each card
- * names one batch. Keep sends that name back, and the writer resolves it from the items (buildRecord, `kept`). */
-const PAGE_ACTOR_RE = /^(agent:sess-\d+)\.[0-9a-f]{8}$/;
-const TOKEN_TEXT_RE = /\b(sess-\d+)\.[0-9a-f]{8}\b/g;
-const PAGE_BATCH_RE = /^(agent:sess-\d+)(?:#\d+)?$/;
-const actorForPage = (by) => (isStr(by) ? by.replace(PAGE_ACTOR_RE, '$1') : by);
-const textForPage = (t) => (isStr(t) ? t.replace(TOKEN_TEXT_RE, '$1') : t);
-/** The page's name of each batch, in the batches' order. `scope(b)` is what two names must share to be told apart. */
-function batchNames(batches, scope) {
-  const seen = new Map();
-  return (batches || []).map((b) => {
-    const shown = actorForPage(b.by);
-    const k = scope(b) + '\u0000' + shown;
-    const n = (seen.get(k) || 0) + 1;
-    seen.set(k, n);
-    return n === 1 ? shown : `${shown}#${n}`;
-  });
-}
-/** A Breakdown layout (plan-tree.js) as the page is sent it: the same keys, and no session token in any actor or flag. */
-function layoutForPage(lay) {
-  const items = {};
-  for (const [id, it] of Object.entries(lay.items || {})) {
-    items[id] = {
-      ...it,
-      createdBy: actorForPage(it.createdBy), updatedBy: actorForPage(it.updatedBy), movedBy: actorForPage(it.movedBy),
-      blocked: it.blocked ? { ...it.blocked, by: actorForPage(it.blocked.by) } : it.blocked,
-      history: (it.history || []).map((h) => ({ ...h, by: actorForPage(h.by) })),
-    };
-  }
-  const names = batchNames(lay.batches, () => '');   // a layout is one initiative's
-  return {
-    ...lay, items,
-    batches: (lay.batches || []).map((b, i) => ({ ...b, key: names[i], by: names[i] })),
-    flags: (lay.flags || []).map((f) => ({ ...f, message: textForPage(f.message) })),
-  };
-}
-
-// ── field validators (shared by the fold's schema check and the writer's input check) ────────────────
-const isStr = (v) => typeof v === 'string';
-const oneLine = (v, max) => isStr(v) && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n]/.test(v);
-function ownerOk(v) {
-  if (v === 'you' || v === 'agent') return true;
-  const m = /^(person|tracker):(.+)$/s.exec(String(v));
-  return !!m && m[2].length >= 1 && m[2].length <= 60 && !/[\r\n]/.test(m[2]);
-}
-/* A real calendar day: V8 reads 2026-02-30 as 2 March, so the parsed day must print back as the same string. */
-const dateOk = (v) => v === null || (isStr(v) && DATE_RE.test(v) && (() => {
-  const t = Date.parse(v + 'T00:00:00Z');
-  return Number.isFinite(t) && new Date(t).toISOString().slice(0, 10) === v;
-})());
-function evidenceErr(e) {
-  if (!e || typeof e !== 'object' || Array.isArray(e)) return 'evidence must be {kind, ref}';
-  if (!EVIDENCE_KINDS.includes(e.kind)) return `evidence kind must be one of ${EVIDENCE_KINDS.join(', ')}`;
-  const ref = e.ref;
-  if (!isStr(ref)) return 'evidence ref must be text';
-  if (e.kind === 'commit' && !/^[0-9a-f]{7,40}$/i.test(ref)) return 'a commit reference is 7 to 40 hex characters';
-  if (e.kind === 'pr' && !/^#?\d+$/.test(ref)) return 'a pull request reference is a number, for example #412';
-  if (e.kind === 'file' && (!ref || ref.length > 300 || path.isAbsolute(ref) || ref.split(/[\\/]/).includes('..') || /[\r\n]/.test(ref))) return 'a file reference is a repository-relative path with no ".."';
-  if (e.kind === 'session' && !/^sess-\d+$/.test(ref)) return 'a session reference is sess-<n>';
-  if (e.kind === 'note' && !oneLine(ref, 200)) return 'an evidence note is 1 to 200 characters on one line';
-  return null;
-}
-/** One field value of `planned`/`set`, checked in isolation. Returns an error sentence or null. */
-function fieldErr(k, v) {
-  switch (k) {
-    case 'title': return oneLine(v, 200) ? null : 'a title is 1 to 200 characters on one line';
-    case 'stage': return isStr(v) && v.trim() ? null : 'a stage is required';
-    case 'order': return typeof v === 'number' && Number.isFinite(v) ? null : 'order must be a finite number';
-    case 'owner': return ownerOk(v) ? null : 'owner must be you, agent, person:<name> or tracker:<ref> (name or ref 1 to 60 characters)';
-    case 'after': return Array.isArray(v) && v.every((x) => isStr(x) && ID_RE.test(x)) ? null : 'after must be a list of item ids';
-    case 'start': case 'due': return dateOk(v) ? null : `${k} must be a date YYYY-MM-DD or null`;
-    case 'milestone': return typeof v === 'boolean' ? null : 'milestone must be true or false';
-    case 'note': return v === null || (isStr(v) && v.length <= 1000) ? null : 'a note is at most 1000 characters';
-    default: return `unknown field ${k}`;
-  }
-}
-
-/** The §1.2 schema of a STORED line. Returns an error sentence or null. Unknown extra keys are tolerated. */
-function lineErr(r) {
-  if (!r || typeof r !== 'object' || Array.isArray(r)) return 'not a JSON object';
-  if (r.v !== 1) return 'v is not 1';
-  if (!isStr(r.eid) || !EID_RE.test(r.eid)) return 'eid is not 12 characters [0-9a-z]';
-  if (!EVENTS.includes(r.ev)) return `unknown ev ${JSON.stringify(r.ev)}`;
-  if (!isStr(r.by) || !BY_RE.test(r.by)) return 'by is not pm:<slug>, agent:unknown or agent:<session>';
-  if (r.via !== 'ui' && r.via !== 'cli') return 'via is not ui or cli';
-  if (!isStr(r.at) || !AT_RE.test(r.at) || Number.isNaN(Date.parse(r.at))) return 'at is not an ISO 8601 UTC time';
-  if (!isStr(r.initiative) || !INIT_RE.test(r.initiative)) return 'initiative is not a record name';
-  if (r.ev !== 'kept') {
-    if (!isStr(r.item) || !ID_RE.test(r.item)) return 'item is not <initiative>.<10 characters>';
-    if (initiativeOf(r.item) !== r.initiative) return 'item does not belong to its initiative';
-  }
-  switch (r.ev) {
-    case 'planned': {
-      for (const k of ['title', 'stage', 'order', 'owner', 'after', 'start', 'due', 'milestone', 'note']) {
-        const e = fieldErr(k, r[k]);
-        if (e) return e;
-      }
-      return null;
-    }
-    case 'set': {
-      const f = r.fields;
-      if (!f || typeof f !== 'object' || Array.isArray(f) || !Object.keys(f).length) return 'fields is not a non-empty object';
-      for (const k of Object.keys(f)) {
-        if (!SET_FIELDS.includes(k)) return `unknown field ${k}`;
-        if ((k === 'start' || k === 'due' || k === 'note') && f[k] === null) continue;
-        const e = fieldErr(k, f[k]);
-        if (e) return e;
-      }
-      return null;
-    }
-    case 'moved':
-      if (!STATES.includes(r.to)) return 'to is not todo, doing, review or done';
-      if (r.evidence !== undefined && evidenceErr(r.evidence)) return evidenceErr(r.evidence);
-      if (r.override !== undefined && r.override !== true) return 'override is written only as true';
-      // The writer computes override for a pm: actor only, so an agent line that carries it was not written by the writer.
-      if (r.override !== undefined && !String(r.by).startsWith('pm:')) return 'override is written only on a pm: line';
-      return null;
-    case 'flagged':
-      if (r.blocked === true) return oneLine(r.reason, 200) ? null : 'a block reason is 1 to 200 characters';
-      if (r.blocked === false) return null;
-      return 'blocked is not true or false';
-    case 'withdrawn': return null;
-    case 'kept':
-      if (r.item !== undefined) return 'a kept line names no item';
-      if (!isStr(r.batch) || !/^agent:/.test(r.batch)) return 'batch is not agent:<session>';
-      if (!Array.isArray(r.items) || !r.items.length || !r.items.every((x) => isStr(x) && ID_RE.test(x))) return 'items is not a non-empty list of item ids';
-      return null;
-    default: return 'unknown ev';
-  }
-}
-
-// ── reading ───────────────────────────────────────────────────────────────────────────────────────
-/** Every line of the ledger, parsed. An absent file is an empty ledger. A torn or unparseable line is a flag. */
-function readLines(root) {
-  const file = ledgerPath(root);
-  let st;
-  try { st = fs.statSync(file); } catch (e) {
-    if (e && e.code === 'ENOENT') return { lines: [], flags: [] };
-    throw e;
-  }
-  /* A FIFO here would block the read forever; a directory would throw. Neither is an empty ledger. */
-  if (!st.isFile()) throw new Error(`${file} is not a regular file — refusing to read it as the plan-items ledger`);
-  return parseText(fs.readFileSync(file, 'utf8'));
-}
-function parseText(text) {
-  const lines = []; const flags = [];
-  const parts = String(text).split('\n');
-  parts.forEach((raw0, i) => {
-    const raw = raw0.replace(/\r$/, '');
-    if (!raw.trim()) return;
-    const n = i + 1;
-    let rec;
-    try { rec = JSON.parse(raw); }
-    catch {
-      flags.push({ kind: 'unparseable', line: n, eid: null, item: null, initiative: null, message: `line ${n} is not JSON (a torn or hand-edited line) — it has no effect` });
-      return;
-    }
-    lines.push({ n, raw: raw.trim(), rec });
-  });
-  return { lines, flags };
-}
-
-// ── the fold ─────────────────────────────────────────────────────────────────────────────────────
-function freshItem(rec) {
-  return {
-    id: rec.item, initiative: rec.initiative, title: rec.title.trim(), stage: rec.stage, order: rec.order, owner: rec.owner,
-    after: rec.after.slice(), start: rec.start, due: rec.due, milestone: rec.milestone, note: rec.note == null ? '' : rec.note,
-    state: 'todo', blocked: null, evidence: null, noEvidence: false, doneAt: null,
-    movedBy: null, movedVia: null, override: false, overrideShown: false,
-    proposed: rec.by.startsWith('agent:'), kept: false,
-    createdBy: rec.by, createdVia: rec.via, createdAt: rec.at,
-    updatedBy: rec.by, updatedVia: rec.via, updatedAt: rec.at,
-    history: [],
-  };
-}
-function historyOf(rec) {
-  const h = { eid: rec.eid, ev: rec.ev, by: rec.by, via: rec.via, at: rec.at };
-  if (rec.ev === 'planned') h.stage = rec.stage;
-  if (rec.ev === 'set') h.fields = { ...rec.fields };
-  if (rec.ev === 'moved') { h.to = rec.to; if (rec.evidence) h.evidence = { ...rec.evidence }; if (rec.override) h.override = true; }
-  if (rec.ev === 'flagged') { h.blocked = rec.blocked; if (rec.blocked) h.reason = rec.reason; }
-  return h;
-}
-const touch = (it, rec) => { it.updatedBy = rec.by; it.updatedVia = rec.via; it.updatedAt = rec.at; it.history.push(historyOf(rec)); };
-
-/** A mutable fold state, so the writer can apply the events of one call to a working copy as it checks them. */
-function createState() {
-  return { items: new Map(), withdrawn: new Set(), flags: [] };
-}
-function flag(S, kind, rec, n, message) {
-  S.flags.push({ kind, line: n == null ? null : n, eid: (rec && rec.eid) || null, item: (rec && rec.item) || null,
-    initiative: (rec && rec.initiative) || null, message });
-}
-/** Apply ONE schema-valid line. Every rule of §1.4 step 4 lives here, and only here. */
-function applyLine(S, rec, n) {
-  if (rec.ev === 'planned') {
-    if (S.items.has(rec.item) || S.withdrawn.has(rec.item)) { flag(S, 'duplicate-id', rec, n, `${rec.item} is planned twice — the later line is ignored`); return; }
-    const it = freshItem(rec);
-    it.history.push(historyOf(rec));
-    S.items.set(rec.item, it);
-    return;
-  }
-  if (rec.ev === 'kept') {
-    if (rec.via !== 'ui') { flag(S, 'kept-not-ui', rec, n, `a Keep line was written with via "${rec.via}", not from the workspace page — it has no effect`); return; }
-    if (!rec.by.startsWith('pm:')) { flag(S, 'kept-not-pm', rec, n, `a Keep line was written by ${rec.by}, not the PM — it has no effect`); return; }
-    for (const id of rec.items) {
-      const it = S.items.get(id);
-      if (!it || !it.proposed || it.createdBy !== rec.batch || it.initiative !== rec.initiative) {
-        S.flags.push({ kind: 'kept-mismatch', line: n == null ? null : n, eid: rec.eid, item: id, initiative: rec.initiative,
-          message: `${id} is not a proposed item of ${rec.batch} on ${rec.initiative} — this part of the Keep has no effect` });
-        continue;
-      }
-      it.proposed = false; it.kept = true;
-      touch(it, rec);
-    }
-    return;
-  }
-  if (S.withdrawn.has(rec.item)) { flag(S, 'after-terminal', rec, n, `${rec.item} was withdrawn — a later ${rec.ev} line has no effect`); return; }
-  const it = S.items.get(rec.item);
-  if (!it) { flag(S, 'unknown-item', rec, n, `${rec.ev} names ${rec.item}, which was never planned — it has no effect`); return; }
-  switch (rec.ev) {
-    case 'set':
-      for (const [k, v] of Object.entries(rec.fields)) {
-        if (k === 'title') it.title = v.trim();
-        else if (k === 'note') it.note = v == null ? '' : v;
-        else if (k === 'after') it.after = v.slice();
-        else it[k] = v;
-      }
-      break;
-    case 'moved': {
-      /* done → done is the one same-state move: it attaches evidence to an item that reads Done without it. It is
-       * not a move, so the Done's time, its mover and its override stay as they were. */
-      const attach = rec.to === 'done' && it.state === 'done';
-      if (!attach) {
-        it.doneAt = rec.to === 'done' ? rec.at : null;
-        it.state = rec.to;
-        it.movedBy = rec.by; it.movedVia = rec.via;
-        it.override = !!rec.override; it.overrideShown = !!rec.override;
-      }
-      it.evidence = rec.evidence ? { ...rec.evidence } : (rec.to === 'done' ? it.evidence : null);
-      // From the evidence the item ENDS UP with: evidence given on the way to Review still counts at Done.
-      it.noEvidence = it.state === 'done' && String(it.movedBy).startsWith('agent:') && !it.evidence;
-      break;
-    }
-    case 'flagged':
-      it.blocked = rec.blocked ? { reason: rec.reason.trim(), by: rec.by, at: rec.at } : null;
-      break;
-    case 'withdrawn':
-      it.state = 'withdrawn';
-      S.items.delete(rec.item);
-      S.withdrawn.add(rec.item);
-      touch(it, rec);
-      return;
-    default: return;
-  }
-  touch(it, rec);
-}
-
-const byTime = (a, b) => (Date.parse(a.rec.at) - Date.parse(b.rec.at)) || (a.rec.eid < b.rec.eid ? -1 : a.rec.eid > b.rec.eid ? 1 : 0);
-
-/**
- * events → current items. Pure and deterministic: the same lines in any order give the same result, which
- * is what lets a union merge interleave two sides' lines safely.
- *
- * @param {Array<{n:number, raw:string, rec:object}>} lines   readLines().lines (or anything of that shape)
- * @param {{now?: number, flags?: Array}} [opts]              `flags` carries readLines' parse flags through
- */
-function fold(lines, { now = Date.now(), flags = [] } = {}) {
-  const S = createState();
-  S.flags.push(...flags);
-  // 1 · schema
-  const valid = [];
-  for (const l of lines || []) {
-    const err = lineErr(l.rec);
-    if (err) { S.flags.push({ kind: 'invalid', line: l.n == null ? null : l.n, eid: (l.rec && isStr(l.rec.eid)) ? l.rec.eid : null, item: (l.rec && isStr(l.rec.item)) ? l.rec.item : null, initiative: (l.rec && isStr(l.rec.initiative)) ? l.rec.initiative : null, message: `line ${l.n} does not match the plan-items schema: ${err} — it has no effect` }); continue; }
-    valid.push(l);
-  }
-  // 2 · byte-identical duplicates (a union-merge artefact) are dropped and counted; one eid with two contents is a flag
-  let dupes = 0;
-  const seenRaw = new Set();
-  const unique = [];
-  for (const l of valid) {
-    if (seenRaw.has(l.raw)) { dupes++; continue; }
-    seenRaw.add(l.raw);
-    unique.push(l);
-  }
-  // 3 · sort by (at, eid) — and only then decide which of two same-eid lines wins, so the winner is order-free
-  unique.sort((a, b) => byTime(a, b) || (a.raw < b.raw ? -1 : a.raw > b.raw ? 1 : 0));
-  const seenEid = new Set();
-  const ordered = [];
-  for (const l of unique) {
-    if (seenEid.has(l.rec.eid)) { flag(S, 'duplicate-event', l.rec, l.n, `event ${l.rec.eid} appears twice with different content — the later one has no effect`); continue; }
-    seenEid.add(l.rec.eid);
-    ordered.push(l);
-  }
-  // 4 · apply
-  for (const l of ordered) applyLine(S, l.rec, l.n);
-  return finish(S, { now, dupes });
-}
-
-/**
- * Every live item that comes after itself through its predecessors. The writer refuses a loop, but two writers can
- * race between their read and their append, and a union merge can join two branches' After lists, so the fold
- * checks too. Withdrawn ids are not in S.items and end a walk.
- */
-function loopItems(S) {
-  const on = [];
-  for (const [start, item] of S.items) {
-    const seen = new Set();
-    const stack = item.after.slice();
-    while (stack.length) {
-      const cur = stack.pop();
-      if (cur === start) { on.push(start); break; }
-      if (seen.has(cur)) continue;
-      seen.add(cur);
-      const it = S.items.get(cur);
-      if (it) stack.push(...it.after);
-    }
-  }
-  return on.sort();
-}
-
-/** Derived fields, batches and the result shape. Called once per fold. */
-function finish(S, { now = Date.now(), dupes = 0 } = {}) {
-  for (const id of loopItems(S)) {
-    const it = S.items.get(id);
-    S.flags.push({ kind: 'after-loop', line: null, eid: null, item: id, initiative: it.initiative,
-      message: `${id} comes after itself through its After list (two writes crossed, or a merge joined them) — change its After list` });
-  }
-  const todayUTC = new Date(now).toISOString().slice(0, 10);
-  const items = {};
-  const list = [...S.items.values()];
-  list.sort((a, b) => (Date.parse(a.createdAt) - Date.parse(b.createdAt)) || a.id.localeCompare(b.id));
-  for (const it of list) {
-    const out = { ...it, after: it.after.slice(), history: it.history.slice() };
-    out.late = !!it.due && it.due < todayUTC && it.state !== 'done';
-    out.byLabel = label(it.updatedBy);
-    items[it.id] = out;
-  }
-  const groups = new Map();
-  for (const it of list) {
-    if (!it.proposed || !it.createdBy.startsWith('agent:')) continue;
-    const key = `${it.initiative}\u0000${it.createdBy}`;
-    if (!groups.has(key)) groups.set(key, []);
-    groups.get(key).push(it);
-  }
-  const batches = [...groups.values()].map((g) => ({
-    initiative: g[0].initiative, by: g[0].createdBy, byLabel: label(g[0].createdBy), count: g.length,
-    items: g.map((x) => x.id), firstAt: g[0].createdAt, lastAt: g[g.length - 1].createdAt,
-  })).sort((a, b) => (Date.parse(a.firstAt) - Date.parse(b.firstAt)) || a.by.localeCompare(b.by));
-  return {
-    items, order: list.map((x) => x.id), batches, flags: S.flags.slice(), dupes,
-    withdrawnCount: S.withdrawn.size, withdrawnIds: [...S.withdrawn].sort(),
-  };
-}
-
-function readFold(root, { now } = {}) {
-  const { lines, flags } = readLines(root);
-  return fold(lines, { now, flags });
-}
-
-const progressLabel = planTree.progressLabel;
-/** Ledger-only progress for one initiative (R6): proposed and withdrawn items never count. */
-function progressOf(result, initiative) {
-  const mine = Object.values(result.items).filter((it) => it.initiative === initiative);
-  const its = mine.filter((it) => !it.proposed);
-  const done = its.filter((it) => it.state === 'done').length;
-  const proposed = mine.length - its.length;
-  return { done, total: its.length, proposed, label: progressLabel(done, its.length, proposed) };
-}
-
-// ── attribution ───────────────────────────────────────────────────────────────────────────────────
-/**
- * Who a `pmos item` call is. A bound agent session FIRST, by its token: an agent that runs its commands in a PTY (or
- * wraps them with `script`) still has a terminal, and a terminal must not turn its writes into the PM's. Only agent
- * sessions get PMOS_SESSION (server.js), so the PM's own shell is still a terminal with no token: the PM. Else unknown.
- */
-function actorFromCli(opts = {}) {
-  return actorLib.fromCli(opts);   // one rule for every ledger (lib/actor.js); the defaults are actor.js's
-}
-
-// ── the writer ────────────────────────────────────────────────────────────────────────────────────
-const refuse = (status, error, index) => ({ ok: false, status, error, index: index == null ? null : index });
-const PM_ITEM_HINT = 'this item is the PM\'s (owner you) — an agent does not change it; ask the PM';
-const PM_MOVE_HINT = 'this item is the PM\'s (owner you) and the PM did not hand it to this session — ask the PM to hand it to you';
-
-/** Does adding `from → each of after` make a loop in the predecessor graph of `items`? */
-function makesLoop(items, from, after) {
-  const seen = new Set();
-  const stack = after.slice();
-  while (stack.length) {
-    const cur = stack.pop();
-    if (cur === from) return true;
-    if (seen.has(cur)) continue;
-    seen.add(cur);
-    const it = items.get(cur);
-    if (it) stack.push(...it.after);
-  }
-  return false;
-}
-
-/**
- * Check one caller event against the working copy and build the record to write. Returns { rec } or a refusal.
- * The record's keys are emitted common-first, then the payload, in the order of the plan's §1.2.
- */
-function buildRecord(ctx, ev, index) {
-  const { S, actor, allowKept, root, stagesCache, nextAt, handedTo } = ctx;
-  if (!ev || typeof ev !== 'object' || Array.isArray(ev)) return refuse(400, 'each line must be an object', index);
-  for (const k of WRITER_FIELDS) if (k in ev) return refuse(400, `field ${k} is set by the writer`, index);
-  if (!EVENTS.includes(ev.ev)) return refuse(400, `unknown event ${JSON.stringify(ev.ev)} — one of ${EVENTS.join(', ')}`, index);
-  if (ev.ev === 'kept' && !allowKept) return refuse(400, 'Keep is written only from the workspace page (Breakdown or Today).', index);
-  if (ev.ev === 'planned' && 'item' in ev) return refuse(400, 'field item is set by the writer', index);
-  const allowed = {
-    planned: ['ev', 'initiative', 'title', 'stage', 'order', 'owner', 'after', 'start', 'due', 'milestone', 'note'],
-    set: ['ev', 'item', 'initiative', 'fields'],
-    moved: ['ev', 'item', 'initiative', 'to', 'evidence'],
-    flagged: ['ev', 'item', 'initiative', 'blocked', 'reason'],
-    withdrawn: ['ev', 'item', 'initiative'],
-    kept: ['ev', 'initiative', 'batch', 'items'],
-  }[ev.ev];
-  for (const k of Object.keys(ev)) if (!allowed.includes(k)) return refuse(400, `field ${k} is not part of a ${ev.ev} line`, index);
-
-  /* `floor` is the newest `at` of the item(s) this line changes: the fold sorts by `at`, so the line must sort after
-   * them even when one of them is dated ahead of this clock (a union merge from a machine whose clock runs ahead). */
-  const common = (initiative, item, floor) => {
-    const rec = { v: 1, eid: newEventId(), ev: ev.ev };
-    if (item) rec.item = item;
-    Object.assign(rec, { initiative, by: actor.by, via: actor.via, at: nextAt(floor) });
-    return rec;
-  };
-  // R23 (X35): the PM's items (owner `you`) are the PM's to change. An agent asks; it does not set or flag them.
-  const agentOnPmItem = (it) => actor.by.startsWith('agent:') && it.owner === 'you';
-  const stagesOf = (initiative) => {
-    if (!stagesCache.has(initiative)) stagesCache.set(initiative, planTree.stagesFor(root, initiative));
-    return stagesCache.get(initiative);
-  };
-  const resolveStage = (initiative, v, index2) => {
-    const stages = stagesOf(initiative);
-    const want = String(v == null ? '' : v).toLowerCase().replace(/\s+/g, ' ').trim();
-    const hit = stages.find((s) => s.id === want || String(s.label).toLowerCase() === want);
-    if (!hit) return refuse(400, `unknown stage ${JSON.stringify(v)} — the stages of ${initiative} are ${stages.map((s) => s.id).join(', ')}`, index2);
-    return { id: hit.id };
-  };
-  /* Only the predecessors a call ADDS are checked: an item whose predecessor was withdrawn later must still be able to
-   * drop that one, or another, from its list. `had` is the item's current list. */
-  const checkAfter = (initiative, list, self, had = []) => {
-    for (const id of list) {
-      if (had.includes(id)) continue;
-      if (id === self) return refuse(409, 'an item cannot come after itself', index);
-      if (S.withdrawn.has(id)) return refuse(409, `${id} is withdrawn and cannot be a predecessor`, index);
-      if (!S.items.has(id)) return refuse(404, `no item ${id} in this repository`, index);
-    }
-    if (self && makesLoop(S.items, self, list)) return refuse(409, 'this would make a loop', index);
-    return null;
-  };
-  // An existing item named by a non-planned line, with its initiative checked against the id.
-  const existing = () => {
-    if (!isStr(ev.item) || !ID_RE.test(ev.item)) return refuse(400, 'item must be an item id, <initiative>.<10 characters>', index);
-    const init = initiativeOf(ev.item);
-    if (ev.initiative !== undefined && ev.initiative !== init) return refuse(400, `item ${ev.item} does not belong to initiative ${ev.initiative}`, index);
-    if (S.withdrawn.has(ev.item)) return refuse(409, `${ev.item} is withdrawn`, index);
-    const it = S.items.get(ev.item);
-    if (!it) return refuse(404, `no item ${ev.item} in this repository`, index);
-    return { it, init };
-  };
-
-  switch (ev.ev) {
-    case 'planned': {
-      const init = ev.initiative;
-      if (!isStr(init) || !INIT_RE.test(init)) return refuse(400, 'initiative must be a record name', index);
-      if (!planTree.recordPath(root, init)) return refuse(404, `no initiative ${init} in this repository`, index);
-      const tErr = fieldErr('title', ev.title);
-      if (tErr) return refuse(400, tErr, index);
-      const st = resolveStage(init, ev.stage, index);
-      if (st.ok === false) return st;
-      let order = ev.order;
-      if (order === undefined || order === null) {
-        let max = 0;
-        for (const it of S.items.values()) if (it.initiative === init && it.stage === st.id && it.order > max) max = it.order;
-        order = max + 1024;
-      } else if (fieldErr('order', order)) return refuse(400, fieldErr('order', order), index);
-      const owner = ev.owner === undefined || ev.owner === null ? (actor.by.startsWith('pm:') ? 'you' : 'agent') : ev.owner;
-      if (fieldErr('owner', owner)) return refuse(400, fieldErr('owner', owner), index);
-      const after = ev.after === undefined || ev.after === null ? [] : ev.after;
-      if (fieldErr('after', after)) return refuse(400, fieldErr('after', after), index);
-      const start = ev.start === undefined ? null : ev.start;
-      const due = ev.due === undefined ? null : ev.due;
-      if (fieldErr('start', start)) return refuse(400, fieldErr('start', start), index);
-      if (fieldErr('due', due)) return refuse(400, fieldErr('due', due), index);
-      if (start && due && start > due) return refuse(400, 'start must be on or before due', index);
-      const milestone = ev.milestone === undefined || ev.milestone === null ? false : ev.milestone;
-      if (fieldErr('milestone', milestone)) return refuse(400, fieldErr('milestone', milestone), index);
-      const note = ev.note === undefined || ev.note === null ? '' : ev.note;
-      if (fieldErr('note', note)) return refuse(400, fieldErr('note', note), index);
-      const a = checkAfter(init, after, null);
-      if (a) return a;
-      const id = newItemId(init, (x) => S.items.has(x) || S.withdrawn.has(x));
-      const rec = common(init, id);
-      Object.assign(rec, { title: ev.title.trim(), stage: st.id, order, owner, after: after.slice(), start, due, milestone, note });
-      return { rec };
-    }
-    case 'set': {
-      const ex = existing(); if (ex.ok === false) return ex;
-      const { it, init } = ex;
-      if (agentOnPmItem(it)) return refuse(403, PM_ITEM_HINT, index);
-      const f = ev.fields;
-      if (!f || typeof f !== 'object' || Array.isArray(f) || !Object.keys(f).length) return refuse(400, 'fields must name at least one of ' + SET_FIELDS.join(', '), index);
-      const out = {};
-      for (const k of Object.keys(f)) {
-        if (!SET_FIELDS.includes(k)) return refuse(400, `field ${k} cannot be set — one of ${SET_FIELDS.join(', ')}`, index);
-        let v = f[k];
-        if ((k === 'start' || k === 'due' || k === 'note') && v === null) { out[k] = null; continue; }
-        if (k === 'stage') { const st = resolveStage(init, v, index); if (st.ok === false) return st; out[k] = st.id; continue; }
-        if (k === 'title' && isStr(v)) v = v.trim();
-        const e = fieldErr(k, v);
-        if (e) return refuse(400, e, index);
-        out[k] = Array.isArray(v) ? v.slice() : v;
-      }
-      const start = 'start' in out ? out.start : it.start;
-      const due = 'due' in out ? out.due : it.due;
-      if (start && due && start > due) return refuse(400, 'start must be on or before due', index);
-      if ('after' in out) { const a = checkAfter(init, out.after, it.id, it.after); if (a) return a; }
-      const rec = common(init, it.id, it.updatedAt);
-      rec.fields = out;
-      return { rec };
-    }
-    case 'moved': {
-      const ex = existing(); if (ex.ok === false) return ex;
-      const { it, init } = ex;
-      if (!STATES.includes(ev.to)) return refuse(400, `to must be one of ${STATES.join(', ')}`, index);
-      if (agentOnPmItem(it) && !handedTo(it.id)) return refuse(403, PM_MOVE_HINT, index);
-      /* done → done with evidence attaches it to an item that reads Done without evidence: the way to correct an agent
-       * Done that forgot --evidence, from the CLI or the item sheet. Any other same-state move is refused. */
-      const attach = ev.to === 'done' && it.state === 'done' && ev.evidence != null && (it.noEvidence || !it.evidence);
-      if (ev.to === it.state && !attach) return refuse(409, `already ${STATE_LABEL[it.state]}`, index);
-      let evidence;
-      if (ev.evidence !== undefined && ev.evidence !== null) {
-        evidence = isStr(ev.evidence) ? parseEvidence(ev.evidence) : ev.evidence;
-        const e = evidence && !evidence.error ? evidenceErr(evidence) : (evidence ? evidence.error : 'evidence must be {kind, ref}');
-        if (e) return refuse(400, e, index);
-        evidence = { kind: evidence.kind, ref: evidence.ref };
-      }
-      const rec = common(init, it.id, it.updatedAt);
-      rec.to = ev.to;
-      if (evidence) rec.evidence = evidence;
-      // override: the PM moved an item the agent owns. Computed here, never accepted from a caller. Attaching
-      // evidence is not a move, so it is never an override.
-      if (actor.by.startsWith('pm:') && it.owner === 'agent' && !attach) rec.override = true;
-      return { rec };
-    }
-    case 'flagged': {
-      const ex = existing(); if (ex.ok === false) return ex;
-      const { it, init } = ex;
-      if (agentOnPmItem(it)) return refuse(403, PM_ITEM_HINT, index);
-      if (ev.blocked === true) {
-        if (!oneLine(ev.reason, 200)) return refuse(400, 'a block reason is 1 to 200 characters on one line', index);
-        const rec = common(init, it.id, it.updatedAt);
-        Object.assign(rec, { blocked: true, reason: ev.reason.trim() });
-        return { rec };
-      }
-      if (ev.blocked === false) {
-        if (ev.reason !== undefined) return refuse(400, 'an unblock carries no reason', index);
-        if (!it.blocked) return refuse(409, `${it.id} is not blocked`, index);
-        const rec = common(init, it.id, it.updatedAt);
-        rec.blocked = false;
-        return { rec };
-      }
-      return refuse(400, 'blocked must be true or false', index);
-    }
-    case 'withdrawn': {
-      const ex = existing(); if (ex.ok === false) return ex;
-      /* Withdraw is terminal (the fold has no un-withdraw), so an agent withdraws only what it planned itself (R23).
-       * The PM's items, and another session's, are the PM's to withdraw. */
-      if (actor.by.startsWith('agent:') && ex.it.createdBy !== actor.by) {
-        return refuse(403, 'an agent withdraws only the items it planned — the PM withdraws the rest', index);
-      }
-      return { rec: common(ex.init, ex.it.id, ex.it.updatedAt) };
-    }
-    case 'kept': {
-      const init = ev.initiative;
-      if (!isStr(init) || !INIT_RE.test(init)) return refuse(400, 'initiative must be a record name', index);
-      if (!isStr(ev.batch) || !/^agent:/.test(ev.batch)) return refuse(400, 'batch must be the agent:<session> that planned the items', index);
-      if (!Array.isArray(ev.items) || !ev.items.length || !ev.items.every((x) => isStr(x) && ID_RE.test(x))) return refuse(400, 'items must be a non-empty list of item ids', index);
-      if (new Set(ev.items).size !== ev.items.length) return refuse(400, 'items names an item twice', index);
-      /* The page names a batch as it was sent it (`agent:sess-<n>`, `#k` on a repeat), never with the token. Such a name
-       * is resolved from the items: the batch is the actor that proposed the first of them, its page name must be the
-       * one sent, and every item is checked against that actor below. The line records the actor in full. */
-      let batch = ev.batch;
-      if (!BY_RE.test(batch)) {
-        const m = PAGE_BATCH_RE.exec(batch);
-        const first = S.items.get(ev.items[0]);
-        if (!m || !first || actorForPage(first.createdBy) !== m[1]) return refuse(409, `${ev.items[0]} is not a proposed item of this batch`, index);
-        batch = first.createdBy;
-      }
-      let floor = null;
-      for (const id of ev.items) {
-        const it = S.items.get(id);
-        if (!it || !it.proposed || it.createdBy !== batch || it.initiative !== init) return refuse(409, `${id} is not a proposed item of this batch`, index);
-        if (!floor || Date.parse(it.updatedAt) > Date.parse(floor)) floor = it.updatedAt;
-      }
-      const rec = common(init, null, floor);
-      Object.assign(rec, { batch, items: ev.items.slice() });
-      return { rec };
-    }
-    default: return refuse(400, 'unknown event', index);
-  }
-}
-
-/** `commit:1a2b3c4` → {kind, ref}. */
-function parseEvidence(s) {
-  const m = /^([a-z]+):(.+)$/s.exec(String(s));
-  if (!m) return { error: 'evidence is <kind>:<ref>, for example commit:1a2b3c4' };
-  return { kind: m[1], ref: m[2] };
-}
-
-function append(root, events, actor, { now, allowKept, handedTo = () => false }) {
-  if (!Array.isArray(events) || !events.length) return refuse(400, 'send at least one line', null);
-  if (events.length > MAX_LINES) return refuse(413, `send at most ${MAX_LINES} lines at once`, null);
-  let read;
-  try { read = readLines(root); } catch (e) { return refuse(500, 'could not read the plan-items ledger — nothing was saved: ' + String((e && e.message) || e).slice(0, 160), null); }
-  const base = fold(read.lines, { now: now == null ? Date.now() : now, flags: read.flags });
-  // The working copy: the folded ledger, with each checked event of this call applied before the next is checked.
-  const S = createState();
-  for (const id of base.order) {
-    const it = base.items[id];
-    S.items.set(id, { ...it, after: it.after.slice(), history: it.history.slice() });
-  }
-  for (const id of base.withdrawnIds) S.withdrawn.add(id);
-  /* Strictly increasing `at`. Lines written by one call (a planned then a set in the same millisecond) must
-   * sort in the order they were written, and the fold sorts by (at, eid). A line dated more than a second
-   * ahead of this clock is ignored for the GLOBAL floor, so one forged future date cannot drag every later write
-   * with it; each line also gets a floor from its own item (`common(…, floor)`), so a write to an item whose newest
-   * line is dated ahead still sorts after that line and is not silently lost. */
-  const clock = now == null ? Date.now() : now;
-  let last = 0;
-  for (const l of read.lines) {
-    const t = l.rec && isStr(l.rec.at) ? Date.parse(l.rec.at) : NaN;
-    if (Number.isFinite(t) && t <= clock + 1000 && t > last) last = t;
-  }
-  const nextAt = (floorIso) => {
-    const f = floorIso ? Date.parse(floorIso) + 1 : 0;
-    const t = Math.max(now == null ? Date.now() : now, last + 1, Number.isFinite(f) ? f : 0);
-    last = t;
-    return new Date(t).toISOString();
-  };
-  const ctx = { S, actor, allowKept, root, stagesCache: new Map(), nextAt, handedTo };
-  const recs = [];
-  for (let i = 0; i < events.length; i++) {
-    let r;
-    try { r = buildRecord(ctx, events[i], i); }
-    catch (e) { return refuse(500, 'could not check the line — nothing was saved: ' + String((e && e.message) || e).slice(0, 160), i); }
-    if (r.ok === false) return r;
-    applyLine(S, r.rec, null);
-    recs.push(r.rec);
-  }
-  let file;
-  try { file = ledgerPath(root); fs.mkdirSync(path.dirname(file), { recursive: true }); }
-  catch { return refuse(500, 'could not record — nothing was saved', null); }
-  const guard = createSinkGuard({ sink: file, what: 'plan items' });
-  let wrote = 0;
-  for (const rec of recs) {
-    try { guard.appendLine(file, rec); wrote++; }
-    catch {
-      return refuse(500, wrote ? `could not record — ${wrote} of ${recs.length} lines were saved before the write failed` : 'could not record — nothing was saved', wrote);
-    }
-  }
-  const touched = [];
-  for (const r of recs) for (const id of (r.ev === 'kept' ? r.items : [r.item])) if (!touched.includes(id)) touched.push(id);
-  return { ok: true, written: recs.map((r) => ({ eid: r.eid, ev: r.ev, item: r.item || null })), items: touched };
-}
-
-/**
- * The workspace page's route. The only path that accepts `kept`. The route passes the actor lib/pm-guard.js answered;
- * with none, actor.fromUi(). Either way it must be the PM via `ui`: anything else is refused, not rewritten.
- */
-function appendFromUi(root, events, { now, actor } = {}) {
-  const who = actor === undefined ? actorLib.fromUi() : actor;
-  if (!actorLib.isPm(who) || who.via !== 'ui') return refuse(403, 'the page writes only as the PM, after the guard', null);
-  return append(root, events, { by: who.by, via: 'ui' }, { now, allowKept: true });
-}
-/** `pmos item`. The actor comes from the terminal and PMOS_SESSION, never from an argument. Refuses `kept`. */
-function appendFromCli(root, events, { now, isTTY, env, sessDir } = {}) {
-  const opts = {};
-  if (isTTY !== undefined) opts.isTTY = isTTY;
-  if (env !== undefined) opts.env = env;
-  const who = actorFromCli(opts);
-  return append(root, events, who, { now, allowKept: false, handedTo: handedToSession(who, env, sessDir) });
-}
-/**
- * itemId → true when the PM handed that item to the actor's session (R23). The session meta lives in the workspace's
- * runtime state (`<state root>/sessions`), resolved from the environment the way the server resolves it; a test passes
- * `sessDir`. The meta is read at most once per call.
- */
-function handedToSession(who, env, sessDir) {
-  const token = actorLib.sessionOf(who);
-  if (!token) return () => false;
-  let s;
-  return (itemId) => {
-    if (s === undefined) {
-      const dir = sessDir || path.join(stateRoot.defaultRoot({ env: env || process.env }), 'sessions');
-      s = actorLib.sessionForToken(token, { sessDir: dir });
-    }
-    return !!s && s.plan_item === itemId;
-  };
-}
-
-// ── needs-you rows (Keep cards, agent Done with no evidence, forged Keep lines) ─────────────────────
-function needsFor(root, { now } = {}) {
-  const r = readFold(root, { now });
-  const rows = [];
-  // The rows go to the page (/api/needs), so each batch is named as the Breakdown names it, without the token.
-  const names = batchNames(r.batches, (b) => b.initiative);
-  r.batches.forEach((b, i) => {
-    rows.push({ run_id: `keep:${b.initiative}:${names[i]}`, initiative_id: b.initiative, kind: 'keep', derived: true,
-      question: b.count === 1 ? '1 item' : `${b.count} items`, doc: null,
-      batch: { by: names[i], byLabel: b.byLabel, count: b.count, items: b.items.slice() } });
-  });
-  for (const id of r.order) {
-    const it = r.items[id];
-    if (!it.noEvidence || it.state !== 'done') continue;
-    rows.push({ run_id: `evidence:${id}`, initiative_id: it.initiative, kind: 'evidence', derived: true,
-      question: `"${it.title}" reads Done with no evidence`, doc: null, item: id });
-  }
-  for (const f of r.flags) {
-    if (f.kind !== 'kept-not-ui' && f.kind !== 'kept-not-pm') continue;
-    rows.push({ run_id: `plan-flag:${f.eid}`, initiative_id: f.initiative, kind: 'plan-flag', derived: true,
-      question: f.kind === 'kept-not-ui'
-        ? 'A Keep line in plan-items.jsonl was not written from the workspace page. It has no effect.'
-        : 'A Keep line in plan-items.jsonl was not written by the PM. It has no effect.',
-      doc: null, flag: { kind: f.kind, eid: f.eid, line: f.line } });
-  }
-  return rows;
-}
-
-// ── the poll signature (§2.5) ───────────────────────────────────────────────────────────────────
-const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
-function itemsSig(root) {
-  let st;
-  try { st = fs.statSync(ledgerPath(root)); } catch { return 'none'; }
-  return sha1(`${st.size}:${st.mtimeMs}:${st.ino}`);
-}
-/** What the ladder reads besides the records: git HEAD and the records (board-cache), and the other ledgers. */
-function evidenceSig(root) {
-  const boardCache = require('./board-cache');
-  let runsDir = null;
-  try { runsDir = engine().layout(root).runsDir; } catch { runsDir = null; }
-  const parts = [];
-  if (runsDir) {
-    let names = [];
-    try { names = fs.readdirSync(runsDir).filter((n) => n.endsWith('.jsonl') && n !== LEDGER).sort(); } catch { names = []; }
-    for (const n of names) {
-      try { const st = fs.statSync(path.join(runsDir, n)); parts.push(`${n}:${st.size}:${st.mtimeMs}`); } catch { /* vanished mid-scan */ }
-    }
-  }
-  return sha1(boardCache.signature(root) + '|' + parts.join(','));
-}
-/**
- * One signature per registered workspace, computed per poll and never stored (D33). `items` is one stat;
- * `evidence` is computed only for the watched workspaces (at most 4), because it runs one `git rev-parse`.
- */
-function ledgerSigs(workspaces, watched) {
-  const want = new Set(String(watched || '').split(',').map((s) => s.trim()).filter(Boolean).slice(0, 4));
-  const out = {};
-  for (const w of workspaces || []) {
-    if (!w || !w.id || !w.root) continue;
-    let items = 'none';
-    try { items = itemsSig(w.root); } catch { items = 'unreadable'; }
-    let evidence = null;
-    if (want.has(w.id)) { try { evidence = evidenceSig(w.root); } catch { evidence = 'unreadable'; } }
-    out[w.id] = { items, evidence };
-  }
-  return out;
-}
-
-/**
- * The Breakdown layout of one initiative and the signature it answers to (GET /api/plan-items). `w` is {id, root};
- * `ladder: false` is the fast read with no owed rows.
- *
- * The signature is taken FIRST, before the ledger and the ladder are read. The page keeps it and reads the layout again
- * only when a poll returns a different one (panel-breakdown.js, "When it reads again"). Taken after the reads, a line
- * appended while they ran (the ladder alone is about 800 ms on a real repository) gave the page the signature WITH the
- * line and the items WITHOUT it: every later poll matched, and the line stayed off the screen until some other write.
- * Taken first, a write during the read leaves a signature older than the data at worst, which costs one more read.
- * The layout is the page's: no session token in it (layoutForPage).
- */
-function readLayout(w, initiative, { ladder = true, now = Date.now() } = {}) {
-  const sig = ledgerSigs([w], w.id)[w.id];
-  const fold = readFold(w.root, { now });
-  let lad = null;
-  if (ladder) {
-    try { lad = consoleState.ladder({ root: w.root, id: initiative }); }
-    catch (e) { lad = { ok: false, error: 'the ladder could not be derived: ' + String((e && e.message) || 'error').slice(0, 140) }; }
-  }
-  return { sig, layout: layoutForPage(planTree.layout({ root: w.root, initiative, fold, ladder: lad, now })) };
-}
-
-// ── Hand to agent: the prompt a bound session starts with (§2.4) ───────────────────────────────────
-/* PMOS_BIN (server.js) is this workspace's own bin/pmos.js, so the agent never runs an older global `pmos` that has
- * no `item` verb. `after` names only live predecessors: the caller drops withdrawn ids. */
-function handoffPrompt(item, initiativeId, stageLabel) {
-  const first = `Finish the work item "${item.title}" (${item.id}) for initiative ${initiativeId}.`;
-  const prompt = [
-    first,
-    `Stage: ${stageLabel}. Due: ${item.due || 'none'}. After: ${item.after && item.after.length ? item.after.join(', ') : 'none'}.`,
-    `Note: ${item.note ? String(item.note).replace(/\s*\n\s*/g, ' ') : 'none'}.`,
-    'Work on the branch this session started on. Do not write planning/work-items.jsonl.',
-    'Report progress with this workspace\'s pmos item command, for example:',
-    `  node "$PMOS_BIN" item move ${item.id} doing`,
-    `  node "$PMOS_BIN" item move ${item.id} done --evidence commit:<sha>`,
-    'An agent Done without --evidence reads "no evidence" and goes to the PM.',
-    'If you forgot --evidence, run the same move again with it.',
-  ].join('\n');
-  return { first, prompt };
-}
-
-module.exports = {
-  LEDGER, EVENTS, STATES, PM_SLUG, ID_RE, INIT_RE, SESSION_RE,
-  ledgerRoot, ledgerPath, newItemId, newEventId, initiativeOf,
-  readLines, parseText, fold, readFold, progressOf, progressLabel, lineErr,
-  actorFromCli, appendFromUi, appendFromCli, needsFor, ledgerSigs, readLayout, handoffPrompt, parseEvidence,
-};