create-pmos 0.22.0 → 0.24.0

package/workspace/lib/engine/workflow-state.js

@@ -45,6 +45,15 @@ const { execFileSync } = require('child_process');
  * and the OKR surface previously held separate, incompatible opinions about the same field.
  */
 const anchors = require('./anchor-resolve');
+/*
+ * ONE reader for delivery too (workflow-status-sweep R-1). `buildCommits` used to answer "is there a
+ * build commit in this range" — a question about a RANGE — while both of its callers asked a
+ * question about an INITIATIVE. Over a pull-request range those coincide, because the range IS one
+ * initiative's work; over the trunk they do not, and every initiative read `done` with the same 488
+ * commits of evidence. The attribution signal already existed, module-private, inside the workspace
+ * server. It is shared now, for the same reason `anchor-resolve` is.
+ */
+const delivery = require('./delivery-index');
 
 // The OKR documents and the budget registry are read once per root, not once per initiative: the
 // board derives ~100 ladders in a single pass and re-reading the same three files each time is the
@@ -114,14 +123,34 @@ function parseLeadingFrontmatter(text) {
 function readFrontmatter(file) {
   try { return parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')); } catch { return null; }
 }
-function readJsonl(file) {
+/*
+ * The ledger reader, and the one place a torn line is REPORTED rather than merely dropped (R-4).
+ *
+ * A line that does not parse is still never guessed at — that part was always right. What was wrong
+ * was the silence: a truncated acceptance row did not make the ladder say "a row here is
+ * unreadable", it made the ladder say the initiative was never accepted. The file's own honesty rule
+ * ("a gate that cannot see its inputs reports that it cannot see them") held for git ranges and not
+ * for ledger lines.
+ *
+ * The channel is out-of-band — an optional `defects` array the caller passes in — rather than a
+ * changed return type, because every existing call site wants the rows and only the sweep wants the
+ * damage. Changing the shape would have made ~six callers handle a case none of them can act on.
+ */
+function readJsonl(file, defects) {
   let text;
   try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
   const out = [];
-  for (const line of text.split('\n')) {
-    const t = line.trim();
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
     if (!t) continue;
-    try { out.push(JSON.parse(t)); } catch { /* torn line — dropped, never guessed */ }
+    try { out.push(JSON.parse(t)); }
+    catch (e) {
+      // Dropped, never guessed — and now said out loud to anyone who asked to hear it.
+      if (Array.isArray(defects)) {
+        defects.push({ file, line: i + 1, reason: String((e && e.message) || 'not valid JSON').slice(0, 120), text: t.slice(0, 120) });
+      }
+    }
   }
   return out;
 }
@@ -211,21 +240,27 @@ function buildRange(root, { spec, whole }) {
     }
     range = base ? `${base}..HEAD` : 'HEAD';
   }
-  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct', '--name-only', range]);
+  // %x1e separates commits; %x1f separates the header from the message and the message from
+  // --name-only's file list. The MESSAGE is captured in this same pass because attribution over the
+  // trunk needs it (R-2) — a second `git log` per initiative is exactly the O(commits × initiatives)
+  // cost this single-pass rewrite existed to remove.
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct%x1f%s %b%x1f', '--name-only', range]);
   if (log == null) return { ok: false, reason: 'git history unreadable' };
 
   const shas = [];
   const changed = [];                 // index -> string[] of paths touched
   const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  const subjects = [];                // index -> subject + body, one line, for attribution
   for (const chunk of log.split('\x1e')) {
     if (!chunk.trim()) continue;
-    const lines = chunk.split('\n');
-    const head = (lines.shift() || '').trim();
+    const parts = chunk.split('\x1f');
+    const head = (parts[0] || '').trim();
     const [sha, ct] = head.split(/\s+/);
     if (!sha) continue;
     shas.push(sha);
     dates.push(Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null);
-    changed.push(lines.map((s) => s.trim()).filter(Boolean));
+    subjects.push(String(parts[1] || '').replace(/\s+/g, ' ').trim());
+    changed.push(String(parts[2] || '').split('\n').map((s) => s.trim()).filter(Boolean));
   }
   const index = new Map();
   shas.forEach((sha, i) => index.set(sha, i));
@@ -245,7 +280,7 @@ function buildRange(root, { spec, whole }) {
       }
     }
   }
