create-pmos 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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@2e880f8
 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,13 +74,41 @@ 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;
+}
 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.');
+  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;
+    }
+  }
+  // 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;
   }
   return true;
@@ -109,8 +137,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,36 +27,55 @@ 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`);
+
+  // 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.`;
 
   // 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)');
+  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)`);
 
   // 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`)');
+    bad(`node-pty failed to load: ${e.message.split('\n')[0]}`, REINSTALL_LTS);
   }
 
-  // 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);
+  // 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' ||
       (want === 'arm64' && got === 'arm64') || (want === 'x64' && got === 'x86_64');
-    if (match) ok(`native binary present${got && got !== 'universal' && info.x === 'Mach-O' ? ` (${got})` : ''}`);
+    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: rm -rf node_modules && npm install`);
+      `install a ${want}-native Node (e.g. \`brew install node\` on an arm64 shell), then: ${REINSTALL}`);
   }
 
   // 4. a real PTY spawns and echoes
@@ -75,7 +94,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)'
+          ? `broken-native-build signature (wrong-arch or spawn-helper missing). ${REINSTALL_LTS}`
           : 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,8 +36,9 @@ 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 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.`);
   process.exit(1);
 }
 
@@ -50,7 +51,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 +171,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 +819,20 @@ 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. `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).
 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}). 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.`;
   }
   if (process.platform === 'win32') {
     return `could not start '${cmd}': ${msg}. Native Windows needs WSL for a real PTY shell — ` +
@@ -1036,7 +1068,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 +1385,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 +1635,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 +1675,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 +1695,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 +1744,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' });
 }