create-pmos 0.25.0 → 0.27.0

package/workspace/lib/working-set.js

@@ -5,25 +5,39 @@
 // 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:
+// ── THE JOIN ─────────────────────────────────────────────────────────────────────────────────
+// This module shipped joining on ONE signal, because one was all a session carried:
 //
 //     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.
+// That is the join lib/four-panel.js `sessionsFor()` makes per initiative on the server, made once
+// over ALL sessions instead, so the board can colour 178 rows without 178 requests.
+//
+// It was too narrow, and the proof was this repository's own history: the initiative that shipped
+// that board was built on a `claude/*` branch, so the feature could not see the session that wrote
+// it. The convention holds in one of four ordinary situations — the PM works on `main`, the harness
+// opens sessions on `claude/*`, plenty of repos have no git at all, and only a worktree made by
+// `＋ session`'s branch control is actually named after its initiative.
+//
+// So a session now RECORDS what it is for (workspace-session-attribution), and attribution runs in
+// precedence order — recorded, then branch, then unattributed — with the answering path carried so
+// an inference is never mistaken for a record. See `attributeSessions`.
+//
+// What is unchanged: this module runs no git and guesses at nothing. It reads the branch strings the
+// server derived (`git rev-parse --abbrev-ref`, published on /api/workspaces) and the session rows
+// the server published, and nothing else.
 //
 // ── 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.
+// Every input that does not resolve contributes NOTHING TO AN INITIATIVE. 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 — none of them lands on a row. 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.
+//
+// It is NOT dropped, though — that was the other half of the same defect. An unresolvable live
+// session is returned as `unattributed`, because a running agent that appears nowhere is invisible
+// on the one surface whose job is to say what is running. Refusing to guess and refusing to mention
+// are different things, and only the first is honesty.
 //
 // `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.
@@ -92,18 +106,63 @@
    * 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;
+    return attributeSessions(sessions, branchOf).byInitiative;
+  }
+
+  /**
+   * ATTRIBUTION, in precedence order, with the answering path carried.
+   *
+   * The first cut of this module joined on the branch alone, because that was the only signal a
+   * session carried. It is no longer: `sessionList()` publishes `initiative` + `attributed_by` for
+   * a session PMOS was told about at spawn, or that the PM bound afterwards. So the order is:
+   *
+   *   1. `s.initiative`        RECORDED — PMOS was told, or the PM said so. First-hand.
+   *   2. `initiative/<id>`     BRANCH — an inference from a naming convention. Kept, because every
+   *                            session running before the field existed has only this; labelled,
+   *                            because an inference must never be mistaken for a record.
+   *   3. neither               UNATTRIBUTED — reported as such, never bucketed or guessed.
+   *
+   * Why the branch survives at all, since a recorded field is strictly better: dropping it would
+   * un-attribute every session on a real `initiative/<id>` worktree the moment this shipped, which
+   * is a regression the PM would experience as the feature losing information it used to have. It
+   * is a fallback with a name, not a second opinion competing with the record — `via` says which
+   * answered, and the two never merge.
+   *
+   * Returns `{ byInitiative: {id: [session…]}, via: {sessionId: 'recorded'|'branch'}, unattributed:
+   * [session…] }`. Insertion-ordered, no empty arrays, and nothing the join could not actually reach.
+   */
+  function attributeSessions(sessions, branchOf) {
+    const byInitiative = Object.create(null);
+    const via = Object.create(null);
+    const unattributed = [];
+    const lookup = typeof branchOf === 'function' ? branchOf : null;
     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);
+      if (!isLive(s)) continue;
+      // 1 — the record. Independent of `ws`: a session in a folder with no git, or one whose
+      // workspace the client has not loaded, is still attributable if PMOS was told what it is for.
+      let id = validId(s.initiative);
+      let how = id ? 'recorded' : null;
+      // 2 — the branch, only where the record is silent. A 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 failures.
+      if (!id && s.ws && lookup) {
+        try { id = initiativeOfBranch(lookup(s.ws)); } catch { id = null; }
+        if (id) how = 'branch';
+      }
+      if (!id) { unattributed.push(s); continue; }
+      (byInitiative[id] || (byInitiative[id] = [])).push(s);
+      if (s.id) via[s.id] = how;
     }
