create-pmos 0.15.0 → 0.16.1

package/README.md

@@ -333,6 +333,71 @@ 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.16.1
+
+**Two fixes on the Terminal Workspace's entry path — how a repository reaches a running workspace.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **`pmos` finds the workspace you already have open, on whatever port it is on.** The launcher used
+  to assume one port (7433, or whatever `PMOS_WS_PORT` said in that shell). So if another program
+  held 7433 and you moved the workspace to a different port, the next `pmos` — in a fresh terminal,
+  in a second repo — looked at 7433, found nothing, and started a *second* server. Your repo was
+  registered, with a workspace you were not looking at, and nothing anywhere reported an error. The
+  server now records the port it is serving and every `pmos` command discovers it, so a second repo
+  joins the workspace on screen. `PMOS_WS_PORT` still pins a port when you want one.
+- **A taken port is no longer a dead end.** If something else holds 7433, `pmos` starts on the next
+  free port and says so, instead of failing with `port 7433 is already in use`. `pmos stop` now stops
+  every workspace server it can find — which is how you collapse two back into one — and `pmos
+  doctor` reports which servers are running and, when none is, who holds the port. A failed start
+  also prints only that attempt's log, so one conflict is reported once rather than three times.
+- **The folder chooser is back in "add a product".** Picking a local folder had regressed to a
+  bare text field in the four-panel surface, so adding a repository meant typing its absolute path.
+  The `choose…` button opens your machine's own folder dialog again, with an in-app folder browser
+  standing in on machines that have none. Typing a path still works, and registration is unchanged:
+  a local folder is registered where it is, and nothing is imported from it.
+
+Unchanged where it matters: **no database, no network at runtime, no telemetry.** The server still
+binds `127.0.0.1` only. The file-mode kit itself is unchanged and still dependency-free — everything
+above is in the optional Terminal Workspace GUI.
+
+## What's new in 0.16.0
+
+**The Terminal Workspace is now a four-panel surface.** The three-column layout is retired and
+replaced by one built to a PM-authored design: repositories, initiatives, initiative detail, and a
+tab strip. Run `npx create-pmos@latest workspace`; the version bump means an existing install
+auto-upgrades.
+
+- **Panel 1 — repositories.** Every repo you've added, with its kind (`⎇` github / `▤` local) and
+  its initiative count, plus a settings & tools drawer holding the secondary modes — `agents`,
+  `memory`, `knowledge` for the current repository, and `focus`, `skills`, `connections`,
+  `scheduled` across all of them.
+- **Panel 2 — initiatives, as a channel list.** Collapsible objective/KR groups over `#slug` rows,
+  one search box that forces the groups open and reports matches elsewhere, and an add form.
+  Initiatives with no anchor are filed and shown as rejected (D59) rather than quietly hidden.
+- **Panel 3 — initiative detail.** The record's pills and derived footer, **task phases** whose
+  status is derived from the workflow ladder rather than declared, a **links** section for
+  references that are not repo files, and the artifact list. A record that fails to parse renders
+  red with the parse error — never a blank panel.
+- **Panel 4 — tabs, scoped per repository.** Three kinds side by side: **term** (a real PTY running
+  your agent CLI untouched), **doc** (view/raw/edit/diff with save, revert and a dirty flag), and
+  **task** (the task spec view). New session, close, and split.
+- **A phone surface.** The same four panels collapse into a mobile navigation model, so triage from
+  a phone is a first-class path and not a scaled-down desktop.
+- **Artifact links are declarations, not integrations.** Linking an artifact to an external
+  destination appends `{artifact_path, kind, target}` to `pmos/state/artifact-links.jsonl`. The sync
+  panel is rendered, but with no connector configured its summary line says exactly that — *no
+  connector configured — nothing was read, and nothing will be written* — and the approval buttons
+  are disabled. It will not show you a difference it never read.
+- **`?fixture=proto`** renders the whole surface from a bundled fixture with no repository at all,
+  which is also how the design comparison is run. It is never the default path.
+
+Unchanged where it matters: **no database, no network at runtime, no telemetry.** The front end
+loads only same-origin assets — fonts and the terminal emulator are served from the install, never
+from a CDN — the server binds `127.0.0.1`, and the only outbound paths remain the ones you invoke
+yourself (`git clone` on repo ingest, `pmos upgrade`, and the one-time `npm install` that builds
+node-pty). No new runtime dependency was added. The file-mode kit itself is unchanged and still
+dependency-free.
+
 ## What's new in 0.15.0
 
 **A major Terminal Workspace rebuild** (#242) — the PM spine, a Claude Design refresh, and a proper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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@7b15792
-assembled: 2026-07-30
+kernel-source: pmos@011b77e
+assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -1,7 +1,7 @@
 ---
 type: Reference
 title: "PMOS Terminal Workspace"
-timestamp: 2026-07-25
+timestamp: 2026-07-30
 ---
 
 # PMOS Terminal Workspace
@@ -35,8 +35,13 @@ That's it. The server keeps running after you close the terminal — sessions su
 ```bash
 pmos status          # is it running? which sessions?
 pmos stop            # shut it down (scrollback is preserved; sessions respawn next time)
-pmos doctor          # diagnose the environment (node-pty arch, PTY spawn test)
+pmos doctor          # diagnose the environment (node-pty arch, PTY spawn test, ports)
 ```
+**The port is found, not assumed.** A running server records the port it serves, so `pmos` in a
+second repo joins the workspace you already have open — whatever port it ended up on, and however it
+was started. If another program holds the default port (7433), `pmos` starts on the next free one and
+says so; `PMOS_WS_PORT=7500 pmos` pins it by hand. `pmos stop` shuts down every workspace server it
+finds, which is how you collapse two back into one.
 
 <details><summary>Without the global install (running from the repo)</summary>
 
@@ -49,14 +54,34 @@ npm run test:ui      # browser checks: terminal geometry, reader scroll, markdow
 ```
 </details>
 
-## Layout (PM-directed, D62 R9 + round 2)
-Three columns. **Left = the workspace**: repos on top, running agents below, equal halves.
-**Middle = the terminal**, sessions as tabs. **Right rail = the library over the document
-reader** — either pane folds away (click its header), the whole rail hides (`rail`), and both
-the split and the rail width are draggable. The layout you choose survives a reload.
-
-- **Add a repo by picking a folder** — `＋` opens your machine's own folder chooser (typing a
-  path still works; where no chooser exists, an in-app folder browser stands in).
+## Layout — four panels (PM-directed design, built by `workspace-four-panel`)
+The three-column layout is retired. The surface is now **four collapsible panels** under a 44px top
+bar and a 26px status bar, on the oklch token layer, in both themes:
+
+1. **Repositories** — every repo you've added, with its kind (`⎇` github / `▤` local) and a
+   `github|local · N initiatives` sub-line. `＋` adds one by picking a folder (typing a path still
+   works; where no chooser exists, an in-app folder browser stands in). The **settings & tools**
+   drawer holds the secondary modes in two groups: *this repository* (`agents` · `memory` ·
+   `knowledge`) and *all repositories* (`focus` · `skills` · `connections` · `scheduled`). There is
+   deliberately no `workflow` entry — workflows are decided by the agent at runtime, not configured.
+2. **Initiatives** — a channel list. Collapsible objective/KR groups over `#slug` rows, one search
+   box that forces the groups open and reports matches elsewhere, and an add form. Unanchored
+   initiatives are filed honestly and shown **rejected** under D59, never hidden.
+3. **Initiative detail** — the record's header and pills (type / anchor / flow / branch), the derived
+   footer, **task phases** (collapsible; a phase's status is derived from its tasks, and the tasks
+   are derived from the workflow ladder unless the record authors them), a **links** section for
+   references that are not repo files, and **artifacts** with an external destination and the sync
+   panel. A record that fails to read renders **red with the parse error** — never a blank panel.
+4. **Tabs** — scoped per repository, two-line labels naming the initiative, three kinds: **term** (a
+   real PTY), **doc** (view/raw/edit/diff, save/revert, dirty flag), and **task** (the task spec).
+   `＋ session`, close, split.
+
+`⌘K`/`Ctrl-K` focuses search; `Esc` closes the active tab. The panel state you choose survives a
+reload.
+
+- **A phone surface.** The same four panel modules render on a phone — one shell, one renderer, no
+  phone-shaped copy of a list. `lib/mobile-nav.js` owns the destinations and the stack; the live
+  terminal host is never re-parented, so a session you navigate away from keeps running.
 - **Rename a session any time** — the ✎ on its row, a double-click on its tab, or `F2`. Live or
   exited, and it survives a server restart.
 - **Documents read like documents** — the identity block becomes a card, tables are tables,
@@ -66,6 +91,18 @@ the split and the rail width are draggable. The layout you choose survives a rel
   denied); markdown renders **repo-relative images inline**. A remote `![](https://…)` image is
   never fetched (no zero-click beacon); a binary stays listed but inert (open it in your editor).
 
