create-pmos 0.18.1 → 0.20.0

package/README.md

@@ -333,6 +333,36 @@ 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.19.0
+
+**A long document scrolls its own panel, and starting a session asks what is already running.** Run
+`npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **Opening a long document no longer scrolls the whole window.** Scrolling a document in the right
+  panel moved the entire interface — the top bar slid away, the status bar rose from below — while
+  the panel's own scrollbar never engaged. Every panel now scrolls inside itself and the app frame
+  never moves. (If you are curious: the shell's middle row was written `1fr`, which is
+  `minmax(auto, 1fr)`, so a tall document enlarged the row rather than overflowing it. Every style
+  involved read as correct, which is why it survived review.)
+- **`＋ session` now asks before it starts one, when the checkout is already busy.** It used to
+  start the session and *then* tell you how many others were in there — a count arriving after the
+  decision, naming something you cannot act on. Now you get a chooser first, listing every session
+  in that checkout.
+- **It says what each one is.** Its name, its agent, the same word the sidebar uses (`working` ·
+  `quiet 12m` · `needs you` · `maybe blocked`), the agent's own last words, and who holds the writer
+  claim.
+- **…and what ending it would cost, without over-claiming.** Only `needs you` reads as settled —
+  its turn finished and it is waiting on you. `working` says output is arriving right now. `quiet`
+  and `maybe blocked` say, in as many words, that the workspace *cannot tell* a finished turn from a
+  permission prompt from a stuck tool. A confident "safe to end" that discarded a running turn would
+  be worse than no reading at all.
+- **You can take the running session instead of making another.** `open it` attaches a tab to it and
+  starts nothing. `end it` is there too — the first click arms it and names what it will end, the
+  second does it. `＋ start another session here anyway` is always one click: being told is never
+  being blocked, and no session is ever refused because another is there.
+- **The same detail is written into the new session's scrollback**, so scrolling back tomorrow
+  answers the same question the chooser did.
+
 ## What's new in 0.18.1
 
 **Three fixes to the workspace terminal, all of them about what the window knew about a session.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → 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. `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@9fee84a
+kernel-source: pmos@ec75724
 assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -162,6 +162,24 @@ session in a tree that already has live ones now says so in the pane — naming
 way out (⑂ a new branch in its own folder). It fires on the plain `＋ session` path too, where no
 git operation runs at all: the server already knew, and used to say nothing.
 
+**`＋ session` asks before it starts one.** A count arriving *after* the spawn is a fact you cannot
+act on, and the answer you usually want is not "start another" at all — it is "which of those is the
+one I was already working in?". So clicking `＋ session` into an occupied tree opens a chooser
+first, listing every session in that tree with:
+
+- **what it is** — its name, its agent, the sidebar's own word for its state (`working` ·
+  `quiet 12m` · `needs you` · `maybe blocked`), the agent's last words, and the writer claim;
+- **what ending it would cost** — one sentence per session, worded from the evidence. Only
+  `needs you` reads as settled ("its turn finished and it is waiting on you"). `quiet` and
+  `maybe blocked` say, in as many words, that PMOS *cannot tell* — a confident "safe" that
+  discards a running turn is worse than no reading at all;
+- **`open it`** — attach a tab to that session and start nothing.
+
+`end it` is there too, and is the only destructive control on the surface: two clicks, the first
+arming it. `＋ start another session here anyway` is always one click away — informing you is never
+obstructing you. The same per-session detail is written into the new pane's scrollback, so scrolling
+back tomorrow answers the same question the chooser did.
+
 **The tree is the unit, not the folder you registered.** A repo registered twice — say `~/repo` and
 `~/repo/packages/app`, the ordinary shape for a product repo added by path — is **one** tree, and
 its sessions are told about each other. Two *worktrees* of one repo are **two** trees, and are not
@@ -178,7 +196,9 @@ Be clear about what this buys: **PMOS hosts your agent's terminal, it does not s
 the files.** Nothing here prevents a write, a checkout or a commit, and no spawn is ever refused
 because someone else is in the tree. It makes a shared tree visible; the discipline is still yours.
 (The role rides on `/api/sessions` rows as `tree` / `tree_role` / `tree_peers`; the tab-bar chip is
-not wired yet.)
+not wired yet. `/api/workspaces` publishes each registration's `tree`, which is what lets the
+chooser answer "who is already in there?" *before* anything is started; `/api/tree/peers` returns
+each session described — `shown`, `label`, `doing` and a `risk` — rather than a list of ids.)
 
 A workspace anywhere **inside** a repo knows its branch — a subdirectory (`repo/packages/app`)
 counts, which matters for a product repo added by path. A folder with **no git** simply says so and