-    return out;
+    return { byInitiative, via, unattributed };
+  }
+
+  /**
+   * Is this a usable initiative id? Deliberately permissive about SHAPE and strict about type —
+   * the server has already validated anything it recorded (`fourPanel.validId`), and re-deriving
+   * that regex here would put a second opinion in the tree about what an id is. What this rejects
+   * is the shapes that cannot be a key at all.
+   */
+  function validId(v) {
+    return typeof v === 'string' && v !== '' && v.indexOf('/') === -1 ? v : null;
   }
 
   /**
@@ -164,16 +223,26 @@
    * 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 } = {}) {
+  function workingSet({ live, trees, tabs, onBoard, via } = {}) {
     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 how = via && typeof via === 'object' ? via : {};
 
     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 || [] });
+      // WHICH PATH ANSWERED, carried onto the row so the reason line can say it. An initiative whose
+      // sessions were all resolved from a branch name is a weaker claim than one PMOS was told
+      // about, and the PM is entitled to know which they are looking at.
+      const rows = sessions || [];
+      const paths = rows.map((s) => (s && s.id ? how[s.id] : null)).filter(Boolean);
+      seen.set(slug, {
+        slug, reason, state: reason === 'session' ? stateOf(sessions) : null, sessions: rows,
+        via: paths.length && paths.every((v) => v === 'branch') ? 'branch'
+          : paths.includes('recorded') ? 'recorded' : null,
+      });
     };
     for (const slug of Object.keys(L)) add(slug, 'session', L[slug]);
     for (const slug of T) add(slug, 'tree', null);
@@ -211,14 +280,41 @@
   /** 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 === 'session') {
+      const t = sessionTitle(entry.slug, entry.sessions);
+      // A branch-only attribution says so. It is a reading of a folder's branch name, not something
+      // PMOS was told, and the difference is the whole point of the recorded field.
+      return entry.via === 'branch'
+        ? t + '\nattributed by the ' + PREFIX + entry.slug + ' branch — no session recorded this initiative'
+        : t;
+    }
     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';
   }
 
+  /**
+   * The tooltip for the unattributed row: every live session PMOS cannot place, named individually.
+   *
+   * This row exists because the alternative is worse. A session the join cannot reach has nowhere to
+   * go on an initiative-keyed board, and dropping it would mean a running agent is invisible on the
+   * surface whose job is to say what is running. It claims NO initiative — the wording has to leave
+   * the PM in no doubt that PMOS does not know, rather than implying a default.
+   */
+  function unattributedTitle(sessions) {
+    const rows = (sessions || []).filter(isLive);
+    if (!rows.length) return '';
+    const n = rows.length;
+    return [
+      n + ' live session' + (n === 1 ? '' : 's') + ' PMOS cannot place on an initiative',
+      ...rows.map((s) => '· ' + (s.name || s.id || 'session') + ' — ' + (s.label || s.shown || 'unknown')),
+      'no initiative was recorded, and no working tree is on an ' + PREFIX + '… branch',
+    ].join('\n');
+  }
+
   return {
     PREFIX, REASONS, REASON_RANK,
-    initiativeOfBranch, isLive, sessionsByInitiative, stateOf,
+    initiativeOfBranch, isLive, sessionsByInitiative, attributeSessions, stateOf,
     initiativesWithTree, initiativesWithTab, workingSet, sessionTitle, reasonTitle,
+    unattributedTitle,
   };
 });

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
+    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js && node state-isolation.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",

package/workspace/public/pm/data.js

