create-pmos 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "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@2e880f8
+kernel-source: pmos@f4589bf
 assembled: 2026-07-27
 mode: vendor

package/workspace/bin/pmos.js

@@ -74,20 +74,23 @@ function openBrowser(url) {
   try { spawn(cmd[0], cmd[1], { detached: true, stdio: 'ignore' }).unref(); } catch {}
 }
 
-// node-pty compiles pty.node (require loads it) and, on macOS only, a separate spawn-helper
-// binary (exec'd at spawn — Linux uses forkpty directly and never builds it). A partial macOS
-// build with pty.node but no spawn-helper loads fine yet dies with 'posix_spawnp failed' on every
-// session — the #1 tenant failure, common on a brand-new/non-LTS Node. So "installed" is not
-// "works": verify the artifacts the running platform actually needs, not just the package folder.
-function nodePtyBuildOk() {
-  const rel = path.join(WS, 'node_modules', 'node-pty', 'build', 'Release');
-  if (!fs.existsSync(path.join(rel, 'pty.node'))) return false;
-  return process.platform !== 'darwin' || fs.existsSync(path.join(rel, 'spawn-helper'));
-}
 function npm(args) {
   return spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args,
     { cwd: WS, stdio: 'inherit', shell: process.platform === 'win32' }).status === 0;
 }
+// node-pty exec()s a prebuilt macOS `spawn-helper` to open each PTY; the prebuild-extraction path
+// can drop its executable bit, and then EVERY session dies with 'posix_spawnp failed' — the #1
+// field failure. Restore +x wherever node-pty keeps the helper (prebuilds/<plat>-<arch>/ or a
+// from-source build/Release/) before the server starts. Idempotent; no-op off macOS.
+function fixSpawnHelperPerms() {
+  if (process.platform === 'win32') return;
+  const root = path.join(WS, 'node_modules', 'node-pty');
+  const targets = [path.join(root, 'build', 'Release', 'spawn-helper')];
+  try { const pb = path.join(root, 'prebuilds'); for (const d of fs.readdirSync(pb)) targets.push(path.join(pb, d, 'spawn-helper')); } catch {}
+  for (const f of targets) {
+    try { const st = fs.statSync(f); if (!(st.mode & 0o111)) fs.chmodSync(f, st.mode | 0o755); } catch {}
+  }
+}
 function ensureInstalled() {
   if (!fs.existsSync(path.join(WS, 'node_modules', 'node-pty'))) {
     say('First run — installing the workspace (one-time, ~20s)…');
@@ -96,21 +99,7 @@ function ensureInstalled() {
       return false;
     }
   }
-  // Self-heal a partial/incomplete native build (node-pty ships no prebuilds, so `npm rebuild`
-  // compiles from source) BEFORE the server tries to spawn a session and dies with posix_spawnp.
-  if (!nodePtyBuildOk()) {
-    say('node-pty is present but its native build is incomplete — rebuilding from source…');
-    npm(['rebuild', 'node-pty']);
-  }
-  if (!nodePtyBuildOk()) {
-    const toolchain = process.platform === 'darwin' ? 'xcode-select --install'
-      : process.platform === 'win32' ? 'Visual Studio Build Tools (C++)'
-      : 'apt install build-essential python3';
-    say('✗ node-pty could not be built on this machine. Run `pmos doctor` for the full diagnosis.');
-    say(`  Most often: install a C/C++ toolchain (${toolchain}),`);
-    say(`  or switch to Node 22 LTS (you are on ${process.version}; a very new/non-LTS Node may not build node-pty).`);
-    return false;
-  }
+  fixSpawnHelperPerms();   // the #1 field failure: a non-executable prebuilt spawn-helper → posix_spawnp
   return true;
 }
 

package/workspace/doctor.js