+**Fixture mode.** `?fixture=proto` renders the whole surface from a bundled seed file, with the
+server unable to read any repository — that is how the design comparison is run
+(`npm run test:parity`), and it is never the default.
+
+## Artifact links are declarations, not integrations
+PMOS makes no outbound request and holds no credential. Linking an artifact to an external
+destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to
+`pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector
+configured its summary line says exactly that: *no connector configured — nothing was read, and
+nothing will be written*, with the approval buttons disabled. A difference summary it never read
+would be the watermelon this repo has a word for.
+
 ## The gates are real, never automatic (R5)
 `approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and
 clear the matching needs entry — only ever on your click.
@@ -83,9 +120,9 @@ count them. `pm_label` is **never** derived from a click — κ labels are the P
 
 ## Your own runs are searchable (the history lens)
 Every session's scrollback is already mirrored to disk, which makes it a record of what earlier
-runs actually **did** — the thing structured run rows don't carry. The rail's fourth lens,
-**history**, searches it; the filter box becomes the query. An agent working in a pane can ask
-the same question itself: `GET /api/search?q=…&ws=…`.
+runs actually **did** — the thing structured run rows don't carry. `GET /api/search?q=…&ws=…`
+searches it, and an agent working in a pane can ask the question itself. (The four-panel rebuild
+has not yet re-surfaced this as a UI lens — the endpoint is live, the front-end entry point is not.)
 
 Two guarantees. It is scoped to **one repo** — a workspace never searches another's history
 (R1/R3), and an unrecognised workspace id resolves to home, so it can only ever see less.

