create-pmos 0.15.0 → 0.16.1

package/workspace/lib/four-panel.js

@@ -0,0 +1,345 @@
+'use strict';
+/* lib/four-panel.js — the assembly behind `GET /api/initiative?id=&ws=`, and the two
+ * declaration stores the four-panel surface writes.
+ *
+ * ── Why this endpoint exists ─────────────────────────────────────────────────────────────────
+ * Panel 3 answers one question about ONE initiative, and answering it today costs four reads that
+ * every client would have to join for itself: `/api/library` for artifacts, `/api/console?
+ * name=ladder` for the engine's rungs, `/api/console?name=handoff` for external references, and a
+ * client-side join of `/api/sessions` against the `initiative/<id>` branch convention. Four
+ * round-trips per selection, and — worse — four chances for two surfaces to disagree about what a
+ * record declares. This module does the join once, server-side, from the SAME producers the
+ * existing endpoints use. It adds no new reader: `ladder`, `links`, `index` and `sessions` are
+ * passed IN by the route, already produced by console-state, handoff.js, initiativeIndex() and
+ * sessionList(). Nothing here re-derives them, so `/api/initiative` and `/api/console` can never
+ * hold two opinions about the same initiative.
+ *
+ * The existing endpoints are untouched on purpose — other surfaces still read them.
+ *
+ * ── The frontmatter reader ───────────────────────────────────────────────────────────────────
+ * The record's frontmatter is parsed with the WORKFLOW ENGINE's parser, not the workspace's
+ * `file-mode-parse`. The two disagree: file-mode-parse requires at least one character after the
+ * colon (`/^([a-z_]+):\s*(.+?)\s*$/`), so a record carrying an empty-valued key — `prd_path:` with
+ * nothing after it, which several records do — terminates the block there and drops every key
+ * below it, including `lane` and `parent_kr`. The engine tolerates the empty value and strips
+ * surrounding quotes. Reading a record through the parser that DERIVES the ladder is the only way
+ * 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.
+ *
+ * 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
+ * `planning/runs/` in pmos-self, where `pmos/state/` does not exist and the runs, evals and
+ * acceptances live. Hard-coding the PRD's path would have put every pmos-self declaration in a
+ * directory nothing else reads; and the workspace's own `state/` was the other candidate and is
+ * wrong for the opposite reason — it is gitignored runtime state, so a declaration written there
+ * would be a record of a PM decision that does not survive the machine.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ARTIFACT_LINKS = 'artifact-links.jsonl';
+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'];
+
+/** 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.
+ */
+function connectors() {
+  return {
+    configured: [],
+    note: 'no connector configured — nothing was read, and nothing will be written.',
+  };
+}
+
+/* ── the record ─────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Read `<initiatives>/<id>.md`. ABSENT and BROKEN are different facts and never share an answer:
+ * a record that does not exist is a supported state the panel already draws ("no record"), while
+ * an unreadable one is PMOS failing to look and must render RED.
+ *
+ * `parse` is the engine's `parseLeadingFrontmatter`, injected so this module owns no second
+ * opinion about what a record declares.
+ */
+function readRecord({ root, dir, id, parse }) {
+  const file = path.join(dir, `${id}.md`);
+  const rel = path.relative(root, file);
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: true, absent: true, record: rel, frontmatter: null };
+    return { ok: false, error: `${rel} could not be read — ${String((e && e.code) || 'read failed')}` };
+  }
+  let fm;
+  try { fm = parse(text); }
+  catch (e) {
+    return { ok: false, error: `${rel} — ${String((e && e.message) || 'the frontmatter could not be parsed').slice(0, 160)}` };
+  }
+  return { ok: true, absent: false, record: rel, frontmatter: fm, tasks: parseTasks(text) };
+}
+
+/**
+ * The OPTIONAL authored-task override (PRD, "Tasks"): a `## Tasks` section in the record BODY,
+ * with `### <phase>` sub-headings and `- title:` items carrying single-line `key: value` fields.
+ *
+ * It lives in the body and not in the frontmatter for a mechanical reason: the leading-frontmatter
+ * readers stop at the first line that is not `key: value`, so a YAML list under a `tasks:` key
+ * would silently drop `lane:` and `parent_kr:` below it. Absence of the section is not a defect
+ * and returns null — the caller derives instead, and a `{}` here would be indistinguishable from
+ * "authored, and empty".
+ */
+function parseTasks(text) {
+  const lines = String(text == null ? '' : text).split('\n');
+  let i = lines.findIndex((l) => /^##\s+Tasks\s*$/i.test(l));
+  if (i < 0) return null;
+  const out = {};
+  let phase = null, task = null;
+  for (i += 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line) && !/^###\s+/.test(line)) break;      // the next section ends Tasks
+    let m = line.match(/^###\s+(\S+)\s*$/);
+    if (m) { phase = m[1]; task = null; if (!out[phase]) out[phase] = []; continue; }
+    if (!phase) continue;
+    m = line.match(/^\s*-\s+title:\s*(.*?)\s*$/);
+    if (m) { task = { title: m[1], status: 'todo' }; out[phase].push(task); continue; }
+    m = line.match(/^\s+([a-zA-Z_]+):\s*(.*?)\s*$/);
+    if (m && task) task[m[1] === 'evaluation' ? 'evalNote' : m[1]] = m[2];
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/* ── artifacts ──────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * This initiative's artifacts out of the library index. The index is the SAME producer
+ * `/api/library` uses, so the two surfaces list the same files in the same order — an artifact
+ * list that differed between panel 3 and the library lens would be two answers to one question.
+ * An initiative the index has never heard of has no artifacts; that is an empty list, not an error.
+ */
+function artifactsFor(index, id) {
+  const rows = (index && Array.isArray(index.initiatives)) ? index.initiatives : [];
+  const hit = rows.find((r) => r && r.id === id);
+  if (!hit || !Array.isArray(hit.artifacts)) return [];
+  return hit.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path, title: a.title || null }));
+}
+
+/* ── sessions ───────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Which live sessions belong to this initiative. Sessions carry NO `initiative_id` — the only
+ * signal is the `initiative/<id>` branch convention, so the join is: every registered working tree
+ * whose branch is `initiative/<id>`, then every session whose `ws` is one of those trees.
+ *
+ * `matched` names the trees the join found. It is carried because "no sessions" and "no working
+ * tree on that branch" are different states with different copy, and a client that only received
+ * an empty array would have to guess which one it was looking at.
+ */
+function sessionsFor({ sessions, workspaces, id }) {
+  const branch = `initiative/${id}`;
+  const trees = (workspaces || []).filter((w) => w && w.branch === branch);
+  const ids = new Set(trees.map((w) => w.id));
+  return {
+    matched: trees.map((w) => ({ ws: w.id, name: w.name, root: w.root, branch: w.branch })),
+    sessions: (sessions || []).filter((s) => s && ids.has(s.ws)),
+  };
+}
+
+/* ── anchor ─────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Resolve the record's `parent_kr` through the same resolver the spine and the ladder use.
+ * `anchors` is `scripts/anchor-resolve.js`, injected; without it the anchor is UNKNOWN and says so
+ * rather than being reported as unanchored — "we could not look" and "there is nothing there" are
+ * the two answers this repo most insists on keeping apart.
+ */
+function anchorFor({ anchors, root, raw }) {
+  if (!anchors) {
+    return {
+      raw: raw || null, status: 'unknown', canonical: null,
+      reason: 'the anchor resolver (scripts/anchor-resolve.js) is not present in this install',
+    };
+  }
+  const index = anchors.parseOkrIndex(root);
+  const budgets = anchors.readBudgets(root);
+  const r = anchors.resolveAnchor(raw == null ? '' : String(raw), index, budgets);
+  return Object.assign({}, r, { canonical: anchors.canonical(r, index && index.period) });
+}
+
+/* ── the declaration stores ─────────────────────────────────────────────────────────────────── */
+
+function linkFile(stateDir, name) {
+  return stateDir ? path.join(stateDir, name) : null;
+}
+
+/**
+ * Where the two stores live for a repo: the same directory the engine already puts this repo's
+ * append-only records in. One resolver, so a declaration cannot land somewhere the reader does not
+ * look. Returns null when the engine is unavailable — the caller then says it could not write,
+ * rather than inventing a location.
+ */
+function storeDir(engine, root) {
+  if (!engine || typeof engine.layout !== 'function') return null;
+  try { return engine.layout(root).runsDir; } catch { return null; }
+}
+
+/** Read one store. A torn line is DROPPED, never guessed — the same rule every jsonl reader here follows. */
+function readDeclarations(stateDir, name) {
+  const file = linkFile(stateDir, name);
+  if (!file) return { ok: false, error: 'no file-mode state directory for this workspace — nothing was read', rows: [] };
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: true, empty: true, file, rows: [] };
+    return { ok: false, error: `${name} could not be read — ${String((e && e.code) || 'read failed')}`, rows: [] };
+  }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch { /* torn line — dropped */ }
+  }
+  return { ok: true, empty: rows.length === 0, file, rows };
+}
+
+/**
+ * Append one declaration. Append-only: a later row for the same artifact supersedes an earlier one
+ * on read, and the earlier one stays on disk, because the history of what the PM declared is the
+ * point of a declaration store.
+ *
+ * A failed write returns `{ok:false}` and never a false green — the same rule `POST /api/gate`
+ * follows, and for the same reason: a click that goes green over a record that was never written
+ * is the worst failure this surface can have.
+ */
+function appendDeclaration(stateDir, name, row) {
+  const file = linkFile(stateDir, name);
+  if (!file) {
+    return { ok: false, error: 'this workspace has no file-mode state directory — the declaration was NOT recorded' };
+  }
+  try {
+    // The directory is created rather than required: a repo that has never recorded a run has no
+    // runs directory yet, and refusing the PM's first declaration for that reason would be a
+    // failure with no cause the PM could act on.
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return { ok: true, recorded: row, sink: file };
+  } catch (e) {
+    return { ok: false, error: `could not write ${name} — ${String((e && e.code) || 'write failed')}`, sink: file };
+  }
+}
+
+/** 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();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const target = String((body && body.target) || '').trim();
+  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' };
+  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),
+      // 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,
+    },
+  };
+}
+
+/** Validate + normalise an initiative-link (manual reference) declaration. */
+function initiativeLinkRow(body, { at } = {}) {
+  const initiative_id = String((body && body.initiative_id) || '').trim();
+  const kind = String((body && body.kind) || '').trim().toLowerCase();
+  const label = String((body && body.label) || '').trim();
+  const target = String((body && (body.target || body.path)) || '').trim();
+  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' };
+  return {
+    ok: true,
+    row: {
+      at: at || new Date().toISOString(),
+      initiative_id,
+      kind: kind.slice(0, 40),
+      label: (label || target).slice(0, 200),
+      target: target.slice(0, 300),
+      declared: true,
+      connector: null,
+    },
+  };
+}
+
+/* ── the assembled payload ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * Join the pieces into the one payload panel 3 reads. Every field is either something a producer
+ * returned or explicitly null; nothing here invents a value.
+ *
+ * The result follows the house contract: `{ok:false,error}` for a failed read (RED),
+ * `{ok:true,absent:true,…}` for an initiative with no record (a supported, calm state — the
+ * 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 }) {
+  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) : []);
+  return {
+    ok: true,
+    id,
+    absent: !!rec.absent,
+    record: rec.record,
+    frontmatter: rec.frontmatter,
+    tasks: rec.tasks || null,
+    artifacts,
+    // Straight through from console-state — the SAME object `/api/console?name=ladder` returns,
+    // including its own {ok,empty,row,scope} discrimination, so a client already reading that
+    // endpoint reads this one without a second shape.
+    ladder: ladder || null,
+    // Straight through from handoff.js. `connected` is the literal false on every path it has.
+    links: links || null,
+    anchor: anchor || null,
+    sessions: sess.sessions,
+    session_trees: sess.matched,
+    declarations: {
+      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),
+      artifacts_error: artifactLinks && artifactLinks.ok ? null : (artifactLinks && artifactLinks.error) || null,
+      links_error: initiativeLinks && initiativeLinks.ok ? null : (initiativeLinks && initiativeLinks.error) || null,
+    },
+    connectors: connectors(),
+  };
+}
+
+module.exports = {
+  ARTIFACT_LINKS, INITIATIVE_LINKS, LINK_KINDS,
+  validId, connectors, readRecord, parseTasks, artifactsFor, sessionsFor, anchorFor,
+  storeDir, readDeclarations, appendDeclaration, artifactLinkRow, initiativeLinkRow, assemble,
+};

package/workspace/lib/git-info.js

@@ -85,6 +85,33 @@ function worktreesAt(top) {
   return out;
 }
 
+// The URL `origin` fetches from, or null when there is no origin (or no git at all). This is the
+// ONLY thing that can answer "did this working tree come from somewhere, or is it a folder on this
+// machine?" — the presence of a `.git` directory answers a different question and answering with it
+// would put a provenance label on a row that no read supports.
+// `git remote get-url` rather than `git config remote.origin.url`: it resolves insteadOf/pushInsteadOf
+// rewrites, so what comes back is the URL git would actually contact.
+function originUrl(root) {
+  if (!root || !isDir(root)) return null;
+  const r = git(root, ['remote', 'get-url', 'origin']);
+  if (r.failed || r.code !== 0 || !r.out) return null;
+  return r.out.split('\n')[0].trim() || null;
+}
+
+// Is this remote a GitHub one? Both URL shapes git accepts: scp-style (git@github.com:o/r.git) and
+// a real URL (https://github.com/o/r, ssh://git@github.com/o/r). Any other host — GitLab, Gitea, a
+// bare path, a local mirror — is NOT github, and saying otherwise would be the unsupported label
+// this function exists to avoid. It answers about the URL only; the caller decides what to call it.
+function isGithubRemote(url) {
+  const u = String(url || '').trim();
+  if (!u) return false;
+  const scp = u.match(/^[^/@]+@([^:/]+):/);              // git@host:owner/repo.git
+  const host = scp ? scp[1] : (u.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/:]+)/i) || [])[1];
+  if (!host) return false;
+  const h = host.toLowerCase();
+  return h === 'github.com' || h.endsWith('.github.com');
+}
+
 // Where an isolated worktree lands: a sibling of the repo, gathered under one `<repo>-worktrees/`
 // folder. Deliberately OUTSIDE the repo — nothing new appears inside the tree, so no `git status`
 // noise and nothing for .gitignore to chase. The path is derived from a name already passed
@@ -240,4 +267,4 @@ function branchInfo(root) {
 }
 
 module.exports = { isRepo, repoRoot, validBranchName, branchInfo, checkout, worktrees, worktreePath,
-  addWorktree, worktreeSafety, removeWorktree };
+  addWorktree, worktreeSafety, removeWorktree, originUrl, isGithubRemote };

package/workspace/lib/mobile-nav.js

@@ -52,10 +52,17 @@ const MODE_TITLE = {
   knowledge: 'knowledge', agent: 'agents', memory: 'memory',
 };
 // What a DETAIL screen is called. It moved here with the reducer, for the same reason.
+// The second block is the four-panel surface's `detail.kind` vocabulary (pm/app.js's DETAIL_TITLE).
+// It is ADDED rather than substituted: the first block is what the retired surface pushes and the
+// two overlap on every key they share, so one map titles a detail screen coming from either. A
+// missing key here is not a crash — `titleOf` falls back to 'detail' — it is a phone header that
+// says nothing, which is why the set is written down rather than left to the fallback.
 const DETAIL_TITLE = {
   initiative: 'initiative', repo: 'repository', flow: 'workflow', sched: 'scheduled task',
   skill: 'skill', know: 'knowledge', agent: 'agent', mem: 'memory',
   ingest: 'ingest proposal', profiles: 'profiles', connections: 'connections',
+  init: 'initiative', prof: 'claude profile', intg: 'connection',
+  addprod: 'add repository', new: 'file new',
 };
 
 const MOBILE_DESTS = ['board', 'scheduled', 'agents', 'memory', 'more'];
@@ -74,6 +81,27 @@ const MOBILE_ROOT = {
 // kind → column. There is no second input, and no screen may carry a column its kind does not give.
 const MOBILE_COLUMN = { list: 'side', more: 'side', detail: 'rail', terminal: 'term', doc: 'term' };
 function mobColumnOf(kind) { return MOBILE_COLUMN[kind] || 'side'; }
+
+/* kind → PANEL INDEX, for the four-panel surface (public/pm/).
+ *
+ * WHY THIS EXISTS ALONGSIDE `column`, RATHER THAN REPLACING IT. `column` names one of the three
+ * columns of the retired `public/app.js` layout, and MOBNAV-P1 pins it to exactly those three
+ * values. The surface that ships now has FOUR panels — repositories · mode list · detail · tabs —
+ * and two of the old `side` screens belong to DIFFERENT panels there: a `list` screen is panel 2
+ * (the mode list) while a `more` screen is panel 1, which is the structure/settings panel and is
+ * therefore the phone's "more" destination in the four-panel design.
+ *
+ * So this is an ADDITIVE widening, not an edit: `columnOf` is untouched and still describes the
+ * three-column layout truthfully for the surface that owns it, and `panelOf` describes the
+ * four-panel one. Both are pure functions of `kind` alone, so the exclusivity guarantee — one
+ * visible surface per screen — is the same property stated against a different layout. Putting it
+ * HERE rather than in pm/mobile.js keeps a single node-walkable source of truth for "which surface
+ * does this screen show", which is the whole reason the reducer was pulled out of app.js.
+ */
+const MOBILE_PANEL = { more: 0, list: 1, detail: 2, terminal: 3, doc: 3 };
+function mobPanelOf(kind) {
+  return Object.prototype.hasOwnProperty.call(MOBILE_PANEL, kind) ? MOBILE_PANEL[kind] : 1;
+}
 function mobDestForMode(k) { return MOBILE_DEST[k] || null; }
 // Complete a partial screen. The column is derived, never passed in, so a caller cannot put a
 // detail on the terminal column by writing it down.
