create-pmos 0.232.0 → 0.233.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.232.0",
+  "version": "0.233.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. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `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@ac35488
+kernel-source: pmos@c113f92
 assembled: 2026-10-14
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-14T08:45:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-14T09:17:36Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-14T08:45:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-14T09:17:36Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-14T08:45:03Z"}
+generated: {by: process:create-pmos, at: "2026-10-14T09:17:36Z"}
 status: stable
 ---
 

package/workspace/bin/pmos.js

@@ -57,9 +57,9 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // 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) {
+function probe(port, ms = PROBE_MS) {
   return new Promise((res) => {
-    const req = http.get(`${urlOf(port)}/api/sessions`, { timeout: PROBE_MS }, (r) => {
+    const req = http.get(`${urlOf(port)}/api/sessions`, { timeout: ms }, (r) => {
       let b = ''; r.on('data', (c) => (b += c));
       r.on('end', () => {
         let j = null; try { j = JSON.parse(b); } catch {}
@@ -94,6 +94,31 @@ async function discover() {
   return hits.filter(Boolean);
 }
 
+/**
+ * Our own servers that are running but did not answer the probe (lib/server-discovery.js busyServers).
+ * Pinned launches only look at the pin, the same as discover().
+ */
+async function busy(livePorts = []) {
+  const held = [];
+  for (const p of D.candidatePorts({ stateDir: STATE, pinned: PINNED })) if (!livePorts.includes(p) && !(await portFree(p))) held.push(p);
+  return D.busyServers(STATE, { livePorts, heldPorts: held });
+}
+
+// How long to wait for a busy server before giving up on it. A server that is only slow answers well
+// inside this; one that is stuck does not, and starting a second server beside it does not help.
+const BUSY_WAIT_MS = 60000;
+async function waitForBusy(servers) {
+  process.stdout.write(`the workspace on port ${servers[0].port} is busy; waiting for it to answer `);
+  const until = Date.now() + BUSY_WAIT_MS;
+  while (Date.now() < until) {
+    for (const b of servers) if (await probe(b.port, 10000)) { say(''); return b.port; }
+    process.stdout.write('.');
+    await sleep(1000);
+  }
+  say('');
+  return null;
+}
+
 /** Can we bind it ourselves? The only honest test of "free" — lsof answers a different question. */
 function portFree(port) {
   return new Promise((res) => {
@@ -257,7 +282,7 @@ async function servesTailnet(port) {
 
 // `remote` starts a NEW server in tailnet mode (pmos phone); a server that is already running is reused as it is.
 // `open: false` registers the repo without opening the desktop browser.
-async function up(dir, { remote = false, open = true } = {}) {
+async function up(dir, { remote = false, open = true, waited = false } = {}) {
   // 1. Is a workspace already running — on ANY port it recorded, not just the one this shell guesses?
   let live = await discover();
   // A server that predates this install is running OLD code under NEW files (or the reverse). Reusing
@@ -289,6 +314,15 @@ async function up(dir, { remote = false, open = true } = {}) {
     }
     return openWorkspace(dir, port, { open });
   }
+  // 2. Is one of OUR servers running but too busy to answer? Then wait for it. Starting a second
+  //    server on the next port is what left a Windows PM with two servers and neither loading.
+  const slow = waited ? [] : await busy();
+  if (slow.length) {
+    if (await waitForBusy(slow)) return up(dir, { remote, open, waited: true });   // re-run: it may be an older version
+    say(`✗ the workspace server on port ${slow[0].port} (pid ${slow[0].pid}) is running but has not answered for a minute.`);
+    say('  Run `pmos stop`, then `pmos` to restart it. If it happens again, run `pmos doctor` and send its output.');
+    return 1;
+  }
   if (!ensureInstalled()) return 1;
   fs.mkdirSync(STATE, { recursive: true });
   cleanStalePids([]);
@@ -337,7 +371,10 @@ async function up(dir, { remote = false, open = true } = {}) {
   child.unref();
   try { fs.writeFileSync(pidFile(port), String(child.pid)); } catch {}
   process.stdout.write('starting the workspace ');
-  for (let i = 0; i < 40 && !exited; i++) {             // up to ~10s
+  // Up to ~60s while the server process is alive. A first start on Windows (antivirus scanning every
+  // new file) can take longer than 10s, and giving up early left a server starting with nobody waiting.
+  for (let i = 0; i < 240 && !exited; i++) {
+    if (i === 40) process.stdout.write('\n  still starting — a first start can take up to a minute ');
     if (await probe(port)) {
       say('');
       say('  sessions keep running after you close this terminal · `pmos stop` shuts it down');
@@ -404,7 +441,8 @@ async function stopOne(port) {
   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; }
+    // Gone means the process ended or the port is free. "Not answering" is not enough: a busy server does not answer either.
+    if (!D.pidAlive(pid) || await portFree(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}).`);
@@ -412,7 +450,9 @@ async function stopOne(port) {
 }
 
 async function stop() {
-  const live = await discover();
+  // A busy server does not answer the probe but is still ours, and still holds its port. Stop it too.
+  const answering = await discover();
+  const live = [...answering, ...await busy(answering.map((l) => l.port))];
   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…');

package/workspace/doctor.js

@@ -167,7 +167,11 @@ function binaryArch(file) {
     } else {
       const want = pinned || D.DEFAULT_PORT;
       if (await free(want)) ok(`no server running; port ${want} is free (start it with: pmos)`);
-      else {
+      else if (D.busyServers(STATE, { heldPorts: [want] }).length) {
+        const b = D.busyServers(STATE, { heldPorts: [want] })[0];
+        bad(`the workspace server on port ${want} (pid ${b.pid}) is running but did not answer within 2s — it is busy`,
+          'wait a minute and run `pmos` again; if it still does not answer, run `pmos stop`, then `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`

package/workspace/lib/server-discovery.js

@@ -102,6 +102,21 @@ function stalePidFiles(stateDir, { livePorts = [], alive = pidAlive } = {}) {
     .map((r) => r.file);
 }
 
+/**
+ * The workspace servers that are running but did not answer: a record whose port is not among the
+ * live ones, whose port is still held, and whose pid is alive. A busy server (a long synchronous job,
+ * or a slow first start on Windows) looks exactly like this. Reading it as "something else holds the
+ * port" is how `pmos` started a second server beside a first one that was only slow. `heldPorts` is
+ * injected (the caller owns the socket), so this stays pure.
+ */
+function busyServers(stateDir, { livePorts = [], heldPorts = [], alive = pidAlive } = {}) {
+  const live = new Set(livePorts.map(Number));
+  const held = new Set(heldPorts.map(Number));
+  return pidRecords(stateDir)
+    .filter((r) => !live.has(r.port) && held.has(r.port) && alive(r.pid))
+    .map((r) => ({ port: r.port, pid: r.pid }));
+}
+
 /**
  * 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.
@@ -123,5 +138,5 @@ function looksLikeWorkspace(body) {
 
 module.exports = {
   DEFAULT_PORT, FALLBACK_SPAN, PID_RE,
-  pidFileName, pidRecords, candidatePorts, pidAlive, stalePidFiles, nextFreePort, looksLikeWorkspace,
+  pidFileName, pidRecords, candidatePorts, pidAlive, stalePidFiles, busyServers, nextFreePort, looksLikeWorkspace,
 };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.232.0",
+  "version": "0.233.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.232.0",
+      "version": "0.233.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

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

package/workspace/test-lists/one-line-setup.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "one-line-setup: on Windows the background server hides the console window of every command it runs (lib/win-hide.js).",
-  "modules": ["win-hide.test.js"],
-  "seconds": { "win-hide.test.js": 1 }
+  "_comment": "one-line-setup: on Windows the background server hides the console window of every command it runs (lib/win-hide.js); `pmos` waits for its own busy server instead of starting a second one (busy-server.test.js).",
+  "modules": ["win-hide.test.js", "busy-server.test.js"],
+  "seconds": { "win-hide.test.js": 1, "busy-server.test.js": 12 }
 }