create-pmos 0.23.0 → 0.25.0

package/README.md

@@ -333,6 +333,34 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.24.0
+
+**The initiative board says which work is yours, and which of it has an agent running.** Run
+`npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **A `NOW · working on` group is pinned at the top of the board.** With a few dozen initiatives
+  filed by objective, the list is in the right *filing* order and the wrong *attention* order — the
+  one you have an agent running on sits wherever its KR happens to fall. This group collects what
+  you are actually on, ordered so whatever is **waiting on you** is the first row on the screen.
+- **Three signals, ranked and told apart.** An initiative is in the group because a session is live
+  on its `initiative/<id>` branch, or a working tree is checked out on that branch with nothing
+  running in it, or you have a tab open on it in this window. They are never merged into one vague
+  "active" badge — each row's tooltip says which one put it there, and the two weaker ones say
+  plainly that nothing is running.
+- **A live session shows on its own row.** The `#` beside an initiative becomes that session's own
+  glyph — `◆ needs you`, `● working`, `◇ maybe blocked`, `◼ quiet` — in the same vocabulary the
+  session sidebar uses. Hovering names **every** session on that initiative with its state, rather
+  than counting them: the status bar already says how many and never which. Several sessions fold to
+  the one that most wants you, and `maybe blocked` outranks `working`.
+- **The glyphs differ in shape, not just colour**, so the board still reads in greyscale and for a
+  colour-blind reader.
+- **Nothing is re-homed and nothing is invented.** An initiative still appears under its own
+  objective and KR — the group is a shortcut, not a second filing system — and it disappears
+  entirely when there is nothing to say. A session PMOS cannot place on an initiative is not placed
+  on one.
+- **Searching for a session name now finds it.** It only ever matched initiatives you had already
+  opened in that window, and returned nothing for the rest without saying it had not looked.
+
 ## What's new in 0.21.0
 
 **The workspace terminal's lines are no longer double-spaced.** Run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Scaffold the PMOS portable kit \u2014 run the PMOS product-management workflow (initiative \u2192 lane-fit spec \u2192 contract \u2192 build \u2192 three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@76ed2d3
+kernel-source: pmos@bb78e24
 assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -67,6 +67,16 @@ bar and a 26px status bar, on the oklch token layer, in both themes:
 2. **Initiatives** — a channel list. Collapsible objective/KR groups over `#slug` rows, one search
    box that forces the groups open and reports matches elsewhere, and an add form. Unanchored
    initiatives are filed honestly and shown **rejected** under D59, never hidden.
+   A **`NOW · working on`** group is pinned above the objectives when — and only when — there is
+   something to say: every initiative with a live session on its `initiative/<id>` branch, a
+   registered working tree on that branch, or a tab open in this window, ordered so whatever is
+   **waiting on you** is the first row on the board. The three signals are ranked, never merged, and
+   each row's tooltip names which one put it there. On a row with a live session the leading `#`
+   becomes that session's own glyph — `◆ needs you`, `● working`, `◇ maybe blocked`, `◼ quiet` —
+   in the vocabulary `lib/session-state.js` uses everywhere else, with every session named
+   individually on hover. The glyphs differ in **shape**, so the signal survives greyscale.
+   The join is the branch convention and nothing else: a session PMOS cannot place on an initiative
+   is not placed on one.
 3. **Initiative detail** — the record's header and pills (type / anchor / flow / branch), the derived
    footer, **task phases** (collapsible; a phase's status is derived from its tasks, and the tasks
    are derived from the workflow ladder unless the record authors them), a **links** section for

package/workspace/lib/four-panel.js

@@ -57,6 +57,15 @@ const path = require('path');
 
 const ARTIFACT_LINKS = 'artifact-links.jsonl';
 const INITIATIVE_LINKS = 'initiative-links.jsonl';
+/**
+ * The THIRD store, and the newest place this module has to refuse something.
+ *
+ * A link says *this file corresponds to that page*. A sync row says *the PM decided which way the
+ * content should travel, and here is what came back*. They are different facts with different
+ * lifetimes — a link outlives any number of syncs — so they are different files rather than a
+ * `direction` column bolted onto a link row, where every re-sync would supersede the link itself.
+ */
+const ARTIFACT_SYNC = 'artifact-sync.jsonl';
 
 /** The destinations the surface can declare. A kind outside this set is refused, not stored. */
 const LINK_KINDS = ['confluence', 'jira', 'google'];
