create-pmos 0.52.0 → 0.53.0

package/workspace/guide/today.md

@@ -0,0 +1,85 @@
+---
+type: Guide
+title: "Today: what needs you"
+description: "The eight kinds of card on Today, the one button on each card, the count, the empty state, and the pmos today command."
+timestamp: 2026-10-05
+---
+
+# Today: what needs you
+
+Today lists only what waits for you. Each card is one thing that only you can close. When nothing waits, Today says so and names the next scheduled draft, for example "Nothing needs you. Next: biweekly draft Fri 16 Oct."
+
+Press **Today** in the top bar, or press `g` and then `t`, to open it. The number on the Today button is the number of cards in the scope you chose: the repository, or All repositories. It is the same number that Today shows at the top of the list.
+
+## A card
+
+Every card has four parts.
+
+- **Cause.** One sentence: why the card is here.
+- **Evidence.** The record that shows it, for example a run id, a file or a date.
+- **One button.** The act that closes the card. The verb comes first, for example **Review**, **Keep** or **Open**.
+- **The three dots.** A menu with **Open the initiative**, **Copy the command** and **Why is this here?**. The menu has the same items on every card. A touch screen and a keyboard reach them as a mouse does.
+
+When you finish the act, the card leaves and the count goes down by one. You do not dismiss a card. A card leaves only when its cause is gone.
+
+## The eight kinds
+
+Today puts the cards in this order. Within a kind, the cards keep a fixed order, so a card does not move while you read.
+
+| Kind | What it is | The button |
+|---|---|---|
+| 1. A gate is owed | A run waits for your acceptance, an outcome check is due, or a report is ready to issue. | Review, Check or Issue |
+| 2. A session is waiting | A session in a terminal asked you a question and waits for the answer. | Open |
+| 3. A step you returned | You returned an acceptance and the initiative has not been accepted since. | Open |
+| 4. Work to check | An item is in Review, or an item is Done with no evidence. | Open |
+| 5. Keep an agent breakdown | An agent proposed items. They count in no progress until you keep them. | Keep |
+| 6. A triaged capture | A capture was triaged and waits for you to add it or dismiss it. | Open |
+| 7. Cycle review | The cycle review is due. You confirm what is in Now, or move it. | Open |
+| 8. Needs repair | A schedule left no output, a line from the PM has no attestation, or a record has no anchor. Today shows the card until it is fixed. | Open |
+
+A stalled initiative is not a card. It shows as a health reason on the initiative, in the list and in its detail.
+
+A source that cannot be read is not a card either. It shows in the notice at the top of Today, so a source that fails never looks like an empty list.
+
+## Close a gate on a run
+
+A card of kind 1 for a run has the button **Review**. The steps are:
+
+1. Press **Review** on the card. The card opens in place and shows what the evaluator said.
+2. Press **Right** or **Wrong** to say whether the evaluator was right.
+3. Optional: press **Add a note** and write one line on why.
+4. Press **Accept** to accept the run, or **Return** to send it back.
+
+That is four taps, or three taps without the note. The workspace records your act in the acceptance ledger. The note and your label are part of that record. If the workspace cannot record the act, the card stays and a message says that nothing was recorded.
+
+## The scope
+
+The switch at the top of Today has two choices.
+
+- **Repository.** The cards of the repository you chose. The number on the Today button counts these cards.
+- **All repositories.** The cards of every repository. The count at the top says how many repositories it counts across.
+
+The number on the Today button and the number at the top of the list are the same in both choices.
+
+## Short lists
+
+Today shows the first three cards. Press **Show more** to see the rest, and **Show fewer** to fold them again. The count always includes every card.
+
+## A source that cannot be read
+
+When Today cannot read a source, for example a broken needs file, it says so in a notice at the top of the list. It does not show an empty list and it does not say that nothing needs you. The notice names the source and the reason. Today still shows the cards of the sources it could read.
+
+## From a terminal
+
+`pmos today` prints the same list as Today, in the same order, with the kind first.
+
+```
+pmos today                  # the repository you are in
+pmos today --ws <id>        # one repository by its id
+pmos today --json           # the list as JSON
+pmos today --root <dir>     # read a repository folder without a server
+```
+
+With the workspace server running, the command asks the server, so it also lists the sessions that wait for you. Without the server it reads the repository files and prints a line that says it did not read the sessions. The command prints "Nothing needs you" and the next draft when the list is empty. It exits with 0 when it read the list, 1 when it could not read it, and 2 when you gave it an option it does not have.
+
+The page and the command read the route `GET /api/today?ws=<id>`. The route changes nothing.

