create-pmos 0.24.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.24.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@ac2ee81
+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/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/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.24.0",
+  "version": "0.26.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.24.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.24.0",
+  "version": "0.26.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",