create-pmos 0.25.0 → 0.26.0

package/README.md

@@ -333,6 +333,33 @@ 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.26.0
+
+**Your sessions now know which initiative they belong to — whatever branch you are on — and each
+initiative shows the agents running on it.** Run `npx create-pmos@latest workspace`; the version bump
+means an existing install auto-upgrades.
+
+- **`NOW · working on` stopped missing sessions.** It could only recognise a session by the *branch*
+  its folder was on — `initiative/<id>` — which is true of almost no real checkout. Work on `main`,
+  or on a branch your agent harness named, and the board could not see the agent you had running.
+  A session now **records** which initiative it is for when you start it from one, so it is
+  attributed whatever branch you are on, and that survives restarting the workspace.
+- **Nothing is guessed, and nothing is hidden.** Where no initiative was recorded, the
+  `initiative/<id>` branch still answers — and the row tells you when the attribution is only a
+  branch reading rather than something PMOS was told. A session it genuinely cannot place is listed
+  under **not on an initiative** instead of vanishing: an agent that is running should never be
+  invisible on the screen whose job is to tell you what is running.
+- **Bind a session that is already running.** `＋ bind` records what a session is for — including
+  every session that was running before this shipped, and any you started outside PMOS. It is stored
+  as **your declaration**, kept distinct from what PMOS was told first-hand, and re-binding tells you
+  what it replaced. Binding never touches the process: same session, same folder, still running.
+- **The initiative panel lists its live sessions.** Select an initiative and you see the agents on
+  it, each with the same word the sidebar uses — `needs you` · `working` · `quiet 12m` ·
+  `maybe blocked` — and its profile.
+- **Click one to get to it.** If its tab is already open, you go to that tab. If not, a tab opens
+  **attached** to the running session, scrollback and all. It never starts a second agent — the row
+  says which of the two will happen before you click.
+
 ## What's new in 0.24.0
 
 **The initiative board says which work is yours, and which of it has an agent running.** Run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.25.0",
+  "version": "0.26.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@bb78e24
+kernel-source: pmos@6f4c86b
 assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -68,17 +68,22 @@ bar and a 26px status bar, on the oklch token layer, in both themes:
    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
+   something to say: every initiative with a live session, a registered working tree on its
+   `initiative/<id>` 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.
+   **A session records which initiative it is for**, so `＋ session` on an initiative is attributed
+   to it whatever branch you are on — and that survives a server restart. Where nothing was recorded
+   the `initiative/<id>` branch still answers, and the row says when the attribution is only a branch
+   reading. A session PMOS cannot place is never guessed at **and never hidden**: it is listed under
+   *not on an initiative*, and `＋ bind` records what it is for as your own declaration.
+3. **Initiative detail** — the record's header and pills (type / anchor / flow / branch), the
+   **sessions** running on it (each with the same word the sidebar uses — click one to go to its tab
+   if it is open, or to open a tab **attached** to the running session; nothing here ever starts an
+   agent), 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
    references that are not repo files, and **artifacts** with an external destination and the sync
    panel. A record that fails to read renders **red with the parse error** — never a blank panel.

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.26.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/data.js

@@ -957,6 +957,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);

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

@@ -45,8 +45,21 @@
  * Three rules hold it honest. Rows are DUPLICATED, never moved — an initiative keeps its place under
  * its own anchor, because the anchor is the truth (D59) and a shortcut that re-homes work is a second
  * filing system. The group is ABSENT, not empty, when nothing is live. And the join is
- * lib/working-set.js's, which is the server's own `initiative/<id>` two-hopper — so a session the
- * join cannot reach contributes nothing rather than being bucketed somewhere plausible.
+ * lib/working-set.js's — so a session the join cannot reach never lands on a row it does not belong
+ * to.
+ *
+ * ── What that first cut got wrong (workspace-session-attribution) ────────────────────────────
+ * It joined on the `initiative/<id>` branch convention ALONE, which holds in one of four ordinary
+ * situations — and the proof was this file's own history: the initiative that shipped this group was
+ * built on a `claude/*` branch, so the group could not see the session that wrote it. A session now
+ * RECORDS what it is for, and `attributeSessions` resolves recorded → branch → unattributed, saying
+ * which path answered.
+ *
+ * The other half was worse than a narrow join. A session the board could not place was DROPPED, so a
+ * running agent was invisible on the 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 — hence `orphanRows`,
+ * which lists them under the group, claims no initiative for them, and offers the bind that turns
+ * the PM's knowledge into a recorded declaration.
  *
  * Fixture mode is structurally unaffected, not conditionally suppressed: `pollSessions` returns early
  * on FIXTURE and `foldWorkspaces` never runs, so `state.sessions` is empty and there are no branches.