-  return { ok: true, base, index, shas, changed, dates, added, wholeHistory: whole ? true : !base };
+  return { ok: true, base, index, shas, changed, dates, subjects, added, wholeHistory: whole ? true : !base };
 }
 
 /*
@@ -273,11 +308,58 @@ function firstAppearance(root, range, rel) {
   return range.index.has(sha) ? range.index.get(sha) : -1;
 }
 
-// The earliest position in the range at which this initiative's implementation was touched, plus a
-// count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
-// reported as n/a rather than as a pass it did not earn.
-function buildCommits(root, range, lane) {
+/*
+ * The earliest position in the range at which this initiative's implementation was touched, plus a
+ * count. A docs-only PR has no build commits, which makes every "before the build" rule vacuous —
+ * reported as n/a rather than as a pass it did not earn.
+ *
+ * ATTRIBUTION (R-2). This function used to take no id, so it answered a question about the RANGE
+ * while both of its callers asked one about an INITIATIVE. Which of those is right depends entirely
+ * on what the range is, and the two cases are answered differently on purpose:
+ *
+ *   · A PULL-REQUEST RANGE (`base..HEAD`) — the range IS this initiative's work, by the branch
+ *     convention the Initiative Gate already enforces. Any build commit in it is therefore this
+ *     initiative's build commit, and the O1/O2 order rules depend on exactly that reading. This path
+ *     is UNCHANGED, deliberately: the gate's verdicts must not move for a reporting fix.
+ *
+ *   · THE WHOLE TRUNK (`range.wholeHistory`) — the range is everyone's work. Attribution comes from
+ *     `delivery-index`: a merged `initiative/<id>` branch, or a commit that names the id and touches
+ *     a build path. Without it every initiative reported `done` with the identical count, which is
+ *     the tell that a per-initiative fact was being read from a repository-wide one.
+ *
+ * `signal` travels back with the answer so the rung can say WHICH evidence decided it. A bare count
+ * is what let 488 stand as an explanation for 177 different initiatives.
+ */
+function buildCommits(root, range, lane, opts) {
   if (!range.ok) return { unknown: true };
+  const id = opts && opts.id;
+  const whole = !!range.wholeHistory;
+
+  // Over the trunk, the id must be attributable before any commit counts. The index is built once
+  // per trunk head by the shared reader and passed in by the board; a caller that did not supply one
+  // gets it built here (single-ladder invocations, where one extra `git log` is the whole cost).
+  let signal = null;
+  let declared = null;
+  if (whole && id) {
+    // The PM's declaration is consulted FIRST, and its failure is reported before anything else
+    // (R-2b). A `delivered_by` that does not check out must not be able to hide behind a convention
+    // signal that happens to succeed: a broken declaration is a defect in the record either way, and
+    // silently ignoring it would leave a false pointer sitting in the file forever.
+    declared = delivery.declaredDelivery(root, opts && opts.declaredDelivery);
+    if (declared && declared.declared && !declared.ok) {
+      return { unknown: false, failedDeclaration: declared, first: null, count: 0, sample: null, signal: null, attributed: true };
+    }
+    const index = (opts && opts.deliveryIndex) || delivery.deliveryIndex(root, listInitiatives(root));
+    signal = delivery.attribution(index, id);
+    if (declared && declared.ok) {
+      // A verified declaration attributes the work regardless of what the conventions found. It is
+      // the PM naming the commit, checked against git — strictly better evidence than a heuristic.
+      return { first: null, count: 0, sample: null, signal: 'declared', declaredSha: declared.sha, attributed: true, mergedOnly: true };
+    }
+    if (signal === 'unknown') return { unknown: true, reason: delivery.attributionEvidence('unknown', id) };
+    if (!signal) return { first: null, count: 0, sample: null, signal: null, attributed: true };
+  }
+
   let first = null; let count = 0; let sample = null;
   for (let i = 0; i < range.shas.length; i++) {
     // range.changed came from the range's own single pass; the per-commit `git show` this replaced
@@ -285,10 +367,29 @@ function buildCommits(root, range, lane) {
     const files = (range.changed && range.changed[i]) || [];
     const hit = files.find((f) => isBuildPath(f, lane));
     if (!hit) continue;
+    // Over the trunk, only commits that carry the id themselves are this initiative's. The branch
+    // signal is a MERGE subject, so the merge commit is the one that names it — which makes the
+    // merge position the honest "when did this land", and keeps a squashed or rebased history
+    // answerable at all. `--name-only` lists no files for a true merge commit, so a branch-attributed
+    // initiative is counted from its merge subject below rather than from this per-file loop.
+    if (whole && id && !commitNamesId(range, i, id)) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
   }
-  return { first, count, sample };
+  if (whole && id && signal === 'branch' && first === null) {
+    // The branch merged and every commit it carried was written on the branch, so no trunk commit
+    // subject names the id. The merge itself is the evidence, and saying "0 commits" over a merged
+    // branch would be the under-claim in a new place.
+    return { first: null, count: 0, sample: null, signal, attributed: true, mergedOnly: true };
+  }
+  return { first, count, sample, signal, attributed: whole && !!id };
+}
+
+// Whether the commit at `i` names this initiative in its own subject or body. The subjects come from
+// the range's own single pass, so this costs nothing per initiative.
+function commitNamesId(range, i, id) {
+  const msg = (range.subjects && range.subjects[i]) || '';
+  return msg.includes(id);
 }
 
 // ── Declaration readers ────────────────────────────────────────────────────────────────────────
@@ -471,7 +572,11 @@ function computeWorkflow(id, opts) {
   const prd = String(fm.prd_path || '').trim();
   const rubric = String(fm.rubric_path || '').trim();
   const prdIdx = prd ? firstAppearance(root, range, prd) : null;
-  const build = buildCommits(root, range, effLane);
+  const build = buildCommits(root, range, effLane, {
+    id,
+    deliveryIndex: opts && opts.deliveryIndex,
+    declaredDelivery: fm.delivered_by,
+  });
 
   // Shared helper: "A must not come after B", stated as positions, never as clock time.
   function ordered(aIdx, bIdx) {
@@ -716,11 +821,37 @@ function computeWorkflow(id, opts) {
   }
 
   // ── build ────────────────────────────────────────────────────────────────────────────────────
+  /*
+   * The evidence names WHICH signal decided, never a bare count (R-2). `488 commit(s) on
+   * implementation paths` was true of the repository and said nothing about the initiative it was
+   * printed under — the identical number on every row was the tell.
+   *
+   * The three pending sentences below are deliberately different from each other. "No commit on the
+   * trunk is attributable to this initiative" is a statement about the INITIATIVE; "no implementation
+   * commits in this range" is a statement about the RANGE, and on a branch level with `main` that
+   * range is legitimately empty. A reader who cannot tell those apart calls the second one "never
+   * built", which is the console's half of this defect.
+   */
   steps.push(build.unknown
-    ? step('build', 'build', 'unknown', range.reason)
-    : build.first === null
-      ? step('build', 'build', 'pending', 'no implementation commits in this range')
-      : step('build', 'build', 'done', `${build.count} commit(s) on implementation paths`));
+    ? step('build', 'build', 'unknown', build.reason || range.reason)
+    : build.failedDeclaration
+      // REPORTED, never CI-blocking — the same stance R1 takes on an unresolvable anchor. Making a
+      // record's own broken pointer fail every unrelated PR would turn one typo into a repo-wide
+      // outage; the RED belongs in the surface. `blocked` still closes the accept step below, which
+      // is where a false delivery claim actually needs to stop something.
+      ? step('build', 'build', 'blocked', build.failedDeclaration.reason,
+        `point delivered_by at a commit that is reachable from the trunk and changes a build path in ${recRel}, or remove the key — a declaration that fails its own check reads as evidence`,
+        { blocking: false, rule: 'R-2b' })
+      : build.mergedOnly
+        ? step('build', 'build', 'done',
+          delivery.attributionEvidence(build.signal || 'branch', id, build.declaredSha))
+        : build.first === null
+          ? step('build', 'build', 'pending', build.attributed
+            ? delivery.attributionEvidence(null, id)
+            : 'no implementation commits in this range')
+          : step('build', 'build', 'done', build.signal
+            ? `${build.count} commit(s) on implementation paths — ${delivery.attributionEvidence(build.signal, id, build.declaredSha)}`
+            : `${build.count} commit(s) on implementation paths`));
 
   // ── quality ─ CI's verdict, never this engine's ──────────────────────────────────────────────
   steps.push(step('quality', 'quality', 'unknown', 'CI decides on the PR — this engine never claims a test result it did not run'));
@@ -976,7 +1107,13 @@ function main(argv) {
   // it is the one thing the trunk range genuinely cannot answer.
   const range = historyRange(root);
   const changeRange = commitRange(root);
-  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range, changeRange }));
+  const ids = listInitiatives(root);
+  // ONE delivery index for the whole board. Built here rather than inside each ladder for the same
+  // reason the commit range is: `deliveryIndex` memoises per trunk head, so a per-initiative build
+  // would be cheap but the intent — one read, shared — is what keeps the rows consistent with each
+  // other even if the trunk moved mid-run.
+  const deliveryIdx = delivery.deliveryIndex(root, ids);
+  const rows = ids.map((i) => computeWorkflow(i, { root, range, changeRange, deliveryIndex: deliveryIdx }));
   if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
   if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
   process.stdout.write(renderBoard(rows, { self, all }));