@@ -70,12 +79,38 @@ const LINK_KINDS = ['confluence', 'jira', 'google'];
  *   resolved    — a lookup performed BY A SESSION that holds the PM's MCP returned this record.
  *                 Carries the destination's own title and the moment it was read.
  *   unreachable — a lookup was attempted and did not succeed. Carries the reason it failed.
+ *   retracted   — the PM withdrew this reference. It is a STATE and not an absence, because the
+ *                 store is append-only and "the PM removed this" is a fact worth keeping; a link
+ *                 deleted from disk would be a link that never existed, and the history of what the
+ *                 PM declared is the whole reason this file is a ledger. A later declaration for
+ *                 the same pair brings the reference back, because `linkView` reads the latest row
+ *                 and nothing here is a tombstone.
  *
  * `connected` was the word this surface used before, and it is retired rather than re-worded: PMOS
  * is never connected to anything — a session is — so the word had no honest referent here. It is
  * also the word that let a row the PM had merely declared read as a row PMOS had verified.
  */
-const LINK_STATES = ['declared', 'resolved', 'unreachable'];
+const LINK_STATES = ['declared', 'resolved', 'unreachable', 'retracted'];
+
+/**
+ * Which way the content travels, and what happened. The sync store's own closed vocabulary.
+ *
+ *   push  — the repo file is the source; its content goes to the destination.
+ *   adopt — the destination is the source; its content comes into the repo file.
+ *
+ *   proposed — the PM chose this direction. A task was composed. NOTHING has been written anywhere,
+ *              and this is the only state PMOS itself can produce.
+ *   applied  — a session holding the PM's MCP performed the write and reported back. Carries the
+ *              profile that did it and the moment it did.
+ *   failed   — the attempt was made and did not succeed. Carries the reason.
+ *
+ * There is deliberately no `in sync`. The prototype's status line read `pushed · repo → jira · in
+ * sync 12:41`, where `12:41` was a literal in a seed module and `in sync` was a claim about two
+ * documents PMOS had never compared. `applied` says the smaller true thing: a session wrote, and
+ * here is who and when.
+ */
+const SYNC_DIRECTIONS = ['push', 'adopt'];
+const SYNC_STATES = ['proposed', 'applied', 'failed'];
 
 /**
  * How a reference came to be in the store. This is the field that makes the store cleanable: the
@@ -384,6 +419,12 @@ function provenance(body, at) {
   if (state === 'unreachable' && !reason) {
     return { error: 'an unreachable reference must carry the reason the lookup failed' };
   }
+  // Withdrawing a reference is the PM's act and nobody else's. A session that could retract could
+  // silently un-say something the PM said, which is the mirror image of the rule above — there, a
+  // caller may not claim to have read what it did not read; here, it may not claim to be the person.
+  if (state === 'retracted' && origin !== 'typed') {
+    return { error: 'a retraction is the PM withdrawing their own reference — send origin: typed' };
+  }
   return {
     origin,
     state,
@@ -472,7 +513,7 @@ function initiativeLinkRow(body, { at } = {}) {
  * the other. Rows are ordered by their recorded time with file order as the tiebreak, because two
  * rows can share a timestamp and file order is the only thing that then says which was written second.
  */
