create-pmos 0.16.0 → 0.16.1

package/README.md

@@ -333,6 +333,33 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.16.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@198c57c
-assembled: 2026-07-30
+kernel-source: pmos@011b77e
+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);

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.16.0",
+  "version": "0.16.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.16.0",
+      "version": "0.16.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "private": true,
   "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/data.js

@@ -774,6 +774,34 @@ export async function addRepo({ source, kind }) {
   };
 }
 
+/**
+ * panel-repos.js — `chooseFolder(start)`. The machine's OWN folder dialog, opened by the server.
+ *
+ * A browser cannot hand back an absolute path — its directory picker yields a name and a handle,
+ * never a path — so the add-a-product form could only ever offer a text field, and the PM had to
+ * know and type the path of the repo they were looking at. The server runs on the PM's machine and
+ * binds 127.0.0.1 (D62), so it opens the native chooser and returns the chosen path; this function
+ * only asks. Registration still goes through `addRepo()` → POST /api/workspaces, so nothing here
+ * bypasses a guard: the dialog produces a string, and the PM confirms it like any other.
+ *
+ * `{cancelled:true}` and `{unsupported:true}` are ANSWERS, not failures — a headless Linux box has
+ * no chooser at all, which is what `listFolder()` below stands in for.
+ */
+export async function chooseFolder(start) {
+  if (FIXTURE) return { ok: false, unsupported: true };
+  return postJson('/api/pick-folder', { start: start || '' });
+}
+
+/**
+ * panel-repos.js — `listFolder(dir)`. The in-app folder browser's data source, for when there is
+ * no native chooser (and for anyone who prefers it). The server returns directory NAMES only —
+ * never a file, never a byte of content — and flags which ones are git repositories.
+ */
+export async function listFolder(dir) {
+  if (FIXTURE) return { ok: false, error: 'fixture mode has no filesystem' };
+  return getJson('/api/fs/list', dir ? { path: dir } : null);
+}
+
 /**
  * panel-tabs.js — `startSession(slug, sess)`. Deliberately NOT a spawn.
  *

package/workspace/public/pm/panel-repos.js

@@ -299,6 +299,93 @@ function field(key, value) {
   });
 }
 
+/* ── choosing the folder, instead of typing its path ─────────────────────────────────────────
+ * The form's local branch used to be a bare text field, so "add the repo I am looking at" meant
+ * knowing its absolute path and typing it correctly — and the two endpoints that exist to avoid
+ * exactly that (`/api/pick-folder`, `/api/fs/list`) had no caller anywhere in the front end.
+ *
+ * Two ways in, because one of them is not always there: the machine's native dialog first, and the
+ * in-app browser when there is no native chooser (headless Linux), when one is already open, or
+ * when the PM asks for it. A cancelled dialog changes nothing — it is an answer, not a failure.
+ */
+const browseRowStyle = 'display:grid;grid-template-columns:76px 1fr auto;gap:10px;padding:10px 14px';
+const chooseStyle = 'font-family:var(--mono);font-size:10.5px;padding:5px 10px;min-height:32px;'
+  + 'background:transparent;border:1px solid var(--border);color:var(--muted-foreground)';
+
+/** The in-app browser, opened at `dir` (empty = the server's idea of home). */
+function openBrowse(dir) {
+  // Fixture mode reads NOTHING off this machine — the comparator drives this surface, and a run
+  // that opened a dialog or listed the PM's home directory would be doing real work behind a
+  // scripted board. It says so instead of degrading into a vaguer "no endpoint" line.
+  if (FIXTURE) {
+    setState({ addLog: [{ t: 'the folder chooser is off in fixture mode — nothing on this machine is read', c: 'var(--warning)' }] });
+    return;
+  }
+  if (!dataMod || typeof dataMod.listFolder !== 'function') {
+    setState({ addLog: [{ t: 'no local endpoint for browsing folders — type the path instead', c: 'var(--warning)' }] });
+    return;
+  }
+  setState({ addBrowse: { loading: true, path: dir || '', entries: [] } });
+  Promise.resolve(dataMod.listFolder(dir)).then((res) => {
+    if (!res || res.ok === false) {
+      setState({ addBrowse: { path: dir || '', entries: [], error: (res && res.error) || 'that folder could not be listed' } });
+      return;
+    }
+    setState({ addBrowse: res });
+  }).catch((e) => setState({ addBrowse: { path: dir || '', entries: [], error: e && e.message ? e.message : String(e) } }));
+}
+
+/** Ask the server to open the machine's folder dialog; fall back to the in-app browser. */
+function chooseFolder() {
+  if (FIXTURE || !dataMod || typeof dataMod.chooseFolder !== 'function') { openBrowse(state.addPath); return; }
+  setState({ addPicking: true });
+  Promise.resolve(dataMod.chooseFolder(state.addPath)).then((res) => {
+    setState({ addPicking: false });
+    if (res && res.ok && res.root) { setState({ addPath: res.root, addBrowse: null }); return; }
+    if (res && res.cancelled) return;                       // the PM closed the dialog: no change, no noise
+    openBrowse(state.addPath);                              // unsupported, busy, or unreachable → in-app
+  }).catch(() => { setState({ addPicking: false }); openBrowse(state.addPath); });
+}
+
+/** Take the folder currently open in the browser as the answer. */
+function useFolder(p) {
+  if (!p) return;
+  setState({ addPath: p, addBrowse: null });
+}
+
+const browseRow = (label, title, onClick, muted) => el('button', {
+  onClick, title,
+  style: 'display:flex;align-items:center;gap:8px;width:100%;padding:5px 10px;min-height:28px;text-align:left;'
+    + 'font-family:var(--mono);font-size:11px;color:var(--' + (muted ? 'muted-foreground' : 'foreground') + ')',
+  hover: 'background:var(--accent)',
+}, label);
+
+/** The browser body: where we are, one row per sub-directory, and a way to take the current one. */
+function browseBody() {
+  const b = state.addBrowse;
+  const rows = [];
+  rows.push(el('div', { style: 'display:flex;align-items:center;gap:8px;padding:6px 10px;border-bottom:1px solid var(--border)' },
+    el('span', { style: 'flex:1;font-family:var(--mono);font-size:11px;overflow-wrap:anywhere' }, ip(b.path || '…')),
+    el('button', { onClick: () => useFolder(b.path), style: chooseStyle + ';min-height:26px', hover: 'border-color:var(--ring)' },
+      ip('use this folder')),
+  ));
+  if (b.error) rows.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--destructive)' }, ip(b.error)));
+  else if (b.loading) rows.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--muted-foreground)' }, ip('reading…')));
+  else {
+    const list = [];
+    if (b.parent) list.push(browseRow('↑  ..', b.parent, () => openBrowse(b.parent), true));
+    for (const e of b.entries || []) {
+      // The repo marker is the whole point of showing this list rather than a plain file chooser:
+      // it says which of these folders PMOS can actually open as a workspace.
+      list.push(browseRow((e.isRepo ? '⑂  ' : '·  ') + e.name, e.path, () => openBrowse(e.path), !e.isRepo));
+    }
+    if (b.denied) list.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--warning)' }, ip('this folder cannot be read')));
+    else if (!list.length) list.push(el('div', { style: 'padding:8px 10px;font-size:11.5px;color:var(--muted-foreground)' }, ip('no sub-folders here')));
+    rows.push(el('div', { style: 'max-height:220px;overflow-y:auto' }, list));
+  }
+  return el('div', { style: 'margin:0 14px 10px;border:1px solid var(--border)' }, rows);
+}
+
 function srcButton(id, label) {
   const on = state.addSrc === id;
   return el('button', {
@@ -425,10 +512,16 @@ export function addProductBody() {
       el('button', { onClick: ingestGithub, style: goStyle }, '⇣ connect + ingest'),
     ));
   } else {
-    out.push(el('div', { style: rowStyle },
+    // Field FIRST, chooser beside it: the path is still typeable (and still the thing that gets
+    // registered), the button only fills it in. The row keeps label + input as its first two
+    // children, which is the shape panel 1's suite reads.
+    out.push(el('div', { style: browseRowStyle },
       el('span', { style: labelStyle }, 'folder'),
       field('addPath', state.addPath),
+      el('button', { onClick: chooseFolder, style: chooseStyle, hover: 'border-color:var(--ring)' },
+        ip(state.addPicking ? 'choosing…' : 'choose…')),
     ));
+    if (state.addBrowse) out.push(browseBody());
     out.push(el('div', { style: 'padding:2px 14px 8px;font-size:11.5px;line-height:1.5;color:var(--muted-foreground)' },
       'Starts with an empty board — nothing is imported from a bare folder. File the first initiative to begin.'));
     out.push(el('div', { style: 'padding:2px 14px 12px;border-bottom:1px solid var(--border)' },

package/workspace/public/pm/state.js

@@ -28,6 +28,10 @@ function initial() {
     product: null, newSessProfile: 'claude-work', intgSynced: {},
     addSrc: 'github', addRepo: 'github.com/acme/atlas-mobile', addPath: '~/code/notes-cli',
     addLog: [], addedProducts: [], extraKnow: {},
+    // the folder chooser's two transient bits: the in-app browser's current listing (null = closed)
+    // and whether the machine's native dialog is open. Neither is persisted — a dialog that
+    // "reopens" on reload is a lie about what the OS is showing.
+    addBrowse: null, addPicking: false,
     newType: 'init', newName: '', newSlug: '', newAnchor: null, newFlow: 'adlc-feature',
     userGroups: {}, userKrs: {}, addedInits: {}, userInits: {}, selTask: null, collapsedPhases: {},
     detail: { kind: 'init' },

package/workspace/server.js

@@ -121,7 +121,11 @@ const CLONE_DIR = path.join(STATE, 'clones');
 // PMOS's OWN memory of which profile to preselect per agent binary (profiles R8.2). It is a
 // workspace preference, not an agent attribute — the file lives here for exactly that reason.
 const PREFS_FILE = path.join(STATE, 'prefs.json');
-const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+const discovery = require('./lib/server-discovery');    // how a launcher FINDS a running server
+const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : discovery.DEFAULT_PORT;
+// Written on listen, removed on shutdown. This is the server's answer to "where am I?" — see
+// lib/server-discovery.js for why a launcher must ask rather than assume.
+const PID_FILE = path.join(STATE, discovery.pidFileName(PORT));
 const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
 const layoutModel = require('./lib/layout');           // the arrangement model — validated on BOTH sides
 // Bind + token policy (D62). DEFAULT = loopback only, no token (unchanged). The opt-in remote flag
@@ -3909,6 +3913,7 @@ if (require.main === module) {
     if (shuttingDown) return; shuttingDown = true;
     for (const s of sessions.values()) if (s.pty) { try { persist(s); } catch {} }
     for (const l of listeners) { try { l.close(); } catch {} }
+    try { fs.unlinkSync(PID_FILE); } catch {}   // stop being discoverable the moment we stop serving
     process.exit(0);
   };
   process.on('SIGTERM', shutdown);
@@ -3916,7 +3921,9 @@ if (require.main === module) {
   const onError = (e) => {
     if (e.code === 'EADDRINUSE') {
       console.error(`✗ port ${PORT} is already in use (another workspace server running?).`);
-      console.error(`  Stop it, or start on another port:  PMOS_WS_PORT=7500 npm start`);
+      console.error(`  \`pmos\` finds a running workspace on any port and reuses it, and picks a free`);
+      console.error(`  port when something else holds this one. \`pmos stop\` shuts running ones down.`);
+      console.error(`  To pin a port by hand:  PMOS_WS_PORT=7500 npm start`);
       process.exit(1);
     }
     if (e.code === 'EADDRNOTAVAIL') {
@@ -3931,7 +3938,13 @@ if (require.main === module) {
     l.on('error', onError);
     l.listen(PORT, addr, () => {
       // stdout only — no request/header logging (D08). Banner (incl. any generated token) printed once.
-      if (++up === BIND.binds.length) for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
+      if (++up !== BIND.binds.length) return;
+      // Record the port WE are serving, whoever started us. The launcher discovers a running
+      // workspace from these files, so a server started by `npm start` (which is exactly what the
+      // old EADDRINUSE advice told the PM to do, on another port) has to leave the same trace as
+      // one started by `pmos` — otherwise the next `pmos` cannot see it and starts a second server.
+      try { fs.mkdirSync(STATE, { recursive: true }); fs.writeFileSync(PID_FILE, String(process.pid)); } catch {}
+      for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
     });
   });
 }