@@ -31,54 +31,58 @@ function binaryArch(file) {
   console.log(`pmos workspace doctor — node ${process.version} (${process.platform}/${process.arch})`);
   console.log(`  install dir: ${WSDIR}\n`);
 
-  // node-pty ships NO prebuilds — it compiles a native addon on install — so `npm rebuild
-  // node-pty` (or a clean reinstall) already builds from source; the old `--build-from-source`
-  // npm flag is unnecessary and newer npm rejects it as unknown config. These are the canonical
-  // fixes, dir-qualified so they are copy-pasteable from anywhere.
-  const TOOLCHAIN = process.platform === 'darwin' ? 'xcode-select --install'
-    : process.platform === 'win32' ? 'Visual Studio Build Tools (C++)'
-    : 'apt install build-essential python3';
-  const REINSTALL = `cd "${WSDIR}" && rm -rf node_modules && npm install   (recompiles node-pty from source; needs a C/C++ toolchain: ${TOOLCHAIN})`;
-  const REINSTALL_LTS = `${REINSTALL}\n       If it still fails on Node ${process.version}, that Node may be too new/non-LTS for node-pty to build — switch to Node 22 LTS and retry.`;
+  const REINSTALL = `cd "${WSDIR}" && rm -rf node_modules && npm install   (reinstalls node-pty for this platform)`;
 
   // 1. Node version
   const major = Number(process.versions.node.split('.')[0]);
-  if (major < 18) bad(`Node ${process.version} is too old`, 'install Node 18+ (arm64-native on Apple Silicon)');
-  else if (major % 2 === 1) { checks.push(true); console.log(`✓ Node ${process.version} (>= 18)`); console.log(`  • note: Node ${major} is an ODD (non-LTS) line — node-pty may lack a matching build. If the checks below fail, try Node 22 LTS.`); }
-  else ok(`Node ${process.version} (>= 18)`);
+  if (major >= 18) ok(`Node ${process.version} (>= 18)`);
+  else bad(`Node ${process.version} is too old`, 'install Node 18+ (arm64-native on Apple Silicon)');
 
   // 2. node-pty loads
   let pty = null;
   try { pty = require('node-pty'); ok('node-pty native module loads'); }
-  catch (e) {
-    bad(`node-pty failed to load: ${e.message.split('\n')[0]}`, REINSTALL_LTS);
-  }
+  catch (e) { bad(`node-pty failed to load: ${e.message.split('\n')[0]}`, REINSTALL); }
 
-  // 3. the compiled binaries are present + arch-matched (the posix_spawnp culprit). node-pty
-  //    compiles pty.node (loaded by require) and, on macOS ONLY, a separate spawn-helper binary
-  //    (exec'd at spawn time — Linux uses forkpty directly and never builds it). A PARTIAL macOS
-  //    build — pty.node present but spawn-helper missing — loads fine (check 2 passes) yet every
-  //    session dies with 'posix_spawnp failed'. That is exactly the field failure on a too-new
-  //    Node, so on macOS check both, not just one.
-  const rel = path.join(__dirname, 'node_modules', 'node-pty', 'build', 'Release');
-  const ptyNode = path.join(rel, 'pty.node');
-  const helper = path.join(rel, 'spawn-helper');
-  if (!fs.existsSync(ptyNode)) {
-    bad('node-pty binary pty.node not found (compile did not complete)', REINSTALL_LTS);
-  } else if (process.platform === 'darwin' && !fs.existsSync(helper)) {
-    bad("node-pty's spawn-helper did not compile — pty.node loads but every session dies with 'posix_spawnp failed'", REINSTALL_LTS);
-  } else {
-    const info = binaryArch(ptyNode);
-    const want = process.arch;                       // arm64 | x64 | …
-    const got = info && info.arch;
-    const match = !info || info.arch === 'universal' || info.x === 'ELF' || info.x === 'PE' ||
+  // 3. native binaries usable — and the #1 field failure, FIXED here. node-pty loads pty.node
+  //    (from prebuilds/<plat>-<arch>/ or a from-source build/Release/) and, on macOS, exec()s a
+  //    prebuilt spawn-helper to open each PTY. The prebuild-extraction path can drop that helper's
+  //    executable bit, so it is present yet every session dies with 'posix_spawnp failed'. This
+  //    check verifies pty.node's arch and, on macOS, that spawn-helper exists and is +x —
+  //    RESTORING the bit rather than only reporting it. (Linux uses forkpty directly, no helper.)
+  let nproot; try { nproot = path.dirname(require.resolve('node-pty/package.json')); }
+  catch { nproot = path.join(__dirname, 'node_modules', 'node-pty'); }
+  const findBin = (name) => [
+    path.join(nproot, 'build', 'Release', name),
+    path.join(nproot, 'prebuilds', `${process.platform}-${process.arch}`, name),
+  ].find((f) => fs.existsSync(f));
+  const ptyNode = findBin('pty.node');
+  let bin3 = true; const note3 = [];
+  if (!ptyNode) { bin3 = false; note3.push('pty.node missing (install incomplete)'); }
+  else {
+    const info = binaryArch(ptyNode); const want = process.arch; const got = info && info.arch;
+    const archOk = !info || info.arch === 'universal' || info.x === 'ELF' || info.x === 'PE' ||
       (want === 'arm64' && got === 'arm64') || (want === 'x64' && got === 'x86_64');
-    if (match) ok(`native binaries present${got && got !== 'universal' && info.x === 'Mach-O' ? ` (${got})` : ''}`);
-    else bad(`ARCH MISMATCH: Node is ${want} but node-pty's binary is ${got} — this causes 'posix_spawnp failed' on every session`,
-      `install a ${want}-native Node (e.g. \`brew install node\` on an arm64 shell), then: ${REINSTALL}`);
+    if (!archOk) { bin3 = false; note3.push(`ARCH MISMATCH (Node ${want} vs binary ${got})`); }
+    else if (got && got !== 'universal' && info.x === 'Mach-O') note3.push(got);
+  }
+  if (bin3 && process.platform === 'darwin') {
+    const helper = findBin('spawn-helper');
+    if (!helper) { bin3 = false; note3.push('spawn-helper missing'); }
+    else {
+      const st = fs.statSync(helper);
+      if (!(st.mode & 0o111)) {
+        try { fs.chmodSync(helper, st.mode | 0o755); note3.push('spawn-helper +x RESTORED — this was the posix_spawnp cause'); }
+        catch { bin3 = false; note3.push('spawn-helper not executable'); }
+      }
+    }
   }
+  if (bin3) ok('node-pty native binaries usable' + (note3.length ? ` (${note3.join('; ')})` : ''));
+  else bad('node-pty native binaries unusable' + (note3.length ? ` — ${note3.join('; ')}` : ''),
+    note3.some((n) => /MISMATCH/.test(n)) ? `install a ${process.arch}-native Node, then: ${REINSTALL}`
+      : note3.some((n) => /not executable/.test(n)) ? `chmod +x "${findBin('spawn-helper')}"`
+      : REINSTALL);
 
-  // 4. a real PTY spawns and echoes
+  // 4. a real PTY spawns and echoes (after the perms fix above this should pass)
   if (pty) {
     const sh = process.platform === 'win32' ? (process.env.COMSPEC || 'powershell.exe') : '/bin/sh';
     try {
@@ -94,7 +98,7 @@ function binaryArch(file) {
     } catch (e) {
       bad(`PTY spawn failed: ${e.message}`,
         /posix_spawnp/.test(e.message)
-          ? `broken-native-build signature (wrong-arch or spawn-helper missing). ${REINSTALL_LTS}`
+          ? `on macOS this is node-pty's spawn-helper lacking +x (check 3 restores it — re-run \`npm run doctor\`); otherwise a wrong-arch binary — ${REINSTALL}`
           : process.platform === 'win32' ? 'native Windows needs WSL for a real PTY — run the workspace inside WSL'
           : 'check that /bin/sh exists and is executable');
     }

package/workspace/server.js

@@ -36,12 +36,30 @@ try {
 } catch (e) {
   console.error('✗ node-pty failed to load — the native module is missing or built for the wrong platform.');
   console.error(`  ${e.message.split('\n')[0]}`);
-  console.error('  Fix:  npm run doctor                          (diagnoses arch/toolchain/Node version)');
-  console.error('        rm -rf node_modules && npm install       (recompiles node-pty from source)');
-  console.error(`  node-pty compiles a native addon — needs a C/C++ toolchain (macOS: xcode-select --install; Debian/Ubuntu: apt install build-essential python3) and a supported Node LTS. You are on ${process.version}; if it is a very new or non-LTS release the build may fail — try Node 22 LTS.`);
+  console.error('  Fix:  npm run doctor                     (diagnoses the exact cause)');
+  console.error('        rm -rf node_modules && npm install  (reinstalls node-pty for this platform)');
   process.exit(1);
 }
 
+// node-pty ships a prebuilt macOS `spawn-helper` binary that it exec()s to open each PTY. The
+// prebuild-extraction path can drop its executable bit, and then EVERY session dies with
+// `posix_spawnp failed` — the #1 field failure (it looks like a broken build but the binary is
+// fine, just not +x). Restore the bit wherever node-pty keeps the helper (prebuilds/<plat>-<arch>/
+// or a from-source build/Release/) BEFORE we spawn anything. Cheap, idempotent, no-op off macOS.
+function ensureSpawnHelperExecutable() {
+  if (process.platform === 'win32') return;
+  try {
+    const root = path.dirname(require.resolve('node-pty/package.json'));
+    const targets = [path.join(root, 'build', 'Release', 'spawn-helper')];
+    const pb = path.join(root, 'prebuilds');
+    try { for (const d of fs.readdirSync(pb)) targets.push(path.join(pb, d, 'spawn-helper')); } catch {}
+    for (const f of targets) {
+      try { const st = fs.statSync(f); if (!(st.mode & 0o111)) fs.chmodSync(f, st.mode | 0o755); } catch {}
+    }
+  } catch {}
+}
+ensureSpawnHelperExecutable();
+
 const { checkSurface } = require('./lib/surface-contract');
 const scheduleLogic = require('./lib/schedule-logic');
 const harness = require('./lib/harness-parse');
@@ -819,20 +837,18 @@ function appendBuf(s, data) {
   s.parsed = null;                      // buffer moved; the cached parse is stale
 }
 
-// Platform-correct guidance when a spawn fails. `posix_spawnp failed` means node-pty's native
-// build is broken: either a wrong-arch binary (e.g. x64 Node on Apple Silicon) or an incomplete
-// compile (the spawn-helper never built — common on a brand-new/non-LTS Node). A shell change
-// won't fix it; a clean recompile will. `npm rebuild node-pty` compiles from source on its own —
-// node-pty ships no prebuilds — so the old `--build-from-source` npm flag is unnecessary (and
-// newer npm rejects it as an unknown config).
+// Platform-correct guidance when a spawn fails. On macOS `posix_spawnp failed` is almost always
+// node-pty's prebuilt `spawn-helper` missing its executable bit (prebuild extraction drops it) —
+// the binary is fine, just not +x. The server auto-restores it at startup and `npm run doctor`
+// re-applies + verifies the fix; a wrong-arch binary (x64 Node on Apple Silicon) is the rarer
+// alternative, cured by a clean reinstall.
 function spawnFailureAdvice(err, cmd, isShell) {
   const msg = String(err && err.message || err);
   if (/posix_spawnp|EFAULT|ENOEXEC|wrong architecture|not valid/i.test(msg)) {
-    return `could not spawn '${cmd}' (${msg}). node-pty's native build is broken (wrong-arch, or ` +
-      `the spawn-helper never compiled). Fix: stop the server, run \`npm run doctor\` (it names the ` +
-      `install dir + the exact cause), then in that dir \`rm -rf node_modules && npm install\`. ` +
-      `Needs a C/C++ toolchain; on a very new or non-LTS Node (${process.version}) the compile can ` +
-      `fail — try Node 22 LTS.`;
+    return `could not spawn '${cmd}' (${msg}). On macOS this is almost always node-pty's prebuilt ` +
+      `spawn-helper lacking its executable bit. Fix: run \`pmos doctor\` (it restores +x and verifies), ` +
+      `then ↻ respawn. If it persists, the binary is wrong-arch — \`rm -rf node_modules && npm install\` ` +
+      `in the workspace install dir.`;
   }
   if (process.platform === 'win32') {
     return `could not start '${cmd}': ${msg}. Native Windows needs WSL for a real PTY shell — ` +
@@ -905,8 +921,21 @@ function ensureTmuxSession(name, cmd, workdir, cols, rows) {
 function attachPty(s) {
   const name = tmuxName(s.id);
   const startedMs = Date.now();
-  const p = pty.spawn(TMUX, ['-L', TMUX_SOCK, 'attach-session', '-t', name],
-    { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
+  let p;
+  try {
+    p = pty.spawn(TMUX, ['-L', TMUX_SOCK, 'attach-session', '-t', name],
+      { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
+  } catch (e) {
+    // A broken node-pty (e.g. a non-executable spawn-helper) throws synchronously here. This must
+    // NOT propagate: on the startup first-shell it would crash the whole server and blank the
+    // entire UI ("no terminal painted"). Degrade to an honest exited pane carrying the fix, exactly
+    // like the direct-PTY path does — the server stays up and the session shows why + a respawn.
+    s.pty = null; s.state = 'exited';
+    s.note = spawnFailureAdvice(e, s.agent || 'session', false);
+    appendBuf(s, `\x1b[38;5;203m✗ ${s.note}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`);
+    persist(s); pushSessions();
+    return null;
+  }
   s.pty = p; s.tmux = name; s.state = 'working';
   // Start the quiet clock at ATTACH, not at first byte: a session that spawns and immediately
   // hangs should go quiet on schedule rather than read 'working' forever. On a restore this