@@ -992,4 +1129,11 @@ module.exports = {
   ENFORCED_FROM,
 };
 
-if (require.main === module) process.exit(main(process.argv));
+/*
+ * `exitCode`, not `process.exit()`. `process.exit` tears the process down without waiting for stdout
+ * to drain, and when stdout is a PIPE — every CI invocation, every `| jq`, every test harness —
+ * writes larger than the pipe buffer are asynchronous. `--json` on this repository is ~65 KB, so it
+ * arrived TRUNCATED MID-STRING and parsed as invalid JSON, while an interactive run to a TTY looked
+ * perfect. Setting the code and letting the process end naturally flushes first.
+ */
+if (require.main === module) process.exitCode = main(process.argv);

package/workspace/lib/session-state.js

@@ -66,8 +66,62 @@
 
   // Filled = corroborated by both sources, hollow = suspected from one. `needs` takes ◆, which has
   // sat declared-but-dead in the client's GLYPH map since the harness tower; this makes it live.
+  //
+  // THE SHAPES CARRY THE SIGNAL, AND COLOUR ONLY REINFORCES IT. Every pair in this map is
+  // distinguishable in greyscale, which is the property `fixture.js`'s SDOT does not have (it gives
+  // `working` and `needs` the same ● and separates them by hue alone). That map is the design
+  // prototype's seed data, parity-locked to prototype-original.html; this one is the shipped
+  // vocabulary. When a surface has to draw a session, it draws from here.
   const GLYPH = { working: '●', quiet: '◼', exited: '○', needs: '◆', blocked: '◇' };
 