@@ -795,6 +795,11 @@ function schedulePoll() {
 export async function loadRepos() {
   if (FIXTURE) return [];
   const out = await getJson('/api/workspaces');
+  // The server's one answer to "is the runtime state settled?", published straight onto state so
+  // panel 1 can say so. Under an unmigrated conflict the lists below are short by everything the
+  // per-user state directory does not hold, and a list that is short without saying so is the
+  // silent failure this key exists to end. `{ok:true}` publishes too — the banner reads `ok`.
+  const health = out && out.state_health ? out.state_health : null;
   const rows = foldWorkspaces(out && out.workspaces);
   productOrder = rows.map((r) => r.name);
   for (const r of rows) products.set(r.name, Object.assign(products.get(r.name) || {}, r));
@@ -808,6 +813,7 @@ export async function loadRepos() {
   // actually on screen. A restored selection from the PM's last session always wins.
   const sel = state.sel || (p ? firstSlugOf(p.name) : null);
   setState({
+    stateHealth: health,
     wsId: p ? p.ws : null,
     // NOT initialised to a value here. What is resolvable is the server's derivation from the PM's
     // agent profiles, it arrives with the first `/api/initiative` payload, and seeding a `[]` in the
@@ -942,6 +948,63 @@ export async function listFolder(dir) {
   return getJson('/api/fs/list', dir ? { path: dir } : null);
 }
 
+/* ── what the session pre-flight asks the server ───────────────────────────────────────────────
+ * Four read-only endpoints that have been served all along with no client reading them. They are
+ * the questions the retired composer asked before a session started, and losing the client half is
+ * what left `＋ session` spawning on defaults nobody chose.
+ *
+ * Every one declines in FIXTURE mode, and that is load-bearing rather than tidy: the fixture render
+ * must make no network call at all — it is what lets no-network.test.js and the design comparator
+ * trust a fixture run. The form degrades to "no repository was read" and the fixture's own profile
+ * list, which is a true statement about fixture mode rather than a blank.
+ */
+
+/**
+ * Every branch of a workspace's repository, plus which one is current and which are already
+ * checked out in another working tree. Returns the server's `gitInfo.branchInfo` verbatim, so a
+ * non-repo answers `{ok:false, code, error}` and NEVER a fabricated branch — the difference
+ * between "this folder has no git" and "git failed" is the picker's to show, so it must survive
+ * the trip.
+ */
+export async function loadBranches(ws) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode reads no repository' };
+  if (!ws) return { ok: false, error: 'no repository selected' };
+  return getJson('/api/git/branches', { ws });
+}
+
+/**
+ * The Claude profile descriptors, as `{ok, absent, dir, profiles, broken, prefs, error}`.
+ *
+ * All six fields matter to the caller and none may be flattened here: `absent` ("the directory does
+ * not exist") is a different sentence from a successful read that found none; `broken` names a
+ * descriptor that must be shown and NOT offered, while every good one beside it is still offered;
+ * and `prefs` is what preselects a chip, replacing a hardcoded 'claude-work' that named a file this
+ * client had never opened.
+ *
+ * `env` values are absent by construction on the server side (profileWire) — D08's discipline
+ * covers anything the browser receives, and an overlay is where a credential lives.
+ */
+export async function loadProfiles() {
+  if (FIXTURE) return { ok: false, error: 'fixture mode reads no profiles' };
+  return getJson('/api/profiles');
+}
+
+/** Remember the profile this agent should preselect next time. The server refuses a preference for
+ * a descriptor it cannot read, so a stored id always resolves to a chip that is on screen. */
+export async function preferProfile(agent, profile) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode remembers nothing' };
+  return postJson('/api/profiles/prefer', { agent, profile });
+}
+
+/** Every working tree of this workspace's repo. The pre-flight reads it for ONE purpose: a branch
+ * checked out elsewhere is a branch git will refuse, and the PM should read that in the picker
+ * rather than as an error after the click. */
+export async function loadWorktrees(ws) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode reads no repository' };
+  if (!ws) return { ok: false, error: 'no repository selected' };
+  return getJson('/api/git/worktrees', { ws });
+}
+
 /**
  * panel-tabs.js — `startSession(slug, sess)`. Deliberately NOT a spawn.
  *
@@ -957,6 +1020,29 @@ export function startSession(slug, sess) {
   setTimeout(pollSessions, 800);
 }
 
+/**
+ * Bind a RUNNING session to an initiative — the PM's own word about work already in flight
+ * (workspace-session-attribution R3).
+ *
+ * Every session that existed before the recorded field shipped has no attribution, and so does every
+ * session started outside PMOS. Without this the field would be a promise about future sessions and
+ * no help at all with the ones on screen.
+ *
+ * What comes back is the server's answer, not an assumption: `previous` names the initiative this
+ * replaced, so a re-bind the PM did not mean to make is visible rather than silent. Pass
+ * `initiative: null` to clear a binding — the honest way back from a wrong one.
+ *
+ * The poll is scheduled rather than the state patched locally: `/api/sessions` is the one reader of
+ * this fact, and writing a second opinion into `state.sessions` here is how the board and the server
+ * would come to disagree about what a session is for.
+ */
+export async function bindSessionInitiative(id, initiative) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode has no server' };
+  const out = await postJson('/api/session/initiative', { id, initiative: initiative || null });
+  if (out && out.ok) setTimeout(pollSessions, 200);
+  return out || { ok: false, error: 'the workspace server did not answer' };
+}
+
 /* ── the scratchpad ─────────────────────────────────────────────────────────────────────────────
  * The pad is PER SESSION, and the server has always stored it that way: `/api/scratchpad` is keyed
  * by the server-issued session id (workspace-scoped, one file per session, deleted with it). What

package/workspace/public/pm/panel-detail.js

@@ -52,7 +52,7 @@
 import { el, setChildren } from './dom.js';
 import { state, setState, FIXTURE } from './state.js';
 import * as FX from './fixture.js';
-import { openDoc, openTab, fileNewModel } from './panel-initiatives.js';
+import { openDoc, openTab, openTerm, fileNewModel } from './panel-initiatives.js';
 import { addProductBody } from './panel-repos.js';
 
 /* ── the prototype's small helpers ─────────────────────────────────────────────────────────── */
@@ -212,6 +212,78 @@ const stickyHeader = el('div', {
   }, '⟨'),
 );
 