package/workspace/lib/four-panel.js

@@ -26,13 +26,22 @@
  * this endpoint's `frontmatter` can agree with its own `ladder`.
  *
  * ── The declaration stores ───────────────────────────────────────────────────────────────────
- * `artifact-links.jsonl` and `initiative-links.jsonl` are APPEND-ONLY records of what the PM
- * declared, never of anything PMOS read. PMOS holds no credential and makes no outbound request
- * (PRD, "External sync"), so a link row is a statement of intent — "this artifact corresponds to
- * that page" — and the surface that renders it must say that nothing was read and nothing will be
- * written. `connectors()` below is the honest answer to "is a connector configured": always none.
- * It is a function rather than a constant so that the day a connector genuinely exists there is
- * exactly one place that has to start telling a different truth.
+ * `artifact-links.jsonl` and `initiative-links.jsonl` are APPEND-ONLY records of external
+ * references. PMOS holds no credential and makes no outbound request (PRD, "External sync") — that
+ * has not changed and must not. What a row may now say about itself has: every row carries a
+ * `state` from a closed three-word vocabulary (`declared` · `resolved` · `unreachable`) and the
+ * provenance behind it, so a reference the PM typed and a reference a session actually read are
+ * different facts on disk instead of the same row wearing the word `connected`.
+ *
+ * `resolved` is the only state that claims anything about the destination, and it cannot be
+ * asserted — only evidenced. See `provenance()`: a row claiming `resolved` without the profile that
+ * resolved it is REFUSED. That refusal is the mechanical form of this whole module's promise, and
+ * it is why the day a connector genuinely exists there is exactly one place that has to start
+ * telling a different truth — and no way for anything else to start telling it early.
+ *
+ * `connectors()` below answers "what could be looked up, and by whom" from the agent profiles on
+ * disk. It used to return a constant `[]`. A constant cannot be wrong, which is exactly why it
+ * could not be trusted: it said "none" on a machine whose profiles declared a Jira MCP.
  *
  * The files land beside the repo's other append-only records, resolved through the workflow
  * engine's own `layout(root)`: `pmos/state/` in a kit repo — exactly as the PRD names it — and
@@ -52,19 +61,110 @@ const INITIATIVE_LINKS = 'initiative-links.jsonl';
 /** The destinations the surface can declare. A kind outside this set is refused, not stored. */
 const LINK_KINDS = ['confluence', 'jira', 'google'];
 
