create-pmos 0.18.1 → 0.20.0

package/workspace/lib/tree-share.js

@@ -1,5 +1,7 @@
 'use strict';
-// Who shares a working tree with whom, and who is DECLARED to be driving it.
+// Who shares a working tree with whom, who is DECLARED to be driving it, and — since
+// workspace-session-choice — what each of those sessions is actually DOING and what ending it
+// would cost.
 //
 // The premise, stated once so nothing below has to hedge: PMOS hosts real PTYs and the agent CLI
 // inside one is untouched (D62). There is nothing between an agent and the filesystem, so this
@@ -21,6 +23,23 @@
 //
 // Pure functions over plain rows, on purpose: the server owns the git shell-outs and the session
 // registry, and the rules are the part worth testing without either.
+//
+// ── ONE module, TWO consumers ────────────────────────────────────────────────────────────────
+// This file is now a UMD, for the same reason lib/session-state.js is: the SERVER computes the
+// co-tenancy sentence at spawn, and the BROWSER computes the same descriptions again when the PM
+// clicks `＋ session` into an occupied tree. A second copy of "what does ending this cost?" would
+// be free to drift, and the two surfaces would end up holding different opinions about one
+// session — the exact failure the session-state table was extracted to stop.
+//
+// What this module deliberately does NOT do is name a session's STATE. The vocabulary (working ·
+// quiet · needs you · maybe blocked · exited) belongs to lib/session-state.js and arrives here
+// already worded, on the row, as `shown` + `label`. Re-deriving a word here would be that second
+// copy in a new costume.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSTreeShare = api;
+})(typeof self !== 'undefined' ? self : this, function () {
 
 /** Live = a session the PM could still be driving. `exited` is a corpse and collides with nobody. */
 function isLive(s) { return !!s && s.state !== 'exited'; }
@@ -73,18 +92,138 @@ function nameList(rows, cap = 3) {
   return `${names.slice(0, cap).join(', ')} and ${names.length - cap} more`;
 }
 
+/** The same list, each pane carrying the word beside it — `label` when the caller supplied one. */
+function statedList(rows, cap = 3) {
+  const parts = (rows || []).map((s) => (s && s.label ? `“${s.name}” (${s.label})` : `“${s.name}”`));
+  if (parts.length <= cap) return parts.join(', ');
+  return `${parts.slice(0, cap).join(', ')} and ${parts.length - cap} more`;
+}
+
+/** A terse age, in the voice the sidebar already uses. `null` in, `null` out — never "0s". */
+function ago(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms < 0) return null;
+  if (ms < 60000) return `${Math.max(1, Math.round(ms / 1000))}s`;
+  if (ms < 3600000) return `${Math.round(ms / 60000)}m`;
+  return `${Math.round(ms / 360000) / 10}h`;
+}
+
+/**
+ * WHAT ENDING THIS SESSION WOULD COST — read only from what the workspace can actually observe.
+ *
+ * The PM's question, asked in as many words, is "is it safe to end?". The honest answer has three
+ * shapes and only one of them is a yes, so the levels are named for the EVIDENCE rather than for a
+ * recommendation:
+ *
+ *   'in-flight' — bytes are arriving right now. Ending it cuts a turn that is running. Not safe,
+ *                 and this one PMOS is sure of.
+ *   'settled'   — the turn finished and the session is waiting on the human (`needs`). This is the
+ *                 only state where "nothing is in flight" is CORROBORATED — session-state reaches
+ *                 `needs` only from a transcript with no unresolved tool call, over a quiet clock.
+ *   'unknown'   — quiet, or a tool call open with nothing moving. The workspace cannot tell a
+ *                 finished turn from a permission prompt from a hung tool, and this is the state it
+ *                 must not launder into a yes. Saying "probably idle" is the whole point: an
+ *                 over-confident "safe" here is the watermelon this repo has a word for.
+ *   'gone'      — already exited; there is nothing left to end.
+ *
+ * `shown` is the presented state from lib/session-state.js. An unrecognised value falls to
+ * 'unknown', because a state this module has never heard of is precisely not a state it may
+ * declare safe.
+ */
+function endRisk(shown, quietMs) {
+  const age = ago(quietMs);
+  if (shown === 'exited') {
+    return { level: 'gone', why: 'already exited — there is nothing left to end' };
+  }
+  if (shown === 'working') {
+    return { level: 'in-flight', why: 'output is arriving right now — ending it cuts a turn that is still running' };
+  }
+  if (shown === 'needs') {
+    return {
+      level: 'settled',
+      why: 'its turn finished and it is waiting on you — ending it costs the scrollback, not work in flight',
+    };
+  }
+  if (shown === 'blocked') {
+    return {
+      level: 'unknown',
+      why: `a tool call has been open${age ? ` ${age}` : ''} with nothing moving — PMOS cannot tell a permission prompt from a stuck tool, so ending it may or may not discard work`,
+    };
+  }
+  return {
+    level: 'unknown',
+    why: `nothing has moved${age ? ` for ${age}` : ''}, and PMOS cannot see whether the turn finished — read this as “probably idle”, not “safe”`,
+  };
+}
+
+/**
+ * One co-tenant, described for a human who is deciding between joining it and starting another.
+ *
+ * Everything here is either copied off the row or derived by `endRisk`; nothing is invented. In
+ * particular `doing` is the agent's own last words as the sidebar already shows them, and it stays
+ * null when the workspace could not read them rather than becoming a cheerful placeholder.
+ */
+function describeTenant(row, writerId) {
+  const s = row || {};
+  const shown = s.shown || (s.state === 'exited' ? 'exited' : 'working');
+  return {
+    id: s.id || null,
+    ws: s.ws || null,
+    name: s.name || '(unnamed)',
+    agent: s.agent || null,
+    shown,
+    label: s.label || shown,
+    doing: s.doing || null,
+    branch: s.branch || null,
+    writer: !!(writerId && s.id === writerId),
+    risk: endRisk(shown, s.quietMs),
+  };
+}
+
+/**
+ * The whole answer to "you are about to start a session in a tree that is already busy".
+ *
+ * Returned as DATA rather than as a paragraph, because the two consumers need different shapes of
+ * it: the server writes a sentence into the pane's scrollback, and the browser draws a chooser with
+ * a button per peer. Both read the same `peers`, so a peer the chooser offers and a peer the pane
+ * line names can never be different sets.
+ */
+function coTenancyReport(mates, opts) {
+  const o = opts || {};
+  const peers = (mates || []).map((m) => describeTenant(m, o.writerId));
+  const n = peers.length;
+  return {
+    tree: o.tree || null,
+    branch: o.branch || null,
+    peers,
+    headline: n
+      ? `${n} session${n === 1 ? '' : 's'} already running in this working tree`
+      : 'nothing else is running in this working tree',
+    // Stated once, here, so every surface that renders this report carries the same limit.
+    shared: 'you share one branch, one index and one set of files with '
+      + (n === 1 ? 'it' : 'them'),
+    advisory: 'Claims are advisory: PMOS hosts your agent’s terminal, it does not sit between it and the files.',
+    escape: 'To work in parallel for real, start the session on a new branch with its own folder (⑂).',
+  };
+}
+
 /**
  * The sentence a session gets when it starts in a tree somebody is already working in.
  *
- * It names the panes (a bare count tells the PM nothing they can act on), states the ONE fact that
- * makes this matter — a shared branch, index and file set — and names the way out that already
- * exists, because a warning with no alternative is just a nag. Returns null when there is nobody
- * there, so the caller never has to test for emptiness.
+ * It names the panes AND what each of them is doing — a name alone tells the PM which pane, but not
+ * whether walking over to it is a good idea. `label` is the sidebar's own word for the session
+ * (working · quiet 12m · needs you · maybe blocked), passed in rather than re-derived, so this
+ * sentence and the sidebar cannot disagree. Rows with no label degrade to bare names rather than
+ * inventing a state.
+ *
+ * It states the ONE fact that makes this matter — a shared branch, index and file set — and names
+ * the way out that already exists, because a warning with no alternative is just a nag. Returns
+ * null when there is nobody there, so the caller never has to test for emptiness.
  */
 function coTenancyNotice(mates, opts) {
   const rows = mates || [];
   if (!rows.length) return null;
   const n = rows.length;
+  const rep = coTenancyReport(rows, opts);
   const role = opts && opts.role === 'writer' ? 'writer' : 'reader';
   const held = opts && opts.writerName;
   const who = role === 'writer'
@@ -94,23 +233,40 @@ function coTenancyNotice(mates, opts) {
     : held
       ? `“${held}” holds the writer claim`
       : 'no session holds the writer claim';
-  return `${n} session${n === 1 ? '' : 's'} already running in this working tree (${nameList(rows)}) — `
-    + `you share one branch, one index and one set of files with ${n === 1 ? 'it' : 'them'}. ${who}. `
-    + 'Claims are advisory: PMOS hosts your agent’s terminal, it does not sit between it and the '
-    + 'files. To work in parallel for real, start the session on a new branch with its own folder (⑂).';
+  return `${rep.headline} (${statedList(rows)}) — ${rep.shared}. ${who}. `
+    + `${rep.advisory} ${rep.escape} `
+    + `To join ${n === 1 ? 'it' : 'one of them'} instead of starting another, open it from ＋ session — `
+    + 'the chooser says what each one is doing and what ending it would cost.';
 }
 
 /**
  * The same fact, written into the pane's own scrollback at spawn.
  *
  * The notice frame is a transient line in whichever client was listening; this one is part of the
- * session's record, so re-opening the tab tomorrow still shows what it was told. Dim, one line,
- * and it never claims anything was prevented.
+ * session's record, so re-opening the tab tomorrow still shows what it was told. Dim, and it never
+ * claims anything was prevented.
+ *
+ * It is no longer ONE line. The sentence is followed by a row per peer carrying that peer's state
+ * and what ending it would cost — the same `peers` the chooser draws, in the same order, because
+ * the PM who scrolls back to this tomorrow is asking the identical question they asked at the
+ * chooser and deserves the identical answer. Bounded at four rows so a twelve-session tree cannot
+ * push the shell's first prompt off the screen; the sentence above already says the true count.
  */
+const ADVISORY_ROWS = 4;
 function paneAdvisory(mates, opts) {
   const line = coTenancyNotice(mates, opts);
   if (!line) return null;
-  return `\x1b[38;5;244m⑂ ${line}\x1b[0m\r\n`;
+  const rep = coTenancyReport(mates, opts);
+  const shown = rep.peers.slice(0, ADVISORY_ROWS);
+  const rows = shown.map((p) => {
+    const who = `${p.name}${p.writer ? ' (writer)' : ''}`;
+    const doing = p.doing ? ` · ${p.doing}` : '';
+    return `\x1b[38;5;244m   · ${who} — ${p.label}${doing}; ${p.risk.why}\x1b[0m\r\n`;
+  });
+  const more = rep.peers.length > shown.length
+    ? [`\x1b[38;5;244m   · …and ${rep.peers.length - shown.length} more, listed in ＋ session\x1b[0m\r\n`]
+    : [];
+  return `\x1b[38;5;244m⑂ ${line}\x1b[0m\r\n` + rows.join('') + more.join('');
 }
 
 /**
@@ -126,4 +282,6 @@ function joinNotices(...parts) {
   return kept.length ? kept.join(' · ') : null;
 }
 
-module.exports = { isLive, coTenants, writerOf, roleOf, coTenancyNotice, paneAdvisory, joinNotices, nameList };
+return { isLive, coTenants, writerOf, roleOf, coTenancyNotice, paneAdvisory, joinNotices,
+  nameList, statedList, ago, endRisk, describeTenant, coTenancyReport, ADVISORY_ROWS };
+});

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "private": true,
-  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
+    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/index.html

@@ -29,6 +29,12 @@
      holding different opinions about one session. Loaded before the module graph so a panel can
      bind from window.PMOSSessionState rather than re-typing a word. -->
 <script src="/lib/session-state.js"></script>
+<!-- ONE module, TWO consumers, again (workspace-session-choice). Who shares a working tree, and
+     what ending one of those sessions would cost, is computed by the SERVER when it writes the
+     advisory into a new pane's scrollback and by the BROWSER when it draws the ＋ session chooser.
+     Both read this file, so the sentence in the terminal and the sentence in the chooser cannot
+     drift apart. Classic script (a UMD setting window.PMOSTreeShare), like the two above. -->
+<script src="/lib/tree-share.js"></script>
 <!-- The phone's navigation reducer. DOM-free, loaded as a classic script (it is a UMD that sets
      window.PMOSMobileNav) and required by test.js, so the whole screen domain is walkable in node
      rather than only in a browser. pm/mobile.js reads it from the global; the module graph does not

package/workspace/public/pm/app.js

@@ -83,9 +83,35 @@ function runningCount() {
 
 /* ── the shell, built once ─────────────────────────────────────────────────────────────────── */
 
+/* ── Why every track and every column here is `minmax(0, …)` / `min-height:0` ─────────────────
+ *
+ * The shell is 100vh and nothing in it is supposed to scroll the PAGE — a panel scrolls, the app
+ * never does. That held right up until a long document was opened in panel 4, and then the whole
+ * user interface scrolled: the top bar slid away, the status bar came up from below, and the doc
+ * pane's own `overflow-y:auto` never engaged.
+ *
+ * The cause is one CSS default, in two guises, and it is worth naming precisely because it is
+ * invisible in a style string that looks correct:
+ *
+ *   • `grid-template-rows: 44px 1fr 26px` — `1fr` is shorthand for `minmax(auto, 1fr)`, and that
+ *     `auto` MINIMUM is the item's min-content height. A tall document therefore does not overflow
+ *     the middle row; it ENLARGES it, past the 100vh the row was supposed to be trapped inside.
+ *   • a grid item / flex item with `min-height: auto` cannot shrink below its content either, so
+ *     even a correctly-sized track hands the overflow straight through to the next box down.
+ *
+ * Overflow that is `visible` still contributes to the SCROLLABLE overflow region of every ancestor
+ * that does not clip it, all the way up to the viewport — which is exactly the reported symptom:
+ * the page scrolls, not the pane. So the fix is the whole chain, not one box. Each ancestor between
+ * the viewport and a scrolling pane declares a zero minimum, and the root clips as the backstop so
+ * a future panel that forgets cannot reach the page again.
+ *
+ * The design prototype had this right (`grid-template-rows:44px minmax(0,1fr) 28px`, see
+ * prototype/workspace-layout-variants/*.html); the port dropped the `minmax(0, …)` and read
+ * identically until something tall was rendered into it.
+ */
 const root = el('div', {
   'data-pm-theme': state.theme,
-  style: 'display:grid;grid-template-rows:44px 1fr 26px;height:100vh;background:var(--background);color:var(--foreground);font-family:var(--sans);font-size:13px;line-height:1.5',
+  style: 'display:grid;grid-template-rows:44px minmax(0,1fr) 26px;height:100vh;overflow:hidden;background:var(--background);color:var(--foreground);font-family:var(--sans);font-size:13px;line-height:1.5',
 });
 
 const themeBtn = el('button', {
@@ -113,7 +139,14 @@ const statusBar = el('div', {
   el('span', { style: 'margin-left:auto' }, 'sessions survive detach · ⌘K search · Esc closes tab'),
 );
 
-const bodyGrid = el('div', { style: 'display:grid;grid-template-columns:' + gridCols() + ';min-height:0' });
+/* The body grid's own geometry, in one place so the initial build and every repaint below cannot
+ * disagree. The implicit ROW is stated explicitly as `minmax(0,1fr)` for the same reason the root's
+ * middle track is: an auto row is floored at its items' min-content height, and one tall panel
+ * would push the grid taller than the box it was given. */
+const BODY_GRID_STYLE = () =>
+  'display:grid;grid-template-columns:' + gridCols() + ';grid-template-rows:minmax(0,1fr);min-height:0;overflow:hidden';
+
+const bodyGrid = el('div', { style: BODY_GRID_STYLE() });
 
 /** The collapsed 36px strip: a full-height button with a rotated vertical-rl label. */
 function makeRail(flag) {
@@ -131,10 +164,14 @@ const rail1 = makeRail('col1');
 const rail2 = makeRail('col2');
 rail0.label.textContent = 'repositories ⟩';
 
-const hostRepos = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);display:flex;flex-direction:column;min-width:0' });
-const hostInits = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0' });
-const hostDetail = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0;display:flex;flex-direction:column' });
-const hostTabs = el('div', { style: 'background:var(--term-bg);display:flex;flex-direction:column;min-width:0' });
+/* `min-height:0` on all four: a grid item's automatic minimum is its content, so a panel taller
+ * than the viewport would otherwise stretch the row it sits in rather than scroll inside it. The
+ * two that already carry `overflow-y:auto` get it for free under the spec — stated anyway, because
+ * "this one is safe because of a rule elsewhere in the same line" is how the next edit breaks it. */
+const hostRepos = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);display:flex;flex-direction:column;min-width:0;min-height:0;overflow-y:auto' });
+const hostInits = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0;min-height:0' });
+const hostDetail = el('div', { style: 'background:var(--sidebar);border-right:1px solid var(--border);overflow-y:auto;min-width:0;min-height:0;display:flex;flex-direction:column' });
+const hostTabs = el('div', { style: 'background:var(--term-bg);display:flex;flex-direction:column;min-width:0;min-height:0;overflow:hidden' });
 
 setChildren(root, [topBar, bodyGrid, statusBar]);
 
@@ -172,7 +209,7 @@ function render() {
   rail1.label.textContent = modeTitle() + ' ⟩';
   rail2.label.textContent = detailTitle() + ' ⟩';
 
-  bodyGrid.setAttribute('style', 'display:grid;grid-template-columns:' + gridCols() + ';min-height:0');
+  bodyGrid.setAttribute('style', BODY_GRID_STYLE());
 
   // On a phone there are no rails to collapse into and no second column to fold away: the four
   // hosts all stay mounted, one is DISPLAYED (pm/mobile.css picks it from `data-mpanel`), and the

package/workspace/public/pm/data.js

@@ -277,9 +277,13 @@ function evalFor(ladderSteps) {
 
 /** A live session, in the shape panel 2 and panel 4 read. `shown` is the server's own derived state. */
 function sessionRow(s) {
-  const label = s.shown === 'quiet' && Number.isFinite(s.quietMs)
+  // `s.label` is the SERVER's rendering of the presented state — one join (lib/session-state's
+  // `label`), one clock, one sentence. This used to be re-derived here from `shown` + `quietMs`,
+  // which is how the sidebar and the pane could describe one session with two different words. The
+  // local derivation survives only as a fallback for a server that predates the field.
+  const label = s.label || (s.shown === 'quiet' && Number.isFinite(s.quietMs)
     ? 'quiet ' + Math.max(1, Math.round(s.quietMs / 60000)) + 'm'
-    : (s.shown === 'needs' ? 'needs you' : s.shown);
+    : (s.shown === 'needs' ? 'needs you' : s.shown));
   return { name: s.name, st: s.shown, label, profile: s.profile_id || null, id: s.id };
 }
 
@@ -441,10 +445,34 @@ function groupsFromSpine(spine) {
 const products = new Map();   // product name → {name, ws, root, count, board, records}
 let productOrder = [];
 
+/* workspace id → the working-tree top it sits in (null for a folder with no git).
+ *
+ * This exists so panel 4 can answer "who else is already in the tree I am about to start a session
+ * in?" BEFORE it starts one. The session rows carry `tree` too, but only for trees that already
+ * have a session — which is one session too late for a chooser that runs on the FIRST click. The
+ * server derives this (`git rev-parse --show-toplevel`, via `repoIdentity`) and publishes it on
+ * /api/workspaces; it is read here and never re-derived. */
+const wsTree = new Map();
+
+/** The working tree a workspace id sits in, or null — for a folder with no git, or an unknown id. */
+export function treeOfWorkspace(id) {
+  return (id && wsTree.get(id)) || null;
+}
+
+/** The branch that tree is on, or null. Shown beside the tree so a chooser names what is shared. */
+const wsBranch = new Map();
+export function branchOfWorkspace(id) {
+  return (id && wsBranch.get(id)) || null;
+}
+
 /** Group registered working trees into products: several worktrees of one repo share a `repo_key`. */
 function foldWorkspaces(rows) {
   const byRepo = new Map();
   for (const w of rows || []) {
+    // Recorded per REGISTERED id, before the fold — folding is by repository, and the whole point
+    // of the tree key is that two registered ids can share one tree while a repo's two worktrees do
+    // not. Reading it off the folded row would lose exactly that distinction.
+    if (w && w.id) { wsTree.set(w.id, w.tree || null); wsBranch.set(w.id, w.branch || null); }
     const key = w.repo_key || w.root;
     if (!byRepo.has(key)) {
       byRepo.set(key, {
@@ -941,6 +969,18 @@ export async function recordArtifactLink({ artifact_path, slug, kind, target })
   return out;
 }
 
+/**
+ * panel-detail.js — `lookupTask({kind, subject, hint, profile})`.
+ *
+ * Asks the server to compose the task a SESSION will run to resolve a reference. It returns text.
+ * Nothing here contacts Jira, Confluence or Google, and nothing here can: the workspace holds no
+ * credential (D53 — the agent layer acts with the PM's own MCP, PMOS records the result).
+ */
+export async function lookupTask({ kind, subject, hint, profile }) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode composes no task' };
+  return postJson('/api/initiative/lookup-task', { kind, subject, hint, profile });
+}
+
 /** panel-detail.js — `recordInitiativeLink({slug, kind, label, path, st})` → `initiative-links.jsonl`. */
 export async function recordInitiativeLink({ slug, kind, label, path }) {
   if (FIXTURE) return { ok: true };

package/workspace/public/pm/fixture.js

@@ -790,7 +790,30 @@ export const artDiffText = dest => 'repo file is the source. read ' + (dest ? de
 export const artSyncPushed = dest => ({ color: 'var(--success)', text: 'pushed · repo → ' + dest.kind + ' · in sync 12:41' });
 export const artSyncPulled = dest => ({ color: 'var(--warning)', text: 'pulled · ' + dest.kind + ' → repo · file updated' });
 
-/** addLink (lines 1757–1766) — the link a source button appends. */
+/* addLink (lines 1757–1766) — PROTOTYPE TRANSCRIPTION ONLY. It has no caller, and must not gain one.
+ *
+ * This is the helper the whole workspace-external-linking initiative was opened about. It returns
+ * `{kind:'jira epic', label:'ATL-501 · <slug>', path:'jira://ATL-501', st:'connected'}` — a Jira key
+ * counted up from the constant 501, a label built from the initiative slug, and the word `connected`
+ * on a row nothing had read. panel-detail.js called it on every ＋ click and wrote the result to
+ * `initiative-links.jsonl`, so PMOS accumulated references to epics that do not exist, rendered in
+ * the same visual grammar it uses for facts.
+ *
+ * WHY IT IS STILL HERE, WHICH IS A REAL TENSION AND NOT AN OVERSIGHT. The initiative's rubric asks
+ * for the fabricating helpers to be REMOVED rather than bypassed, and deleting this function is the
+ * literal reading. But this module is a TRANSCRIPTION of the prototype, and fixture-parity.test.mjs
+ * exists to pin it line-for-line — deleting the function deletes that suite's assertion, and the
+ * same rubric forbids weakening an assertion to make a change pass. Both rules are right and they
+ * point opposite ways.
+ *
+ * The property that actually matters is not this function's existence; it is that nothing in real
+ * mode can reach it. So it stays, as the pinned record of what the prototype drew, and the guarantee
+ * is enforced mechanically instead of by deletion: pm-detail-test.js asserts that no module outside
+ * this file references `makeLink`. If a later change wires it back up, that test fails and names it.
+ *
+ * The seeded rows below (`ATL-482` and its siblings) are the same case and are correct: a prototype
+ * draws specimens. They are rendered in FIXTURE mode only and never reach the real store.
+ */
 export function makeLink(slug, src, existing = []) {
   if (src === 'jira') {
     const num = 501 + existing.filter(x => x.kind === 'jira epic').length;