+/* ── 1b · SESSIONS — the agents running on THIS initiative ──────────────────────────────────────
+ *
+ * The PM's report: *"when I click the initiative on the initiative panel (which is column number 3),
+ * I can see the active sessions list, then when i click, either go to the tab (if tab is open), or
+ * open new tab and directly resume to the session."*
+ *
+ * Their first sentence was not that the list is unclickable — there was no list. `data.js` has been
+ * building `rec.sessions` (each row carrying the server's own id and rendered label) and `rec.noSess`
+ * since the four-panel port, and `initBody()` rendered header → phases → links → artifacts → footer.
+ * Neither field appeared anywhere in this file. The join ran on the server, survived the wire, was
+ * normalised by the data layer, and was dropped by the renderer.
+ *
+ * ── WHY THIS DOES NOT RENDER `rec.sessions` ──────────────────────────────────────────────────
+ * Because `FX.DATA` carries seed `sessions` arrays, and drawing them would light up seven fixture
+ * rows and break the design comparator's text axis on the first render. The board solved this the
+ * same way and for the same reason: read the LIVE join, which fixture mode structurally cannot fill
+ * (`pollSessions` returns early on FIXTURE). There is no server in fixture mode, so there are no
+ * live sessions to claim.
+ *
+ * ── THE CLICK ────────────────────────────────────────────────────────────────────────────────
+ * `openTerm` with the session's SERVER id and no `spawn`. Those two facts are the whole behaviour:
+ * `openTab` focuses a tab whose id already exists rather than duplicating it, and the absent `spawn`
+ * is what withholds authorisation to create a PTY — so a click either lands on the open tab or opens
+ * one attached to the running process. It cannot start a second agent.
+ */
+
+/** The live sessions on one initiative, from the shared join — never from the record's seed rows. */
+function liveSessionsFor(slug) {
+  if (FIXTURE || !slug) return [];
+  const ws = typeof window !== 'undefined' ? window.PMOSWorkingSet : null;
+  const map = state.wsBranches && typeof state.wsBranches === 'object' ? state.wsBranches : {};
+  if (!ws || typeof ws.attributeSessions !== 'function') return [];
+  const attr = ws.attributeSessions(state.sessions, (id) => map[id] || null);
+  return attr.byInitiative[slug] || [];
+}
+
+function sessionsBlock(slug) {
+  const rows = liveSessionsFor(slug);
+  if (!rows.length) return null;                    // nothing running: no heading over nothing
+  const ss = typeof window !== 'undefined' ? window.PMOSSessionState : null;
+  const openIds = new Set((state.tabs || []).filter((t) => t && t.kind === 'term' && t.sessionId).map((t) => t.sessionId));
+
+  return el('div', { style: 'padding:9px 14px 10px;border-bottom:1px solid var(--border)' },
+    el('div', { style: 'font-family:var(--mono);font-size:10px;letter-spacing:.12em;text-transform:uppercase;color:var(--muted-foreground);margin-bottom:6px' },
+      'sessions'),
+    rows.map((s) => {
+      const st = ss && ss.GLYPH[s.shown] ? s.shown : null;
+      const here = openIds.has(s.id);
+      return el('button', {
+        onClick: () => openTerm(slug, { name: s.name, st: s.shown, label: s.label, id: s.id, profile: s.profile_id }),
+        style: 'display:flex;align-items:center;gap:8px;width:100%;padding:5px 6px;min-height:30px',
+        hover: 'background:var(--accent)',
+        // What the click will do, said BEFORE it — the difference between landing on a tab already
+        // open and opening one that attaches. Neither ever starts an agent, and that is worth saying
+        // on the control rather than only in a comment nobody reading the surface can see.
+        title: (s.name || s.id) + ' — ' + (s.label || s.shown || '')
+          + (s.profile_id ? '\nprofile ' + s.profile_id : '')
+          + (here ? '\nits tab is open — this goes to it' : '\nopens a tab attached to this running session; nothing is started'),
+      },
+        el('span', { style: 'flex:none;font-size:11px;color:' + (st && ss ? ss.COLOR[st] : 'var(--muted-foreground)') },
+          st && ss ? ss.GLYPH[st] : '·'),
+        el('span', { style: 'font-family:var(--mono);font-size:11.5px;color:var(--foreground);overflow:hidden;text-overflow:ellipsis;white-space:nowrap' },
+          iv(s.name || s.id)),
+        el('span', { style: 'margin-left:auto;flex:none;font-size:10px;color:var(--muted-foreground)' },
+          iv(s.label || s.shown || '')),
+        el('span', { style: 'flex:none;font-family:var(--mono);font-size:9.5px;color:var(--muted-foreground)' },
+          iv(here ? 'open' : 'resume')),
+      );
+    }),
+  );
+}
+
 /* ── 1 · HEADER — slug, tag, pills (lines 338–346) ──────────────────────────────────────────── */
 
 function headerBlock(name, tag, pills) {
@@ -908,6 +980,11 @@ function initBody(slug) {
     out.push(...noLadderBlock(FX.wash(ansC), ansC, (rec.answer && rec.answer.text) || '', rec.noLadder));
   }
 
+  // What is RUNNING on this initiative, above the ladder: the loop position is the slower fact, and
+  // an agent waiting on the PM is the one they came to the panel for.
+  const sess = sessionsBlock(slug);
+  if (sess) out.push(sess);
+
   const phases = phaseBlock(slug, rec);
   if (phases) out.push(phases);
 
@@ -961,6 +1038,97 @@ function anchorButton(an) {
   );
 }
 