package/workspace/bin/pmos.js

@@ -14,41 +14,59 @@
  *
  * The server is started DETACHED: closing this terminal does not kill it — sessions
  * keep running until `pmos stop` (the persistent-server model, R7). Dependency-free.
+ *
+ * THE PORT IS DISCOVERED, NEVER ASSUMED (lib/server-discovery.js). Assuming 7433 is what made
+ * "add another repo to the running workspace" fail: after the EADDRINUSE advice moved the PM's
+ * workspace to 7500, a plain `pmos` in the next repo looked at 7433, saw nothing, and started a
+ * SECOND server there — registering the repo with a workspace nobody had on screen. Every command
+ * below therefore starts from `discover()`, and a port is only chosen when nothing is running.
  */
 'use strict';
 const http = require('http');
+const net = require('net');
 const fs = require('fs');
 const path = require('path');
 const { spawn, spawnSync } = require('child_process');
+const D = require('../lib/server-discovery');
 
 const WS = path.resolve(__dirname, '..');              // workspace/
 const STATE = path.join(WS, 'state');
-const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+// An explicit PMOS_WS_PORT is a PIN: this launcher then talks to that port and no other. Without
+// one, the port comes from discovery — the default first, then whatever the running servers
+// recorded for themselves.
+const PINNED = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : null;
 // pid/log are PER-PORT: a second workspace (or a test server) on another port must never clobber
 // this one's pid file — that is exactly how `pmos stop` was left unable to find the real server.