+  // The colour that goes with the glyph, as a SEMANTIC TOKEN NAME — never a hex, never an oklch.
+  // The workspace's own token layer (pm/tokens.css, D38) resolves it, and workspace-ci's
+  // token-hygiene step fails on raw hex in a component rule.
+  //
+  // It lives HERE, beside WORD and GLYPH, for the reason the module's header gives: a second copy of
+  // one table is free to drift. The initiative board needed a colour per presented state and there
+  // was none anywhere in the repo — adding one inside the panel would have started exactly the
+  // second table this file exists to prevent.
+  //
+  // `blocked` takes --warning and not --destructive on purpose. Its own WORD names its uncertainty
+  // ("maybe blocked") because its evidence cannot separate a permission prompt from a hung tool from
+  // a corpse; a destructive colour would launder that into a confident claim of failure.
+  // `quiet` is muted: nothing is happening and nothing is wrong, and any louder colour would make an
+  // idle session read as a problem on a board of 178 rows.
+  const COLOR = {
+    working: 'var(--success)',
+    quiet: 'var(--muted-foreground)',
+    exited: 'var(--muted-foreground)',
+    needs: 'var(--brand)',
+    blocked: 'var(--warning)',
+  };
+
+  /**
+   * How loudly a presented state asks for the PM, highest first. Used where several sessions have to
+   * collapse into ONE mark — a board row standing for every session on an initiative.
+   *
+   * `blocked` outranks `working` deliberately. A working session is doing what it was asked to; a
+   * "maybe blocked" one may be sitting on a permission prompt, which is the PM's to clear. Ranking
+   * it below the running states would bury the only two states that can want a human.
+   *
+   * `exited` is 0: a corpse is not a claim on anyone's attention. A caller filtering live sessions
+   * drops it before it gets here; the entry exists so the map is total over PRESENTED.
+   */
+  const ATTENTION = { needs: 4, blocked: 3, working: 2, quiet: 1, exited: 0 };
+
+  /**
+   * The presented state that should stand for a whole GROUP of sessions — the loudest one.
+   * Returns null for an empty list, so a caller cannot draw a mark for nothing.
+   */
+  function loudest(states) {
+    let best = null;
+    for (const s of states || []) {
+      if (!(s in ATTENTION)) continue;          // an unknown word is never promoted into a claim
+      if (best === null || ATTENTION[s] > ATTENTION[best]) best = s;
+    }
+    return best;
+  }
+
   // Which presented states may carry the open call's verb + age. Unchanged for `working` (shipped
   // behaviour); extended to `blocked`, where the age is the most informative part of a weak claim —
   // "a call has been open 6m and nothing is moving" is the whole signal.