@@ -148,11 +161,26 @@ const branches = () => (state.wsBranches && typeof state.wsBranches === 'object'
  * `return` two modules away.
  */
 function liveSessions() {
-  if (FIXTURE) return {};
+  return attribution().byInitiative;
+}
+
+/**
+ * The full attribution — `{byInitiative, via, unattributed}` — computed ONCE per render and shared
+ * by the row markers, the working-set group, the unattributed row and the search. Deriving it three
+ * times would be three chances to disagree about one fact.
+ *
+ * The join now prefers what a session RECORDED over what its branch is called; `via` says which
+ * answered, and `unattributed` is every live session neither path could place. That last list is
+ * why this returns the whole shape rather than just the map: a running agent PMOS cannot attribute
+ * still has to be visible somewhere, and dropping it was half the defect this fixes.
+ */
+function attribution() {
+  const empty = { byInitiative: {}, via: {}, unattributed: [] };
+  if (FIXTURE) return empty;
   const ws = WS();
-  if (!ws) return {};
+  if (!ws || typeof ws.attributeSessions !== 'function') return empty;
   const map = branches();
-  return ws.sessionsByInitiative(state.sessions, (id) => map[id] || null);
+  return ws.attributeSessions(state.sessions, (id) => map[id] || null);
 }
 
 /**
@@ -161,13 +189,14 @@ function liveSessions() {
  * `onBoard` is what stops a tab or a working tree belonging to ANOTHER repository putting a row on
  * this repository's board — `slugProduct()` is the same map panel 4 scopes its tabs by.
  */
-function workingSet(live, product) {
+function workingSet(attr, product) {
   if (FIXTURE) return [];
   const ws = WS();
   if (!ws) return [];
   const owner = slugProduct();
   return ws.workingSet({
-    live,
+    live: attr.byInitiative,
+    via: attr.via,
     trees: ws.initiativesWithTree(Object.values(branches())),
     tabs: ws.initiativesWithTab(state.tabs),
     onBoard: (slug) => owner[slug] === product,
@@ -224,9 +253,18 @@ export function openTab(tab) {
 }
 
 export function openTerm(slug, sess) {
+  /* THE TAB ID, and why a session with no initiative gets a different one.
+   *
+   * `term:<slug>:<name>` is the id every initiative-opened terminal has always had, and it is what
+   * makes `openTab` focus an already-open tab instead of duplicating it. A session PMOS cannot place
+   * on an initiative has no slug — and interpolating one anyway produced `term:null:agent 1`, where
+   * every unattributed session with the same name would collide on one tab. Keying those by the
+   * SERVER's own session id instead is both collision-free and more honest: the tab is a view of
+   * that process, not of an initiative it does not belong to. */
+  const key = slug ? 'term:' + slug + ':' + sess.name : 'term:sess:' + ((sess && sess.id) || sess.name);
   openTab({
-    id: 'term:' + slug + ':' + sess.name, kind: 'term', title: sess.name, slug,
-    repo: slugProduct()[slug], sess: sess.name, state: sess.st, profile: sess.profile || 'claude-work',
+    id: key, kind: 'term', title: sess.name, slug: slug || null,
+    repo: slug ? slugProduct()[slug] : null, sess: sess.name, state: sess.st, profile: sess.profile || 'claude-work',
     /* The SERVER's session id, when the row that was clicked carries one. This is the exact join:
      * with it, the terminal attaches to precisely the PTY the PM pointed at, and a reload attaches
      * to the same one again. Without it the tab falls back to matching by NAME, and names repeat
@@ -333,11 +371,67 @@ function groupNode(g, product) {
       body.push(el('div', { style: 'padding:5px 12px 6px 27px;font-size:11px;color:var(--muted-foreground);font-style:italic' },
         'nothing filed yet — a successful read of nothing'));
     }
+    // Rows this group carries that are NOT initiatives — today, the live sessions PMOS cannot place.
+    // Appended by the caller so `groupNode` stays the one renderer and does not learn a second model.
+    if (g.after) body.push(g.after);
   }
 
   return el('div', { style: 'margin-top:4px' }, groupHeader, body);
 }
 
+/* ── the live sessions PMOS cannot place ──────────────────────────────────────────────────────
+ *
+ * One row per unattributable live session, under the working-set group, in the same row shape the
+ * initiatives use so the eye reads one list. It deliberately does NOT look like an initiative row:
+ * the id slot carries the session's own name and its glyph is the session state, because this row
+ * stands for a process, not for a record.
+ *
+ * Clicking it opens that session's terminal — the same `openTerm` join every other session click
+ * uses, by the server's id, with no `spawn`. `＋ bind` is the second control: it turns the PM's
+ * knowledge of what the session is for into a recorded declaration, which is the only way a session
+ * started before this field existed can ever join an initiative.
+ */
+function orphanRows(rows) {
+  const ss = SS();
+  const ws = WS();
+  const head = el('div', {
+    style: 'display:flex;align-items:baseline;gap:6px;padding:6px 12px 3px 27px',
+    title: ws ? ws.unattributedTitle(rows) : null,
+  },
+    el('span', { style: 'flex:none;font-family:var(--mono);font-size:10px;color:var(--warning)' }, iv('⌁')),
+    el('span', { style: 'font-size:10.5px;color:var(--muted-foreground);overflow:hidden;text-overflow:ellipsis;white-space:nowrap' },
+      iv('not on an initiative — ' + rows.length + ' live session' + (rows.length === 1 ? '' : 's'))),
+  );
+
+  const body = rows.map((s) => {
+    const st = ss && ss.GLYPH[s.shown] ? s.shown : null;
+    return el('button', {
+      onClick: () => openTerm(null, { name: s.name, st: s.shown, label: s.label, id: s.id, profile: s.profile_id }),
+      style: 'display:flex;align-items:center;gap:7px;width:100%;padding:5px 12px 5px 27px;min-height:32px;border-left:2px solid transparent;background:transparent',
+      hover: 'background:var(--accent)',
+      title: (s.name || s.id) + ' — ' + (s.label || s.shown || '')
+        + '\nPMOS was never told what this session is for. ＋ bind records it.',
+    },
+      el('span', { style: 'flex:none;font-size:12px;color:' + (st && ss ? ss.COLOR[st] : 'var(--muted-foreground)') },
+        st && ss ? ss.GLYPH[st] : '·'),
+      el('span', { style: 'font-family:var(--mono);font-size:12.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:9px;color:var(--muted-foreground)' }, iv(s.label || s.shown || '')),
+    );
+  });
+
+  const bind = el('button', {
+    onClick: () => setState({ bindSess: rows.length === 1 ? rows[0].id : null, bindResult: null, detail: { kind: 'bind' }, col2: true }),
+    style: 'display:flex;align-items:center;gap:7px;width:100%;padding:6px 12px 6px 27px;color:var(--muted-foreground)',
+    hover: 'color:var(--foreground);background:var(--accent)',
+  },
+    el('span', { style: 'flex:none;width:9px;text-align:center;font-size:14px' }, '＋'),
+    el('span', { style: 'font-size:11px' }, 'bind a session to an initiative'),
+  );
+
+  return el('div', null, head, body, bind);
+}
+
 /* ── "matches elsewhere" — artifacts and sessions that the group list cannot show ──────────── */
 
 /**
@@ -522,9 +616,10 @@ export function renderInitiatives(host) {
   const DATA = records();
   const selSlug = selectedSlug();
   const detKind = (state.detail && state.detail.kind) || '';
-  // ONE join per render, shared by the row markers, the working-set group and the search. Computing
-  // it three times would be three chances to disagree about one fact.
-  const live = liveSessions();
+  // ONE attribution per render, shared by the row markers, the working-set group, the unattributed
+  // row and the search. Computing it four times would be four chances to disagree about one fact.
+  const attr = attribution();
+  const live = attr.byInitiative;
 
   /** One row's view model. `why` is null everywhere except in the working-set group. */
   const rowOf = (slug, why) => {
@@ -561,13 +656,26 @@ export function renderInitiatives(host) {
    *
    * Absent when empty. Not a "0", not a placeholder: a heading over nothing is a heading the PM
    * learns to skip. */
-  const now = workingSet(live, product).filter((e) => !q || e.slug.includes(q));
-  if (now.length) {
+  const now = workingSet(attr, product).filter((e) => !q || e.slug.includes(q));
+  /* EVERY LIVE SESSION PMOS CANNOT PLACE (workspace-session-attribution R5).
+   *
+   * The board shipped joining on the `initiative/<id>` branch alone, so a session on `main`, on a
+   * `claude/*` branch, or in a repo with no git simply vanished from it. Refusing to guess which
+   * initiative it belongs to is right; refusing to MENTION it is not, and only the first is honesty.
+   *
+   * It is rendered as a row inside the same group rather than as a group of its own, because it is
+   * not an initiative and must not sit in a list keyed by one. `＋ bind` opens the chooser that
+   * turns it into the PM's own declaration. */
+  const orphans = q ? [] : (attr.unattributed || []);
+  if (now.length || orphans.length) {
+    const rows = now.map((e) => rowOf(e.slug, WS() ? WS().reasonTitle(e) : null));
     kids.push(groupNode({
-      gid: 'NOW', dyn: true, idc: FX.C.brand, gname: 'working on', gct: String(now.length),
+      gid: 'NOW', dyn: true, idc: FX.C.brand, gname: 'working on',
+      gct: String(now.length + orphans.length),
       hasKr: true, krid: '⑂', krname: 'live sessions · checked-out trees · open tabs',
-      inits: now.map((e) => rowOf(e.slug, WS() ? WS().reasonTitle(e) : null)),
+      inits: rows,
       isEmpty: false,
+      after: orphans.length ? orphanRows(orphans) : null,
     }, product));
   }
   for (const g of groups) kids.push(groupNode(g, product));

package/workspace/public/pm/state.js

@@ -50,6 +50,11 @@ function initial() {
      * second click ends it, and anything else disarms. Neither is persisted: a chooser that
      * reappeared on reload would be a question about a moment that has passed. */
     startPrompt: null, endConfirm: null,
+    /* The bind screen's three transient bits (workspace-session-attribution R3): which live session
+     * is selected, what the PM has typed to find an initiative, and the server's own answer to the
+     * last bind. None is persisted — a half-finished declaration restored on reload would be a
+     * question about a moment that has passed, and `bindResult` is a report about one request. */
+    bindSess: null, bindTo: '', bindResult: null,
     col0: true, col1: true, col2: true, scratchOpen: false, scratchText: '', copied: false,
     flowsMap: null, schedList: null, agentList: null, memory: null,
     savedDocs: {}, scratchCopied: false,

package/workspace/public/pm/tab-term.js

@@ -360,7 +360,19 @@ function bind(rec) {
     SOCK.spawning.set(rec.tab.id, true);
     SOCK.spawnQueue.push(rec.tab.id);
     note(rec, 'pmos: starting a session…', true);
-    const ok = send({ t: 'new', name: rec.tab.sess, agent: 'shell', ws: wsForTab(rec.tab) });
+    /* `initiative` is the ONE field this message was missing (workspace-session-attribution R2).
+     * `＋ session` is clicked on an initiative row, `openTerm` puts that row's id on the tab as
+     * `slug`, and `state.js` persists it — so the answer to "what is this session for?" has been
+     * sitting on `rec.tab` at the moment of every spawn, while the message named three other fields.
+     * Without it the server could only infer the initiative from the git branch, which is why a
+     * session on `main` or on `claude/*` was invisible to the board.
+     *
+     * A tab with no slug sends nothing extra and the session is unattributed. That is the honest
+     * outcome, not a failure: the server never refuses a spawn over a label. */
+    const ok = send({
+      t: 'new', name: rec.tab.sess, agent: 'shell', ws: wsForTab(rec.tab),
+      initiative: rec.tab.slug || null,
+    });
     if (!ok) {
       SOCK.spawning.delete(rec.tab.id);
       SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== rec.tab.id);

package/workspace/server.js

@@ -1476,6 +1476,14 @@ function persist(s) {
   // fact: a record persisted before profiles existed restores as "not recorded", and inventing a
   // key for the past would be a lie about it.
   if ('profile' in s) meta.profile = s.profile == null ? null : s.profile;
+  // WHAT THIS SESSION IS FOR, and where that came from. Same `in`-guard as `profile` above and for
+  // the same reason: every session running before this field existed has no attribution, and
+  // writing a key for it would turn "we were never told" into "it belongs to nothing". Both keys
+  // move together — an attribution with no provenance could not be told apart from a reading.
+  if ('initiative' in s) {
+    meta.initiative = s.initiative == null ? null : s.initiative;
+    meta.attributedBy = s.attributedBy || null;
+  }
   try {
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
@@ -1773,6 +1781,16 @@ function sessionList() {
         ? treeShare.roleOf(s.id, treeOfWs.get(s.ws) || null, writerByTree.get(treeOfWs.get(s.ws)))
         : null,
       tree_peers: treeShare.coTenants(rowsAll, treeOfWs, treeOfWs.get(s.ws) || null, s.id).length,
+      // ── what this session is for (workspace-session-attribution R1) ──
+      // THREE STATES, kept apart on the wire because the surface has to tell them apart:
+      //   initiative: 'x', attributed_by: 'spawn'    PMOS was told at spawn — first-hand
+      //   initiative: 'x', attributed_by: 'declared' the PM bound a running session — their word
+      //   initiative: null, attributed_by: null      never recorded — NOT "belongs to nothing"
+      // The branch reading is deliberately NOT folded in here. It is the client's fallback
+      // (lib/working-set.js), computed from `/api/workspaces`, and merging it into this field would
+      // make an inference indistinguishable from a record — the exact confusion this field removes.
+      initiative: 'initiative' in s ? (s.initiative == null ? null : s.initiative) : null,
+      attributed_by: 'initiative' in s ? (s.attributedBy || null) : null,
       profile_id: 'profile' in s ? (s.profile == null ? null : s.profile) : null,
       profile_line: profilesLib.profileLine(
         !('profile' in s) ? undefined
@@ -2133,6 +2151,24 @@ function nextSessionId() {
   return id;
 }
 
+/**
+ * An initiative id, or null — the ONE gate every attribution path goes through.
+ *
+ * `fourPanel.validId` is the repo's existing answer to "is this a record name?" and it is reused
+ * rather than re-typed: it already guards the `/api/initiative` path interpolation and the two
+ * declaration stores, so a second regex here would be a second opinion about what an id is, free to
+ * drift from the one that decides whether a file can be read.
+ *
+ * Returning null rather than throwing is deliberate. An unusable value must leave the session
+ * UNATTRIBUTED — which is a real, honest state with a surface of its own — never half-attributed to
+ * something that failed to parse, and never a spawn refused over a label.
+ */
+function initiativeIdOrNull(v) {
+  if (v == null) return null;
+  const s = String(v).trim();
+  return s && fourPanel.validId(s) ? s : null;
+}
+
 // Resolve a requested profile id BEFORE anything is spawned (profiles R3/R9). The rule the whole
 // feature turns on: a session must never claim a profile whose overlay was not applied. So the
 // three outcomes are kept apart — nothing asked for, asked for and readable, asked for and gone —
@@ -2150,7 +2186,7 @@ function resolveProfileForSpawn(id) {
       : `profile "${id}" is not among the descriptors in ${read.dir} — PMOS will not substitute another` };
 }
 
-function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
+function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative }) {
   const id = nextSessionId();
   const w = getWs(ws);
   const root = w ? w.root : SELF_ROOT;
@@ -2172,6 +2208,24 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
   const base = { id, ws: w ? w.id : wsId(SELF_ROOT), root, name: (name && String(name).trim()) || agent, agent, origin: tag,
     profile: pres.id, profileRefusal: pres.ok ? null : pres.error };
 
+  /* WHAT THIS SESSION IS FOR (workspace-session-attribution R1).
+   *
+   * A PMOS session has never recorded which initiative it is working on — not here, not on the wire,
+   * not on disk — so every initiative-keyed surface had to INFER it from the `initiative/<id>` branch
+   * convention, which holds in one of four ordinary situations. The board that shipped on that
+   * inference could not see the session that wrote it, because that session was on a `claude/*`
+   * branch.
+   *
+   * The key is set ONLY when the caller supplied one, exactly as `profile` is, and for the same
+   * reason: its ABSENCE has to stay a fact. A session started before this field existed, or started
+   * outside PMOS, restores as not-recorded — and "not recorded" must never be confused with
+   * "recorded as none", which is what a `null` default would have produced. `attributedBy` says
+   * where the value came from, because a value the PM declared and a value PMOS was told at spawn
+   * are different claims and the surface has to be able to tell them apart.
+   */
+  const init = initiativeIdOrNull(initiative);
+  if (init) { base.initiative = init; base.attributedBy = 'spawn'; }
+
   // A missing agent CLI is detected BEFORE any spawn (on Linux the exec-in-fork failure is
   // otherwise silent) — the same honest exited pane on both the tmux and the direct path.
   if (!isShell && !commandExists(agent)) {
@@ -2247,7 +2301,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
 // A FAILED git operation in a real repo must never spawn a session on the wrong branch (rubric
 // hard floor): we return {ok:false} and spawn nothing. Kept as its own function so the
 // git-then-maybe-spawn contract is unit-testable without a WS client.
-function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative }) {
   const w = getWs(ws);
   if (!w) return { ok: false, error: 'no workspace' };
   // The profile is checked BEFORE any git operation. A composer that picked a profile PMOS cannot
@@ -2289,7 +2343,7 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
       broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
     }
   }
-  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative });
   // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
   // block above. The isolate default already computes that other sessions would be disturbed — and
   // then the whole git block is skipped when no branch was picked, which is the common path and the
@@ -2377,6 +2431,10 @@ function startWork({ initiative, repoKey, ws, agent, name, profile }) {
     createBranch: plan.createBranch,
     isolate: plan.isolate,
     profile,
+    // THE FIX THIS FUNCTION HAS BEEN ONE ARGUMENT AWAY FROM SINCE IT WAS WRITTEN. `initiative`
+    // arrived here, decided the branch and supplied a fallback display name, and was then dropped
+    // — so the one start path DESIGNED to know what it was starting work on never told the session.
+    initiative,
   });
   if (!r.ok) return r;
   return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
@@ -3994,6 +4052,45 @@ async function handleRequest(req, res) {
     // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
     return json(res, { ws: w ? w.id : null, ...out });
   }
+  if (p === '/api/session/initiative' && req.method === 'POST') {
+    /* Bind a RUNNING session to an initiative — the PM's own word about work already in flight
+     * (workspace-session-attribution R3/R8).
+     *
+     * Every session running when this shipped has no attribution, and so does every session started
+     * outside PMOS. Without this they would stay unattributed forever, which would make the whole
+     * field a promise about the future and no help with the work on screen today.
+     *
+     * Three properties this endpoint holds:
+     *   1. It is a DECLARATION. `attributedBy: 'declared'` is written, never 'spawn', so the surface
+     *      can keep the PM's word apart from what PMOS was told first-hand. Same distinction
+     *      `initiative-links.jsonl` already draws with `origin`/`state`.
+     *   2. It is SINGLE-VALUED, and a replacement says what it replaced. `previous` comes back on
+     *      the response rather than being overwritten with no trace (R8) — a re-bind the PM did not
+     *      mean to do is otherwise unrecoverable and unnoticeable.
+     *   3. It touches NOTHING else. No checkout, no branch, no respawn. The session keeps running
+     *      exactly as it was; the only thing that changes is what PMOS says it is for.
+     *
+     * `initiative: null` CLEARS the binding, which is the honest way back from a wrong one — and it
+     * still writes the key, because a session the PM has explicitly unbound is a different state
+     * from one that was never recorded.
+     */
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const s = sessions.get(String(body.id || ''));
+    if (!s) return json(res, { ok: false, error: 'no such session' }, 404);
+    const clearing = body.initiative === null || body.initiative === '';
+    const next = clearing ? null : initiativeIdOrNull(body.initiative);
+    if (!clearing && !next) {
+      return json(res, { ok: false, error: 'that initiative id is not a record name' }, 400);
+    }
+    const previous = 'initiative' in s ? (s.initiative || null) : null;
+    s.initiative = next;
+    s.attributedBy = next ? 'declared' : null;
+    persist(s);
+    pushSessions();
+    return json(res, { ok: true, id: s.id, initiative: next, attributed_by: s.attributedBy, previous });
+  }
   if (p === '/api/initiative/link' && req.method === 'POST') {
     // Recording that an artifact corresponds to an external page. This writes a DECLARATION and
     // makes no request: PMOS holds no credential, so it can state what the PM says the mapping is
@@ -4522,7 +4619,10 @@ wss.on('connection', (ws) => {
     } else if (m.t === 'resize') {
       const s = sessions.get(m.id); if (s && s.pty) { try { s.pty.resize(m.cols, m.rows); s.cols = m.cols; s.rows = m.rows; } catch {} }
     } else if (m.t === 'new') {
-      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile });
+      // `initiative` is what the client has always held and never sent: `＋ session` is clicked on
+      // an initiative row, the tab carries its `slug`, and the spawn message named three other
+      // fields. An absent or unusable value leaves the session unattributed — never a refused spawn.
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile, initiative: m.initiative });
       // A refused profile is its own sentence, not "branch: …" — the composer's error line names
       // what PMOS could not read, and nothing was started.
       if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'branch: ') + r.error })); return; }