create-pmos 0.6.3 → 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.3",
+  "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@f4589bf
+kernel-source: pmos@4ce6980
 assembled: 2026-07-27
 mode: vendor

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

@@ -69,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
@@ -95,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)
@@ -1058,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) {
@@ -1553,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;
@@ -1745,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 });