@@ -134,6 +188,6 @@
     return w;
   }
 
-  return { CADENCE, TURN, PRESENTED, WORD, GLYPH, CARRIES_CALL_AGE,
-    presented, presentedStates, isNeedsClaim, label };
+  return { CADENCE, TURN, PRESENTED, WORD, GLYPH, COLOR, ATTENTION, CARRIES_CALL_AGE,
+    presented, presentedStates, isNeedsClaim, loudest, label };
 });

package/workspace/lib/working-set.js

@@ -0,0 +1,224 @@
+'use strict';
+// working-set — which initiatives is the PM actually working on, and which of those are live.
+//
+// Two questions the initiative board could not answer, asked by the PM about their own board of 178
+// records: *which of these am I currently working on*, and *which one has an active session*. Both
+// were computable from state the browser already held, and nothing put them together.
+//
+// ── THE JOIN, AND WHY IT IS ONLY EVER TWO HOPS ───────────────────────────────────────────────
+// A session carries NO initiative id. It never has. The only thing tying a PTY to an initiative is
+// the branch convention — a working tree on `initiative/<id>` — and that is exactly the join
+// lib/four-panel.js `sessionsFor()` already makes on the server, per initiative, inside
+// /api/initiative:
+//
+//     session ──s.ws──▶ workspace ──w.branch──▶ "initiative/<id>" ──▶ the initiative
+//
+// This module is that same join, made once over ALL sessions instead of once per initiative, so the
+// board can colour 178 rows without 178 requests. It is deliberately NOT a second opinion: it takes
+// the branch strings the server derived (`git rev-parse --abbrev-ref`, published on /api/workspaces)
+// and the session rows the server published, and it runs no git and guesses at nothing.
+//
+// ── WHAT IT REFUSES TO DO ────────────────────────────────────────────────────────────────────
+// Every input that does not resolve contributes NOTHING. A session whose workspace is unknown, a
+// workspace with no branch, a branch that is not `initiative/…`, a branch that is the literal
+// `initiative/` with no id — each is dropped in silence rather than bucketed somewhere plausible.
+// A marker on the wrong initiative is worse than no marker: the PM would stop trusting the column,
+// and an untrusted signal costs more than an absent one.
+//
+// `exited` is not live. A session that has ended is a corpse, not a claim on anyone's attention, and
+// it is filtered before the loudest-state fold rather than ranked at the bottom of it.
+//
+// ── THREE SIGNALS, KEPT APART ────────────────────────────────────────────────────────────────
+// "Working on" is not one fact. It is three, with different strengths and different lifetimes:
+//
+//   session  a live PTY is on initiative/<id>            — strongest; ends when the process does
+//   tree     a registered working tree is on that branch — nothing is running in it
+//   open     this window has a tab open on it            — intent, not machine state; persisted
+//
+// They are ranked, never merged. `reason` survives all the way to the row's tooltip so the surface
+// can say which one it is: a single undifferentiated "active" badge would assert something none of
+// the three supports on its own.
+//
+// Pure functions over plain rows, like lib/tree-share.js and for the same reason — the rules are the
+// part worth walking exhaustively in node, without a browser and without a server.
+//
+// ── ONE module, TWO consumers ────────────────────────────────────────────────────────────────
+// A UMD, so the SERVER can hold the same rules the BROWSER draws from. Today the drawing consumer is
+// pm/panel-initiatives.js; test.js is the other, and it walks the whole input domain.
+(function (root, factory) {
+  const api = factory(
+    typeof require === 'function' && typeof module !== 'undefined' && module.exports
+      ? require('./session-state')
+      : (root && root.PMOSSessionState),
+  );
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSWorkingSet = api;
+})(typeof self !== 'undefined' ? self : this, function (SS) {
+
+  const PREFIX = 'initiative/';
+
+  /** The three reasons an initiative is in the working set, loudest first. */
+  const REASONS = ['session', 'tree', 'open'];
+  const REASON_RANK = { session: 2, tree: 1, open: 0 };
+
+  /**
+   * The initiative id a branch name names, or null.
+   *
+   * Strict on purpose. `initiative/` with nothing after it is not an initiative, and neither is
+   * `feature/initiative/x` — the convention is a PREFIX, and matching it loosely is how a marker
+   * lands on a row that has nothing to do with the session.
+   */
+  function initiativeOfBranch(branch) {
+    const b = typeof branch === 'string' ? branch : '';
+    if (!b.startsWith(PREFIX)) return null;
+    const id = b.slice(PREFIX.length);
+    return id ? id : null;
+  }
+
+  /** Is this session row one the board should draw? A corpse is not. */
+  function isLive(s) {
+    return !!s && s.shown !== 'exited';
+  }
+
+  /**
+   * Every LIVE session, grouped by the initiative its working tree is on.
+   *
+   *   sessions   the rows /api/sessions publishes (id, ws, name, shown, label, …)
+   *   branchOf   ws id → branch string, or null. The caller supplies it because the browser holds
+   *              it as a Map built by foldWorkspaces and the server holds it as a workspace list;
+   *              taking a function rather than either shape keeps this module ignorant of both.
+   *
+   * Returns `{ <id>: [session, …] }` — insertion-ordered, never containing an empty array, and
+   * never containing an initiative the join could not actually reach.
+   */
+  function sessionsByInitiative(sessions, branchOf) {
+    const out = Object.create(null);
+    if (typeof branchOf !== 'function') return out;
+    for (const s of Array.isArray(sessions) ? sessions : []) {
+      if (!isLive(s) || !s.ws) continue;
+      let id = null;
+      // A branch lookup that THROWS must not take the board down with it. The map is the data
+      // layer's and this module does not own its failure modes.
+      try { id = initiativeOfBranch(branchOf(s.ws)); } catch { id = null; }
+      if (!id) continue;
+      (out[id] || (out[id] = [])).push(s);
+    }
+    return out;
+  }
+
+  /**
+   * The one presented state that stands for a whole initiative's sessions — the loudest, via
+   * session-state's own ATTENTION order. Null when there is nothing live, so a caller cannot draw
+   * a mark for nothing.
+   */
+  function stateOf(sessions) {
+    if (!SS || typeof SS.loudest !== 'function') return null;
+    return SS.loudest((sessions || []).map((s) => s && s.shown));
+  }
+
+  /**
+   * Every initiative a registered working tree is checked out on.
+   *
+   * `branches` is a flat list of branch strings — the caller enumerates its own registry. A tree on
+   * initiative/<id> means the PM has a checkout dedicated to that initiative, whether or not
+   * anything is running in it; that is a weaker claim than a live session and a real one.
+   */
+  function initiativesWithTree(branches) {
+    const out = new Set();
+    for (const b of Array.isArray(branches) ? branches : []) {
+      const id = initiativeOfBranch(b);
+      if (id) out.add(id);
+    }
+    return out;
+  }
+
+  /**
+   * Every initiative this window has a tab open on.
+   *
+   * The weakest of the three signals and the only one that reflects INTENT rather than machine
+   * state. It is also durable: pm/state.js persists `tabs`, so it survives a reload — which is the
+   * whole reason it is worth reading. It can be stale (a tab left open for a week reads like one
+   * opened a minute ago), which is why it ranks last and why its reason is carried, not hidden.
+   */
+  function initiativesWithTab(tabs) {
+    const out = new Set();
+    for (const t of Array.isArray(tabs) ? tabs : []) {
+      if (t && typeof t.slug === 'string' && t.slug) out.add(t.slug);
+    }
+    return out;
+  }
+
+  /**
+   * THE WORKING SET — the rows the board pins above the Objectives.
+   *
+   *   live      {id: [session…]}  from sessionsByInitiative
+   *   trees     Set<id>           from initiativesWithTree
+   *   tabs      Set<id>           from initiativesWithTab
+   *   onBoard   (id) => boolean   is this slug on the repository currently showing? REQUIRED, and
+   *                               the reason a tab or a tree belonging to another repository cannot
+   *                               leak a row onto the wrong board.
+   *
+   * Ordered by attention: needs → blocked → working → quiet → tree → open, alphabetical within a
+   * band. So the initiative waiting on the PM is the first row on the screen.
+   *
+   * Each entry is `{slug, reason, state, sessions}`. `reason` is one of REASONS and is never
+   * collapsed away — the surface says which of the three it is.
+   */
+  function workingSet({ live, trees, tabs, onBoard } = {}) {
+    const L = live && typeof live === 'object' ? live : {};
+    const T = trees instanceof Set ? trees : new Set();
+    const B = tabs instanceof Set ? tabs : new Set();
+    const keep = typeof onBoard === 'function' ? onBoard : () => false;
+
+    const seen = new Map();
+    const add = (slug, reason, sessions) => {
+      if (!slug || seen.has(slug) || !keep(slug)) return;
+      seen.set(slug, { slug, reason, state: reason === 'session' ? stateOf(sessions) : null, sessions: sessions || [] });
+    };
+    for (const slug of Object.keys(L)) add(slug, 'session', L[slug]);
+    for (const slug of T) add(slug, 'tree', null);
+    for (const slug of B) add(slug, 'open', null);
+
+    const attention = (e) => (e.state && SS && SS.ATTENTION ? (SS.ATTENTION[e.state] || 0) : 0);
+    return [...seen.values()].sort((a, b) => {
+      if (REASON_RANK[a.reason] !== REASON_RANK[b.reason]) return REASON_RANK[b.reason] - REASON_RANK[a.reason];
+      if (attention(a) !== attention(b)) return attention(b) - attention(a);
+      return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+    });
+  }
+
+  /**
+   * What the PM reads when they hover a row's session mark: every live session named INDIVIDUALLY,
+   * with the SERVER's own word for its state.
+   *
+   * The glyph summarises and the tooltip does not — a count would reproduce the status bar's
+   * "3 sessions running", which is the thing that says how many and never which. `s.label` is
+   * server-rendered (session-state's `label`, one clock, one sentence), so this cannot word a
+   * session differently from the pane it belongs to. A row with no label falls back to `shown`
+   * rather than inventing a sentence.
+   */
+  function sessionTitle(slug, sessions) {
+    const rows = (sessions || []).filter(isLive);
+    if (!rows.length) return '';
+    const lines = rows.map((s) => '· ' + (s.name || s.id || 'session') + ' — ' + (s.label || s.shown || 'unknown'));
+    const n = rows.length;
+    return [
+      n + ' live session' + (n === 1 ? '' : 's') + ' on ' + PREFIX + slug,
+      ...lines,
+    ].join('\n');
+  }
+
+  /** One line naming why an initiative is in the working set. Stated, never implied. */
+  function reasonTitle(entry) {
+    if (!entry) return '';
+    if (entry.reason === 'session') return sessionTitle(entry.slug, entry.sessions);
+    if (entry.reason === 'tree') return 'a registered working tree is on ' + PREFIX + entry.slug + ' — nothing is running in it';
+    return 'you have a tab open on this initiative in this window';
+  }
+
+  return {
+    PREFIX, REASONS, REASON_RANK,
+    initiativeOfBranch, isLive, sessionsByInitiative, stateOf,
+    initiativesWithTree, initiativesWithTab, workingSet, sessionTitle, reasonTitle,
+  };
+});

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.22.0",
+      "version": "0.24.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/index.html

@@ -35,6 +35,13 @@
      Both read this file, so the sentence in the terminal and the sentence in the chooser cannot
      drift apart. Classic script (a UMD setting window.PMOSTreeShare), like the two above. -->
 <script src="/lib/tree-share.js"></script>
+<!-- The session→initiative join, made once over every session instead of once per initiative
+     (workspace-active-visibility). The SERVER makes the same two-hopper per initiative inside
+     /api/initiative (lib/four-panel.js sessionsFor); the BOARD needs it for 178 rows at once and
+     cannot spend 178 requests on it. Loaded here rather than imported so it stays walkable in node
+     — test.js requires it and walks its whole input domain. It reads window.PMOSSessionState for
+     the attention order, so it must come AFTER that script. -->
+<script src="/lib/working-set.js"></script>
 <!-- The phone's navigation reducer. DOM-free, loaded as a classic script (it is a UMD that sets
      window.PMOSMobileNav) and required by test.js, so the whole screen domain is walkable in node
      rather than only in a browser. pm/mobile.js reads it from the global; the module graph does not