package/workspace/guide/validate-with-typesafe.md

@@ -102,7 +102,7 @@ The workspace reads the TypeSafe key only on this machine. After you save the ke
 
 ## Set it up
 
-1. Open **validate** in the settings and tools drawer.
+1. Open Settings. Under Validate consent, press **Open Validate**. Validate opens as a tab.
 2. Under **TypeSafe key**, paste the key and press **save**. Press **remove** to delete a saved key.
 3. Under **this repository**, press **turn on**. This choice applies to the selected repository only.
 4. Enter the paths that the workspace must never send, one for each line. A path ends with `/` for a folder. A `*` matches any characters. Press **save excluded paths**.

package/workspace/lib/actor.js

@@ -0,0 +1,91 @@
+'use strict';
+/* actor.js — who a write is, read from the CALL PATH, never from a field (pm-os-absorb, PRD R23 and R25).
+ *
+ *   fromUi()              → { by: 'pm:wawan', via: 'ui' }      the page, after the route's own checks
+ *   fromCli({isTTY, env}) → { by, via: 'cli' }                 a bound agent session, else a terminal (the PM), else unknown
+ *   isPm(actor) · isAgent(actor) · sessionOf(actor)
+ *   pageName(by)          → 'agent:sess-<n>' for 'agent:sess-<n>.<8hex>', else `by` unchanged
+ *
+ * F5: a ledger line's `by` carries the session token; the page must never see it. Every GET route and every needs
+ * provider maps each `by` it answers through pageName (proposals, moves, item owners, report attributions).
+ *
+ * The placements, measurements and issues writers take their actor from here, so the four ledgers attribute one way.
+ * A caller never passes `by` or `via`: a writer that accepted them would make attribution something a caller chooses.
+ *
+ * THE SESSION-TOKEN MAP (Run 2, slice 2A). server.js gives each agent session a token, `sess-<n>.<8 hex>`, in its PTY
+ * environment as PMOS_SESSION. The token itself is never written to disk or sent to the page (D08, F5). server.js
+ * persists its SHA-256 (`tokenHash`) in the session's own meta file, so after a restart the map still answers which
+ * session a token belongs to and which initiative that session is bound to. The map is read from the files each time
+ * (no cache, D33), so a CLI with no server reads the same answer as the server.
+ *
+ *   tokenHash(token)                       → 64 hex characters, or null for a value that is not a token
+ *   sessionForToken(token, { sessDir })    → { session, initiative } | null
+ *
+ * HONEST LIMIT. A token is an attribution, not a credential: a process that unsets PMOS_SESSION is no longer an agent
+ * to fromCli. pm-guard.js requirePmCli asks such a caller to type the id of a PM-only act (X12); CI detection is the
+ * backstop for the rest.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PM_SLUG = 'wawan';
+const SESSION_RE = /^sess-\d+\.[0-9a-f]{8}$/;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+const VIA = ['ui', 'cli'];
+
+const PM = Object.freeze({ by: `pm:${PM_SLUG}`, via: 'ui' });
+
+/** The page. Call it only after the route has run its checks (pm-guard.js requirePmPress for a PM-only act). */
+function fromUi() { return { by: PM.by, via: 'ui' }; }
+
+/**
+ * A `pmos <verb>` call. 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 spawnSession), so the PM's own shell is a terminal with no token: the PM. Else unknown.
+ */
+function fromCli({ isTTY = !!(process.stdin.isTTY && process.stdout.isTTY), env = process.env } = {}) {
+  const tok = env && env.PMOS_SESSION;
+  if (typeof tok === 'string' && SESSION_RE.test(tok)) return { by: `agent:${tok}`, via: 'cli' };
+  if (isTTY) return { by: `pm:${PM_SLUG}`, via: 'cli' };
+  return { by: 'agent:unknown', via: 'cli' };
+}
+
+const valid = (a) => !!a && typeof a.by === 'string' && BY_RE.test(a.by) && VIA.includes(a.via);
+const isPm = (a) => valid(a) && a.by.startsWith('pm:');
+const isAgent = (a) => valid(a) && a.by.startsWith('agent:');
+/** The session token of an agent actor, or null. */
+const sessionOf = (a) => (isAgent(a) && a.by !== 'agent:unknown' ? a.by.slice('agent:'.length) : null);
+
+/** The name the page may show. Strips the session token's secret suffix; anything else passes through. */
+function pageName(by) {
+  if (typeof by !== 'string') return by;
+  const m = /^(agent:sess-\d+)\.[0-9a-f]{8}$/.exec(by);
+  return m ? m[1] : by;
+}
+
+/** The SHA-256 of a session token. The map stores this, never the token. */
+function tokenHash(token) {
+  if (typeof token !== 'string' || !SESSION_RE.test(token)) return null;
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * The session a token belongs to, read from the session meta files server.js persists (`<sessDir>/<id>.json`). The id
+ * part of the token names the file, and the stored hash must match: a token with the right id and a wrong suffix is not
+ * that session. Null when there is no such session or no hash on record. `plan_item` is the item Hand to agent gave the
+ * session (null for any other session).
+ */
+function sessionForToken(token, { sessDir } = {}) {
+  const h = tokenHash(token);
+  if (!h || typeof sessDir !== 'string' || !sessDir) return null;
+  const id = token.slice(0, token.indexOf('.'));
+  let meta;
+  try { meta = JSON.parse(fs.readFileSync(path.join(sessDir, id + '.json'), 'utf8')); } catch { return null; }
+  if (!meta || meta.id !== id || typeof meta.tokenHash !== 'string' || meta.tokenHash.length !== h.length) return null;
+  if (!crypto.timingSafeEqual(Buffer.from(meta.tokenHash), Buffer.from(h))) return null;
+  const str = (v) => (typeof v === 'string' && v ? v : null);
+  return { session: id, initiative: str(meta.initiative), plan_item: str(meta.plan_item) };
+}
+
+module.exports = { tokenHash, sessionForToken, PM_SLUG, SESSION_RE, BY_RE, VIA, fromUi, fromCli, valid, isPm, isAgent, sessionOf, pageName };

package/workspace/lib/board-cache.js

@@ -32,9 +32,38 @@ const REFRESH_TIMEOUT_MS = 120000;   // a derivation that cannot finish in 2 min
 const cache = new Map();             // root -> { sig, at, value, error }
 const inflight = new Map();          // root -> true
 
+// headSha runs on every signature, and the needs poll asks for a signature per registered tree several times per
+// request, so a `git rev-parse` each time held the server for seconds with twenty trees registered. The answer is
+// kept per root while the files a commit, checkout or reset touches (HEAD, its ref, packed-refs, the HEAD reflog)
+// are unchanged; anything unreadable falls back to asking git.
+const headMemo = new Map();          // root -> { key, sha }
+function gitDirOf(root) {
+  const dotgit = path.join(root, '.git');
+  const st = fs.statSync(dotgit);
+  if (st.isDirectory()) return { dir: dotgit, common: dotgit };
+  const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotgit, 'utf8'));
+  if (!m) throw new Error('no gitdir');
+  const dir = path.resolve(root, m[1].trim());
+  let common = dir;
+  try { common = path.resolve(dir, fs.readFileSync(path.join(dir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
+  return { dir, common };
+}
+function headKey(root) {
+  const { dir, common } = gitDirOf(root);
+  const head = fs.readFileSync(path.join(dir, 'HEAD'), 'utf8').trim();
+  const stat = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}:${st.ino}`; } catch { return '-'; } };
+  const ref = /^ref:\s*(.+)$/.exec(head);
+  return [head, ref ? stat(path.join(common, ref[1])) : '', stat(path.join(common, 'packed-refs')), stat(path.join(dir, 'logs', 'HEAD'))].join('|');
+}
 function headSha(root) {
+  let key = null;
+  try { key = headKey(root); } catch { key = null; }
+  const hit = headMemo.get(root);
+  if (key && hit && hit.key === key) return hit.sha;
   const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 });
-  return r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+  const sha = r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+  if (key) headMemo.set(root, { key, sha });
+  return sha;
 }
 
 // The records' own state, so an UNCOMMITTED edit still invalidates. Cheap: one readdir + one stat
@@ -42,8 +71,9 @@ function headSha(root) {
 function recordsSig(root) {
   // Both layouts (pmos-self `planning/`, a PM repository's `pmos/state/`), and the ledgers the
   // board's rows depend on: an uncommitted lifecycle or acceptance line must not wait out the TTL (D70).
+  // pm-os-absorb: plan-items.jsonl (Run 4's Build rule reads items) and issues.jsonl (Run 5's report lane reads issues).
   const dirs = [path.join(root, 'planning', 'initiatives'), path.join(root, 'pmos', 'state', 'initiatives')];
-  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl'].flatMap((f) => [
+  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl', 'plan-items.jsonl', 'issues.jsonl'].flatMap((f) => [
     path.join(root, 'planning', 'runs', f), path.join(root, 'pmos', 'state', f)]);
   let total = 0; let newest = 0; let any = false;
   for (const dir of dirs) {

package/workspace/lib/board-cli.js

@@ -0,0 +1,108 @@
+'use strict';
+/* board-cli.js — `pmos board`: the Board's items, by column, from a terminal (pm-os-absorb Run 4, slice 4D, PRD R24).
+ *
+ *   pmos board [--mine | --init <initiative>] [--json] [--root <dir>]
+ *
+ * The SAME fold the Board page reads (lib/board-fold.js, the one behind GET /api/board), so a terminal line and a card
+ * cannot disagree about an item. No server is needed: the command reads the ledgers of the repository. With no flag it
+ * prints the Active filter (an item with an event in the last stall_days, an open item under an initiative in Now, and
+ * your own items). `--mine` prints your own items. `--init <initiative>` prints one initiative. `--json` prints the same
+ * answer as GET /api/board for that filter, without the workspace id. The command only reads: it writes no line.
+ *
+ * Exit codes: 0 done, 1 refused (an initiative that is not on the Board, an unreadable repository), 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const consoleState = require('./console-state');
+const boardFold = require('./board-fold.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { board: [] };
+const USAGE = [
+  'usage: pmos board [--mine | --init <initiative>] [--json] [--root <dir>] — the items of every initiative, by column',
+  '  pmos board                      the Active filter: recent events, open items under Now, and your own items',
+  '  pmos board --mine               your own items',
+  '  pmos board --init <initiative>  one initiative',
+  '  pmos board --json               the answer of GET /api/board, for scripts',
+  'Done shows the last 14 days. A work initiative only: a document initiative has no item on the Board.',
+];
+const BOOL = new Set(['json', 'mine', 'help']);
+const VALUE = new Set(['init', 'root']);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const COLUMNS = [['todo', 'Todo'], ['doing', 'Doing'], ['review', 'Review'], ['done', 'Done']];
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  return { pos, flags: { ...flags, ...bools } };
+}
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+const shortDate = (d) => { const t = new Date(d + 'T00:00:00Z'); return `${t.getUTCDate()} ${MONTHS[t.getUTCMonth()]}`; };
+const ownerOf = (o) => (o === 'you' ? 'you' : o === 'agent' ? 'agent' : String(o).replace(/^[a-z]+:/, ''));
+
+/** One card as a line: initiative · stage · "title" · owner, then what a person must notice. */
+function line(it, titleOf) {
+  const bits = [titleOf[it.initiative] || it.initiative, it.stageLabel, `"${it.title}"`, ownerOf(it.owner)];
+  if (it.due) bits.push(`due ${shortDate(it.due)}`);
+  if (it.blocked) bits.push(`blocked: ${it.blocked.reason}`);
+  if (it.noEvidence) bits.push('no evidence');
+  if (it.late) bits.push('late');
+  if (it.overrideShown) bits.push('moved by you');
+  if (it.proposed) bits.push('proposed');
+  if (it.factory && it.factory.notMerged && it.factory.label) bits.push(it.factory.label);
+  return bits.join(' · ');
+}
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), now } = {}) {
+  const args = argv[0] === 'board' ? argv.slice(1) : argv.slice();
+  const { pos, flags } = parse(args);
+  if (flags.help) { for (const l of USAGE) say(l); return 0; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  if (pos.length) { say(`pmos board takes no argument (${pos[0]}). To show one initiative, type: pmos board --init <initiative>`); return 2; }
+  if (flags.mine && flags.init) { say('--mine and --init cannot be used together. Choose one filter.'); return 2; }
+  const json = !!flags.json;
+  const filter = flags.mine ? 'mine' : flags.init ? 'init:' + flags.init : 'active';
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  // a root that is not a PMOS repository is refused: the fold would read it as a repository with no initiatives
+  try {
+    const loaded = consoleState.loadEngine();
+    if (!loaded.ok) return fail('the workflow engine is not installed: ' + loaded.error);
+    if (!fs.statSync(root).isDirectory() || !fs.statSync(loaded.engine.layout(root).initiatives).isDirectory()) throw new Error('no initiatives directory');
+  } catch (e) { return fail(`${root} is not a PMOS repository (no initiatives directory)`); }
+  let out;
+  try { out = boardFold.boardFor({ id: 'cli', root }, { filter, now }); }
+  catch (e) { return fail('the Board could not be read: ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!out.ok) return fail(out.error, out.status === 400 ? 2 : 1);
+  if (json) { say(JSON.stringify(out)); return 0; }
+  const titleOf = Object.fromEntries(out.initiatives.map((i) => [i.id, i.title]));
+  const label = out.filter === 'active' ? 'Active' : out.filter === 'mine' ? 'Mine' : out.filter.slice(5);
+  const n = COLUMNS.reduce((s, [k]) => s + out.board[k].length, 0);
+  say(`Board · ${label} · ${n === 1 ? '1 item' : n + ' items'}`);
+  for (const [k, name] of COLUMNS) {
+    const ids = out.board[k];
+    say(`${name} · ${ids.length}${k === 'done' && out.board.doneOlder ? ` · ${out.board.doneOlder} older in the Tree` : ''}`);
+    for (const id of ids) say('  ' + line(out.items[id], titleOf));
+  }
+  const rel = out.releases || [];
+  if (rel.length) {
+    say(`Release · ${rel.length}`);
+    for (const r of rel) say(`  ${r.initiativeTitle} · batch ${r.batch} · ${r.items.length === 1 ? '1 work item' : r.items.length + ' work items'} ready`);
+  }
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/board-fold.js

@@ -0,0 +1,232 @@
+'use strict';
+/* board-fold.js — the Board's ONE fold: every work item of every work-lane initiative, in its column (pm-os-absorb Run 4,
+ * slice 4D; PRD R9, R19, R12 kind 4; D86 points 1 and 4).
+ *
+ *   boardFor(w, { filter, now }) → { ok: true, filter, now, sig, initiatives, items, board, counts }
+ *                                | { ok: false, status, error }
+ *   parseFilter(text)            → { kind: 'active' | 'mine' | 'init', init? } | null
+ *   workInitiatives(root)        → [{ id, title, lane, laneLabel }]   the work lanes only (D86 point 4)
+ *   factoryView(entry, item)     → { item, state, pr, integrated, notMerged, label } | null
+ *
+ * THREE READERS, ONE ANSWER. GET /api/board (lib/routes-board.js), `pmos board` (lib/board-cli.js) and the Today rows of
+ * lib/work-check-needs.js all read through this file, so a card, a terminal line and a Today card cannot disagree about
+ * an item. The fold is lib/plan-items.js's: a card's column is its tree row's state, because both read the same fold and
+ * lib/plan-tree.js layout() builds each initiative's columns (R19, the same 14-day Done window).
+ *
+ * FILTERS (R9). `active` is the default: an item with an event in the last stall_days (planning/plan-rules.json), an open
+ * item under an initiative that is in Now, and the PM's own items (owner `you`). `mine` is the PM's own items. `init:<id>`
+ * is one initiative. Done shows the last 14 days under Active and under an initiative, however old the item's last event is
+ * (the layout's own window, lib/plan-tree.js DONE_WINDOW_MS); older Done items are counted, never listed. Under Mine, Done
+ * shows the PM's own items by the same window.
+ *
+ * WORK LANES ONLY. A document lane (scripts/lane-defs.js group 'document': prd, strategy, project-plan, decision-record,
+ * report) is a file, not a row: its initiative has no card, no option in the filter and no needs row. The group is read
+ * from the lane definitions, never from a list kept here.
+ *
+ * FACTORY. A work item that the factory materialized from a plan item carries `factory` (lib/factory-join.js): its state,
+ * its pull request, whether `pmos verify-work` saw it integrated. A card dragged to Done before that reads "Done · your
+ * call · not merged" (R7). Nothing here writes a factory record; the factory graph never writes the control graph.
+ *
+ * THE PAGE NEVER SEES A SESSION TOKEN (F5). Every `by` in the answer goes through actor.pageName, and so does every
+ * batch name. The signature is taken BEFORE the ledgers are read (the F2 fix): a line appended during the read leaves a
+ * signature older than the data at worst, which costs one more read and never hides a change.
+ */
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+const consoleState = require('./console-state');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const placements = require('./placements.js');
+const ledgers = require('./plan-ledgers.js');
+const factoryJoin = require('./factory-join.js');
+const planRules = require('./plan-rules.js');
+const actor = require('./actor.js');
+
+const DAY = 86400000;
+const HORIZON_RANK = { now: 0, next: 1, later: 2 };
+const STATES = ['todo', 'doing', 'review', 'done'];
+const NOT_MERGED = planTree.NOT_MERGED_LABEL || 'Done · your call · not merged';
+const TOKEN_TEXT_RE = /\b(sess-\d+)\.[0-9a-f]{8}\b/g;
+const scrub = (t) => (typeof t === 'string' ? t.replace(TOKEN_TEXT_RE, '$1') : t);
+
+function parseFilter(text) {
+  const f = text == null || text === '' ? 'active' : String(text);
+  if (f === 'active' || f === 'mine') return { kind: f };
+  const m = /^init:(.+)$/.exec(f);
+  if (m && planItems.INIT_RE.test(m[1])) return { kind: 'init', init: m[1] };
+  return null;
+}
+const canonical = (f) => (f.kind === 'init' ? 'init:' + f.init : f.kind);
+
+/** The initiatives of `root` whose lane is a work lane, with the title their record gives. */
+function workInitiatives(root) {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  const eng = loaded.engine;
+  const out = [];
+  for (const id of eng.listInitiatives(root)) {
+    let pl;
+    try { pl = planTree.profileAndLane(root, id); } catch { continue; }
+    const def = pl.defs && pl.defs[pl.lane];
+    if (!def || def.group !== 'work') continue;
+    let title = id;
+    if (pl.record) {
+      try { title = String((eng.parseLeadingFrontmatter(fs.readFileSync(pl.record, 'utf8')) || {}).title || '').trim() || id; } catch { title = id; }
+    }
+    out.push({ id, title, lane: pl.lane, laneLabel: def.label || pl.lane });
+  }
+  return out;
+}
+
+/** One initiative's batches as the page names them: a repeated actor reads `agent:sess-3#2` (as the Breakdown names them). */
+function pageBatches(batches) {
+  const seen = new Map();
+  return (batches || []).map((b) => {
+    const shown = actor.pageName(b.by);
+    const n = (seen.get(shown) || 0) + 1;
+    seen.set(shown, n);
+    const name = n === 1 ? shown : `${shown}#${n}`;
+    return { ...b, key: name, by: name };
+  });
+}
+
+/** An item as the page is sent it: no session token in any actor or text. */
+function pageItem(it, extra) {
+  return {
+    ...it, ...extra,
+    createdBy: actor.pageName(it.createdBy), updatedBy: actor.pageName(it.updatedBy), movedBy: actor.pageName(it.movedBy),
+    note: scrub(it.note),
+    blocked: it.blocked ? { ...it.blocked, by: actor.pageName(it.blocked.by), reason: scrub(it.blocked.reason) } : it.blocked,
+    history: (it.history || []).map((h) => ({ ...h, by: actor.pageName(h.by), text: scrub(h.text) })),
+  };
+}
+
+/** The factory's view of one plan item: { item, state, pr, integrated, notMerged, label } or null. */
+function factoryView(entry, it) {
+  if (it.factory && typeof it.factory === 'object') return it.factory;   // lib/plan-tree.js already joined it
+  const w = entry && (entry.items || []).find((x) => x && x.plan_item === it.id);
+  if (!w) return null;
+  const notMerged = it.state === 'done' && w.integrated !== true;
+  return { item: w.id, state: w.state, pr: w.pr || null, integrated: w.integrated === true, notMerged, label: notMerged ? NOT_MERGED : null };
+}
+
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const statOf = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}`; } catch { return 'none'; } };
+
+/** The grants a release press made, by target `<initiative>:<batch>`: read only, and only the lines that still hold. A grant
+ *  holds while it is unexpired, or once it is used (the factory spent it). Expired and unused, it is gone: the PM may press again. */
+function releaseGrants(root, now = Date.now()) {
+  const out = new Map();
+  let text = '';
+  try { text = fs.readFileSync(path.join(ledgers.runsDir(root), 'grants.jsonl'), 'utf8'); } catch { return out; }
+  const rows = [];
+  for (const raw of text.split('\n')) { if (!raw.trim()) continue; try { rows.push(JSON.parse(raw)); } catch { /* a torn line is the writer's to name */ } }
+  const used = new Set(rows.filter((r) => r && r.type === 'use' && typeof r.grant_id === 'string').map((r) => r.grant_id));
+  for (const r of rows) {
+    if (!r || r.type !== 'grant' || r.scope !== 'release' || typeof r.target !== 'string') continue;
+    if (used.has(r.id) || !(Date.parse(r.expires_at) <= now)) out.set(r.target, { grant_id: r.id });
+  }
+  return out;
+}
+
+/** What the page's views read besides the two plan ledgers and the factory join: the initiative records (title, lane), the
+ *  rules file (stall_days) and the grants ledger (a pressed Release card goes). One stat each, so a write by the CLI shows. */
+function sideSig(root) {
+  const parts = [];
+  try {
+    const eng = consoleState.loadEngine();
+    if (eng.ok) for (const id of eng.engine.listInitiatives(root)) { const pl = planTree.profileAndLane(root, id); parts.push(id + '=' + (pl.record ? statOf(pl.record) : 'none') + ':' + pl.lane); }
+  } catch { parts.push('initiatives:unreadable'); }
+  try { const rp = planRules.rulesPath(root); parts.push('rules=' + (rp ? statOf(rp) : 'none')); } catch { parts.push('rules:unreadable'); }
+  try { parts.push('grants=' + statOf(path.join(ledgers.runsDir(root), 'grants.jsonl'))); } catch { parts.push('grants:unreadable'); }
+  return sha1(parts.join('|'));
+}
+
+/** The signature alone, for the page's watcher: the same hash boardFor puts in `sig`, taken without reading the items. */
+function sigFor(w) {
+  const root = w.root;
+  let itemsSig; let placeSig;
+  try { itemsSig = planItems.ledgerSigs([{ id: w.id, root }], '')[w.id].items; } catch { itemsSig = 'unreadable'; }
+  try { placeSig = ledgers.ledgerSig(root, 'placements'); } catch { placeSig = 'unreadable'; }
+  const join = factoryJoin.joinFactory(root);
+  return sha1([itemsSig, placeSig, JSON.stringify(join.byInit || {}), String((join.flags || []).length), sideSig(root)].join('|'));
+}
+
+function boardFor(w, { filter, now = Date.now() } = {}) {
+  const f = parseFilter(filter);
+  if (!f) return { ok: false, status: 400, error: 'the filter is active, mine or init:<initiative>' };
+  const root = w.root;
+  // the signature first (F2): the ledgers it names are read below
+  let itemsSig; let placeSig;
+  try { itemsSig = planItems.ledgerSigs([{ id: w.id, root }], '')[w.id].items; } catch { itemsSig = 'unreadable'; }
+  try { placeSig = ledgers.ledgerSig(root, 'placements'); } catch { placeSig = 'unreadable'; }
+
+  const sideSigAt = sideSig(root);
+  const inits = workInitiatives(root);
+  if (f.kind === 'init' && !inits.some((i) => i.id === f.init)) {
+    return { ok: false, status: 404, error: `no initiative ${f.init} on the Board` };
+  }
+  const rules = planRules.readRules(root);
+  const place = placements.readPlacements(root, { now, rules, records: inits.map((i) => ({ id: i.id, lane: i.lane })) });
+  const join = factoryJoin.joinFactory(root);
+  const fold = planItems.readFold(root, { now });
+  const stallMs = rules.stall_days * DAY;
+
+  const rows = inits.map((i) => {
+    const p = place.byInit && place.byInit[i.id];
+    return { ...i, horizon: placements.horizonOf(place, i.id), rank: p && Number.isFinite(p.rank) ? p.rank : 0 };
+  }).sort((a, b) => (HORIZON_RANK[a.horizon] - HORIZON_RANK[b.horizon]) || (a.rank - b.rank) || a.id.localeCompare(b.id));
+
+  const wanted = (it, row) => {
+    if (f.kind === 'init') return it.initiative === f.init;
+    if (it.owner === 'you') return true;
+    if (f.kind === 'mine') return false;
+    if (it.state === 'done') return true;   // plan-tree's 14-day window lists the recent ones; the rest are counted
+    if (row.horizon === 'now') return true;
+    return Date.parse(it.updatedAt) >= now - stallMs;
+  };
+
+  const items = {};
+  const board = { todo: [], doing: [], review: [], done: [], doneOlder: 0 };
+  const initiatives = [];
+  for (const row of rows) {
+    const lay = planTree.layout({ root, initiative: row.id, fold, ladder: null, now });
+    const entry = factoryJoin.factoryOf(join, row.id);
+    const keep = new Set(Object.keys(lay.items).filter((id) => wanted(lay.items[id], row)));
+    let listed = 0;
+    for (const st of STATES) for (const id of lay.board[st]) {
+      if (!keep.has(id)) continue;
+      listed++;
+      items[id] = pageItem(lay.items[id], { stageLabel: (lay.stages.find((s) => s.id === lay.items[id].stage) || {}).label || lay.items[id].stage, factory: factoryView(entry, lay.items[id]) });
+      board[st].push(id);
+    }
+    const doneAll = [...keep].filter((id) => lay.items[id].state === 'done').length;
+    board.doneOlder += doneAll - lay.board.done.filter((id) => keep.has(id)).length;
+    initiatives.push({
+      id: row.id, title: row.title, lane: row.lane, laneLabel: row.laneLabel, horizon: row.horizon, rank: row.rank,
+      stages: lay.stages.map((s) => ({ id: s.id, label: s.label })), batches: pageBatches(lay.batches), shown: listed,
+    });
+  }
+  const counts = { todo: board.todo.length, doing: board.doing.length, review: board.review.length, done: board.done.length, doneOlder: board.doneOlder };
+  const sig = sha1([itemsSig, placeSig, JSON.stringify(join.byInit || {}), String((join.flags || []).length), sideSigAt].join('|'));
+  const granted = releaseGrants(root, now);
+  // the ready batches a person can release: one card each (D86 point 2). Shown under every filter, for a work initiative.
+  const releases = [];
+  for (const row of rows) {
+    if (f.kind === 'init' && row.id !== f.init) continue;
+    const entry = factoryJoin.factoryOf(join, row.id);
+    for (const b of (entry && entry.batches) || []) {
+      if (!b || !b.ready || granted.has(`${row.id}:${b.id}`)) continue;
+      const ws = (b.items || []).map((wid) => {
+        const wi = (entry.items || []).find((x) => x && x.id === wid) || {};
+        const pi = wi.plan_item && items[wi.plan_item];
+        return { id: wid, plan_item: wi.plan_item || null, title: pi ? pi.title : wid, state: wi.state || null, pr: wi.pr || null, integrated: wi.integrated === true };
+      });
+      releases.push({ initiative: row.id, initiativeTitle: row.title, batch: b.id, items: ws });
+    }
+  }
+  return { ok: true, filter: canonical(f), now: new Date(now).toISOString(), sig, initiatives, items, board, counts, releases };
+}
+
+module.exports = { boardFor, sigFor, sideSig, releaseGrants, parseFilter, workInitiatives, factoryView, STATES, NOT_MERGED };