create-pmos 0.24.0 → 0.26.0

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

@@ -37,6 +37,12 @@ function initial() {
     detail: { kind: 'init' },
     tabs: [], active: null, splitId: null,
     initLinks: {}, artLinks: {}, artSyncOpen: {}, artSyncState: {},
+    /* The sync half of panel 3, all per-window and none of it persisted. `artSyncTask` holds the
+     * task text the server composed for a direction the PM just chose; `linkGone` holds the
+     * references withdrawn since the last hydration, so a retracted row leaves the screen at the
+     * click rather than at the next read. Neither is a source of truth — what a link IS and what
+     * was synced both come back from the store on the next `/api/initiative`. */
+    artSyncTask: {}, linkGone: {},
     extraSess: {}, termHist: {}, startN: 1, docEdits: {}, docModes: {},
     /* `＋ session` into a working tree that already has sessions in it opens a CHOOSER instead of
      * spawning (workspace-session-choice): `{slug, tree, branch, peers}` while it is open, null
@@ -44,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

@@ -702,11 +702,21 @@ function readTextDoc(root, rel) {
 // falling back to the filename convention when an artifact declares nothing.
 // Ordered LONGEST-DISCRIMINATOR-FIRST: `-copy-brief` must be tested before `-brief`, and
 // `-eval-rubric` before any `-rubric`, because the first match wins and slices the stem.
+//
+// The qualified-brief entries (`-comms-brief`, `-launch-brief`) are here for a reason worth stating,
+// because it is the same reason `-copy-brief` was: a stem ending `-comms-brief` ALSO ends `-brief`,
+// so without its own entry it matches the shorter one and the slice leaves a `-comms` tail on the
+// stem. That tail belongs to the qualifier, not to the initiative, and it is enough to put a comms
+// brief in a different group from the PRD it was written for — which is precisely what the PM
+// reported seeing (PRD, defect 3).
 const ROLE_SUFFIXES = [
   ['-eval-rubric', 'rubric'], ['-design-brief', 'design brief'], ['-design-reference', 'design'],
-  ['-copy-brief', 'copy brief'], ['-user-stories', 'user stories'], ['-copy', 'copy'],
+  ['-copy-brief', 'copy brief'], ['-comms-brief', 'comms brief'], ['-launch-brief', 'launch brief'],
+  ['-user-stories', 'user stories'], ['-user-story', 'user stories'], ['-stories', 'user stories'],
+  ['-one-pager', 'one-pager'], ['-copy', 'copy'],
   ['-dogfood', 'dogfood'], ['-reconcile', 'reconcile'], ['-findings', 'findings'],
   ['-scoping', 'scoping'], ['-intake', 'intake'], ['-brief', 'brief'], ['-prd', 'PRD'],
+  ['-spec', 'spec'],
 ];
 const ROLE_BY_DIR = {
   prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
@@ -864,12 +874,34 @@ function initiativeIndex(root) {
   for (const m of metas) if (!m.initiative) byStem.set(m.stem, (byStem.get(m.stem) || 0) + 1);
   const groups = new Map();
   const ungrouped = [];
+  // PREFIX ATTACHMENT, and the three constraints that keep it from becoming a similarity score.
+  //
+  // The join above is stem EQUALITY, and equality is the wrong shape for how PMs name files. An
+  // initiative `ooh-zbsg-ast1` carries `ooh-zbsg-ast1-design-prd.md`, `ooh-zbsg-ast1-user-stories.md`
+  // and `ooh-zbsg-ast1-comms-brief.md`; after the role suffix is sliced those are three DIFFERENT
+  // stems, so the initiative's own PRD was attributed to no initiative and never reached panel 3.
+  // Measured on this repository one initiative ago: 148 documents attributed to nothing, 31 of them
+  // beginning with a declared id.
+  //
+  //   1. Only EXPLICITLY DECLARED ids may capture (`declared`, not `groups`). A group that exists
+  //      only because two filenames happened to share a stem was never named by anyone, and giving
+  //      it the authority to claim documents would let a naming coincidence annex a neighbourhood.
+  //   2. LONGEST WINS, so `workspace-session-choice-prd.md` cannot be captured by `workspace-session`
+  //      when both are declared. Sorted once per call, not per document.
+  //   3. It runs LAST, after equality and after the convention join, so it can only move a document
+  //      that would otherwise be `ungrouped`. It cannot take a document away from a group that has a
+  //      better claim on it, which is what makes the total document count provably unchanged.
+  //
+  // The boundary being held here is the one `lib/related-docs.js` holds for the same reason: a
+  // concrete tie, never "feels related". `x-` is a tie the PM typed. Similarity is not.
+  const capturing = [...declared].sort((a, b) => b.length - a.length);
+  const prefixOwner = (stem) => capturing.find((id) => stem.length > id.length + 1 && stem.startsWith(id + '-')) || null;
   const keyFor = (m) => {
     if (m.initiative) return m.initiative;
     if (declared.has(m.stem)) return m.stem;
     // the convention join: `jira-sync-prd.md` + `jira-sync-eval-rubric.md` are one unit
     if ((byStem.get(m.stem) || 0) > 1) return m.stem;
-    return null;
+    return prefixOwner(m.stem);
   };
   for (const m of metas) {
     const k = keyFor(m);
@@ -1444,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);
@@ -1741,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
@@ -2101,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 —
@@ -2118,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;
@@ -2140,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)) {
@@ -2215,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
@@ -2257,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
@@ -2345,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 };
@@ -3952,6 +4042,7 @@ async function handleRequest(req, res) {
         : null,
       artifactLinks: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_LINKS),
       initiativeLinks: fourPanel.readDeclarations(stateDir, fourPanel.INITIATIVE_LINKS),
+      artifactSync: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_SYNC),
       // Which destinations a session could look up, derived from the PM's agent profiles. The home
       // directory is passed IN rather than read inside four-panel.js for the same reason
       // readProfiles takes it as a parameter: a module that reads os.homedir() itself can only be
@@ -3961,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
@@ -3986,6 +4116,36 @@ async function handleRequest(req, res) {
     // A write that failed returns 500 and says so — never a false green (the /api/gate rule).
     return json(res, { ...wrote, connectors: fourPanel.connectors(os.homedir()) }, wrote.ok ? 200 : 500);
   }
+  if (p === '/api/initiative/sync' && req.method === 'POST') {
+    // The PM chose a direction for a link they already recorded, or a session is reporting what it
+    // did about one. Both arrive here, and the difference between them is exactly the difference the
+    // store enforces: a direction the PM chose is `proposed` and claims nothing, while a session's
+    // report is `applied` and is REFUSED unless it names the profile that performed it.
+    //
+    // This route composes the task text and appends the row. It performs no sync — there is no
+    // branch here that contacts Confluence, Jira or Google, and there cannot be one: the workspace
+    // holds no credential (D53), and `no-network.test.js` asserts the absence structurally.
+    const w = getWs(url.searchParams.get('ws'));
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w2 = body.ws ? getWs(body.ws) : w;
+    const built = fourPanel.syncRow(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    const task = fourPanel.syncTask({
+      direction: built.row.direction, kind: built.row.kind,
+      artifact_path: built.row.artifact_path, target: built.row.target, profile: body.profile || null,
+    });
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, error: engine.error }, 500);
+    const stateDir = fourPanel.storeDir(engine.engine, w2 ? w2.root : SELF_ROOT);
+    const wrote = fourPanel.appendDeclaration(stateDir, fourPanel.ARTIFACT_SYNC, built.row);
+    // A write that failed returns 500 and says so — never a false green (the /api/gate rule). The
+    // task is returned either way: a PM whose store is unwritable can still run the work by hand,
+    // and withholding the text would turn a recording failure into a capability failure.
+    return json(res, { ...wrote, task: task.ok ? task.text : null, task_error: task.ok ? null : task.error },
+      wrote.ok ? 200 : 500);
+  }
   if (p === '/api/initiative/lookup-task' && req.method === 'POST') {
     // The task a SESSION runs to resolve a reference. This endpoint composes a string and returns
     // it. It contacts nothing — that is the entire point of the design: PMOS describes the lookup,
@@ -4459,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; }