create-pmos 0.6.1 → 0.6.3

package/package.json

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

package/payload/okf/core/concepts/frontmatter-format.md

@@ -57,7 +57,10 @@ The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontma
 the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
 
 - **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
-- **Planning:** `PRD`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+- **Planning:** `Initiative`, `PRD`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+  - `Initiative` is the repo-native initiative record in [`planning/initiatives/`](/planning/initiatives/), read by the
+    [Initiative Gate](/.github/scripts/initiative-gate.sh). Its D56 **work-type lane** rides a separate `lane:` key —
+    not `type:` — so the lane vocabulary and this registry never collide.
 - **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
 
 ### Extending the vocabulary

package/workspace/bin/pmos.js

@@ -74,15 +74,32 @@ function openBrowser(url) {
   try { spawn(cmd[0], cmd[1], { detached: true, stdio: 'ignore' }).unref(); } catch {}
 }
 
+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'))) 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;
+  if (!fs.existsSync(path.join(WS, 'node_modules', 'node-pty'))) {
+    say('First run — installing the workspace (one-time, ~20s)…');
+    if (!npm(['install', '--no-audit', '--no-fund'])) {
+      say('✗ install failed. Run `pmos doctor` for the exact fix.');
+      return false;
+    }
   }
+  fixSpawnHelperPerms();   // the #1 field failure: a non-executable prebuilt spawn-helper → posix_spawnp
   return true;
 }
 
@@ -109,8 +126,13 @@ async function up(dir) {
   if (!ensureInstalled()) return 1;
   fs.mkdirSync(STATE, { recursive: true });
   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) };
   const child = spawn(process.execPath, [path.join(WS, 'server.js')], {
-    cwd: WS, detached: true, stdio: ['ignore', log, log], env: process.env,
+    cwd: WS, detached: true, stdio: ['ignore', log, log], env,
   });
   child.unref();
   try { fs.writeFileSync(PIDFILE, String(child.pid)); } catch {}

package/workspace/doctor.js

@@ -27,7 +27,11 @@ function binaryArch(file) {
 }
 
 (async () => {
-  console.log(`pmos workspace doctor — node ${process.version} (${process.platform}/${process.arch})\n`);
+  const WSDIR = __dirname;                              // the install dir the fixes operate in
+  console.log(`pmos workspace doctor — node ${process.version} (${process.platform}/${process.arch})`);
+  console.log(`  install dir: ${WSDIR}\n`);
+
+  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]);
@@ -37,29 +41,48 @@ function binaryArch(file) {
   // 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`)');
-  }
+  catch (e) { bad(`node-pty failed to load: ${e.message.split('\n')[0]}`, REINSTALL); }
 
-  // 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');
+  // 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(bin);
-    const want = process.arch;                       // arm64 | x64 | …
-    const got = info && info.arch;
-    const match = !info || info.arch === 'universal' || info.x === 'ELF' || info.x === 'PE' ||
+    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 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`);
+    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 {
@@ -75,7 +98,7 @@ function binaryArch(file) {
     } 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)'
+          ? `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/lib/remote-access.js

@@ -131,6 +131,29 @@ function extractWsToken(req = {}) {
   }
   return null;
 }
+// A browser only carries the token on the FIRST navigation URL — it cannot attach a header or query
+// to sub-resource loads (CSS/JS) or the WebSocket upgrade. So a valid ?token= navigation SEEDS a
+// same-origin cookie (see server.js httpGuard) and every later request presents the token via that
+// cookie. Parse it here. The cookie is still gated by the Origin/Host allowlist, and its value is
+// redacted from any log line (D08).
+const COOKIE_NAME = 'pmos_token';
+function extractCookieToken(headers = {}) {
+  const raw = headers.cookie || headers.Cookie || '';
+  if (!raw) return null;
+  for (const part of String(raw).split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    if (part.slice(0, eq).trim() === COOKIE_NAME) {
+      try { return decodeURIComponent(part.slice(eq + 1).trim()); } catch { return part.slice(eq + 1).trim(); }
+    }
+  }
+  return null;
+}
+// The single presented-token resolver used by BOTH guards: Authorization header, then ?token= query,
+// then a bearer subprotocol (WS handshakes), then the seeded cookie (browser sub-resources + WS).
+function presentedToken(req = {}) {
+  return extractWsToken(req) || extractCookieToken(req.headers || {});
+}
 
 // ── Origin / Host allowlist (D64 / pivot-workspace-first, Track A1) ─────────────────────
 // The threat: the server owns real PTYs and, for loopback peers, is token-EXEMPT. Without an