+/**
+ * The closed vocabulary a link row may use about itself. Three states, and the word `connected` is
+ * deliberately not among them.
+ *
+ *   declared    — the PM named this reference. Nothing was checked. Carries no claim about the
+ *                 destination beyond the PM's own say-so.
+ *   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.
+ *
+ * `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'];
+
+/**
+ * How a reference came to be in the store. This is the field that makes the store cleanable: the
+ * rows written by the fabricating build carry neither, so they are distinguishable from real ones
+ * forever rather than only until someone forgets.
+ *
+ *   typed    — a human wrote the reference into the form. The only origin a `declared` row can have.
+ *   resolved — a session searched the destination and returned this record.
+ */
+const LINK_ORIGINS = ['typed', 'resolved'];
+
+/**
+ * Which MCP server name on a profile makes which destination resolvable. The names on the left are
+ * what a profile descriptor actually declares (`mcp: [jira, confluence, ...]`); the kinds on the
+ * right are this store's closed vocabulary. Anything a profile declares that is not in here simply
+ * does not make a destination resolvable — an unknown server name is not evidence of anything.
+ */
+const MCP_FOR_KIND = {
+  jira: ['jira', 'atlassian'],
+  confluence: ['confluence', 'atlassian'],
+  google: ['gworkspace', 'google-workspace', 'gdrive', 'google-drive'],
+};
+
 /** An initiative id is a FILENAME, never a path. Same guard the handoff surface uses. */
 const ID_RE = /^[A-Za-z0-9][\w.-]*$/;
 const validId = (id) => typeof id === 'string' && id.length <= 120 && ID_RE.test(id);
 
 /**
- * No connector is configured, on every code path, because PMOS holds no credential. Returned as a
- * list so the client can render "which destinations are live" without a second shape to learn; it
- * is empty, and the note says why.
+ * Which destinations can be RESOLVED right now, and by what.
+ *
+ * This used to return a constant `[]` with a note explaining that PMOS holds no credential. The
+ * note was true and the list was not an answer — it said "none" on a machine where the PM's own
+ * agent profile declares a Jira MCP, and it would have gone on saying "none" after a real
+ * connection existed. A constant cannot be wrong, which is exactly why it cannot be trusted.
+ *
+ * The honest answer is derived, and it is careful about WHOSE capability it is describing. PMOS
+ * still holds no credential and still makes no outbound request — that has not changed and must
+ * not. What has changed is that PMOS can now see which agent PROFILES declare an MCP server for a
+ * destination, and a session started on such a profile can perform a lookup with the PM's own auth
+ * (D53: the agent layer acts, PMOS records). So `configured` does not mean "PMOS is connected"; it
+ * means "a session on this profile could look this up for you", and every entry names the profile
+ * so the claim is attributable rather than ambient.
+ *
+ * `declared: true` on every entry is the load-bearing hedge. A profile DECLARES an MCP server in a
+ * file; PMOS has not reached it, cannot reach it, and will not pretend the declaration is a
+ * handshake. A profile that lists a Jira MCP whose token expired last week still reads as
+ * resolvable here, and the resulting failure surfaces where it actually happens — as an
+ * `unreachable` row carrying the reason, written by the session that tried.
  */
-function connectors() {
+function connectors(homeDir) {
+  const empty = (note) => ({ configured: [], declaredBy: [], note });
+  const home = typeof homeDir === 'string' && homeDir ? homeDir : null;
+  if (!home) {
+    return empty('no home directory to read agent profiles from — PMOS cannot say what is resolvable, so it says nothing.');
+  }
+
+  let read;
+  try { read = require('./profiles').readProfiles(home); }
+  catch { return empty('the profile reader is unavailable — PMOS cannot say what is resolvable, so it says nothing.'); }
+
+  // ABSENT and BROKEN are different facts here for the same reason they are in the profile reader:
+  // "you have declared no profiles" is calm and actionable, "PMOS could not look" is a failure the
+  // PM has to go fix, and collapsing them would hide the second behind the first.
+  if (!read.ok) {
+    return empty(`agent profiles could not be read — ${read.error || 'unknown error'}. Nothing is claimed about what is resolvable.`);
+  }
+  if (!read.profiles || !read.profiles.length) {
+    return empty('no agent profile declares an MCP server for these destinations — a reference you add here is one you typed, and PMOS will say so.');
+  }
+
+  const configured = [];
+  for (const kind of LINK_KINDS) {
+    const names = MCP_FOR_KIND[kind] || [];
+    for (const prof of read.profiles) {
+      const mcp = Array.isArray(prof.mcp) ? prof.mcp : [];
+      const hit = mcp.find((s) => names.includes(String(s).toLowerCase()));
+      if (!hit) continue;
+      configured.push({ kind, profile: prof.id, server: hit, declared: true });
+      break;                                  // one profile per kind is enough to offer the lookup
+    }
+  }
+
+  if (!configured.length) {
+    return empty('no agent profile declares an MCP server for these destinations — a reference you add here is one you typed, and PMOS will say so.');
+  }
   return {
-    configured: [],
-    note: 'no connector configured — nothing was read, and nothing will be written.',
+    configured,
+    declaredBy: [...new Set(configured.map((c) => c.profile))],
+    note: 'a session on the named profile can look these up with your own credentials. PMOS itself holds none and reads nothing.',
   };
 }
 
@@ -244,6 +344,58 @@ function appendDeclaration(stateDir, name, row) {
   }
 }
 