-const PIDFILE = path.join(STATE, `server-${PORT}.pid`);
-const LOGFILE = path.join(STATE, `server-${PORT}.log`);
-const URL_ = `http://127.0.0.1:${PORT}`;
+const pidFile = (port) => path.join(STATE, D.pidFileName(port));
+const logFile = (port) => path.join(STATE, `server-${port}.log`);
+const urlOf = (port) => `http://127.0.0.1:${port}`;
 const NO_OPEN = process.env.PMOS_NO_OPEN === '1';      // tests set this
 
 const say = (s) => console.log(s);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-function probe() {
+// A probe is a question, not a wait: 2.5s is generous for loopback JSON on a busy machine, and the
+// old 900ms was tight enough that a server under load read as "not running" — the launcher would
+// then start a second one and collide with the first.
+const PROBE_MS = 2500;
+function probe(port) {
   return new Promise((res) => {
-    const req = http.get(`${URL_}/api/sessions`, { timeout: 900 }, (r) => {
+    const req = http.get(`${urlOf(port)}/api/sessions`, { timeout: PROBE_MS }, (r) => {
       let b = ''; r.on('data', (c) => (b += c));
-      r.on('end', () => { try { res(JSON.parse(b)); } catch { res(null); } });
+      r.on('end', () => {
+        let j = null; try { j = JSON.parse(b); } catch {}
+        res(D.looksLikeWorkspace(j) ? j : null);       // JSON from something else is NOT our server
+      });
     });
     req.on('error', () => res(null));
     req.on('timeout', () => { req.destroy(); res(null); });
   });
 }
-function api(method, pathname, body) {
+function api(port, method, pathname, body) {
   return new Promise((res) => {
     const data = body ? JSON.stringify(body) : null;
-    const req = http.request(`${URL_}${pathname}`, {
-      method, timeout: 3000,
+    const req = http.request(`${urlOf(port)}${pathname}`, {
+      method, timeout: 5000,
       headers: data ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } : {},
     }, (r) => { let b = ''; r.on('data', (c) => (b += c)); r.on('end', () => { try { res(JSON.parse(b)); } catch { res(null); } }); });
     req.on('error', () => res(null));
@@ -58,6 +76,53 @@ function api(method, pathname, body) {
   });
 }
 
+/** Every workspace server that answers, in candidate order (the default port first). */
+async function discover() {
+  const ports = D.candidatePorts({ stateDir: STATE, pinned: PINNED });
+  const hits = await Promise.all(ports.map(async (port) => {
+    const s = await probe(port);
+    return s ? { port, sessions: s.sessions } : null;
+  }));
+  return hits.filter(Boolean);
+}
+
+/** Can we bind it ourselves? The only honest test of "free" — lsof answers a different question. */
+function portFree(port) {
+  return new Promise((res) => {
+    const s = net.createServer();
+    s.once('error', () => res(false));
+    s.once('listening', () => s.close(() => res(true)));
+    s.listen(port, '127.0.0.1');
+  });
+}
+
+/** Who holds this port, in words the PM can act on. posix only; null when we cannot tell. */
+function portOwner(port) {
+  if (process.platform === 'win32') return null;
+  try {
+    const r = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-F', 'cn'], { encoding: 'utf8' });
+    const lines = String(r.stdout || '').split('\n');
+    let pid = null, cmd = null;
+    for (const l of lines) {
+      if (l.startsWith('p') && pid === null) pid = Number(l.slice(1)) || null;
+      if (l.startsWith('c') && cmd === null) cmd = l.slice(1).trim() || null;
+    }
+    return pid ? { pid, cmd: cmd || 'unknown' } : null;
+  } catch { return null; }
+}
+
+// The pid of whatever is LISTENING on a port — the fallback when the pid file is missing
+// (a crash, or a stale run that removed it). posix only; Windows keeps the manual message.
+function listenerPid(port) {
+  const owner = portOwner(port);
+  return owner ? owner.pid : null;
+}
+
+/** Forget the records of servers that are neither answering nor alive (see stalePidFiles). */
+function cleanStalePids(livePorts) {
+  for (const f of D.stalePidFiles(STATE, { livePorts })) { try { fs.unlinkSync(f); } catch {} }
+}
+
 // The workspace is the REPO you are in, not the folder you happen to stand in — so `pmos`
 // from a subdirectory opens the whole repo, the same way every git tool behaves.
 function repoRootOf(dir) {
@@ -106,96 +171,184 @@ function ensureInstalled() {
 // Register the target directory and open the browser ON IT. The `focus` broadcast matters:
 // the OS may refocus an already-open tab instead of opening our URL, and without it the PM
 // would be looking at the previously-opened repo — the defect this replaces.
-async function openWorkspace(dir) {
+async function openWorkspace(dir, port) {
   const root = repoRootOf(dir);
-  const reg = await api('POST', '/api/workspaces', { root, name: path.basename(root) });
+  const reg = await api(port, 'POST', '/api/workspaces', { root, name: path.basename(root) });
   if (!reg || !reg.ok) {
     say(`✗ could not open ${root}${reg && reg.error ? ` — ${reg.error}` : ''}`);
-    openBrowser(URL_);
+    openBrowser(urlOf(port));
     return 1;
   }
   const w = reg.workspace;
-  say(`✓ workspace “${w.name}” — ${URL_}?ws=${w.id}`);
+  say(`✓ workspace “${w.name}” — ${urlOf(port)}?ws=${w.id}`);
   say(`  ${root}`);
-  openBrowser(`${URL_}?ws=${w.id}`);
+  openBrowser(`${urlOf(port)}?ws=${w.id}`);
   return 0;
 }
 
+/**
+ * Where to start a server, when none is running. Two failure shapes are separated here because the
+ * PM's next action differs:
+ *   - the PINNED port is taken → we do not silently move; a pin was an instruction. Say who holds it.
+ *   - the DEFAULT port is taken by something that is not a workspace → roll forward and SAY SO. The
+ *     old behaviour was to spawn into it anyway, print the child's EADDRINUSE, and stop — leaving
+ *     the PM to pick a port by hand and, having picked one, to lose the next repo to 7433.
+ */
+async function choosePort() {
+  const want = PINNED || D.DEFAULT_PORT;
+  if (await portFree(want)) return { port: want };
+  if (PINNED) return { port: null, blocked: want, owner: portOwner(want) };
+  // portFree is async and nextFreePort is pure, so probe the span first and let it pick.
+  const span = [];
+  for (let p = want; p < want + D.FALLBACK_SPAN; p++) span.push([p, await portFree(p)]);
+  const free = new Map(span);
+  const port = D.nextFreePort(want, (p) => free.get(p) === true);
+  return port ? { port, movedFrom: want, owner: portOwner(want) } : { port: null, blocked: want, owner: portOwner(want) };
+}
+
 async function up(dir) {
-  if (await probe()) return openWorkspace(dir);
+  // 1. Is a workspace already running — on ANY port it recorded, not just the one this shell guesses?
+  let live = await discover();
+  if (live.length) {
+    const port = live[0].port;
+    if (live.length > 1) {
+      // Two servers of one install is the split this change exists to prevent, and it can still be
+      // arrived at by hand (`npm start` twice on different ports). There is no reliable way to pick
+      // the one the PM is LOOKING at — workspaces.json and the session store are shared by both, so
+      // every per-repo signal reads the same on each — so this does not guess quietly: it uses
+      // candidate order, names every server it found, and says how to collapse them back to one.
+      say(`note: ${live.length} workspace servers are running (${live.map((l) => l.port).join(', ')}) — using ${port}.`);
+      say('      They share this install\'s state but not each other\'s live terminals. `pmos stop` shuts them all down.');
+    }
+    return openWorkspace(dir, port);
+  }
   if (!ensureInstalled()) return 1;
   fs.mkdirSync(STATE, { recursive: true });
+  cleanStalePids([]);
+
+  const choice = await choosePort();
+  if (!choice.port) {
+    const who = choice.owner ? `${choice.owner.cmd} (pid ${choice.owner.pid})` : 'another program';
+    say(`✗ port ${choice.blocked} is held by ${who}, and it is not a workspace server.`);
+    say(PINNED
+      ? `  PMOS_WS_PORT pinned this launcher to ${choice.blocked}. Stop that process, or pin a free port instead.`
+      : `  Stop that process, or start elsewhere:  PMOS_WS_PORT=7500 pmos`);
+    return 1;
+  }
+  if (choice.movedFrom && choice.port !== choice.movedFrom) {
+    const who = choice.owner ? `${choice.owner.cmd} (pid ${choice.owner.pid})` : 'another program';
+    say(`note: port ${choice.movedFrom} is in use by ${who} — starting this workspace on ${choice.port} instead.`);
+  }
+  const port = choice.port;
+
+  const LOGFILE = logFile(port);
+  // Only THIS attempt's log lines may be shown below. The log is append-only, so reading its tail
+  // reprinted failures from previous launches — the PM saw the same EADDRINUSE three times and
+  // reasonably read it as three live conflicts.
+  let logFrom = 0;
+  try { logFrom = fs.statSync(LOGFILE).size; } catch {}
   const log = fs.openSync(LOGFILE, 'a');
   // Tell the server which repo is HOME. An installed/vendored workspace does not live inside the
   // repo it manages (it's under node_modules or an npx bundle), so the server cannot derive home
   // from its own location — without this it would register the PACKAGE folder as "Home" (the
   // tenant defect). Pass the repo we're opening; a caller-set PMOS_SELF_ROOT still wins.
-  const env = { ...process.env, PMOS_SELF_ROOT: process.env.PMOS_SELF_ROOT || repoRootOf(dir) };
+  // PMOS_WS_PORT is passed EXPLICITLY: the port was chosen here, and inheriting the shell's idea
+  // of it would put the child somewhere other than where this launcher then looks.
+  const env = {
+    ...process.env,
+    PMOS_SELF_ROOT: process.env.PMOS_SELF_ROOT || repoRootOf(dir),
+    PMOS_WS_PORT: String(port),
+  };
   const child = spawn(process.execPath, [path.join(WS, 'server.js')], {
     cwd: WS, detached: true, stdio: ['ignore', log, log], env,
   });
   child.unref();
-  try { fs.writeFileSync(PIDFILE, String(child.pid)); } catch {}
+  try { fs.writeFileSync(pidFile(port), String(child.pid)); } catch {}
   process.stdout.write('starting the workspace ');
   for (let i = 0; i < 40; i++) {                        // up to ~10s
-    if (await probe()) {
+    if (await probe(port)) {
       say('');
       say('  sessions keep running after you close this terminal · `pmos stop` shuts it down');
-      return openWorkspace(dir);
+      return openWorkspace(dir, port);
     }
     process.stdout.write('.');
     await sleep(250);
   }
+  // Last chance before reporting failure: another launcher may have won the race and be serving
+  // this repo already, on a port it recorded while we were waiting.
+  live = await discover();
+  if (live.length) { say(''); return openWorkspace(dir, live[0].port); }
+
   say(`\n✗ the server did not come up. Its log says:`);
-  try { say('  ' + fs.readFileSync(LOGFILE, 'utf8').trim().split('\n').slice(-6).join('\n  ')); } catch {}
+  try {
+    const fd = fs.openSync(LOGFILE, 'r');
+    const size = fs.statSync(LOGFILE).size;
+    const buf = Buffer.alloc(Math.max(0, size - logFrom));
+    if (buf.length) fs.readSync(fd, buf, 0, buf.length, logFrom);
+    fs.closeSync(fd);
+    const fresh = buf.toString('utf8').trim();
+    say(fresh ? '  ' + fresh.split('\n').slice(-6).join('\n  ') : '  (it wrote nothing at all)');
+  } catch {}
   say('  Run `pmos doctor` for a diagnosis.');
   return 1;
 }
 
 async function status() {
-  const s = await probe();
-  if (!s) { say(`○ not running (start it with: pmos)`); return 1; }
-  const wl = (await api('GET', '/api/workspaces')) || { workspaces: [] };
-  const live = s.sessions.filter((x) => x.state !== 'exited').length;
-  say(`✓ running — ${URL_}`);
-  say(`  ${wl.workspaces.length} workspace(s): ${wl.workspaces.map((w) => w.name).join(' · ') || 'none'}`);
-  say(`  ${s.sessions.length} session(s), ${live} live: ${s.sessions.map((x) => `${x.name}[${x.state}]`).join(' · ') || 'none'}`);
+  const live = await discover();
+  if (!live.length) { say(`○ not running (start it with: pmos)`); return 1; }
+  for (const s of live) {
+    const wl = (await api(s.port, 'GET', '/api/workspaces')) || { workspaces: [] };
+    const alive = s.sessions.filter((x) => x.state !== 'exited').length;
+    say(`✓ running — ${urlOf(s.port)}`);
+    say(`  ${wl.workspaces.length} workspace(s): ${wl.workspaces.map((w) => w.name).join(' · ') || 'none'}`);
+    say(`  ${s.sessions.length} session(s), ${alive} live: ${s.sessions.map((x) => `${x.name}[${x.state}]`).join(' · ') || 'none'}`);
+  }
+  if (live.length > 1) say(`note: ${live.length} servers are running — a repo opened by \`pmos\` goes to ${live[0].port}.`);
   return 0;
 }
 
 async function ls() {
-  if (!(await probe())) { say('○ not running (start it with: pmos)'); return 1; }
-  const wl = (await api('GET', '/api/workspaces')) || { workspaces: [] };
-  if (!wl.workspaces.length) { say('no workspaces registered.'); return 0; }
-  for (const w of wl.workspaces) {
-    say(`${w.home ? '★' : '·'} ${w.name}  ${w.sessions} session(s)  [${w.shape}]`);
-    say(`   ${w.root}`);
+  const live = await discover();
+  if (!live.length) { say('○ not running (start it with: pmos)'); return 1; }
+  let any = false;
+  for (const s of live) {
+    const wl = (await api(s.port, 'GET', '/api/workspaces')) || { workspaces: [] };
+    if (live.length > 1) say(`— ${urlOf(s.port)}`);
+    for (const w of wl.workspaces) {
+      any = true;
+      say(`${w.home ? '★' : '·'} ${w.name}  ${w.sessions} session(s)  [${w.shape}]`);
+      say(`   ${w.root}`);
+    }
   }
+  if (!any) say('no workspaces registered.');
   return 0;
 }
 
-// The pid of whatever is LISTENING on our port — the fallback when the pid file is missing
-// (a crash, or a stale run that removed it). posix only; Windows keeps the manual message.
-function listenerPid() {
-  if (process.platform === 'win32') return null;
-  try {
-    const r = spawnSync('lsof', ['-ti', `tcp:${PORT}`, '-sTCP:LISTEN'], { encoding: 'utf8' });
-    const pid = Number(String(r.stdout || '').split('\n')[0].trim());
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch { return null; }
+/** Stop ONE server, by pid file if it left one, otherwise by whoever owns the port. */
+async function stopOne(port) {
+  let pid = null;
+  try { pid = Number(fs.readFileSync(pidFile(port), 'utf8').trim()) || null; } catch {}
+  if (!pid) pid = listenerPid(port);   // pid file lost — find the server by the port it owns
+  if (!pid) { say(`✗ could not locate the server on port ${port} (no pid file, and nothing I can see owns it). Stop it manually.`); return 1; }
+  try { process.kill(pid); } catch (e) { say(`✗ could not signal pid ${pid}: ${e.message}`); return 1; }
+  for (let i = 0; i < 20; i++) {
+    if (!(await probe(port))) { say(`✓ stopped — ${urlOf(port)}`); try { fs.unlinkSync(pidFile(port)); } catch {} return 0; }
+    await sleep(250);
+  }
+  say(`✗ port ${port} still responding after 5s — kill it manually (pid ${pid}).`);
+  return 1;
 }
 
 async function stop() {
-  if (!(await probe())) { say('○ not running.'); try { fs.unlinkSync(PIDFILE); } catch {} return 0; }
-  let pid = null;
-  try { pid = Number(fs.readFileSync(PIDFILE, 'utf8').trim()); } catch {}
-  if (!pid) pid = listenerPid();     // pid file lost — find the server by the port it owns
-  if (!pid) { say(`✗ could not locate the server process (no pid file, and nothing I can see owns port ${PORT}). Stop it manually.`); return 1; }
+  const live = await discover();
+  if (!live.length) { say('○ not running.'); cleanStalePids([]); return 0; }
   // sessions are tmux-backed: stopping the server leaves them running; the next `pmos` re-attaches.
   say('stopping the workspace — sessions keep running in tmux and re-attach on the next launch…');
-  try { process.kill(pid); } catch (e) { say(`✗ could not signal pid ${pid}: ${e.message}`); return 1; }
-  for (let i = 0; i < 20; i++) { if (!(await probe())) { say('✓ stopped.'); try { fs.unlinkSync(PIDFILE); } catch {} return 0; } await sleep(250); }
-  say('✗ still responding after 5s — kill it manually.'); return 1;
+  // ALL of them, not just the first: a stranded second server is precisely what this command is
+  // reached for, and stopping one of two leaves the PM in the state they came here to escape.
+  let code = 0;
+  for (const s of live) code = (await stopOne(s.port)) || code;
+  return code;
 }
 
 function doctor() {