create-pmos 0.16.0 → 0.17.0

package/README.md

@@ -333,6 +333,63 @@ 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.17.0
+
+**Your board stops calling shipped work unstarted.** Run `npx create-pmos@latest workspace`; the
+version bump means an existing install auto-upgrades.
+
+- **An initiative's status is now read from what happened, not from what someone typed.** The
+  workspace took each initiative's state from a `status:` line written by hand into a PRD and
+  matched it against a list of words. In the repo this was built in, that one field held 23
+  different values, 33 initiatives had none at all, and several were cut off mid-sentence by a
+  stray comma. The plainest value of the lot — `build complete, PR #138` — matched the word
+  "build" first and displayed as *in progress*. Status is now derived from your acceptance
+  records, your logged runs, your open items, and your repository's own merge history, and each
+  row states which of those it was read from. Nothing you type can move it.
+- **`delivered` and `accepted` are no longer the same thing.** Work that merged and work you
+  actually signed off are now separate states. That gap is usually the interesting number: in the
+  repo this was built in, 62 of 63 delivered initiatives had no acceptance recorded — invisible
+  while both wore one label.
+- **The board reads your whole project history, not just the branch you are standing on.** It
+  shared a commit range with the CI gate, and that range is *empty* when your branch is level with
+  `main` — so every initiative reported "no implementation commits" and fell back to its earliest
+  stage. Work finished weeks ago looked identical to work never begun. The gate still reads only
+  the pull request, which is correct for judging whether a spec came before its build.
+- **A history it cannot read is now said out loud.** In a shallow clone (some CI checkouts) the
+  delivery history genuinely is not there. The board reports that, with the reason, instead of
+  quietly showing everything as unstarted — which would look exactly like a project where nothing
+  has happened.
+
+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.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.16.0",
+  "version": "0.17.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@198c57c
-assembled: 2026-07-30
+kernel-source: pmos@4cb5198
+assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -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>
 

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() {

package/workspace/doctor.js

@@ -6,6 +6,8 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
+const http = require('http');
+const net = require('net');
 const { spawnSync } = require('child_process');
 
 const checks = [];
@@ -116,6 +118,58 @@ function binaryArch(file) {
     console.log('  optional fix: install tmux (macOS `brew install tmux`; Linux `apt install tmux`) for restart-proof sessions.');
   }
 
+  // 6. ports — who is running, and who holds the door. `pmos` points here after a failed start,
+  //    and until now the doctor had nothing to say about the one thing that had just failed.
+  //    Reports every workspace server it can find (the launcher discovers them the same way) and,
+  //    when none is running, whether the port it would use is free and who holds it if not.
+  {
+    const D = require('./lib/server-discovery');
+    const STATE = path.join(__dirname, 'state');
+    const pinned = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : null;
+    const ports = D.candidatePorts({ stateDir: STATE, pinned });
+    const probe = (port) => new Promise((res) => {
+      const req = http.get(`http://127.0.0.1:${port}/api/sessions`, { timeout: 2000 }, (r) => {
+        let b = ''; r.on('data', (c) => (b += c));
+        r.on('end', () => { let j = null; try { j = JSON.parse(b); } catch {} res(D.looksLikeWorkspace(j) ? j : null); });
+      });
+      req.on('error', () => res(null));
+      req.on('timeout', () => { req.destroy(); res(null); });
+    });
+    const free = (port) => 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');
+    });
+    const owner = (port) => {
+      if (process.platform === 'win32') return null;
+      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 ? `${cmd || 'unknown'} (pid ${pid})` : null;
+    };
+    const live = [];
+    for (const p of ports) if (await probe(p)) live.push(p);
+    if (live.length === 1) ok(`workspace server running on port ${live[0]} — http://127.0.0.1:${live[0]}`);
+    else if (live.length > 1) {
+      console.log(`• ${live.length} workspace servers are running (ports ${live.join(', ')}).`);
+      console.log('  Each hosts its OWN repos, and a browser tab only sees one of them. `pmos stop` shuts them all down.');
+    } else {
+      const want = pinned || D.DEFAULT_PORT;
+      if (await free(want)) ok(`no server running; port ${want} is free (start it with: pmos)`);
+      else {
+        const who = owner(want) || 'another program';
+        bad(`no workspace server is answering, but port ${want} is held by ${who}`,
+          pinned ? `stop that process, or pin a free port:  PMOS_WS_PORT=7500 pmos`
+            : 'run `pmos` — it starts on the next free port when this one is taken; or stop that process');
+      }
+    }
+  }
+
   const fails = checks.filter((c) => !c).length;
   console.log(`\n${checks.length - fails}/${checks.length} checks passed${fails ? ' — fix the ✗ items above, then re-run npm run doctor' : ' — environment healthy, npm start away'}`);
   process.exit(fails ? 1 : 0);