+/**
+ * The provenance half of every link row, and the one rule that makes the vocabulary mean something.
+ *
+ * THE RULE: `resolved` cannot be asserted, only evidenced. A row may claim `state: 'resolved'` only
+ * if it also carries the profile that resolved it and the moment it did. A caller that says
+ * "resolved" and cannot say by whom is not describing a lookup, and the store refuses it rather
+ * than recording an unsupported claim — which is exactly the failure this whole initiative exists
+ * to remove, arriving through the front door instead of through a fabricating helper.
+ *
+ * The consequence worth stating plainly: a reference the PM TYPED can never be stored as
+ * `resolved`, no matter what the client sends. `origin: 'typed'` forces `declared`. That is what
+ * makes the three states worth reading — a `resolved` row is a fact about the destination, and
+ * nothing else in the system can mint one.
+ */
+function provenance(body, at) {
+  const origin = String((body && body.origin) || 'typed').trim().toLowerCase();
+  if (!LINK_ORIGINS.includes(origin)) {
+    return { error: `origin must be one of: ${LINK_ORIGINS.join(', ')}` };
+  }
+  let state = String((body && body.state) || (origin === 'resolved' ? 'resolved' : 'declared')).trim().toLowerCase();
+  if (!LINK_STATES.includes(state)) {
+    return { error: `state must be one of: ${LINK_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 title = body && body.title ? String(body.title).slice(0, 300) : null;
+
+  // A typed reference is the PM's word, and the PM's word is a declaration. Silently downgrading
+  // would be the friendlier-looking choice and the wrong one: a client that asked to store a typed
+  // reference AS resolved has a bug, and a store that quietly corrects it hides the bug while the
+  // next caller writes the same line.
+  if (origin === 'typed' && state === 'resolved') {
+    return { error: 'a typed reference cannot be stored as resolved — nothing read it. Send origin: resolved with the profile that did.' };
+  }
+  if (state === 'resolved' && !profile) {
+    return { error: 'a resolved reference must name the profile whose session resolved it' };
+  }
+  if (state === 'unreachable' && !reason) {
+    return { error: 'an unreachable reference must carry the reason the lookup failed' };
+  }
+  return {
+    origin,
+    state,
+    profile,
+    reason,
+    title,
+    // Only a row that actually read something carries a read time. Absent means "nothing read it",
+    // which is a fact the surface renders rather than a gap it fills in.
+    resolved_at: state === 'resolved' ? (at || new Date().toISOString()) : null,
+  };
+}
+
 /** Validate + normalise an artifact-link declaration. Returns `{ok:false,error}` for a bad shape. */
 function artifactLinkRow(body, { at } = {}) {
   const artifact_path = String((body && body.artifact_path) || '').trim();
@@ -255,6 +407,8 @@ function artifactLinkRow(body, { at } = {}) {
   if (!target) return { ok: false, error: 'target is required' };
   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' };
+  const prov = provenance(body, at);
+  if (prov.error) return { ok: false, error: prov.error };
   return {
     ok: true,
     row: {
@@ -263,10 +417,13 @@ function artifactLinkRow(body, { at } = {}) {
       artifact_path,
       kind,
       target: target.slice(0, 300),
-      // Stated on every row, not implied by its absence: this is a DECLARATION. Nothing was read
-      // from the destination and nothing was written to it.
-      declared: true,
-      connector: null,
+      ...prov,
+      // Kept, and no longer the whole story. `declared: true` said "PMOS read nothing" back when
+      // that was true of every row; now it is true of exactly the rows whose state says so, and
+      // the state is the field to read. Retained because rows on disk carry it and a reader that
+      // drops a field silently changes what the history means.
+      declared: prov.state !== 'resolved',
+      connector: prov.state === 'resolved' ? prov.profile : null,
     },
   };
 }
@@ -280,20 +437,95 @@ function initiativeLinkRow(body, { at } = {}) {
   if (!validId(initiative_id)) return { ok: false, error: 'that initiative id is not a record name' };
   if (!kind) return { ok: false, error: 'kind is required' };
   if (!target) return { ok: false, error: 'a target reference is required' };
+  const prov = provenance(body, at);
+  if (prov.error) return { ok: false, error: prov.error };
   return {
     ok: true,
     row: {
       at: at || new Date().toISOString(),
       initiative_id,
       kind: kind.slice(0, 40),
-      label: (label || target).slice(0, 200),
+      // The destination's OWN title when a lookup returned one; otherwise what the PM typed, and
+      // failing that the reference itself. Never a label built out of the initiative slug — that
+      // was the fabrication, and a label assembled from local strings is one whatever it is called.
+      label: (prov.title || label || target).slice(0, 200),
       target: target.slice(0, 300),
-      declared: true,
-      connector: null,
+      ...prov,
+      declared: prov.state !== 'resolved',
+      connector: prov.state === 'resolved' ? prov.profile : null,
     },
   };
 }
 
+/**
+ * Collapse an append-only store into what the surface shows: ONE row per subject and destination
+ * kind, the latest winning.
+ *
+ * Both halves of that matter and they pull in opposite directions, which is why this is a read-time
+ * derivation rather than a write-time replace. The store is a history of what the PM declared and
+ * every row stays on disk — that is the whole reason it is append-only. The SURFACE is a statement
+ * of what is true now, and six clicks on one button are not six references; they are one reference
+ * declared six times. Before this, the store was right and the surface showed all six.
+ *
+ * `subject` is the artifact path for an artifact link and the initiative id for a reference, so a
+ * PRD linked to Jira and the initiative linked to Jira are different pairs and neither supersedes
+ * 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) {
+  const list = Array.isArray(rows) ? rows : [];
+  const seen = new Map();
+  list.forEach((row, i) => {
+    if (!row || typeof row !== 'object') return;
+    const subject = row.artifact_path || row.initiative_id || '';
+    const key = subject + '|' + 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,
+      // Rows written before provenance existed carry neither an origin nor a state. They are NOT
+      // rewritten to look like typed references — that would launder exactly the fabricated 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'),
+    }));
+}
+
+/**
+ * The task a session performs to resolve a reference. Composed here, on the server, because it is
+ * the thing the whole design turns on and a string built in a click handler is a string no test
+ * ever sees.
+ *
+ * Note what it asks for and what it does not. It asks the session to SEARCH and to report what it
+ * found, including finding nothing; it does not ask it to create, publish, or push anything, and it
+ * names the recording endpoint so the session records through the same validated path the PM's own
+ * typing goes through. There is no branch here in which PMOS makes a request.
+ */
+function lookupTask({ kind, subject, hint, profile } = {}) {
+  const k = String(kind || '').toLowerCase();
+  if (!LINK_KINDS.includes(k)) return { ok: false, error: `kind must be one of: ${LINK_KINDS.join(', ')}` };
+  const what = k === 'jira' ? 'Jira issue or epic' : k === 'confluence' ? 'Confluence page' : 'Google Doc';
+  return {
+    ok: true,
+    profile: profile || null,
+    text: [
+      `Find the ${what} that corresponds to "${String(subject || '').slice(0, 200)}".`,
+      hint ? `The PM's hint about which one: ${String(hint).slice(0, 200)}` : null,
+      '',
+      `Use your ${k} MCP tools to SEARCH. Do not create, publish, or modify anything.`,
+      'Report the candidates you found — key/id, title, and URL for each — and let the PM pick.',
+      'If you find nothing, say so plainly. If the lookup fails, report the error verbatim.',
+      'Do not guess an identifier, and do not construct one from the name above — a made-up',
+      'reference is worse here than no reference, which is the defect this replaced.',
+    ].filter((l) => l !== null).join('\n'),
+  };
+}
+
 /* ── the assembled payload ──────────────────────────────────────────────────────────────────── */
 
 /**
@@ -305,11 +537,13 @@ function initiativeLinkRow(body, { at } = {}) {
  * 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 }) {
+function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor, artifactLinks, initiativeLinks, homeDir }) {
   if (!rec.ok) return { ok: false, id, error: rec.error };
   const artifacts = artifactsFor(index, id);
   const sess = sessionsFor({ sessions, workspaces, id });
-  const mine = (rows, pred) => (rows && rows.ok ? rows.rows.filter(pred) : []);
+  // linkView LAST, so superseding happens across this initiative's rows only — collapsing the whole
+  // store first would let another initiative's link to the same path win a pair that is not its own.
+  const mine = (rows, pred) => linkView((rows && rows.ok ? rows.rows.filter(pred) : []));
   return {
     ok: true,
     id,
@@ -334,12 +568,13 @@ function assemble({ id, rec, ladder, links, index, sessions, workspaces, anchor,
       artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
       links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
     },
-    connectors: connectors(),
+    connectors: connectors(homeDir),
   };
 }
 
 module.exports = {
-  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS,
+  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS, LINK_STATES, LINK_ORIGINS, MCP_FOR_KIND,
   validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
   storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
+  linkView, lookupTask,
 };