@@ -232,4 +255,5 @@ module.exports = {
   LOOPBACK, isLoopbackAddr, isTailnetIp, detectTailnetIp, remoteRequested,
   resolveBinds, extractHttpToken, extractWsToken, tokenMatches, authorize, startupLines,
   checkHostOrigin, isAllowedOrigin, hostnameAllowed,
+  COOKIE_NAME, extractCookieToken, presentedToken,
 };

package/workspace/lib/transcript-read.js

@@ -167,7 +167,8 @@ function prettyTool(name) {
  * reach the screen goes through it (D08), because tool names and skill names are free text.
  */
 function readHarness(file, clean = (x) => x) {
-  const out = { model: null, effort: null, turns: 0, tokens: null, tools: null, skills: null, missing: {} };
+  const out = { model: null, effort: null, turns: 0, tokens: null, tools: null, skills: null,
+    title: null, openCall: null, missing: {} };
   let raw;
   try {
     const st = fs.statSync(file);
@@ -189,11 +190,35 @@ function readHarness(file, clean = (x) => x) {
   let toolTotal = 0;
   const tok = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
   let sawUsage = false;
+  // For the open-call signal (R2): pair tool_use → tool_result by id in one pass. The NEWEST
+  // tool_use with no matching result is the call in flight; its record timestamp dates it. This is
+  // the same "written before its result exists" property the append-only transcript guarantees.
+  // NOTE the honesty bound lives in the CALLER (server): a dangling call on a crashed/interrupted
+  // session is a permanent phantom (measured: 2/25 real transcripts), so the age is rendered ONLY
+  // while the session's derived state is `working` — age without liveness is refused. Here we only
+  // report the raw fact {verb, sinceTs}; we never claim it is live.
+  const openUse = new Map();       // tool_use_id → { verb, ts }  (insertion order = chronological)
+  const resolved = new Set();      // tool_use_ids that got a tool_result
 
   for (const line of raw.split('\n')) {
     if (!line) continue;
     let r;
     try { r = JSON.parse(line); } catch { continue; }   // a torn line is skipped, never guessed
+    // The CLI's own rolling one-line session title (R1). It is FROZEN at the first prompt (every
+    // session carries exactly one, no timestamp), so the UI labels it "opening focus", never
+    // "current". Last one wins in case the layout ever changes.
+    if (r.type === 'ai-title') {
+      if (typeof r.aiTitle === 'string' && r.aiTitle.trim()) out.title = clean(r.aiTitle.trim());
+      continue;
+    }
+    // tool_result blocks live inside `user` records; harvest the ids they resolve.
+    if (r.type === 'user') {
+      const um = r.message || {};
+      for (const c of (Array.isArray(um.content) ? um.content : [])) {
+        if (c && c.type === 'tool_result' && c.tool_use_id) resolved.add(c.tool_use_id);
+      }
+      continue;
+    }
     if (r.type === 'attachment') {
       const a = r.attachment || {};
       if (a.type === 'skill_listing' && typeof a.skillCount === 'number') {
@@ -224,10 +249,17 @@ function readHarness(file, clean = (x) => x) {
         const name = clean(prettyTool(c.name));
         toolCounts[name] = (toolCounts[name] || 0) + 1;
         toolTotal++;
+        if (c.id) openUse.set(c.id, { verb: name, ts: r.timestamp || null });
       }
     }
   }
 
+  // The newest tool_use with no matching tool_result is the call in flight (R2). Map preserves
+  // insertion (chronological) order, so the last unresolved entry is the newest.
+  for (const [id, info] of openUse) {
+    if (!resolved.has(id)) out.openCall = { verb: info.verb, sinceTs: info.ts };
+  }
+
   if (!out.model) out.missing.model = 'the transcript names no model yet';
   if (!out.effort) out.missing.effort = 'the transcript records no effort level';
   if (toolTotal) out.tools = { counts: toolCounts, total: toolTotal };
@@ -239,6 +271,11 @@ function readHarness(file, clean = (x) => x) {
   else out.missing.tokens = 'the transcript records no token usage yet';
   if (!out.skills) out.missing.skills = 'the CLI listed no skills for this session';
   if (!out.turns) out.missing.turns = 'no model turns in the transcript yet';
+  // NOTE: `title` and `openCall` deliberately get NO `missing` entry. This map carries reasons the
+  // UI RENDERS in place of a value; both of these instead fall back to a real shipped rendering
+  // (agent · cwd for an untitled session; the plain `working`/`quiet` word when no call is open).
+  // Putting them here would break the map's contract — "empty missing == everything was readable" —
+  // and put a reason on screen where a perfectly good value already goes.
 
   return out;
 }

package/workspace/public/app.js

@@ -203,10 +203,28 @@ function shownState(s) {
   const q = Math.max(0, Date.now() - s.lastOutputAt);
   return q >= QUIET_AFTER_MS ? { shown: 'quiet', quietMs: q } : { shown: 'working', quietMs: q };
 }
+// The open call's AGE, appended to `working` only. `working · Bash 4m` is the first honest signal
+// for HUNG the workspace has — a call open past a glance is a call that may be stuck. The honesty
+// bound is structural, not a check bolted on: age rides `shown === 'working'`, and shownState only
+// returns 'working' while lastOutputAt is recent, so a crashed/interrupted session whose dangling
+// tool_use is a permanent phantom reads `quiet`/`exited` and NEVER a live age. Age without liveness
+// is refused. `sinceTs` comes from the transcript record; we tick it client-side like the quiet clock.
+function callAge(s, shown) {
+  if (shown !== 'working') return '';
+  const oc = s.hx && s.hx.openCall;
+  if (!oc || !oc.sinceTs) return '';
+  const ms = Date.parse(oc.sinceTs);
+  if (!Number.isFinite(ms)) return '';
+  const age = Date.now() - ms;
+  if (age < 0) return '';
+  return ` · ${oc.verb} ${shortDur(age)}`;
+}
 function stateLabel(s) {
   const { shown, quietMs } = shownState(s);
   const w = STATE_WORD[shown] || shown;
-  return { shown, text: shown === 'quiet' ? `${w} ${shortDur(quietMs)}` : w };
+  if (shown === 'quiet') return { shown, text: `${w} ${shortDur(quietMs)}` };
+  if (shown === 'working') return { shown, text: `${w}${callAge(s, shown)}` };
+  return { shown, text: w };
 }
 function renderSessions() {
   const mine = mySessions();
@@ -222,7 +240,7 @@ function renderSessions() {
         <span class="r1"><span class="st" aria-hidden="true">${GLYPH[st.shown] || '•'}</span>
           <span class="nm">${esc(s.name)}${s.origin && s.origin.startsWith('schedule:') ? '<span class="schtag">scheduled</span>' : ''}</span>
           <span class="chip">${esc(st.text)}</span></span>
-        <span class="sub">${esc(s.agent)} · ${esc(s.cwd)}</span>
+        ${subLine(s)}
         ${saysLine(s)}
       </button>
       <button class="ren" data-rename="${s.id}" aria-label="Rename ${esc(s.name)}" title="rename (F2)">✎</button>
@@ -248,6 +266,17 @@ function renderSessions() {
   updateEmptyOverlay();
   paintRename();
 }
+// The sub-line: the run's OWN focus, not `agent · cwd` (which was identical on every row in a
+// workspace — zero information). The CLI's `ai-title` is FROZEN at the first prompt (it carries no
+// timestamp and never updates), so it is labelled "opening focus" and never framed as what the run
+// is doing now. When there is no resolvable title — a shell/codex/untitled/unresolved session — it
+// falls back to the shipped `agent · cwd`, so the line is never blank and never a guessed title.
+// When a title IS shown, `agent · cwd` moves into the harness drawer (see harnessDrawer), not lost.
+function subLine(s) {
+  const title = s.hx && s.hx.title;
+  if (title) return `<span class="sub"><span class="lead">opening focus</span> ${esc(title)}</span>`;
+  return `<span class="sub">${esc(s.agent)} · ${esc(s.cwd)}</span>`;
+}
 // The agent's own last words, verbatim — never a paraphrase (a summary would be another model
 // call per session, and a drifting paraphrase was a leg-A defect). When the parser cannot read,
 // it says so: an unreadable signal must never render as an empty line.
@@ -297,6 +326,9 @@ function harnessDrawer(s) {
         `${hx.skills.names.length ? ` <span class="src">${esc(hx.skills.names.slice(0, 5).join(', '))}…</span>` : ''}` +
         ` <span class="src">available, not “in use” — the CLI records no such event</span></dd>`
       : `<dt>skills</dt>${na(m.skills || 'not available')}`);
+    // agent · cwd moved here from the row's sub-line (which now carries the run's title). Useful
+    // once, when reading a session — not worth a per-row line where it repeated on every session.
+    rows.push(`<dt>where</dt><dd>${esc(s.agent)} <span class="src">${esc(s.cwd)}</span></dd>`);
     rows.push('<dt>instructions</dt><dd>CLAUDE.md · AGENTS.md <span class="src">identical in every session here</span></dd>');
     // The one row that stays unavailable, and it is architectural rather than a parsing limit:
     // Quality gate state is GitHub CI, Review gate state is hosted Supabase, and the workspace

package/workspace/public/styles.css

@@ -164,6 +164,10 @@ button{font:inherit;color:inherit;background:none;border:0;cursor:pointer}
 .sess .sub{font-size:10.5px;color:var(--text-muted);margin:2px 0 0 18px;display:block;
   overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .sess[data-state="blocked"] .sub{color:var(--warn-text)}
+/* "opening focus" — the permanent lead label on the run-title sub-line. It states plainly that the
+   title is the run's FIRST prompt (frozen, no timestamp), never its current activity. */
+.sess .sub .lead{font-family:var(--mono);font-size:8px;letter-spacing:.06em;text-transform:uppercase;
+  color:var(--text-dim);margin-right:5px}
 /* ── harness tower (workspace-harness-tower): the state chip, the agent's own last words,
       and the per-session harness drill-in. State is carried by SHAPE (the glyph), HUE, and the
       WORD in the chip — three channels, so nothing depends on colour alone. ── */
@@ -232,6 +236,11 @@ details.hz .kv .src{font-family:var(--mono);font-size:8.5px;color:var(--text-dim
 .termpane{position:absolute;inset:0;padding:8px 8px 6px 10px;display:none}
 .termpane.on{display:block}
 .termpane .xterm{height:100%}
+/* Touch scrollback: xterm's .xterm-viewport owns the scroll, but iOS Safari won't pan it by swipe
+   without an explicit touch-action + momentum flag (the terminal otherwise swallows the gesture).
+   Presentation-only; harmless on pointer devices. */
+.termpane .xterm .xterm-viewport{touch-action:pan-y;-webkit-overflow-scrolling:touch;overscroll-behavior:contain}
+.termpane .xterm .xterm-screen{touch-action:pan-y}
 /* scoped to termhost (its positioned ancestor) — sidebar/tabs/needs stay clickable */
 .exited-overlay{position:absolute;inset:0;z-index:5;display:none;place-items:center;background:var(--glass)}
 .exited-overlay.on{display:grid}

package/workspace/server.js

@@ -36,11 +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)');
-  console.error('        npm rebuild node-pty --build-from-source');
+  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');
@@ -50,7 +69,28 @@ const remoteAccess = require('./lib/remote-access');   // tailnet bind + token g
 const rateLimit = require('./lib/rate-limit');         // per-connection token bucket for spawn/input (D64 A3)
 const consoleState = require('./lib/console-state');   // read-only console surfaces over file-mode state (D64 B)
 const fmParse = require('./lib/file-mode-parse');      // canonical file-mode parsers, shared with metrics.py (D64 D)
-const SELF_ROOT = path.resolve(__dirname, '..');       // the repo the workspace ships inside
+// The "home" repo this server manages. In PMOS-self the app ships INSIDE its repo
+// (pmos/workspace) so the parent dir IS the repo. But a kit/tenant copy is installed standalone
+// — `npm i -g` puts it under node_modules/pmos-workspace, or it runs from an npx bundle — and
+// there the parent is a PACKAGE dir, not a repo. Deriving the home from __dirname then made the
+// package folder masquerade as the home workspace (the tenant defect: the GUI showed the
+// create-pmos package as "Home" instead of the repo the PM launched). So: the launcher passes
+// PMOS_SELF_ROOT = the repo it opened; that becomes home. Absent the env, we only adopt the
+// parent as home when it genuinely looks like the PMOS repo the app is embedded in. Otherwise
+// there is NO privileged home — every registered repo is equal.
+const PARENT_DIR = path.resolve(__dirname, '..');
+const INSTALLED_COPY = /[\\/]node_modules[\\/]/.test(__dirname);   // npm i -g / vendored install
+function dirExists(p) { try { return !!p && fs.statSync(p).isDirectory(); } catch { return false; } }
+const SELF_ROOT = process.env.PMOS_SELF_ROOT ? path.resolve(process.env.PMOS_SELF_ROOT) : PARENT_DIR;
+// EMBEDDED_SELF: the app physically lives inside SELF_ROOT (genuine PMOS-self). Only then is the
+// server's own state/ the file-mode mirror (stateDirFor) — a tenant home must write to its OWN
+// repo's pmos/state, never into this installed package.
+const EMBEDDED_SELF = !INSTALLED_COPY && SELF_ROOT === PARENT_DIR &&
+  (fs.existsSync(path.join(PARENT_DIR, 'DECISIONS.md')) || fs.existsSync(path.join(PARENT_DIR, 'AGENTS.md')));
+// HOME_ENABLED: is there a privileged home workspace at all? Yes when embedded, or when the
+// launcher named a real repo via PMOS_SELF_ROOT. An installed copy launched WITHOUT that env
+// (unsupported direct run) has no home — the client must open a repo to do anything.
+const HOME_ENABLED = EMBEDDED_SELF || (!!process.env.PMOS_SELF_ROOT && dirExists(SELF_ROOT));
 const PUB = path.join(__dirname, 'public');
 const XROOT = path.join(__dirname, 'node_modules', '@xterm');
 const STATE = path.join(__dirname, 'state');
@@ -149,16 +189,21 @@ function registerWorkspace(root, name) {
 // while it still owns sessions, so scrollback is never orphaned by a click.
 function forgetWorkspace(id) {
   const w = workspaces.get(id);
-  if (!w || w.root === SELF_ROOT) return false;
+  if (!w || (HOME_ENABLED && w.root === SELF_ROOT)) return false;
   if ([...sessions.values()].some((s) => s.ws === id)) return false;
   workspaces.delete(id); saveWorkspaces(); pushWorkspaces();
   return true;
 }
-function homeWorkspace() { return workspaces.get(wsId(SELF_ROOT)); }
+// The home is SELF_ROOT when enabled; otherwise (installed copy, no launcher env) there is no
+// privileged home, so an unresolved ws id falls back to the first registered repo rather than
+// resolving to the package dir.
+function homeWorkspace() {
+  return HOME_ENABLED ? workspaces.get(wsId(SELF_ROOT)) : [...workspaces.values()][0];
+}
 function getWs(id) { return (id && workspaces.get(id)) || homeWorkspace(); }
 function wsList() {
   return [...workspaces.values()].map((w) => ({
-    id: w.id, name: w.name, root: w.root, home: w.root === SELF_ROOT,
+    id: w.id, name: w.name, root: w.root, home: HOME_ENABLED && w.root === SELF_ROOT,
     shape: wsShape(w.root), addedAt: w.addedAt,
     sessions: [...sessions.values()].filter((s) => s.ws === w.id).length,
   }));
@@ -792,15 +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` almost always means the
-// node-pty NATIVE BINARY is broken/wrong-arch (e.g. x64 Node on Apple Silicon) — a shell change
-// won't fix that; a rebuild will.
+// 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}). This is usually a broken node-pty native build ` +
-      `(arch mismatch). Fix: stop the server, run \`npm run doctor\` in workspace/, ` +
-      `then \`npm rebuild node-pty --build-from-source\`.`;
+    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 — ` +
@@ -873,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
@@ -1036,7 +1097,7 @@ function stateDirFor(w, { create = false } = {}) {
     const d = path.join(w.root, ...rel);
     if (isDir(d)) return d;
   }
-  if (w.root === SELF_ROOT) return STATE;   // pmos-self: the server's own state/ IS its file-mode mirror
+  if (EMBEDDED_SELF && w.root === SELF_ROOT) return STATE;   // pmos-self: the server's own state/ IS its file-mode mirror (never a tenant home — that writes to its OWN repo below)
   // A PMOS-shaped repo with no state dir yet gets the kit's own layout on first write. Never
   // invented for a plain repo — there we fall back and SAY SO rather than write somewhere wrong.
   if (create && wsShape(w.root) === 'pmos') {
@@ -1353,7 +1414,7 @@ async function handleRequest(req, res) {
     // tell any open client to switch — otherwise the browser refocuses the old tab and the
     // PM sees the previous repo, which is precisely the reported defect
     if (body.focus !== false) broadcast({ t: 'focus', ws: w.id });
-    return json(res, { ok: true, workspace: { ...w, home: w.root === SELF_ROOT, shape: wsShape(w.root) } });
+    return json(res, { ok: true, workspace: { ...w, home: HOME_ENABLED && w.root === SELF_ROOT, shape: wsShape(w.root) } });
   }
   if (p === '/api/workspaces/forget' && req.method === 'POST') {
     let body = {};
@@ -1603,12 +1664,29 @@ function httpGuard(req, res) {
     res.end(JSON.stringify({ ok: false, error: 'forbidden origin/host' }));
     return;
   }
+  // Token may arrive as an Authorization header, a ?token= query param, or the seeded cookie. A
+  // browser only carries the token on the FIRST navigation URL — it cannot attach a header/query to
+  // sub-resource loads (CSS/JS) or the WS upgrade — so the documented "open http://…/?token=<t>"
+  // phone flow (REMOTE.md + startup banner) must reach THIS page-load guard, and every later request
+  // rides the cookie we seed just below. presentedToken() resolves all channels. (local hotfix)
   if (!remoteAccess.authorize({ remoteAddress: req.socket.remoteAddress,
-      presentedToken: remoteAccess.extractHttpToken(req.headers), expectedToken: TOKEN })) {
+      presentedToken: remoteAccess.presentedToken(req), expectedToken: TOKEN })) {
     res.writeHead(401, { 'Content-Type': 'application/json', 'WWW-Authenticate': 'Bearer' });
     res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
     return;
   }
+  // Seed a same-origin session cookie when a VALID token arrived via the ?token= query on a non-loopback
+  // navigation, so the browser's subsequent sub-resource + WS-upgrade requests authenticate without it
+  // in the URL. HttpOnly (JS never needs it) + SameSite=Strict + the D64 Origin/Host allowlist keep a
+  // foreign site from riding it; no Secure flag because the tailnet speaks plain HTTP (WireGuard-encrypted).
+  if (!remoteAccess.isLoopbackAddr(req.socket.remoteAddress)) {
+    let qTok = null;
+    try { qTok = new URL(req.url || '', 'http://localhost').searchParams.get('token'); } catch { /* ignore */ }
+    if (qTok && remoteAccess.tokenMatches(qTok.trim(), TOKEN)) {
+      res.setHeader('Set-Cookie',
+        `${remoteAccess.COOKIE_NAME}=${encodeURIComponent(TOKEN)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=604800`);
+    }
+  }
   return handleRequest(req, res);
 }
 const server = http.createServer(httpGuard);
@@ -1626,8 +1704,10 @@ function handleUpgrade(req, socket, head) {
     socket.destroy();
     return;
   }
+  // A browser WebSocket cannot set a header or a ?token= — it authenticates via the same-origin cookie
+  // seeded on the page load. presentedToken() resolves header → query → subprotocol → cookie.
   if (!remoteAccess.authorize({ remoteAddress: socket.remoteAddress,
-      presentedToken: remoteAccess.extractWsToken(req), expectedToken: TOKEN })) {
+      presentedToken: remoteAccess.presentedToken(req), expectedToken: TOKEN })) {
     socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
     socket.destroy();     // reject the upgrade; nothing about the request is logged (D08)
     return;
@@ -1644,7 +1724,7 @@ wss.on('connection', (ws) => {
   // dropped silently; excess spawns get an honest error rather than piling up shells.
   ws._rlSpawn = rateLimit.createBucket(8, 0.5);
   ws._rlInput = rateLimit.createBucket(400, 200);
-  ws.send(JSON.stringify({ t: 'hello', workspaces: wsList(), home: wsId(SELF_ROOT), sessions: sessionList() }));
+  ws.send(JSON.stringify({ t: 'hello', workspaces: wsList(), home: HOME_ENABLED ? wsId(SELF_ROOT) : null, sessions: sessionList() }));
 
   ws.on('message', (raw) => {
     let m; try { m = JSON.parse(raw); } catch { return; }
@@ -1693,12 +1773,14 @@ wss.on('connection', (ws) => {
 });
 
 loadWorkspaces();
-registerWorkspace(SELF_ROOT);      // the home workspace is always hosted
+if (HOME_ENABLED) registerWorkspace(SELF_ROOT);   // the home workspace is hosted (PMOS-self, or the repo the launcher named)
 writeTmuxConf();                   // must exist before restore may reattach or spawn creates
 restorePersisted();
 
-// A first shell so the workspace is never empty on first run (honest real PTY).
-if ([...sessions.values()].filter((s) => s.pty).length === 0) {
+// A first shell so the workspace is never empty on first run (honest real PTY). Only when there
+// is a repo to open it IN: an installed copy with no home and no registered repo yet must wait
+// for the launcher to POST a workspace rather than spawn a shell in the package directory.
+if ((HOME_ENABLED || workspaces.size) && [...sessions.values()].filter((s) => s.pty).length === 0) {
   spawnSession({ name: 'shell', agent: 'shell' });
 }