create-pmos 0.6.2 → 0.6.4

package/README.md

@@ -1,7 +1,7 @@
 ---
 type: Reference
 title: "create-pmos"
-timestamp: 2026-07-23
+timestamp: 2026-07-27
 ---
 
 # create-pmos
@@ -333,6 +333,22 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.6.4
+
+Workspace GUI session controls — two things the PM asked for while working in real terminals.
+
+- **Branch awareness + pick/create at session start.** The header now shows the active repo's current
+  git branch (dirty-marked), and the new-session form lets you start a session on an existing branch
+  or create a new one. It's honest about the shared working tree: switching a branch is repo-wide and
+  moves every session in that repo — the form says so rather than faking per-session isolation.
+- **Scratchpad.** A collapsible drawer at the bottom of the terminal column (toggle from the header or
+  ⌘J) to stage commands and notes before they hit the terminal — it never overlays the terminal or the
+  document reader, persists per workspace, and has **copy** and **→ terminal** (which pastes without
+  pressing enter, so nothing auto-runs).
+
+**Upgrade note:** the workspace app ships inside the package; `npx create-pmos@latest workspace`
+installs the new build. Your `state/`, `planning/`, and `okf/` records are untouched — purely additive.
+
 ## What's new in 0.6.1
 
 A completeness fix: two skills the kit already *pointed at* but didn't *ship*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@2e880f8
+kernel-source: pmos@4ce6980
 assembled: 2026-07-27
 mode: vendor

package/workspace/bin/pmos.js

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

package/workspace/doctor.js

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

package/workspace/lib/git-info.js

@@ -0,0 +1,71 @@
+'use strict';
+// Read-mostly git helpers for the workspace (branch awareness + select/create at session start).
+// Everything here shells `git` via spawnSync with an ARGS ARRAY — never a shell string — so no
+// caller input is ever interpolated into a command line. A workspace's working tree is SHARED by
+// every session in it (D62), so a branch is a property of the REPO, not a session: switching moves
+// every session in that repo. Callers surface that truth; this module never pretends otherwise.
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const GIT_TIMEOUT = 5000;   // never let a slow/hung repo (huge tree, network remote) block the server
+
+function isRepo(root) {
+  // a normal repo has a `.git` dir; a linked worktree has a `.git` FILE — both count.
+  try { return !!root && fs.existsSync(path.join(root, '.git')); } catch { return false; }
+}
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT });
+  return { code: r.status, out: (r.stdout || '').trim(), err: (r.stderr || '').trim(), failed: !!r.error };
+}
+
+// git check-ref-format for a BRANCH name, re-implemented defensively so nothing dubious ever
+// reaches `git` (defense in depth — `git` itself is the final authority and rejects the rest).
+// Rejects: empty, whitespace/control, the special chars ~ ^ : ? * [ \ , the sequences .. and @{,
+// a leading '-' (would be read as a flag), leading/trailing '/' or '.', doubled '/', a trailing
+// '.lock', and the lone '@'. Allows the ordinary set A–Z a–z 0–9 . _ / -, e.g. initiative/foo-bar.
+function validBranchName(name) {
+  if (typeof name !== 'string') return false;
+  const n = name.trim();
+  if (!n || n.length > 200) return false;
+  if (/[\x00-\x20~^:?*[\\\s]/.test(n)) return false;   // control/space + git's forbidden set
+  if (n.includes('..') || n.includes('@{') || n.includes('//')) return false;
+  if (n === '@') return false;
+  if (n.startsWith('-') || n.startsWith('/') || n.startsWith('.')) return false;
+  if (n.endsWith('/') || n.endsWith('.') || n.endsWith('.lock')) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(n)) return false;
+  return true;
+}
+
+// { ok, current, branches[], detached, dirty }. A non-repo or a failed git returns ok:false with a
+// reason — NEVER a fabricated branch (a wrong branch chip is worse than none; anti-drift).
+function branchInfo(root) {
+  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, error: 'git not available' };
+  if (head.code !== 0) return { ok: false, error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  const current = detached ? null : head.out;
+  const refs = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+  const branches = refs.code === 0 && refs.out ? refs.out.split('\n').filter(Boolean) : [];
+  const status = git(root, ['status', '--porcelain']);
+  const dirty = status.code === 0 ? status.out.length > 0 : false;
+  return { ok: true, current, branches, detached, dirty };
+}
+
+// Check out an existing branch, or create one with -b. Confined to `root` by cwd; the name is
+// validated first so nothing malformed reaches git. On any failure returns { ok:false, error } and
+// leaves the caller to NOT spawn a session on the wrong branch (a failed checkout must never spawn).
+function checkout(root, branch, { create = false } = {}) {
+  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
+  if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
+  const args = create ? ['checkout', '-b', branch, '--'] : ['checkout', branch, '--'];
+  const r = git(root, args);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: (r.err || r.out || 'checkout failed').split('\n')[0].slice(0, 200) };
+  const info = branchInfo(root);
+  return { ok: true, current: info.ok ? info.current : branch };
+}
+
+module.exports = { isRepo, validBranchName, branchInfo, checkout };