+/* ── BIND — the PM's own word about a session already running ──────────────────────────────────
+ *
+ * Every session that existed before a session could record its initiative has no attribution, and so
+ * does every session started outside PMOS. This is the only way one of them ever joins an initiative,
+ * which is why "show them read-only" was not enough.
+ *
+ * The whole surface turns on one distinction, stated in the copy rather than left to a code comment:
+ * what is recorded here is a DECLARATION. PMOS was not told at spawn and did not read it off
+ * anything — the PM is saying so. `initiative-links.jsonl` already draws that line with
+ * `origin`/`state`, and a binding that presented itself as a reading would be the same watermelon
+ * this repo keeps finding.
+ */
+function bindBody() {
+  const out = [];
+  const rows = (state.sessions || []).filter((s) => s && s.shown !== 'exited');
+  const picked = state.bindSess && rows.find((s) => s.id === state.bindSess);
+  const board = state.board && state.board[state.product] ? state.board[state.product] : [];
+  const slugs = [];
+  for (const g of board) for (const sl of g.slugs || []) if (!slugs.includes(sl)) slugs.push(sl);
+  const typed = String(state.bindTo || '');
+  const matches = typed ? slugs.filter((sl) => sl.includes(typed.toLowerCase())).slice(0, 8) : [];
+
+  out.push(el('div', { style: 'padding:13px 14px 11px;border-bottom:1px solid var(--border)' },
+    el('div', { style: 'font-size:14px;font-weight:600;margin-bottom:4px' }, 'bind a session'),
+    el('div', { style: 'font-size:11.5px;line-height:1.5;color:var(--muted-foreground)' },
+      'PMOS was never told what these sessions are for, and nothing here can read it. '
+      + 'What you pick is recorded as YOUR declaration — not as something PMOS observed.')));
+
+  out.push(el('div', { style: 'padding:10px 14px 2px;' + NEW_LABEL }, 'session'));
+  if (!rows.length) {
+    out.push(el('div', { style: 'padding:2px 14px 10px;font-size:11.5px;color:var(--muted-foreground);font-style:italic' },
+      'no live sessions — a successful read of nothing'));
+    return out;
+  }
+  out.push(el('div', { style: 'display:flex;flex-direction:column;gap:2px;padding:2px 14px 6px' },
+    rows.map((s) => el('button', {
+      onClick: () => setState({ bindSess: s.id }),
+      style: 'display:flex;gap:8px;align-items:center;min-height:32px;padding:0 9px;background:'
+        + (picked && picked.id === s.id ? 'var(--secondary)' : 'transparent')
+        + ';border:1px solid ' + (picked && picked.id === s.id ? 'var(--input)' : 'var(--border)'),
+      hover: 'border-color:var(--ring)',
+    },
+      el('span', { style: 'font-family:var(--mono);font-size:11px;color:var(--foreground)' }, iv(s.name || s.id)),
+      el('span', { style: 'font-size:11px;color:var(--muted-foreground)' }, iv(s.label || s.shown || '')),
+      // What it is bound to NOW, and by what. A session already attributed can be re-bound, and the
+      // PM is entitled to see what they would be replacing before they replace it (R8).
+      s.initiative
+        ? el('span', { style: 'margin-left:auto;font-family:var(--mono);font-size:9.5px;color:var(--muted-foreground)' },
+          iv('→ ' + s.initiative + (s.attributed_by === 'declared' ? ' · declared' : ' · recorded')))
+        : null,
+    ))));
+
+  out.push(el('div', { style: 'padding:6px 14px 2px;' + NEW_LABEL }, 'initiative'));
+  out.push(el('div', { style: 'padding:2px 14px 4px' },
+    newField('bindTo', typed, () => setState({}), 'type part of an initiative id',
+      'width:100%;font-family:var(--mono);font-size:11px;padding:5px 7px;background:var(--secondary);border:1px solid var(--border);color:var(--foreground)')));
+  if (matches.length) {
+    out.push(el('div', { style: 'display:flex;flex-direction:column;gap:2px;padding:2px 14px 6px' },
+      matches.map((sl) => el('button', {
+        onClick: () => {
+          if (!picked) return;
+          const data = sibling('data', './data.js');
+          if (!data || typeof data.bindSessionInitiative !== 'function') return;
+          data.bindSessionInitiative(picked.id, sl).then((r) => {
+            setState({
+              bindResult: r && r.ok
+                ? '“' + (picked.name || picked.id) + '” is now on ' + sl
+                  + (r.previous ? ' — replacing ' + r.previous : '')
+                : 'could not bind — ' + ((r && r.error) || 'the server did not answer'),
+            });
+          });
+        },
+        style: 'display:flex;gap:8px;align-items:center;min-height:30px;padding:0 9px;background:transparent;border:1px solid var(--border)',
+        hover: 'border-color:var(--ring)',
+      }, el('span', { style: 'font-family:var(--mono);font-size:11px' }, iv(sl))))));
+  } else if (typed) {
+    out.push(el('div', { style: 'padding:2px 14px 8px;font-size:11.5px;color:var(--muted-foreground);font-style:italic' },
+      'nothing on this board matches — a successful read of nothing'));
+  }
+
+  if (!picked) {
+    out.push(el('div', { style: 'padding:4px 14px 10px;font-size:11.5px;color:var(--muted-foreground)' },
+      'pick a session first.'));
+  }
+  if (state.bindResult) {
+    out.push(el('div', { style: 'margin:4px 14px 10px;padding:8px 11px;border:1px solid var(--border);font-size:11.5px;line-height:1.5' },
+      iv(state.bindResult)));
+  }
+  return out;
+}
+
 function fileNewBody() {
   const nw = fileNewModel();
   const out = [];
@@ -1073,11 +1241,15 @@ function modeDetailBody(kind) {
 
 export function renderDetail(host) {
   const kind = (state.detail && state.detail.kind) || 'init';
-  headerTitleText.textContent = FX.detailTitle(kind);
+  // `bind` is not one of the prototype's detail kinds, and `fixture.js` is its seed data — adding a
+  // key there to title one screen would be drift into a file the parity suite exists to keep
+  // transcribed. The override lives here instead, where the screen does.
+  headerTitleText.textContent = kind === 'bind' ? 'bind a session' : FX.detailTitle(kind);
 
   let body;
   if (kind === 'init') body = initBody(selectedSlug());
   else if (kind === 'addprod') body = addProductBody();
+  else if (kind === 'bind') body = bindBody();
   else if (kind === 'new') body = fileNewBody();
   else if (kind === 'none') body = [noneBody()];
   else body = modeDetailBody(kind);