-function linkView(rows) {
+function linkView(rows, { includeRetracted = false } = {}) {
   const list = Array.isArray(rows) ? rows : [];
   const seen = new Map();
   list.forEach((row, i) => {
@@ -493,7 +534,154 @@ function linkView(rows) {
       // this initiative was opened to make identifiable. They are reported as what they are.
       origin: row.origin || null,
       state: row.state || (row.origin ? 'declared' : 'unattributed'),
-    }));
+    }))
+    // A pair whose LATEST row is a retraction is not a link any more, and the surface is a statement
+    // of now. The row it came from is still on disk and still readable — `includeRetracted` is how
+    // a caller that wants the history rather than the statement asks for it — but the panel that
+    // asks "what is linked" gets an answer that does not include what the PM withdrew.
+    .filter((row) => includeRetracted || row.state !== 'retracted');
+}
+
+/* ── the sync ledger ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Validate + normalise one sync row, and enforce the rule this whole store exists for.
+ *
+ * THE RULE, which is `provenance`'s rule carried onto a stronger verb: **`applied` cannot be
+ * asserted, only evidenced.** A row may claim a session wrote to the destination only if it can name
+ * the profile whose session did it. A caller that says "applied" and cannot say by whom is not
+ * describing a write.
+ *
+ * It matters more here than it did for `resolved`, not less. A failed search is obviously
+ * unfinished; a *publish* that a PM ran in another window looks finished from inside this process,
+ * and the difference between "the task was composed" and "the page was updated" is invisible from
+ * here. `proposed` is therefore the ONLY state PMOS can produce on its own, and it says exactly what
+ * happened: a direction was chosen and a task was written down.
+ */
+function syncRow(body, { at } = {}) {
+  const artifact_path = String((body && body.artifact_path) || '').trim();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const target = String((body && body.target) || '').trim();
+  const direction = String((body && body.direction) || '').trim().toLowerCase();
+  if (!artifact_path) return { ok: false, error: 'artifact_path is required' };
+  if (artifact_path.includes('..')) return { ok: false, error: 'artifact_path must be a repo-relative path' };
+  if (!LINK_KINDS.includes(kind)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  if (!target) return { ok: false, error: 'target is required — a sync needs the destination it was linked to' };
+  if (!SYNC_DIRECTIONS.includes(direction)) {
+    return { ok: false, error: `direction must be one of: ${SYNC_DIRECTIONS.join(', ')}` };
+  }
+  const state = String((body && body.state) || 'proposed').trim().toLowerCase();
+  if (!SYNC_STATES.includes(state)) return { ok: false, error: `state must be one of: ${SYNC_STATES.join(', ')}` };
+  const profile = body && body.profile ? String(body.profile).slice(0, 120) : null;
+  const reason = body && body.reason ? String(body.reason).slice(0, 300) : null;
+  const detail = body && body.detail ? String(body.detail).slice(0, 300) : null;
+  if (state === 'applied' && !profile) {
+    return { ok: false, error: 'an applied sync must name the profile whose session performed it — PMOS wrote nothing itself. Send profile with the session that did.' };
+  }
+  if (state === 'failed' && !reason) {
+    return { ok: false, error: 'a failed sync must carry the reason it failed' };
+  }
+  const initiative_id = body && body.initiative_id ? String(body.initiative_id) : null;
+  if (initiative_id && !validId(initiative_id)) return { ok: false, error: 'that initiative id is not a record name' };
+  return {
+    ok: true,
+    row: {
+      at: at || new Date().toISOString(),
+      initiative_id,
+      artifact_path,
+      kind,
+      target: target.slice(0, 300),
+      direction,
+      state,
+      profile,
+      reason,
+      // What the session reported about what it wrote — a page version, a commit, a summary of the
+      // change. Free text, and only ever the session's own words: nothing here composes one.
+      detail,
+      // Only a row that actually wrote something carries a write time, for the same reason only a
+      // row that read something carries a read time. Absent means nobody has written, which is a
+      // fact the surface renders rather than a gap it fills in with a clock.
+      applied_at: state === 'applied' ? (at || new Date().toISOString()) : null,
+    },
+  };
+}
+
+/**
+ * One row per (artifact, destination kind): the latest sync, which is what the status line says.
+ * Same read-time collapse as `linkView` and for the same reason — the store is the history, the
+ * surface is the statement of now.
+ */
+function syncView(rows) {
+  const list = Array.isArray(rows) ? rows : [];
+  const seen = new Map();
+  list.forEach((row, i) => {
+    if (!row || typeof row !== 'object') return;
+    const key = String(row.artifact_path || '') + '|' + String(row.kind || '');
+    const prev = seen.get(key);
+    if (!prev) { seen.set(key, { row, i }); return; }
+    const a = String(prev.row.at || ''), b = String(row.at || '');
+    if (b > a || (b === a && i > prev.i)) seen.set(key, { row, i });
+  });
+  return [...seen.values()].sort((x, y) => x.i - y.i).map(({ row }) => ({ ...row }));
+}
+
+/**
+ * The task a session performs to carry out a sync. Composed here, on the server, for the same
+ * reason `lookupTask` is: it is the thing the design turns on, and a string built in a click handler
+ * is a string no test ever sees.
+ *
+ * Note what changed from `lookupTask`, because it is the whole risk of this initiative. That task
+ * said *search, and do not create, publish or modify anything*. This one asks a session to WRITE.
+ * So it names its target and names what it will overwrite, in both directions, and forbids touching
+ * anything else — the cost of a vague target here is an overwritten Confluence page or an
+ * overwritten repo file, not a wrong pixel. It also asks the session to record the outcome through
+ * the same validated endpoint, where a claim of success will be refused unless it names the profile
+ * that made it.
+ */
+function syncTask({ direction, kind, artifact_path, target, profile } = {}) {
+  const d = String(direction || '').toLowerCase();
+  const k = String(kind || '').toLowerCase();
+  if (!SYNC_DIRECTIONS.includes(d)) return { ok: false, error: `direction must be one of: ${SYNC_DIRECTIONS.join(', ')}` };
+  if (!LINK_KINDS.includes(k)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  const file = String(artifact_path || '').slice(0, 300);
+  const dest = String(target || '').slice(0, 300);
+  if (!file) return { ok: false, error: 'artifact_path is required' };
+  if (!dest) return { ok: false, error: 'target is required' };
+  const what = k === 'jira' ? 'Jira issue' : k === 'confluence' ? 'Confluence page' : 'Google Doc';
+  const lines = d === 'push'
+    ? [
+      `Publish the repository file ${file} to the ${what} at ${dest}.`,
+      '',
+      `Use your ${k} MCP tools. THE DESTINATION YOU WILL OVERWRITE IS ${dest} — write to that record`,
+      'and to nothing else. Do not create a new page, do not touch a parent or a child, and do not',
+      'edit any other record you happen to find while looking.',
+      'Convert the markdown to the destination\'s own format; keep the repository file unchanged.',
+      'Report the version or revision you wrote and the time you wrote it.',
+    ]
+    : [
+      `Bring the ${what} at ${dest} into the repository file ${file}.`,
+      '',
+      `Use your ${k} MCP tools to READ ${dest}. THE FILE YOU WILL OVERWRITE IS ${file} — write to`,
+      'that path and to nothing else, and PRESERVE ITS EXISTING YAML FRONTMATTER BLOCK VERBATIM:',
+      'the repository\'s gates read those keys, and a document that arrives without them fails CI.',
+      'Convert the destination\'s content to markdown, and report what changed in the file.',
+    ];
+  return {
+    ok: true,
+    direction: d,
+    profile: profile || null,
+    text: [
+      ...lines,
+      '',
+      'Then record the outcome: POST /api/initiative/sync with state applied and the profile you ran',
+      `under (${profile || 'the profile holding this MCP'}), or state failed with the reason verbatim.`,
+      'A success that cannot name the profile that performed it will be refused, and refusal is',
+      'correct — PMOS wrote nothing itself and must not report that it did.',
+      'If you did not complete the write, say so plainly. An unreported failure reads here as a',
+      'sync that never happened, which is the honest outcome; a reported success that did not',
+      'happen is the defect this whole surface exists to refuse.',
+    ].join('\n'),
+  };
 }
 
 /**
@@ -537,7 +725,7 @@ function lookupTask({ kind, subject, hint, profile } = {}) {
  * artifacts are still listed, because the library can see them and claiming otherwise would hide
  * real files), `{ok:true,…}` otherwise.
  */
-function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, homeDir }) {
+function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, artifactSync, homeDir }) {
   if (!rec.ok) return { ok: false, id, error: rec.error };
   const artifacts = artifactsFor(index, id);
   const sess = sessionsFor({ sessions, workspaces, id });
@@ -565,16 +753,23 @@ function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor,
       artifacts: mine(artifactLinks, (r) => r && (r.initiative_id === id
         || artifacts.some((a) => a.path === r.artifact_path))),
       links: mine(initiativeLinks, (r) => r && r.initiative_id === id),
+      // Scoped the same way the links are, and collapsed the same way: this initiative's rows only,
+      // latest per (artifact, destination). A sync row for another initiative's copy of the same
+      // path is not this initiative's status line.
+      sync: syncView((artifactSync && artifactSync.ok ? artifactSync.rows : []).filter((r) => r
+        && (r.initiative_id === id || artifacts.some((a) => a.path === r.artifact_path)))),
       artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
       links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
+      sync_error: artifactSync && artifactSync.ok ? null : (artifactSync && artifactSync.error) || null,
     },
     connectors: connectors(homeDir),
   };
 }
 
 module.exports = {
-  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND,
+  ARTIFACT_LINKS, INITIATIVE_LINKS, ARTIFACT_SYNC,
+  LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND, SYNC_DIRECTIONS, SYNC_STATES,
   validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
   storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
-  linkView, lookupTask,
+  linkView, lookupTask, syncRow, syncView, syncTask,
 };

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.23.0",
+  "version": "0.25.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.23.0",
+      "version": "0.25.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",