package/workspace/public/app.js

@@ -31,6 +31,8 @@ const state = {
   docPath: null,               // the document open in the reader
   fsDir: null,                 // the in-app folder browser's current directory
   ctrlArmed: false,            // mobile control bar: Ctrl is a one-shot modifier for the next key
+  branch: null,                // {ok,current,branches[],detached,dirty} for the selected workspace
+  newBranchMode: false,        // new-session form: creating a branch vs picking an existing one
 };
 
 // ── workspace state survives reloads (R7): theme + selected workspace + focused session,
@@ -121,9 +123,37 @@ function handle(m) {
   } else if (m.t === 'created') {
     // server pushes a fresh 'sessions'; jump to the new one
     selectSession(m.id);
+  } else if (m.t === 'branch') {
+    // a checkout changed the repo's branch — refresh the chip if it's the workspace on screen
+    if (m.ws === state.wsId) { state.branch = m; renderBranch(); }
+  } else if (m.t === 'error') {
+    // a rejected action (e.g. a failed branch checkout that must NOT spawn) — say so, don't swallow
+    flash(m.error || 'the server rejected that action');
   }
 }
 
+// ── branch awareness (R2): the active workspace's current git branch, always visible. Fetched on
+// demand (never on every broadcast) — on workspace switch, on opening the new-session form, and
+// after a checkout the server announces. A non-repo/unreadable workspace shows NO chip, never a
+// stale or guessed branch. ──
+async function loadBranch() {
+  const id = state.wsId;
+  let info = { ok: false };
+  try { const r = await fetch('/api/git/branches?ws=' + encodeURIComponent(id || '')); info = await r.json(); } catch {}
+  if (id !== state.wsId) return;   // a slower fetch for a workspace we've since left must not paint
+  state.branch = info; renderBranch();
+}
+function renderBranch() {
+  const el = $('branchChip'); if (!el) return;
+  const b = state.branch;
+  if (!b || !b.ok) { el.hidden = true; el.textContent = ''; el.title = ''; return; }
+  const label = b.detached ? 'detached HEAD' : (b.current || '');
+  el.hidden = !label;
+  el.textContent = '⎇ ' + label + (b.dirty ? '*' : '');
+  el.title = b.dirty ? 'uncommitted changes in the working tree' : 'current branch (shared by every session in this repo)';
+  el.classList.toggle('dirty', !!b.dirty);
+}
+
 // ── workspaces ──
 async function selectWorkspace(id, opts = {}) {
   if (!id) return;
@@ -138,7 +168,8 @@ async function selectWorkspace(id, opts = {}) {
   const remembered = opts.restoreSession ? store.get('active') : null;
   const pick = mine.find((s) => s.id === remembered) || mine.find((s) => s.state !== 'exited') || mine[0];
   if (pick) selectSession(pick.id); else clearActive();
-  await Promise.all([loadLibrary(), loadNeeds()]);
+  if (changed) { state.branch = null; renderBranch(); loadScratchpad(); }
+  await Promise.all([loadLibrary(), loadNeeds(), loadBranch()]);
 }
 function renderWorkspaces() {
   const html = state.workspaces.map((w) => {
@@ -385,6 +416,7 @@ function syncActiveState() {
     if (s) b.dataset.state = s.state;
   });
   updateExitedOverlay();
+  refreshScratchSend();   // the scratchpad's send button follows the active session's liveness
 }
 
 // ── renaming a session (R11): inline, in both surfaces, live or exited. The name chosen at
@@ -482,7 +514,7 @@ function selectSession(id) {
   const s = state.sessions.find((x) => x.id === id);
   if (!s) return;
   // selecting a session from the palette may cross workspaces — follow it there
-  if (s.ws !== state.wsId) { state.wsId = s.ws; store.set('wsid', s.ws); renderWorkspaces(); renderSessions(); loadLibrary(); loadNeeds(); }
+  if (s.ws !== state.wsId) { state.wsId = s.ws; store.set('wsid', s.ws); renderWorkspaces(); renderSessions(); loadLibrary(); loadNeeds(); state.branch = null; renderBranch(); loadBranch(); loadScratchpad(); }
   state.active = id;
   store.set('active', id);   // survives reloads (R7)
   // attach once per connection — re-selecting an attached session must not reset + re-replay
@@ -512,6 +544,7 @@ function updateExitedOverlay() {
     $('respawnBtn').onclick = () => send({ t: 'respawn', id: s.id });
     $('removeBtn').onclick = () => send({ t: 'remove', id: s.id });
   } else ov.classList.remove('on');
+  refreshScratchSend();   // send-to-terminal follows whether the active session is live
 }
 function updateEmptyOverlay() {
   // a workspace with no sessions must say so — not show another workspace's terminal
@@ -1062,7 +1095,7 @@ function resolveDocPath(ctx, u) {
   return stack.join('/');
 }
 
-// ── new session: name it before it starts ──
+// ── new session: name it, pick its branch, before it starts ──
 function openNewForm() {
   const w = state.workspaces.find((x) => x.id === state.wsId);
   $('newForm').hidden = false;
@@ -1070,6 +1103,7 @@ function openNewForm() {
   // pre-filled but editable — a default that reads better than "shell" in a list of shells
   const n = mySessions().length + 1;
   $('newName').value = `${w ? w.name : 'session'} ${n}`;
+  fillBranchPicker();               // populate from the workspace's live branch info
   const inp = $('newName');
   setTimeout(() => { inp.focus(); inp.select(); }, 0);
 }
@@ -1077,8 +1111,29 @@ function closeNewForm() {
   $('newForm').hidden = true;
   $('newBtn').setAttribute('aria-expanded', 'false');
 }
+// Populate the branch control from state.branch. A non-repo workspace hides the whole control —
+// there is no honest branch to pick. The default is "stay on the current branch" (no checkout).
+function fillBranchPicker() {
+  const wrap = $('newBranchWrap'), sel = $('newBranch');
+  const b = state.branch;
+  if (!b || !b.ok) { wrap.hidden = true; return; }
+  wrap.hidden = false;
+  const cur = b.detached ? '' : (b.current || '');
+  const opts = [`<option value="">stay on current${cur ? ' (' + esc(cur) + ')' : ''}</option>`]
+    .concat((b.branches || []).map((n) => `<option value="${esc(n)}"${n === cur ? ' disabled' : ''}>${esc(n)}${n === cur ? ' — current' : ''}</option>`))
+    .concat([`<option value="__new__">+ new branch…</option>`]);
+  sel.innerHTML = opts.join('');
+  sel.value = '';
+  setNewBranchMode(false);
+}
+function setNewBranchMode(on) {
+  state.newBranchMode = on;
+  $('newBranchName').hidden = !on;
+  if (on) setTimeout(() => $('newBranchName').focus(), 0);
+}
 $('newBtn').onclick = () => ($('newForm').hidden ? openNewForm() : closeNewForm());
 $('newCancel').onclick = closeNewForm;
+$('newBranch').onchange = (e) => setNewBranchMode(e.target.value === '__new__');
 $('newAgents').querySelectorAll('button').forEach((b) => b.onclick = () => {
   state.newAgent = b.dataset.agent;
   $('newAgents').querySelectorAll('button').forEach((x) => x.setAttribute('aria-checked', String(x === b)));
@@ -1086,10 +1141,85 @@ $('newAgents').querySelectorAll('button').forEach((b) => b.onclick = () => {
 $('newForm').addEventListener('submit', (e) => {
   e.preventDefault();
   const name = $('newName').value.trim();
-  send({ t: 'new', agent: state.newAgent, name: name || state.newAgent, ws: state.wsId });
+  const msg = { t: 'new', agent: state.newAgent, name: name || state.newAgent, ws: state.wsId };
+  // branch: either create a new one, or check out an existing pick. Empty = stay put (no checkout).
+  const sel = $('newBranch');
+  if (!$('newBranchWrap').hidden && sel) {
+    if (sel.value === '__new__') {
+      const nb = $('newBranchName').value.trim();
+      if (!nb) { flash('type a name for the new branch, or pick "stay on current"'); return; }
+      msg.branch = nb; msg.createBranch = true;
+    } else if (sel.value) {
+      msg.branch = sel.value;
+    }
+  }
+  send(msg);
   closeNewForm();
 });
 
+// ── scratchpad (R4): per-workspace staging text; copy or send-to-terminal without auto-running ──
+let scratchTimer = null;
+function setScratchStatus(s) { const el = $('scratchStatus'); if (el) el.textContent = s; }
+async function loadScratchpad() {
+  const id = state.wsId;
+  let text = '';
+  try { const r = await fetch('/api/scratchpad?ws=' + encodeURIComponent(id || '')); const j = await r.json(); if (j && j.ok) text = j.text || ''; } catch {}
+  if (id !== state.wsId) return;               // a slower fetch for a workspace we've left must not paint
+  $('scratchText').value = text; setScratchStatus('');
+}
+function saveScratchpad() {
+  const ws = state.wsId, text = $('scratchText').value;
+  clearTimeout(scratchTimer);
+  scratchTimer = setTimeout(async () => {
+    setScratchStatus('saving…');
+    try {
+      const r = await fetch('/api/scratchpad', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ws, text }) });
+      const j = await r.json();
+      setScratchStatus(j && j.ok ? 'saved' : 'save failed');   // a broken save is never a silent green
+    } catch { setScratchStatus('save failed'); }
+  }, 500);
+}
+// Open/close the drawer. It lives in the flex column below the terminal, so toggling it resizes
+// termhost — the existing ResizeObserver refits the terminal; nothing is ever covered.
+function openScratch(on) {
+  const el = $('scratch');
+  const open = on == null ? el.dataset.open !== 'true' : !!on;
+  el.dataset.open = String(open);
+  $('scratchToggle').setAttribute('aria-expanded', String(open));
+  $('scratchBtn').setAttribute('aria-pressed', String(open));
+  store.set('scratch-open', open ? '1' : '0');
+  if (open) setTimeout(() => $('scratchText').focus(), 0);
+}
+// send-to-terminal writes the text into the active session's PTY WITHOUT a trailing newline — the
+// PM reviews and presses enter. Disabled when there is no live session to receive it.
+function activeLiveSession() {
+  const s = state.sessions.find((x) => x.id === state.active);
+  return s && s.state !== 'exited' ? s : null;
+}
+function refreshScratchSend() {
+  const btn = $('scratchSend'); if (!btn) return;
+  const live = !!activeLiveSession();
+  btn.disabled = !live;
+  btn.title = live ? 'Paste into the active terminal (does not press enter)' : 'no live session to send to';
+}
+$('scratchToggle').onclick = () => openScratch();
+$('scratchBtn').onclick = () => openScratch();
+$('scratchText').addEventListener('input', saveScratchpad);
+$('scratchCopy').onclick = async () => {
+  const text = $('scratchText').value;
+  try { await navigator.clipboard.writeText(text); setScratchStatus('copied'); }
+  catch { $('scratchText').select(); setScratchStatus('press ⌘C to copy'); }
+};
+$('scratchSend').onclick = () => {
+  const s = activeLiveSession();
+  if (!s) { flash('no live session to send to — start or select one'); return; }
+  const text = $('scratchText').value;
+  if (!text) return;
+  send({ t: 'input', id: s.id, data: text });   // no trailing newline: nothing auto-runs
+  setScratchStatus('sent → terminal');
+};
+{ const open = store.get('scratch-open') === '1'; if (open) openScratch(true); }
+
 // ── add a workspace: pick a folder (the GUI twin of running `pmos` in that repo) ──
 function closeAddWs() {
   $('addWsForm').hidden = true; $('addWsBtn').setAttribute('aria-expanded', 'false'); $('addWsPath').value = '';
@@ -1657,6 +1787,9 @@ document.addEventListener('keydown', (e) => {
   if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
     e.preventDefault(); e.stopPropagation(); togglePalette(); return;
   }
+  if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'j') {
+    e.preventDefault(); e.stopPropagation(); openScratch(); return;
+  }
   if (e.key === 'F2' && state.active && !state.renaming) { e.preventDefault(); startRename(state.active); return; }
   if (e.key === 'Escape') {
     if ($('palette').style.display === 'grid') { e.stopPropagation(); closePalette(); }

package/workspace/public/index.html

@@ -13,7 +13,9 @@
   <header class="bar">
     <span class="mark">P</span><b>PMOS</b><span class="sub">workspace</span>
     <span class="conn" id="conn">connecting…</span>
+    <span class="branch" id="branchChip" hidden title="current branch"></span>
     <div class="right">
+      <button class="ibtn" id="scratchBtn" title="Scratchpad — stage text before the terminal (⌘J)" aria-pressed="false">scratch</button>
       <button class="ibtn" id="railBtn" title="Hide/show the library rail" aria-pressed="false">rail</button>
       <button class="ibtn" id="themeBtn" title="Toggle theme">theme</button>
     </div>
@@ -53,6 +55,12 @@
               <button type="button" data-agent="claude" role="radio" aria-checked="false">claude</button>
               <button type="button" data-agent="codex" role="radio" aria-checked="false">codex</button>
             </div>
+            <div class="brwrap" id="newBranchWrap" hidden>
+              <label class="lbl" for="newBranch">branch</label>
+              <select id="newBranch" aria-label="Branch to run this session on"></select>
+              <input id="newBranchName" type="text" hidden placeholder="new-branch-name" aria-label="New branch name" autocomplete="off" spellcheck="false" />
+              <p class="hint warn">the branch is shared by every session in this repo — switching or creating one moves them all</p>
+            </div>
             <div class="row">
               <button type="submit" class="go">start session</button>
               <button type="button" class="quiet" id="newCancel">cancel</button>
@@ -85,6 +93,23 @@
         </div>
       </div>
       <div class="needs" id="needs" role="status" style="display:none"></div>
+
+      <!-- Scratchpad: a collapsible drawer at the BOTTOM of the terminal column. Folded it is a thin
+           bar; open it takes a bounded slice below the terminal — it never overlays the tabs, the
+           terminal, or the document rail. Persists per workspace. -->
+      <section class="scratch" id="scratch" data-open="false" aria-label="Scratchpad">
+        <div class="scratch-head">
+          <button type="button" class="scratch-toggle" id="scratchToggle" aria-expanded="false" aria-controls="scratchText">
+            <span class="chev" aria-hidden="true">▴</span> scratchpad
+          </button>
+          <span class="scratch-status" id="scratchStatus" role="status"></span>
+          <span class="scratch-actions">
+            <button type="button" class="mini" id="scratchCopy" title="Copy to clipboard">copy</button>
+            <button type="button" class="mini" id="scratchSend" title="Paste into the active terminal (does not press enter)">→ terminal</button>
+          </span>
+        </div>
+        <textarea id="scratchText" class="scratch-text" placeholder="Stage commands or notes here, then copy or send them to the terminal…" spellcheck="false" autocomplete="off" aria-label="Scratchpad text"></textarea>
+      </section>
     </main>
 
     <aside class="rail" id="rail" aria-label="Library and document">

package/workspace/public/styles.css

@@ -773,3 +773,40 @@ details.tree>summary:hover{color:var(--text-2)}
 .cs-perrow .bar{flex:1;height:6px;border-radius:4px;background:var(--chip);overflow:hidden}
 .cs-perrow .bar i{display:block;height:100%;background:var(--accent);border-radius:4px}
 .cs-perrow .v{font-family:var(--mono);font-size:10px;color:var(--text-dim);flex:none;width:28px;text-align:right}
+
+/* ── branch awareness (workspace-session-controls) ── */
+.bar .branch{font-family:var(--mono);font-size:10px;letter-spacing:.04em;color:var(--text-3);
+  padding:3px 8px;border:1px solid var(--border);border-radius:7px;background:var(--chip);
+  white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:26ch}
+.bar .branch[hidden]{display:none}
+.bar .branch.dirty{color:var(--warn-text);border-color:var(--warn)}
+
+/* new-session branch picker — matches the miniform vocabulary */
+.brwrap{display:flex;flex-direction:column;gap:6px}
+.brwrap[hidden]{display:none}
+.brwrap select{min-height:38px;padding:0 8px;border:1px solid var(--border-strong);border-radius:8px;
+  background:var(--chip);color:var(--text-2);font-family:var(--mono);font-size:11px}
+.brwrap select:focus{border-color:var(--accent)}
+.brwrap input[hidden]{display:none}
+.miniform .hint.warn{color:var(--warn-text)}
+
+/* ── scratchpad drawer: bottom of the terminal column, collapsible, never overlays anything ── */
+.scratch{flex:none;border-top:1px solid var(--border-3);background:var(--panel);display:flex;flex-direction:column;min-height:0}
+.scratch-head{display:flex;align-items:center;gap:8px;padding:5px 10px;min-height:34px;
+  background:var(--panel-head);border-bottom:1px solid transparent}
+.scratch[data-open="true"] .scratch-head{border-bottom-color:var(--border-3)}
+.scratch-toggle{display:inline-flex;align-items:center;gap:7px;border:0;background:none;
+  font-family:var(--mono);font-size:8.5px;letter-spacing:.15em;text-transform:uppercase;color:var(--text-dim);cursor:pointer}
+.scratch-toggle:hover{color:var(--text-2)}
+.scratch-toggle .chev{display:inline-block;transition:transform .15s;font-size:9px}
+.scratch[data-open="true"] .scratch-toggle .chev{transform:rotate(180deg)}
+.scratch-status{font-family:var(--mono);font-size:9.5px;color:var(--text-dim);letter-spacing:.04em}
+.scratch-actions{margin-left:auto;display:flex;gap:6px}
+.scratch-actions .mini{min-height:28px;padding:0 10px;border:1px solid var(--border);border-radius:7px;
+  background:var(--chip);color:var(--accent-text);font-family:var(--mono);font-size:10px;letter-spacing:0;cursor:pointer}
+.scratch-actions .mini:hover{border-color:var(--accent)}
+.scratch-actions .mini:disabled{color:var(--text-dim);border-color:var(--border-3);cursor:not-allowed;opacity:.6}
+.scratch-text{display:none;width:100%;box-sizing:border-box;resize:vertical;height:22vh;min-height:90px;max-height:45vh;
+  border:0;padding:10px 12px;background:var(--term-bg);color:var(--text-2);
+  font-family:var(--mono);font-size:12px;line-height:1.5;outline:none}
+.scratch[data-open="true"] .scratch-text{display:block}

package/workspace/server.js

@@ -36,12 +36,30 @@ try {
 } catch (e) {
   console.error('✗ node-pty failed to load — the native module is missing or built for the wrong platform.');
   console.error(`  ${e.message.split('\n')[0]}`);
-  console.error('  Fix:  npm run doctor                          (diagnoses arch/toolchain/Node version)');
-  console.error('        rm -rf node_modules && npm install       (recompiles node-pty from source)');
-  console.error(`  node-pty compiles a native addon — needs a C/C++ toolchain (macOS: xcode-select --install; Debian/Ubuntu: apt install build-essential python3) and a supported Node LTS. You are on ${process.version}; if it is a very new or non-LTS release the build may fail — try Node 22 LTS.`);
+  console.error('  Fix:  npm run doctor                     (diagnoses the exact cause)');
+  console.error('        rm -rf node_modules && npm install  (reinstalls node-pty for this platform)');
   process.exit(1);
 }
 
+// node-pty ships a prebuilt macOS `spawn-helper` binary that it exec()s to open each PTY. The
+// prebuild-extraction path can drop its executable bit, and then EVERY session dies with
+// `posix_spawnp failed` — the #1 field failure (it looks like a broken build but the binary is
+// fine, just not +x). Restore the bit wherever node-pty keeps the helper (prebuilds/<plat>-<arch>/
+// or a from-source build/Release/) BEFORE we spawn anything. Cheap, idempotent, no-op off macOS.
+function ensureSpawnHelperExecutable() {
+  if (process.platform === 'win32') return;
+  try {
+    const root = path.dirname(require.resolve('node-pty/package.json'));
+    const targets = [path.join(root, 'build', 'Release', 'spawn-helper')];
+    const pb = path.join(root, 'prebuilds');
+    try { for (const d of fs.readdirSync(pb)) targets.push(path.join(pb, d, 'spawn-helper')); } catch {}
+    for (const f of targets) {
+      try { const st = fs.statSync(f); if (!(st.mode & 0o111)) fs.chmodSync(f, st.mode | 0o755); } catch {}
+    }
+  } catch {}
+}
+ensureSpawnHelperExecutable();
+
 const { checkSurface } = require('./lib/surface-contract');
 const scheduleLogic = require('./lib/schedule-logic');
 const harness = require('./lib/harness-parse');
@@ -51,6 +69,7 @@ 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 gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
 // 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
@@ -77,6 +96,7 @@ const PUB = path.join(__dirname, 'public');
 const XROOT = path.join(__dirname, 'node_modules', '@xterm');
 const STATE = path.join(__dirname, 'state');
 const SESS_DIR = path.join(STATE, 'sessions');
+const SCRATCH_DIR = path.join(STATE, 'scratchpad');   // per-workspace staging text (D62; local-only, gitignored)
 const WS_FILE = path.join(STATE, 'workspaces.json');
 const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
 const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
@@ -819,20 +839,18 @@ function appendBuf(s, data) {
   s.parsed = null;                      // buffer moved; the cached parse is stale
 }
 
-// Platform-correct guidance when a spawn fails. `posix_spawnp failed` means node-pty's native
-// build is broken: either a wrong-arch binary (e.g. x64 Node on Apple Silicon) or an incomplete
-// compile (the spawn-helper never built — common on a brand-new/non-LTS Node). A shell change
-// won't fix it; a clean recompile will. `npm rebuild node-pty` compiles from source on its own —
-// node-pty ships no prebuilds — so the old `--build-from-source` npm flag is unnecessary (and
-// newer npm rejects it as an unknown config).
+// Platform-correct guidance when a spawn fails. On macOS `posix_spawnp failed` is almost always
+// node-pty's prebuilt `spawn-helper` missing its executable bit (prebuild extraction drops it) —
+// the binary is fine, just not +x. The server auto-restores it at startup and `npm run doctor`
+// re-applies + verifies the fix; a wrong-arch binary (x64 Node on Apple Silicon) is the rarer
+// alternative, cured by a clean reinstall.
 function spawnFailureAdvice(err, cmd, isShell) {
   const msg = String(err && err.message || err);
   if (/posix_spawnp|EFAULT|ENOEXEC|wrong architecture|not valid/i.test(msg)) {
-    return `could not spawn '${cmd}' (${msg}). node-pty's native build is broken (wrong-arch, or ` +
-      `the spawn-helper never compiled). Fix: stop the server, run \`npm run doctor\` (it names the ` +
-      `install dir + the exact cause), then in that dir \`rm -rf node_modules && npm install\`. ` +
-      `Needs a C/C++ toolchain; on a very new or non-LTS Node (${process.version}) the compile can ` +
-      `fail — try Node 22 LTS.`;
+    return `could not spawn '${cmd}' (${msg}). On macOS this is almost always node-pty's prebuilt ` +
+      `spawn-helper lacking its executable bit. Fix: run \`pmos doctor\` (it restores +x and verifies), ` +
+      `then ↻ respawn. If it persists, the binary is wrong-arch — \`rm -rf node_modules && npm install\` ` +
+      `in the workspace install dir.`;
   }
   if (process.platform === 'win32') {
     return `could not start '${cmd}': ${msg}. Native Windows needs WSL for a real PTY shell — ` +
@@ -905,8 +923,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
@@ -1029,6 +1060,38 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
   persist(s); pushSessions(); pushWorkspaces();
   return s;
 }
+
+// New session, optionally on a chosen/created branch. The working tree is SHARED across a repo's
+// sessions, so the checkout is repo-wide — the UI says so. A FAILED checkout must never spawn a
+// session on the wrong branch (rubric hard floor): we return {ok:false} and spawn nothing. Kept as
+// its own function so the checkout-then-maybe-spawn contract is unit-testable without a WS client.
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch }) {
+  if (branch) {
+    const w = getWs(ws);
+    const r = gitInfo.checkout(w.root, branch, { create: !!createBranch });
+    if (!r.ok) return { ok: false, error: r.error };
+    broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
+  }
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws });
+  return { ok: true, session: s };
+}
+
+// ── Scratchpad: per-workspace staging text (R4). Local-only, one file per workspace keyed by the
+// workspace's hashed id (never a caller-supplied path), capped so it can't be used as a blob store.
+const SCRATCH_MAX = 200_000;
+function scratchpadPath(w) { return w ? path.join(SCRATCH_DIR, w.id + '.txt') : null; }
+function readScratchpad(w) {
+  const f = scratchpadPath(w);
+  if (!f) return '';
+  try { return fs.readFileSync(f, 'utf8'); } catch { return ''; }
+}
+function writeScratchpad(w, text) {
+  const f = scratchpadPath(w);
+  if (!f) throw new Error('no workspace');
+  fs.mkdirSync(SCRATCH_DIR, { recursive: true });
+  fs.writeFileSync(f, String(text == null ? '' : text).slice(0, SCRATCH_MAX));
+}
+
 // Remove a session from the registry + disk. Only non-live sessions can be removed;
 // a live one must be killed first (its onExit flips it to exited).
 function removeSession(id) {
@@ -1524,6 +1587,28 @@ async function handleRequest(req, res) {
     res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' }); return res.end(md);
   }
   if (p === '/api/sessions') return json(res, { sessions: sessionList() });
+  if (p === '/api/git/branches') {
+    // Read-only branch awareness for a workspace. A non-repo returns {ok:false} (never a fake
+    // branch). Fixed git args, no caller input in the read path (R1).
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' });
+    return json(res, gitInfo.branchInfo(w.root));
+  }
+  if (p === '/api/scratchpad' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    try { writeScratchpad(w, body.text); }
+    catch (e) { warnWriteFail('scratchpad', e); return json(res, { ok: false, error: 'could not save scratchpad' }, 500); }
+    return json(res, { ok: true });
+  }
+  if (p === '/api/scratchpad') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    return json(res, { ok: true, text: readScratchpad(w) });
+  }
   if (p === '/api/doc') {
     const w = getWs(url.searchParams.get('ws'));
     const doc = w ? readTextDoc(w.root, url.searchParams.get('path') || '') : null;
@@ -1716,8 +1801,9 @@ wss.on('connection', (ws) => {
     } else if (m.t === 'resize') {
       const s = sessions.get(m.id); if (s && s.pty) { try { s.pty.resize(m.cols, m.rows); s.cols = m.cols; s.rows = m.rows; } catch {} }
     } else if (m.t === 'new') {
-      const s = spawnSession({ name: m.name, agent: m.agent || 'shell', cwd: m.cwd, ws: m.ws });
-      ws.send(JSON.stringify({ t: 'created', id: s.id }));
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch });
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: 'branch: ' + r.error })); return; }
+      ws.send(JSON.stringify({ t: 'created', id: r.session.id }));
     } else if (m.t === 'respawn') {
       const old = sessions.get(m.id); if (!old || old.pty) return;
       const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws });