create-pmos 0.4.0 → 0.6.0

package/workspace/README.md

@@ -0,0 +1,112 @@
+---
+type: Reference
+title: "PMOS Terminal Workspace"
+timestamp: 2026-07-25
+---
+
+# PMOS Terminal Workspace
+
+The local companion that runs the PM's agent sessions as **real terminals**, with the PMOS
+workflow (library, gates, needs-you) around them. Built to D62 (as ratified + twice amended):
+a **persistent, localhost-only session server** owning real PTYs, with a **GUI client** attached
+over WebSocket. The native TUI is a deferred later client (D62 amendment 2).
+
+## Why it can't lose your harness
+Each session spawns your agent CLI (Claude Code / Codex / a shell) as a real PTY; xterm.js is a
+true terminal emulator on the other end. The CLI runs **untouched** — its own login (Claude
+subscription included), slash commands, keybindings. The workspace is the terminal, not a wrapper.
+
+## Everything survives a session
+The server holds PTYs in memory and mirrors each session's scrollback + metadata to `state/`.
+Close/reload the client → re-attach replays scrollback and the run continues (detach, not kill).
+Restart the server → prior sessions reload as `exited` with full history and one-click respawn.
+
+## Run it — just type `pmos`
+One-time setup (installs the `pmos` command on your machine):
+```bash
+cd workspace
+npm install -g .
+```
+Then, from any terminal, any folder:
+```bash
+pmos                 # starts the workspace (installs deps on first run) + opens the browser
+```
+That's it. The server keeps running after you close the terminal — sessions survive (R7).
+```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)
+```
+
+<details><summary>Without the global install (running from the repo)</summary>
+
+```bash
+cd workspace
+npm install          # node-pty (native), ws, @xterm/*
+npm start            # http://127.0.0.1:7433  (localhost only — never public, D62)
+npm test             # end-to-end checks: PTY round-trip, restart-persistence, gates, launcher
+npm run test:ui      # browser checks: terminal geometry, reader scroll, markdown (needs Chrome)
+```
+</details>
+
+## Layout (PM-directed, D62 R9 + round 2)
+Three columns. **Left = the workspace**: repos on top, running agents below, equal halves.
+**Middle = the terminal**, sessions as tabs. **Right rail = the library over the document
+reader** — either pane folds away (click its header), the whole rail hides (`rail`), and both
+the split and the rail width are draggable. The layout you choose survives a reload.
+
+- **Add a repo by picking a folder** — `＋` opens your machine's own folder chooser (typing a
+  path still works; where no chooser exists, an in-app folder browser stands in).
+- **Rename a session any time** — the ✎ on its row, a double-click on its tab, or `F2`. Live or
+  exited, and it survives a server restart.
+- **Documents read like documents** — the identity block becomes a card, tables are tables,
+  nested/ordered/task lists survive, and a relative `.md` link opens that document in the reader.
+- **Preview more than markdown** — `.skill` files render as markdown; text/config files open as
+  escaped source; `.html` opens as source with an opt-in **sandboxed** render (scripts + network
+  denied); markdown renders **repo-relative images inline**. A remote `![](https://…)` image is
+  never fetched (no zero-click beacon); a binary stays listed but inert (open it in your editor).
+
+## The gates are real, never automatic (R5)
+`approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and
+clear the matching needs entry — only ever on your click.
+
+**The record lands in the repo that earned it.** Each workspace resolves its own state dir —
+`pmos/state/` (the kit's layout, D54), then `state/`, then `.pmos/`; the home workspace uses the
+server's own `state/`. A PMOS-shaped repo with no state dir yet gets the kit layout on first
+write. That path matters: `scripts/metrics.py` reads `pmos/state/acceptances.jsonl` for the north
+star and κ, so an acceptance recorded anywhere else is a green click over an empty record. A
+plain (non-PMOS) repo has no layout to invent — the gate records into the server's `state/` and
+the response says `fallback: true` rather than guessing.
+
+Records carry the kit's `accepted` field (`accept` → true, `return` → false) so file-mode metrics
+count them. `pm_label` is **never** derived from a click — κ labels are the PM's own word (D40).
+
+## Your own runs are searchable (the history lens)
+Every session's scrollback is already mirrored to disk, which makes it a record of what earlier
+runs actually **did** — the thing structured run rows don't carry. The rail's fourth lens,
+**history**, searches it; the filter box becomes the query. An agent working in a pane can ask
+the same question itself: `GET /api/search?q=…&ws=…`.
+
+Two guarantees. It is scoped to **one repo** — a workspace never searches another's history
+(R1/R3), and an unrecognised workspace id resolves to home, so it can only ever see less.
+And every returned line is **scrubbed** of ANSI and of anything credential-shaped (bearer
+tokens, JWTs, `Authorization:` values, api keys): scrollback holds whatever the agent printed,
+so D08's never-log-headers discipline applies to what this hands back. Matching runs against
+the *scrubbed* text, so the endpoint cannot be used to grep a secret out.
+
+## Boundaries (honest v1 seams)
+- **Server binds 127.0.0.1** — the D62 hosted-PTY-bridge rejection stands; a tailnet/phone client
+  attaches to the same local server, never a public endpoint.
+- **needs-you feed** — an explicit `needs.json` (written by the harness/MCP) is authoritative for
+  the entries it names; everything else is **derived** from the repo's own append-only state, so a
+  repo nobody has seeded still shows its real work. Derived: an eval with no acceptance for its run
+  (the Acceptance Gate is open, D12), and a declared outcome past its horizon with no disposition
+  (the D57 check is due — a *missing* horizon counts as due, mirroring `metrics.py`). Derivation
+  only reports: an overdue outcome carries **no** close button, because disposal is
+  `record_outcome_check` with evidence, and auto-disposal is prohibited (D57).
+- File reads are **path-guarded** to the repo. The reader serves previewable **text kinds**
+  (markdown incl. `.skill`, text/config, HTML source) and streams repo-relative **images** through
+  a MIME-allowlisted `/api/asset`; binaries and out-of-root/cross-workspace paths are refused.
+  Remote images are never fetched (no beacon). Request headers are never logged (D08).
+
+Screenshots: `docs/screenshot-dark.png`, `docs/screenshot-light.png`, `docs/screenshot-doc.png`.

package/workspace/REMOTE.md

@@ -0,0 +1,131 @@
+---
+type: Reference
+title: "Workspace remote access over a private tailnet (Tailscale)"
+timestamp: 2026-07-26
+---
+
+# Reaching the workspace from your phone — over a private tailnet, never the public internet
+
+The workspace server owns **real terminal sessions (PTYs)** running your `claude` on **your own
+subscription**. By default it binds `127.0.0.1` only, so it is reachable solely from the machine it
+runs on. This runbook enables reaching **the same local server** from another of your own devices —
+a phone, a laptop — over a **private Tailscale tailnet**. It never exposes a public endpoint.
+
+## Why a tailnet, and why no public endpoint (D62)
+
+A [Tailscale](https://tailscale.com) tailnet is a private [WireGuard](https://www.wireguard.com/)
+mesh between **your own devices**. Every device is authenticated and encrypted end-to-end; addresses
+live in the CGNAT range `100.64.0.0/10` and are routable **only** between devices on your tailnet —
+never from the public internet.
+
+PMOS's locked decision **D62** rejects, permanently:
+
+- **any public endpoint** for the workspace server, and
+- **any hosted PTY bridge** (proxying the terminal through a hosted, browser-reachable surface).
+
+A public server that owns a PTY running your Claude subscription is severe exposure. The tailnet path
+sidesteps that entirely: the phone attaches to the *same local server* across your own private
+network. Accordingly, this feature will **only ever** bind loopback plus your machine's own tailnet
+address. If you ask it to bind anything else (`0.0.0.0`, a LAN or public IP), it **refuses to start**.
+
+## Setup
+
+1. **Install Tailscale** on the machine running the workspace and on your phone:
+   - Machine: https://tailscale.com/download — then `tailscale up`.
+   - Phone: install the Tailscale app from your app store and sign in to the **same** tailnet.
+   - Confirm the machine's tailnet IPv4: `tailscale ip -4` (a `100.x.y.z` address).
+
+2. **Start the server in remote mode**, from `workspace/`:
+
+   ```sh
+   PMOS_REMOTE=tailnet npm start
+   ```
+
+   On startup it prints (once):
+
+   ```
+   pmos workspace server — REMOTE (tailnet) mode
+     local:   http://127.0.0.1:7433
+     tailnet: http://100.x.y.z:7433   (private WireGuard net, device-authenticated, never public — D62)
+     token (generated — shown ONCE, copy it now): <a long token>
+     attach with header  Authorization: Bearer <token>   or query  ?token=<token>
+     loopback requests are token-free; every tailnet request must present the token.
+   ```
+
+   **Copy the token now** — it is shown only once and never logged again.
+
+3. **Open it from your phone.** In the phone's browser (on the same tailnet), open:
+
+   ```
+   http://100.x.y.z:7433/?token=<token>
+   ```
+
+   The client attaches to the **same live sessions** the desktop sees; the token authorizes both the
+   page and its WebSocket. Requests from the machine itself (`127.0.0.1`) never need the token.
+
+## Configuration
+
+| Variable | Effect |
+|---|---|
+| `PMOS_REMOTE=tailnet` | Opt in. Bind loopback **+** the machine's tailnet IPv4, and require a token beyond loopback. |
+| `PMOS_BIND_TAILNET=1` | Equivalent to `PMOS_REMOTE=tailnet`. |
+| `PMOS_TOKEN=<t>` | Use your own token instead of a generated one. **Never printed** — supply it yourself on both ends. |
+| `PMOS_TAILNET_IP=<100.x.y.z>` | Pin the tailnet address (skips auto-detection). Must be within `100.64.0.0/10`. |
+| `PMOS_BIND_ADDR=<addr>` | Force a specific bind. Accepted **only** if loopback or within `100.64.0.0/10`; anything else refuses to start. |
+| *(none of the above)* | **Default:** loopback only, no token — unchanged local behavior. |
+
+## Security model (what is guaranteed)
+
+- **Never public.** The only addresses the server will ever bind are loopback and a
+  `100.64.0.0/10` tailnet address. `0.0.0.0`, `::`, LAN, and public IPs are refused — the server
+  exits with a clear error rather than binding them. There is no code path to a public bind.
+- **Token beyond loopback.** With remote mode on, every non-loopback HTTP request and WebSocket
+  upgrade must present the bearer token, or it is rejected (`401` / socket closed). Loopback requests
+  stay token-free for local development. The comparison is constant-time.
+- **Origin/Host allowlist (D64).** Both the HTTP guard and the WebSocket-upgrade handshake reject any
+  request whose `Origin` is foreign (not same-origin with the `Host` it arrived on) or whose `Host`
+  hostname is not loopback/localhost or your tailnet address. This closes the cross-origin-localhost /
+  DNS-rebinding vector: without it, **any website open in your browser** could open a WebSocket to
+  `ws://127.0.0.1:<port>` and spawn a shell + type into it, because loopback peers are token-exempt.
+  A same-origin page served by the workspace passes; a cross-site page is rejected `403`. Native
+  clients / `curl` (which send no `Origin`) still pass this check and are then gated by the token.
+- **No header/token logging (D08).** The request-guard path logs nothing about the request. The
+  token is printed at most once at startup (only when generated); a token you supply is never echoed.
+- **Rate-limited control channel (D64).** The WS messages that spawn shells (`new`/`respawn`) and
+  feed a PTY (`input`) are per-connection rate-limited, bounding abuse if the socket is ever reached.
+- **Independent layers.** The tailnet (WireGuard device auth), the bearer token, and the origin/host
+  allowlist all gate access — a device must be *on your tailnet*, *hold the token*, **and** present a
+  same-origin request from an allowed host.
+
+## Exposing to the internet — the required hardening (D64)
+
+The workspace is **tailnet-first**. The tailnet path above is the supported way to reach it from
+another of your own devices and needs no internet exposure. If you nonetheless expose an instance to
+the internet, D64 permits it **only after all three of the following are in place — never before, and
+never as a raw public bind**:
+
+1. **The bearer token for every non-loopback peer** (already enforced in remote mode).
+2. **The Origin/Host allowlist** (already enforced — see above).
+3. **TLS termination at the exposure boundary.** **The workspace server does not terminate TLS.** It
+   speaks plain HTTP/WS and must sit behind something that terminates TLS for it — Tailscale's own
+   HTTPS (`tailscale serve` / `tailscale funnel`) or a reverse proxy (Caddy, nginx, a tunnel) that
+   holds the certificate and forwards to the loopback/tailnet listener. Do **not** put the raw HTTP
+   port on a public interface — the server refuses non-loopback/non-tailnet binds precisely so this
+   stays a conscious proxy decision, not an accident.
+
+When a reverse proxy forwards to the workspace, keep the forwarded `Host` set to the loopback/tailnet
+host the server actually binds, so the Origin/Host allowlist still recognises same-origin requests.
+
+## Troubleshooting
+
+- **"refusing to bind … only loopback or a Tailscale tailnet address (100.64.0.0/10) is permitted"**
+  — you passed `PMOS_BIND_ADDR` (or `PMOS_TAILNET_IP`) that isn't loopback or tailnet. Use your real
+  `tailscale ip -4` value.
+- **"no Tailscale tailnet address … was found"** — Tailscale isn't up on this machine. Run
+  `tailscale up`, or set `PMOS_TAILNET_IP`.
+- **"cannot bind 100.x.y.z:PORT — that address is not present on this machine"** — the pinned
+  `PMOS_TAILNET_IP` isn't actually assigned to this machine. Check `tailscale ip -4`.
+- **Phone gets 401** — the token is missing or wrong. Re-open with `?token=<token>` (or send
+  `Authorization: Bearer <token>`). Restarting the server without `PMOS_TOKEN` mints a new token.
+- **Phone can't connect at all** — confirm both devices show each other in the Tailscale app, and
+  that you used the `100.x.y.z` address, not a LAN IP.