@@ -120,8 +148,10 @@ function mobCurrentOf(nav) {
 function mobMigrateView(v) { return MOBILE_ROOT[v] ? v : 'board'; }
 
   return { push: mobPush, pop: mobPop, switchDest: mobSwitchDest, init: mobNavInit,
-    current: mobCurrentOf, titleOf: mobTitleOf, columnOf: mobColumnOf, destForMode: mobDestForMode,
+    current: mobCurrentOf, titleOf: mobTitleOf, columnOf: mobColumnOf, panelOf: mobPanelOf,
+    destForMode: mobDestForMode,
     MODE_TITLE,
     migrateView: mobMigrateView, screen: mobScreen, root: mobRootOf,
-    DESTS: MOBILE_DESTS, DEST_FOR_MODE: MOBILE_DEST, ROOTS: MOBILE_ROOT, DETAIL_TITLE };
+    DESTS: MOBILE_DESTS, DEST_FOR_MODE: MOBILE_DEST, ROOTS: MOBILE_ROOT,
+    PANEL_OF_KIND: MOBILE_PANEL, DETAIL_TITLE };
 });

package/workspace/lib/server-discovery.js

@@ -0,0 +1,127 @@
+'use strict';
+/* lib/server-discovery.js — WHICH workspace server is running, and on WHICH port.
+ *
+ * The launcher used to answer that question with a constant: port 7433, or whatever
+ * `PMOS_WS_PORT` said in THIS shell. That constant is why a second repo could not be added to a
+ * running workspace. The sequence the PM hit, end to end:
+ *
+ *   1. something already held 7433 (a wedged server, a crashed one whose socket lingered, or an
+ *      unrelated program), so the server exited with EADDRINUSE and printed the advice
+ *      `PMOS_WS_PORT=7500 npm start`;
+ *   2. the PM followed it, and the workspace came up on 7500 — the browser tab is on 7500;
+ *   3. `pmos` in the other repo, in a fresh shell with no `PMOS_WS_PORT`, looked at 7433 only,
+ *      found nothing, and started a SECOND server there. The repo was registered — with the
+ *      server nobody was looking at.
+ *
+ * Nothing in that sequence errors. That is the whole defect: two servers, each honest, and a repo
+ * that "never added" because it landed in the one that isn't on screen.
+ *
+ * So the port is DISCOVERED, never assumed. The candidate list is built from state the running
+ * server itself writes (`state/server-<port>.pid`, written on listen and removed on shutdown —
+ * server.js), which makes a server discoverable however it was started: `pmos`, `npm start`, or a
+ * hand-typed `PMOS_WS_PORT=7500 node server.js`.
+ *
+ * An explicit `PMOS_WS_PORT` is treated as a PIN, not a hint: it narrows the candidates to that one
+ * port and never widens them. The test suite depends on that isolation — a suite that could attach
+ * to the PM's real workspace would drive their live sessions.
+ *
+ * Everything here is pure, or reads the filesystem and nothing else: no sockets, no child
+ * processes. The I/O lives in the caller (bin/pmos.js, doctor.js), so the whole policy is testable
+ * in-process without binding a port.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_PORT = 7433;
+// How far the launcher rolls forward when the default port is taken by something that is not a
+// workspace server. Bounded on purpose: "start somewhere, anywhere" would scatter servers across
+// the ephemeral range and make discovery a scan.
+const FALLBACK_SPAN = 12;
+
+// state/server-<port>.pid — the launcher AND the server agree on this name; it is the only place a
+// port is recorded, so it is the only shape parsed here.
+const PID_RE = /^server-(\d{2,5})\.pid$/;
+
+const pidFileName = (port) => `server-${Number(port)}.pid`;
+
+/**
+ * Every `state/server-<port>.pid` on disk, most recently written first. A record is returned even
+ * when its pid is unreadable — a file whose contents are gone still names a port worth probing,
+ * and treating it as absent is how a running server becomes invisible.
+ */
+function pidRecords(stateDir) {
+  let names = [];
+  try { names = fs.readdirSync(stateDir); } catch { return []; }
+  const out = [];
+  for (const name of names) {
+    const m = PID_RE.exec(name);
+    if (!m) continue;
+    const file = path.join(stateDir, name);
+    let pid = null, mtime = 0;
+    try { pid = Number(String(fs.readFileSync(file, 'utf8')).trim()) || null; } catch {}
+    try { mtime = fs.statSync(file).mtimeMs; } catch {}
+    out.push({ port: Number(m[1]), pid, file, mtime });
+  }
+  out.sort((a, b) => b.mtime - a.mtime);
+  return out;
+}
+
+/**
+ * The ports to probe, in order. With a pinned port that list is exactly one long — see the header:
+ * a pin is an instruction, and widening it would let a test (or a second workspace deliberately
+ * kept apart) attach to a server it was told not to touch.
+ */
+function candidatePorts({ stateDir, pinned = null, defaultPort = DEFAULT_PORT } = {}) {
+  const pin = Number(pinned);
+  if (Number.isInteger(pin) && pin > 0) return [pin];
+  const seen = new Set();
+  const out = [];
+  const push = (p) => { if (Number.isInteger(p) && p > 0 && !seen.has(p)) { seen.add(p); out.push(p); } };
+  push(Number(defaultPort) || DEFAULT_PORT);
+  for (const r of pidRecords(stateDir)) push(r.port);
+  return out;
+}
+
+/** Is this pid still around? EPERM means yes-but-not-ours, which is still alive. */
+function pidAlive(pid, kill) {
+  const k = kill || ((p, sig) => process.kill(p, sig));
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { k(pid, 0); return true; } catch (e) { return !!e && e.code === 'EPERM'; }
+}
+
+/**
+ * Which pid files describe a server that is gone. Deliberately conservative: a file is stale only
+ * when its port does NOT answer AND its pid is NOT alive. A server that is mid-start — listening
+ * socket not yet open, process very much alive — must survive this, or one launcher would delete
+ * another's record and make it undiscoverable a second later.
+ */
+function stalePidFiles(stateDir, { livePorts = [], alive = pidAlive } = {}) {
+  const live = new Set(livePorts.map(Number));
+  return pidRecords(stateDir)
+    .filter((r) => !live.has(r.port) && !alive(r.pid))
+    .map((r) => r.file);
+}
+
+/**
+ * The first port at or after `start` that `isFree` accepts, within the bounded span. `isFree` is
+ * injected (the caller owns the socket), so this stays pure and the span is assertable.
+ */
+function nextFreePort(start, isFree, span = FALLBACK_SPAN) {
+  const from = Number(start) || DEFAULT_PORT;
+  for (let p = from; p < from + span; p++) if (isFree(p)) return p;
+  return null;
+}
+
+/**
+ * Does this JSON body come from a workspace server? `/api/sessions` answers `{sessions:[…]}`, and
+ * requiring the array is what keeps an unrelated program that happens to serve JSON on 7433 from
+ * being adopted as "the workspace" — the launcher would then register the PM's repo into it.
+ */
+function looksLikeWorkspace(body) {
+  return !!body && typeof body === 'object' && Array.isArray(body.sessions);
+}
+
+module.exports = {
+  DEFAULT_PORT, FALLBACK_SPAN, PID_RE,
+  pidFileName, pidRecords, candidatePorts, pidAlive, stalePidFiles, nextFreePort, looksLikeWorkspace,
+};

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.12.0",
+  "version": "0.16.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.12.0",
+      "version": "0.16.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",
@@ -19,6 +19,10 @@
       "bin": {
         "pmos": "bin/pmos.js"
       },
+      "devDependencies": {
+        "pixelmatch": "^7.1.0",
+        "pngjs": "^7.0.0"
+      },
       "engines": {
         "node": ">=18"
       }
@@ -57,6 +61,19 @@
         "node-addon-api": "^7.1.0"
       }
     },
+    "node_modules/pixelmatch": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/pixelmatch/-/pixelmatch-7.2.0.tgz",
+      "integrity": "sha512-xhcb4yHu9sM/G7foGzoLtXYcC0zHEaOXXjRKhGup0fw78Nf2Tkiapv4EQyMzrbcmQPsllAI7DbFY2UT7PlI9Pg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "pngjs": "^7.0.0"
+      },
+      "bin": {
+        "pixelmatch": "bin/pixelmatch"
+      }
+    },
     "node_modules/playwright-core": {
       "version": "1.61.1",
       "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz",
@@ -69,6 +86,16 @@
         "node": ">=18"
       }
     },
+    "node_modules/pngjs": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
+      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.19.0"
+      }
+    },
     "node_modules/ws": {
       "version": "8.21.1",
       "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.1.tgz",