package/workspace/bin/pmos.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/* pmos — one-word launcher for the PMOS Terminal Workspace (Herdr-style).
+ *
+ *   pmos            open THIS directory's repo as a workspace (starting the server if needed)
+ *   pmos <path>     open another directory as a workspace
+ *   pmos status     is the server running? which workspaces, which sessions?
+ *   pmos ls         list the registered workspaces
+ *   pmos stop       stop the server (running sessions end — it says so first)
+ *   pmos doctor     diagnose the environment (node-pty arch, PTY spawn, …)
+ *
+ * The directory you type `pmos` in IS the workspace: it is resolved to its git root and
+ * registered with the server, and the browser opens focused on it. One server hosts many
+ * repos — opening a second repo never disturbs the first one's running sessions.
+ *
+ * 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.
+ */
+'use strict';
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+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;
+// 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 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() {
+  return new Promise((res) => {
+    const req = http.get(`${URL_}/api/sessions`, { timeout: 900 }, (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));
+    req.on('timeout', () => { req.destroy(); res(null); });
+  });
+}
+function api(method, pathname, body) {
+  return new Promise((res) => {
+    const data = body ? JSON.stringify(body) : null;
+    const req = http.request(`${URL_}${pathname}`, {
+      method, timeout: 3000,
+      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));
+    req.on('timeout', () => { req.destroy(); res(null); });
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+// 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) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' });
+  const top = r.status === 0 ? String(r.stdout).trim() : '';
+  return top && fs.existsSync(top) ? top : path.resolve(dir);
+}
+
+function openBrowser(url) {
+  if (NO_OPEN) return;
+  const cmd = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try { spawn(cmd[0], cmd[1], { detached: true, stdio: 'ignore' }).unref(); } catch {}
+}
+
+function ensureInstalled() {
+  if (fs.existsSync(path.join(WS, 'node_modules', 'node-pty'))) return true;
+  say('First run — installing the workspace (one-time, ~20s)…');
+  const r = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm',
+    ['install', '--no-audit', '--no-fund'], { cwd: WS, stdio: 'inherit' });
+  if (r.status !== 0) {
+    say('✗ install failed. Run `npm run doctor` inside the workspace folder for the exact fix.');
+    return false;
+  }
+  return true;
+}
+
+// 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) {
+  const root = repoRootOf(dir);
+  const reg = await api('POST', '/api/workspaces', { root, name: path.basename(root) });
+  if (!reg || !reg.ok) {
+    say(`✗ could not open ${root}${reg && reg.error ? ` — ${reg.error}` : ''}`);
+    openBrowser(URL_);
+    return 1;
+  }
+  const w = reg.workspace;
+  say(`✓ workspace “${w.name}” — ${URL_}?ws=${w.id}`);
+  say(`  ${root}`);
+  openBrowser(`${URL_}?ws=${w.id}`);
+  return 0;
+}
+
+async function up(dir) {
+  if (await probe()) return openWorkspace(dir);
+  if (!ensureInstalled()) return 1;
+  fs.mkdirSync(STATE, { recursive: true });
+  const log = fs.openSync(LOGFILE, 'a');
+  const child = spawn(process.execPath, [path.join(WS, 'server.js')], {
+    cwd: WS, detached: true, stdio: ['ignore', log, log], env: process.env,
+  });
+  child.unref();
+  try { fs.writeFileSync(PIDFILE, String(child.pid)); } catch {}
+  process.stdout.write('starting the workspace ');
+  for (let i = 0; i < 40; i++) {                        // up to ~10s
+    if (await probe()) {
+      say('');
+      say('  sessions keep running after you close this terminal · `pmos stop` shuts it down');
+      return openWorkspace(dir);
+    }
+    process.stdout.write('.');
+    await sleep(250);
+  }
+  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 {}
+  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'}`);
+  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}`);
+  }
+  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; }
+}
+
+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; }
+  // 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;
+}
+
+function doctor() {
+  const r = spawnSync(process.execPath, [path.join(WS, 'doctor.js')], { stdio: 'inherit' });
+  return r.status || 0;
+}
+
+(async () => {
+  const arg = process.argv[2];
+  const cmd = (arg || 'up').toLowerCase();
+  let code = 0;
+  if (cmd === 'status') code = await status();
+  else if (cmd === 'ls' || cmd === 'list') code = await ls();
+  else if (cmd === 'stop') code = await stop();
+  else if (cmd === 'doctor') code = doctor();
+  else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    say('usage: pmos [<path>|status|ls|stop|doctor]');
+    say('  pmos          open the current repo as a workspace (starts the server if needed)');
+    say('  pmos <path>   open another repo as a workspace');
+    code = 0;
+  } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {
+    // `pmos open ../other-repo` — the path is the argument AFTER the verb
+    code = await up(process.argv[3] ? path.resolve(process.argv[3]) : process.cwd());
+  } else if (arg && !arg.startsWith('-')) {
+    code = await up(path.resolve(arg));                 // `pmos ../other-repo`
+  } else {
+    code = await up(process.cwd());
+  }
+  process.exit(code);
+})();

package/workspace/doctor.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/* pmos workspace doctor — diagnoses the environment the server needs.
+ * Checks, in order: Node version → node-pty loads → native binary arch matches the Node
+ * process → a real PTY actually spawns and echoes. Prints the exact fix for each failure.
+ * Exit 0 = healthy; exit 1 = something needs fixing (the output says what). */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const checks = [];
+const ok = (name, extra) => { checks.push(true); console.log(`✓ ${name}${extra ? ' — ' + extra : ''}`); };
+const bad = (name, fix) => { checks.push(false); console.log(`✗ ${name}`); if (fix) console.log(`  fix: ${fix}`); };
+
+// Read the CPU arch a compiled binary was built for, from its magic bytes (no external tools).
+function binaryArch(file) {
+  try {
+    const b = Buffer.alloc(8);
+    const fd = fs.openSync(file, 'r'); fs.readSync(fd, b, 0, 8, 0); fs.closeSync(fd);
+    if (b[0] === 0x7f && b[1] === 0x45) return { x: 'ELF', arch: b[4] === 2 ? (b.readUInt16LE ? 'elf64' : 'elf') : 'elf32' };
+    const m = b.readUInt32LE(0);
+    if (m === 0xfeedfacf) { const cpu = b.readUInt32LE(4); return { x: 'Mach-O', arch: cpu === 0x0100000c ? 'arm64' : cpu === 0x01000007 ? 'x86_64' : 'cpu:' + cpu.toString(16) }; }
+    if (m === 0xbebafeca || m === 0xcafebabe) return { x: 'Mach-O universal', arch: 'universal' };
+    if (b[0] === 0x4d && b[1] === 0x5a) return { x: 'PE', arch: 'windows' };
+  } catch {}
+  return null;
+}
+
+(async () => {
+  console.log(`pmos workspace doctor — node ${process.version} (${process.platform}/${process.arch})\n`);
+
+  // 1. Node version
+  const major = Number(process.versions.node.split('.')[0]);
+  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]}`,
+      'npm rebuild node-pty --build-from-source   (needs: macOS `xcode-select --install`; Linux `apt install build-essential python3`)');
+  }
+
+  // 3. native binary arch matches the running Node (the posix_spawnp culprit)
+  const helper = path.join(__dirname, 'node_modules', 'node-pty', 'build', 'Release',
+    process.platform === 'win32' ? 'pty.node' : 'spawn-helper');
+  const alt = path.join(__dirname, 'node_modules', 'node-pty', 'build', 'Release', 'pty.node');
+  const bin = fs.existsSync(helper) ? helper : (fs.existsSync(alt) ? alt : null);
+  if (!bin) bad('node-pty native binary not found (build incomplete)', 'rm -rf node_modules && npm install');
+  else {
+    const info = binaryArch(bin);
+    const want = process.arch;                       // arm64 | x64 | …
+    const got = info && info.arch;
+    const match = !info || info.arch === 'universal' || info.x === 'ELF' || info.x === 'PE' ||
+      (want === 'arm64' && got === 'arm64') || (want === 'x64' && got === 'x86_64');
+    if (match) ok(`native binary 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: rm -rf node_modules && npm install`);
+  }
+
+  // 4. a real PTY spawns and echoes
+  if (pty) {
+    const sh = process.platform === 'win32' ? (process.env.COMSPEC || 'powershell.exe') : '/bin/sh';
+    try {
+      const out = await new Promise((resolve, reject) => {
+        let acc = '';
+        const p = pty.spawn(sh, [], { name: 'xterm-256color', cols: 80, rows: 24, cwd: __dirname, env: process.env });
+        const t = setTimeout(() => { try { p.kill(); } catch {}; reject(new Error('timeout — shell spawned but never echoed')); }, 4000);
+        p.onData((d) => { acc += d; if (acc.includes('DOCTOR_OK')) { clearTimeout(t); try { p.kill(); } catch {}; resolve(acc); } });
+        p.onExit(() => { if (!acc.includes('DOCTOR_OK')) { clearTimeout(t); reject(new Error(`shell exited before echoing (got ${acc.length} bytes)`)); } });
+        p.write('echo DOCTOR_OK\r');
+      });
+      ok(`real PTY spawns + echoes (${sh})`);
+    } catch (e) {
+      bad(`PTY spawn failed: ${e.message}`,
+        /posix_spawnp/.test(e.message)
+          ? 'this is the broken-native-build signature — npm rebuild node-pty --build-from-source (and see the arch check above)'
+          : process.platform === 'win32' ? 'native Windows needs WSL for a real PTY — run the workspace inside WSL'
+          : 'check that /bin/sh exists and is executable');
+    }
+  }
+
+  // 5. tmux — the session-persistence backing. Not fatal: absent, the server falls back to
+  //    direct PTYs (sessions still work, but a `pmos stop`/restart ends them). Present, a session
+  //    OUTLIVES a server restart and is re-attached live. This check explains which mode you're in.
+  const tmuxV = spawnSync('tmux', ['-V'], { encoding: 'utf8' });
+  if (tmuxV.status === 0) {
+    ok(`tmux present (${String(tmuxV.stdout).trim()}) — sessions PERSIST across \`pmos stop\`/restart`);
+  } else {
+    // a soft note, not a ✗: everything still works, just without restart-proof sessions
+    console.log('• tmux not found — sessions run on direct PTYs and END on `pmos stop`/restart (no live persistence).');
+    console.log('  optional fix: install tmux (macOS `brew install tmux`; Linux `apt install tmux`) for restart-proof sessions.');
+  }
+
+  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);
+})();