create-pmos 0.6.3 → 0.7.0

package/workspace/public/app.js

@@ -21,8 +21,14 @@ const state = {
   lib: null,                    // library payload for the selected workspace
   lens: 'initiatives',          // 'initiatives' | 'folders'
   filter: '',
-  active: null,                 // active session id
-  terms: new Map(),            // id -> {term, fit, el}
+  active: null,                 // active session id — always groups[focusG].activeId
+  groups: [{ activeId: null }, { activeId: null }],  // terminal groups (R6); [1] exists when split
+  focusG: 0,                   // which group the keyboard, ⌘J send and rename act on
+  layouts: [],                 // this workspace's arrangements (R1) — stock four + custom
+  layoutId: null,              // the one currently applied
+  layoutSaveT: null,           // debounce handle for the write-back
+  layoutDirty: false,          // an adjustment not yet on disk — flushed on pagehide
+  terms: new Map(),            // id -> {term, fit, el, g}
   attached: new Set(),         // ids attached ON THIS CONNECTION (cleared on reconnect)
   needs: [],
   newAgent: 'shell',
@@ -31,6 +37,9 @@ 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
+  sessSig: null,               // structural fingerprint of the last session push (see structSig)
 };
 
 // ── workspace state survives reloads (R7): theme + selected workspace + focused session,
@@ -84,6 +93,7 @@ function mySessions() { return state.sessions.filter((s) => s.ws === state.wsId)
 
 function handle(m) {
   if (m.t === 'hello') {
+    if (Number.isFinite(m.quietAfterMs) && m.quietAfterMs > 0) QUIET_AFTER_MS = m.quietAfterMs;
     state.workspaces = m.workspaces; state.home = m.home; state.sessions = m.sessions;
     // pick: the URL (a fresh `pmos` in this repo) → the last one used → home
     const remembered = store.get('wsid');
@@ -105,12 +115,22 @@ function handle(m) {
       if (!ids.has(id)) { try { t.term.dispose(); } catch {} t.el.remove(); state.terms.delete(id); state.attached.delete(id); }
     }
     if (state.renaming && !ids.has(state.renaming)) cancelRename();
-    state.sessions = m.sessions; renderSessions(); renderWorkspaces();
+    // The liveness heartbeat pushes this message every couple of seconds, so it can no longer cost
+    // a full innerHTML rebuild of the session pane: that would drop text selection, reset scroll
+    // and flicker the sidebar twice a second. Split it — a STRUCTURAL change (a session appeared,
+    // vanished, was renamed, or exited) rebuilds; a mere liveness/harness update repaints the
+    // volatile bits in place. The openness of a drill-in and an in-flight rename already survived
+    // a rebuild; this keeps everything else intact too.
+    const sig = structSig(m.sessions);
+    const structural = sig !== state.sessSig;
+    state.sessSig = sig;
+    state.sessions = m.sessions;
+    if (structural) { renderSessions(); renderWorkspaces(); } else { paintVolatile(); }
     if (state.active && !ids.has(state.active)) {
       const mine = mySessions();
       const nx = mine.find((s) => s.state !== 'exited') || mine[mine.length - 1];
       if (nx) selectSession(nx.id); else clearActive();
-    } else { syncActiveState(); }
+    } else if (structural) { syncActiveState(); }
   } else if (m.t === 'attached') {
     const t = ensureTerm(m.id);
     t.term.reset();
@@ -118,12 +138,49 @@ function handle(m) {
     fitOne(m.id);
   } else if (m.t === 'data') {
     const t = state.terms.get(m.id); if (t) t.term.write(m.data);
+    // Bytes arriving IS the liveness signal, and it is the same fact the server stamps into
+    // lastOutputAt — so an attached session's dot flips to `working` on the byte rather than on
+    // the next heartbeat. It is a nudge, not a second source of truth: the very next heartbeat
+    // overwrites it with the server's stamp, and it only ever moves the clock FORWARD, so it can
+    // make a row read `working` a beat early but can never keep a dead row looking alive. Only
+    // attached sessions get `data` at all — which is exactly why the heartbeat is the mechanism
+    // and this is the garnish.
+    const live = state.sessions.find((x) => x.id === m.id);
+    if (live && live.state !== 'exited') { live.lastOutputAt = Date.now(); tickQuiet(); }
   } 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 +195,9 @@ 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()]);
+  // the arrangement belongs to the repo (R7) — a different workspace brings its own layouts
+  if (changed) { state.branch = null; renderBranch(); loadScratchpad(); loadLayouts(); }
+  await Promise.all([loadLibrary(), loadNeeds(), loadBranch()]);
 }
 function renderWorkspaces() {
   const html = state.workspaces.map((w) => {
@@ -186,7 +245,11 @@ const GLYPH = { working: '●', quiet: '◼', blocked: '◆', done: '✓', idle:
 // The word beside the glyph. 'quiet' means no output for a while — NOT 'waiting on you'.
 // Quiescence proves quiet, not waiting (PRD R1); the wording may not be upgraded.
 const STATE_WORD = { working: 'working', quiet: 'quiet', exited: 'exited' };
-const QUIET_AFTER_MS = 30000;            // mirrors harness-parse.QUIET_AFTER_MS
+// The threshold the server derives `quiet` from, sent in `hello`. It used to be re-typed here as a
+// literal "mirrors harness-parse.QUIET_AFTER_MS" — two copies of one number, free to drift apart and
+// give the sidebar and the server different opinions about the same session. The literal survives
+// only as the value to assume before hello lands.
+let QUIET_AFTER_MS = 30000;
 function shortDur(ms) {
   if (ms == null) return '';
   const sec = Math.round(ms / 1000);
@@ -272,18 +335,30 @@ function renderSessions() {
 // 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) {
+// Split inner-from-wrapper so the heartbeat's in-place painter can compare and assign innerHTML.
+// Comparing outerHTML against a source string never matches (the browser re-serialises), so it
+// would rewrite the node on every beat — and a node rewritten twice a second is a node the PM
+// cannot select text in.
+function subInner(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>`;
+  if (title) return `<span class="lead">opening focus</span> ${esc(title)}`;
+  return `${esc(s.agent)} · ${esc(s.cwd)}`;
 }
+function subLine(s) { return `<span class="sub">${subInner(s)}</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.
-function saysLine(s) {
-  if (s.lastWords) return `<span class="says">${esc(s.lastWords)}</span>`;
+// {cls, html} rather than a finished span, for the same in-place-repaint reason as subInner — and
+// here the CLASS also changes (`says` for real words, `says na` for a stated reason), so the
+// painter has to be able to set the two independently.
+function saysParts(s) {
+  if (s.lastWords) return { cls: 'says', html: esc(s.lastWords) };
   const why = s.missing && s.missing.lastWords;
-  return why ? `<span class="says na">${esc(why)}</span>` : '';
+  return why ? { cls: 'says na', html: esc(why) } : null;
+}
+function saysLine(s) {
+  const p = saysParts(s);
+  return p ? `<span class="${p.cls}">${p.html}</span>` : '';
 }
 // The harness readout: a drill-in, not a rail. The leg-A grilling established the harness is
 // near-static within a run, so this is read once to understand a session — not watched.
@@ -299,7 +374,7 @@ function fmtTokens(n) {
 // the CLI does not PRINT its model, effort, tokens or skill set to the terminal — parsing
 // scrollback for them returned four empty rows, which is what sent this back for a second pass.
 // Rows that genuinely cannot be known are still drawn as unavailable, never as a plausible value.
-function harnessDrawer(s) {
+function harnessRows(s) {
   const hx = s.hx || { missing: {} };
   const m = hx.missing || {};
   const rows = [];
@@ -336,9 +411,50 @@ function harnessDrawer(s) {
     rows.push(`<dt>gates</dt>${na('not visible from the workspace — gate state is hosted')}`);
     if (hx.cliVersion) rows.push(`<dt>cli</dt><dd><span class="src">${esc(hx.cliVersion)} — undocumented layout; a CLI upgrade may blank these rows</span></dd>`);
   }
+  return rows.join('');
+}
+// The rows are split out of the drawer so the heartbeat can repaint the <dl> ALONE. Replacing the
+// whole <details> would slam it shut on every push — the drill-in has to survive its own updates.
+function harnessDrawer(s) {
   return `<details class="hz" data-id="${s.id}">
     <summary>model + harness<span class="sr">${esc(s.name)}</span></summary>
-    <dl class="kv">${rows.join('')}</dl></details>`;
+    <dl class="kv">${harnessRows(s)}</dl></details>`;
+}
+// What a session push must REBUILD the DOM for, as opposed to repaint in place. Everything here is
+// baked into renderSessions'/renderTabs' markup and has no in-place painter: the row's identity,
+// its workspace, its name, its raw lifecycle state (which drives the close button's wording and the
+// per-workspace live count), and the `scheduled` tag. Liveness and harness are deliberately ABSENT
+// — they change on every heartbeat and are what paintVolatile exists to carry.
+function structSig(list) {
+  // delimited with the ASCII unit/record separators, so a name ending where a state begins cannot
+  // fingerprint identically to a different split of the same characters
+  return list.map((s) => [s.id, s.ws, s.name, s.state, s.origin || ''].join('')).join('');
+}
+// The in-place repaint for a heartbeat push: everything on a row that changes while the run is
+// running. Never innerHTML on the pane itself — an open drill-in, an in-flight rename, the sidebar's
+// scroll position and any text the PM has selected all survive this.
+function paintVolatile() {
+  tickQuiet();                       // chip, glyph, data-state, accessible name (both surfaces)
+  for (const s of mySessions()) {
+    const row = $('sessions').querySelector(`.sessrow[data-id="${s.id}"]`);
+    if (!row) continue;
+    // the sub-line ("opening focus …" or the agent · cwd fallback) and the agent's last words —
+    // both come from the server and both were frozen at the last lifecycle event. Assign only on a
+    // real difference: an unconditional rewrite twice a second would drop the PM's text selection.
+    const sub = row.querySelector('.sub');
+    if (sub) { const next = subInner(s); if (sub.innerHTML !== next) sub.innerHTML = next; }
+    const says = row.querySelector('.says'), nextSays = saysParts(s);
+    if (nextSays && says) {
+      if (says.className !== nextSays.cls) says.className = nextSays.cls;
+      if (says.innerHTML !== nextSays.html) says.innerHTML = nextSays.html;
+    } else if (nextSays) {
+      row.querySelector('.sess').insertAdjacentHTML('beforeend', `<span class="${nextSays.cls}">${nextSays.html}</span>`);
+    } else if (says) { says.remove(); }
+    // the drill-in's rows — model, tokens, tools, skills. Only the <dl> is replaced, so the
+    // <details> element itself (and therefore its open/closed state) is untouched.
+    const dl = $('sessions').querySelector(`details.hz[data-id="${s.id}"] .kv`);
+    if (dl) { const next = harnessRows(s); if (dl.innerHTML !== next) dl.innerHTML = next; }
+  }
 }
 // A row must be able to go quiet with NO server push. Repaint the chip, glyph, data-state and
 // accessible name only — never innerHTML — so an open drill-in and an in-flight rename survive.
@@ -356,35 +472,63 @@ function tickQuiet() {
       chip.textContent = st.text;
       btn.setAttribute('aria-label', `${s.name} — ${st.text}`);
     }
-    const tab = $('stabs').querySelector(`.stab-wrap[data-id="${s.id}"]`);
-    if (tab && tab.dataset.state !== st.shown) tab.dataset.state = st.shown;
+    // both groups list every session, so the tick has to reach every strip that shows this one
+    document.querySelectorAll(`.stabs .stab-wrap[data-id="${s.id}"]`).forEach((tab) => {
+      if (tab.dataset.state === st.shown) return;
+      tab.dataset.state = st.shown;
+      // the tab's glyph is derived too, so it has to move with the colour — otherwise the fix in
+      // renderTabs would hold only until the first tick that flipped the state without a re-render.
+      const g = tab.querySelector('.g'); if (g) g.textContent = GLYPH[st.shown] || '•';
+      const btnTab = tab.querySelector('.stab'); if (btnTab) btnTab.setAttribute('aria-label', `${s.name} — ${st.text}`);
+    });
   }
 }
 try { const _q = setInterval(tickQuiet, 5000); if (_q.unref) _q.unref(); } catch {}
 
 function renderTabs() {
+  // Both groups list EVERY session (R6): clicking a tab shows that session in THAT group, which
+  // is how the PM chooses what goes where without a drag.
+  renderTabStrip(0);
+  if (splitOn()) renderTabStrip(1);
+  paintGroups();
+}
+function renderTabStrip(gi) {
+  const host = $(GROUP_TABS[gi]);
+  if (!host) return;
+  const act = state.groups[gi].activeId;
   // wrap = two SIBLING buttons (select + close) — no interactive-inside-interactive nesting
-  $('stabs').innerHTML = mySessions().map((s) => `
-    <div class="stab-wrap" data-state="${stateLabel(s).shown}" data-id="${s.id}" data-active="${s.id === state.active}">
-      <button class="stab" role="tab" data-id="${s.id}" aria-selected="${s.id === state.active}"
-        aria-label="${esc(s.name)} — ${s.state}" title="double-click to rename">
-        <span class="g" aria-hidden="true">${GLYPH[s.state] || '•'}</span>${esc(s.name)}</button>
+  host.innerHTML = mySessions().map((s) => {
+    // the glyph and the accessible name read the DERIVED state, like the wrapper's data-state
+    // beside them. Reading the raw `s.state` here drew a `working` ● in the `quiet` colour — the
+    // shape said one thing and the colour said another, on the surface most looked at.
+    const st = stateLabel(s);
+    return `
+    <div class="stab-wrap" data-state="${st.shown}" data-id="${s.id}" data-active="${s.id === act}">
+      <button class="stab" role="tab" data-id="${s.id}" aria-selected="${s.id === act}"
+        aria-label="${esc(s.name)} — ${esc(st.text)}" title="double-click to rename">
+        <span class="g" aria-hidden="true">${GLYPH[st.shown] || '•'}</span>${esc(s.name)}</button>
       <button class="x" data-close="${s.id}"
         aria-label="${s.state === 'exited' ? 'remove' : 'close'} ${esc(s.name)}">✕</button>
-    </div>`).join('');
-  $('stabs').querySelectorAll('.stab').forEach((b) => {
-    b.onclick = () => selectSession(b.dataset.id);
+    </div>`;
+  }).join('');
+  host.querySelectorAll('.stab').forEach((b) => {
+    b.onclick = () => selectSession(b.dataset.id, gi);
     b.ondblclick = () => startRename(b.dataset.id);
   });
   // live tab ✕ kills the process (state flips to exited); exited tab ✕ removes it for good
-  $('stabs').querySelectorAll('.x').forEach((b) => b.onclick = () => send({ t: 'kill', id: b.dataset.close }));
+  host.querySelectorAll('.x').forEach((b) => b.onclick = () => send({ t: 'kill', id: b.dataset.close }));
 }
 function syncActiveState() {
   document.querySelectorAll('.sess,.stab-wrap').forEach((b) => {
     const s = state.sessions.find((x) => x.id === b.dataset.id);
-    if (s) b.dataset.state = s.state;
+    // the DERIVED state (working|quiet|exited), never the raw one. Writing `s.state` here put
+    // `working` back over a row that renderSessions/tickQuiet had correctly painted `quiet`, so
+    // the dot's colour depended on which of the two ran last — a coin-flip at the old push rate,
+    // and a visible 2s/5s flicker once the liveness heartbeat started pushing on a cadence.
+    if (s) b.dataset.state = stateLabel(s).shown;
   });
   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
@@ -409,7 +553,9 @@ function paintRename() {
   const id = state.renaming;
   if (!id) return;
   const row = $('sessions').querySelector(`.sessrow[data-id="${id}"]`);
-  const tab = $('stabs').querySelector(`.stab-wrap[data-id="${id}"]`);
+  // rename in place wherever the PM double-clicked: the sidebar row, or either group's tab
+  const tab = $(GROUP_TABS[state.focusG]).querySelector(`.stab-wrap[data-id="${id}"]`)
+    || document.querySelector(`.stabs .stab-wrap[data-id="${id}"]`);
   const host = row || tab;
   if (!host) return;
   const input = document.createElement('input');
@@ -430,12 +576,26 @@ function paintRename() {
 }
 
 // ── terminals ──
-function ensureTerm(id) {
+// Sessions live in GROUPS (R6). One group is the shipped behaviour; a split layout shows a second
+// beside it. A session is visible in at most one group at a time — its pane MOVES between hosts
+// rather than being duplicated, so there is never a second xterm bound to the same PTY.
+const GROUP_HOST = ['termhost', 'termhost1'];
+const GROUP_TABS = ['stabs', 'stabs1'];
+function groupOf(id) { const t = state.terms.get(id); return t ? t.g : 0; }
+function groupHost(g) { return $(GROUP_HOST[g] || GROUP_HOST[0]); }
+function splitOn() { return !$('group1').hidden; }
+function syncActive() { state.active = state.groups[state.focusG].activeId; }
+
+function ensureTerm(id, g) {
+  const want = typeof g === 'number' ? g : 0;
   let t = state.terms.get(id);
-  if (t) return t;
+  if (t) {
+    if (t.g !== want) { t.g = want; groupHost(want).appendChild(t.el); fitOne(id); }
+    return t;
+  }
   const el = document.createElement('div');
   el.className = 'termpane'; el.dataset.id = id;
-  $('termhost').appendChild(el);
+  groupHost(want).appendChild(el);
   const term = new window.Terminal({
     fontFamily: '"IBM Plex Mono", ui-monospace, monospace', fontSize: 13, theme: xtheme(),
     cursorBlink: true, scrollback: 5000, allowProposedApi: true,
@@ -455,7 +615,7 @@ function ensureTerm(id) {
   });
   term.onData((d) => send({ t: 'input', id, data: applyCtrl(d) }));
   term.onResize(({ cols, rows }) => send({ t: 'resize', id, cols, rows }));
-  t = { term, fit, el };
+  t = { term, fit, el, g: want };
   state.terms.set(id, t);
   return t;
 }
@@ -464,43 +624,104 @@ function fitOne(id) {
   requestAnimationFrame(() => { try { t.fit.fit(); } catch {} });
 }
 // Anything that changes the terminal's box must re-fit it, or xterm keeps rendering more rows
-// than fit and the BOTTOM OF THE TERMINAL disappears under the clip (R9). A single observer on
-// the host catches every cause — the needs strip, the reader, a folded rail pane, the tab strip
-// wrapping, a window resize — instead of a fitOne() call sprinkled at each call site.
+// than fit and the BOTTOM OF THE TERMINAL disappears under the clip (R9). Observers on the hosts
+// catch every cause — the needs strip, the reader, a folded pane, the tab strip wrapping, a window
+// resize, a layout change, a split — instead of a fitOne() call sprinkled at each call site.
+// EVERY group's visible session is re-fitted: fitting only the focused one leaves the other
+// group rendering rows for the width it had before the split.
 let refitTimer = null;
 function refit() {
   clearTimeout(refitTimer);
-  refitTimer = setTimeout(() => { if (state.active) fitOne(state.active); }, 30);
+  refitTimer = setTimeout(() => {
+    for (const g of state.groups) if (g.activeId) fitOne(g.activeId);
+  }, 30);
 }
-if (window.ResizeObserver) new ResizeObserver(refit).observe($('termhost'));
+if (window.ResizeObserver) { const ro = new ResizeObserver(refit); ro.observe($('termhost')); ro.observe($('termhost1')); }
 window.addEventListener('resize', refit);
 document.addEventListener('visibilitychange', () => { if (!document.hidden) refit(); });
 // first paint measures the fallback font; the real metrics arrive with the webfont
 if (document.fonts && document.fonts.ready) document.fonts.ready.then(() => { for (const [id] of state.terms) fitOne(id); });
 
-function selectSession(id) {
+function selectSession(id, g) {
   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(); }
-  state.active = id;
+  if (s.ws !== state.wsId) { state.wsId = s.ws; store.set('wsid', s.ws); renderWorkspaces(); renderSessions(); loadLibrary(); loadNeeds(); state.branch = null; renderBranch(); loadBranch(); loadScratchpad(); loadLayouts(); }
+  // Which group shows it: the one asked for; else the group already showing it (so a click in the
+  // sidebar focuses where it lives rather than yanking it across); else the focused group.
+  let want = typeof g === 'number' ? g : state.groups.findIndex((gr) => gr.activeId === id);
+  if (want < 0) want = state.focusG;
+  if (want === 1 && !splitOn()) want = 0;
+  // the same session must never render in both groups — the other one gives it up
+  const other = want === 0 ? 1 : 0;
+  if (state.groups[other].activeId === id) state.groups[other].activeId = null;
+  state.groups[want].activeId = id;
+  state.focusG = want;
+  syncActive();
   store.set('active', id);   // survives reloads (R7)
   // attach once per connection — re-selecting an attached session must not reset + re-replay
   if (!state.attached.has(id)) { state.attached.add(id); send({ t: 'attach', id }); }
-  ensureTerm(id);
-  for (const [sid, t] of state.terms) t.el.classList.toggle('on', sid === id);
-  document.querySelectorAll('.sess').forEach((b) => b.setAttribute('aria-current', String(b.dataset.id === id)));
-  document.querySelectorAll('.stab').forEach((b) => b.setAttribute('aria-selected', String(b.dataset.id === id)));
-  document.querySelectorAll('.stab-wrap').forEach((b) => b.dataset.active = String(b.dataset.id === id));
+  ensureTerm(id, want);
+  paintGroups();
   fitOne(id);
   const t = state.terms.get(id); if (t) setTimeout(() => t.term.focus(), 0);
   updateExitedOverlay(); updateEmptyOverlay();
 }
+// One place decides what is visible where: each group shows exactly its own activeId, every other
+// pane is hidden, and the sidebar/tab selection marks follow.
+function paintGroups() {
+  for (const [sid, t] of state.terms) {
+    const gr = state.groups[t.g];
+    t.el.classList.toggle('on', !!gr && gr.activeId === sid);
+  }
+  const shown = new Set(state.groups.map((gr) => gr.activeId).filter(Boolean));
+  document.querySelectorAll('.sess').forEach((b) => b.setAttribute('aria-current', String(shown.has(b.dataset.id))));
+  GROUP_TABS.forEach((tid, gi) => {
+    const host = $(tid); if (!host) return;
+    const act = state.groups[gi].activeId;
+    host.querySelectorAll('.stab').forEach((b) => b.setAttribute('aria-selected', String(b.dataset.id === act)));
+    host.querySelectorAll('.stab-wrap').forEach((b) => b.dataset.active = String(b.dataset.id === act));
+  });
+  $('group0').dataset.focus = String(state.focusG === 0);
+  $('group1').dataset.focus = String(state.focusG === 1);
+  $('noSess1').classList.toggle('on', splitOn() && !state.groups[1].activeId);
+}
 function clearActive() {
-  state.active = null;
-  $('termhost').querySelectorAll('.termpane').forEach((e) => e.classList.remove('on'));
+  state.groups.forEach((g) => { g.activeId = null; });
+  syncActive();
+  document.querySelectorAll('.termpane').forEach((e) => e.classList.remove('on'));
+  paintGroups();
   updateExitedOverlay(); updateEmptyOverlay();
 }
+
+// ── split / un-split (R6) ──
+function applySplit(on) {
+  const was = splitOn();
+  $('group1').hidden = !on;
+  $('groups').dataset.split = on ? 'on' : 'off';
+  if (on && !state.groups[1].activeId) {
+    // fill the second group with the next session that is not already on screen; if there is
+    // none, the empty-group card offers `＋ new session` rather than a black rectangle
+    const taken = new Set([state.groups[0].activeId]);
+    const next = mySessions().find((s) => !taken.has(s.id));
+    if (next) {
+      state.groups[1].activeId = next.id;
+      if (!state.attached.has(next.id)) { state.attached.add(next.id); send({ t: 'attach', id: next.id }); }
+      ensureTerm(next.id, 1);
+    }
+  }
+  if (!on && state.groups[1].activeId) {
+    // un-split does NOT close the session — it goes back to being a tab in the primary group
+    const id = state.groups[1].activeId;
+    state.groups[1].activeId = null;
+    const t = state.terms.get(id);
+    if (t) { t.g = 0; groupHost(0).appendChild(t.el); }
+    if (state.focusG === 1) state.focusG = 0;
+  }
+  if (was !== on) renderTabs();
+  syncActive();
+  paintGroups();
+}
 function updateExitedOverlay() {
   const s = state.sessions.find((x) => x.id === state.active);
   const ov = $('exited');
@@ -512,6 +733,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
@@ -715,57 +937,362 @@ function closeDoc() {
   refit();
 }
 
-// ── rail + pane folding (R12), all persisted ──
-function foldPane(which, open) {
-  const pane = which === 'doc' ? $('paneDoc') : $('paneLib');
-  const btn = which === 'doc' ? $('docFold') : $('libFold');
-  pane.dataset.fold = open ? 'on' : 'off';
-  btn.setAttribute('aria-expanded', String(open));
-  store.set('fold-' + which, open ? 'on' : 'off');
-  refit();
+// ══ THE LAYOUT SYSTEM (workspace-layout-system) ═════════════════════════════════════════════
+// A layout is a named state tuple; the grid template is computed from it by lib/layout.js. The
+// PM picks one in one act, then adjusts it freely — and the adjustment is kept against THAT
+// layout automatically. There is no dirty state, no save and no discard (R4), which is why
+// `restore` on a stock layout is not a nicety: it is the only way back.
+const LAY = window.PMOSLayout;
+const NARROW = window.matchMedia('(max-width:1100px)');
+const PHONE = window.matchMedia('(max-width:760px)');
+
+// Start from the stock four so the control is populated and `review` — today's arrangement — is
+// on screen before the server's copy arrives. loadLayouts() replaces this per workspace.
+state.layouts = LAY.stockLayouts();
+state.layoutId = LAY.DEFAULT_ID;
+
+function curLayout() {
+  return state.layouts.find((l) => l.id === state.layoutId) || state.layouts[0] || LAY.stockLayout(LAY.DEFAULT_ID);
 }
-function showRail() { if ($('bodyGrid').classList.contains('rail-off')) toggleRail(true); }
-function toggleRail(on) {
-  const off = on === undefined ? !$('bodyGrid').classList.contains('rail-off') : !on;
-  $('bodyGrid').classList.toggle('rail-off', off);
-  $('railBtn').setAttribute('aria-pressed', String(off));
-  store.set('rail', off ? 'off' : 'on');
+
+// Write the arrangement into the DOM. Custom properties, never direct grid declarations — a
+// direct one would outrank the ≤760px media query and take the phone's switcher with it (R9).
+function applyLayout() {
+  const l = curLayout();
+  const body = $('bodyGrid');
+  // Below 1100px the reader floats over the terminal instead of squeezing it, so its track comes
+  // OUT of the template; below that again the phone's own system owns the whole thing.
+  const float = NARROW.matches && !PHONE.matches && (l.reader === 'left' || l.reader === 'right');
+  const eff = float ? Object.assign({}, l, { reader: 'off' }) : l;
+  const g = LAY.gridFor(eff);
+  body.style.setProperty('--lay-cols', g.columns);
+  body.style.setProperty('--lay-rows', g.rows);
+  body.style.setProperty('--lay-areas', g.areas);
+  body.dataset.side = l.side;
+  body.dataset.reader = float ? l.reader : l.reader;   // the pane still exists; it just floats
+  body.dataset.float = float ? 'on' : 'off';
+  if (float) body.style.setProperty('--lay-areas', g.areas);
+
+  // folds
+  paintFold('paneWs', 'wsFold', l.folds.ws);
+  paintFold('paneSess', 'sessFold', l.folds.sess);
+  paintFold('paneLib', 'libFold', l.folds.lib);
+  paintFold('paneDoc', 'docFold', l.folds.doc);
+
+  // split is a desktop arrangement; below 1100px two groups are two unusable terminals (R9)
+  applySplit(l.split === 'on' && !NARROW.matches);
+
+  $('layName').textContent = l.name;
+  renderLayoutMenu();
   refit();
 }
-// restore the layout the PM last chose
-foldPane('lib', store.get('fold-lib') !== 'off');
-foldPane('doc', store.get('fold-doc') !== 'off');
-if (store.get('rail') === 'off') toggleRail(false);
-{ const s = store.get('libsplit'); if (s) document.documentElement.style.setProperty('--libsplit', s); }
-{ const w = store.get('railw'); if (w) document.documentElement.style.setProperty('--rail-w', w); }
+function paintFold(paneId, btnId, open) {
+  const pane = $(paneId), btn = $(btnId);
+  if (!pane) return;
+  pane.dataset.fold = open ? 'on' : 'off';
+  if (btn) btn.setAttribute('aria-expanded', String(open));
+}
+
+// Mutate the current layout and keep it. Every adjustment path funnels through here, so there is
+// exactly one place that decides what "kept" means — and exactly one write-back to debounce.
+function tweak(patch) {
+  const l = curLayout();
+  Object.assign(l, patch);
+  l.lastUsedAt = Date.now();
+  applyLayout();
+  saveLayouts();
+}
+function selectLayout(id) {
+  if (!state.layouts.some((l) => l.id === id)) return;
+  state.layoutId = id;
+  const l = curLayout();
+  l.lastUsedAt = Date.now();
+  applyLayout();
+  saveLayouts();
+}
+// R4's escape hatch. Auto-keep is destructive: without this a flattened `focus` is gone for good.
+function restoreLayout(id) {
+  const fresh = LAY.stockLayout(id);
+  if (!fresh) return;
+  const i = state.layouts.findIndex((l) => l.id === id);
+  if (i < 0) return;
+  fresh.lastUsedAt = Date.now();
+  state.layouts[i] = fresh;
+  applyLayout();
+  saveLayouts();
+}
+
+// ── persistence: per workspace, server-side (R7) ──
+async function loadLayouts() {
+  let doc = null;
+  try {
+    const r = await fetch('/api/layouts?ws=' + encodeURIComponent(state.wsId || ''));
+    doc = await r.json();
+  } catch { doc = null; }
+  if (!doc || !doc.ok || !Array.isArray(doc.layouts) || !doc.layouts.length) {
+    // R8 — a workspace with nothing stored inherits whatever the PM had already tuned by hand
+    // in the pre-feature client, so the upgrade never costs them their rail width.
+    const legacy = {};
+    for (const k of ['rail', 'railw', 'libsplit', 'fold-lib', 'fold-doc']) legacy[k] = store.get(k);
+    const migrated = LAY.migrateLegacy(legacy);
+    state.layouts = migrated.layouts;
+    state.layoutId = migrated.currentId;
+    applyLayout();
+    saveLayouts();          // write it once so the migration is not re-run every load
+    return;
+  }
+  const clean = LAY.sanitize(doc);
+  state.layouts = clean.layouts;
+  state.layoutId = clean.currentId;
+  applyLayout();
+}
+function layoutBody() {
+  return JSON.stringify({ ws: state.wsId, layouts: state.layouts, currentId: state.layoutId });
+}
+function saveLayouts() {
+  state.layoutDirty = true;
+  clearTimeout(state.layoutSaveT);
+  state.layoutSaveT = setTimeout(async () => {
+    if (!state.wsId) return;
+    const body = layoutBody();
+    try {
+      await fetch('/api/layouts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
+      state.layoutDirty = false;
+    } catch {}   // a failed write costs the arrangement, never the session — stay quiet
+  }, 200);
+}
+// A debounce alone loses the write when the PM picks a layout and immediately closes the tab —
+// measured, not theorised: the browser suite caught exactly that. sendBeacon is the one send that
+// survives teardown, so the last thing they chose is the thing that comes back.
+function flushLayouts() {
+  if (!state.layoutDirty || !state.wsId) return;
+  clearTimeout(state.layoutSaveT);
+  state.layoutDirty = false;
+  try {
+    const blob = new Blob([layoutBody()], { type: 'application/json' });
+    if (!navigator.sendBeacon || !navigator.sendBeacon('/api/layouts', blob)) {
+      fetch('/api/layouts', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: layoutBody(), keepalive: true });
+    }
+  } catch {}
+}
+window.addEventListener('pagehide', flushLayouts);
+document.addEventListener('visibilitychange', () => { if (document.hidden) flushLayouts(); });
+
+// ── the layout menu ──
+function layoutWire(l) {
+  // a wireframe of the arrangement: the name alone does not say what you get
+  const cells = [];
+  if (l.side === 'left') cells.push(1);
+  if (l.reader === 'left') cells.push(3);
+  cells.push(l.split === 'on' ? 5 : 4);
+  if (l.reader === 'right') cells.push(3);
+  if (l.side === 'right') cells.push(1);
+  const rows = l.reader === 'bottom' ? '<i style="flex:1"></i>' : '';
+  return `<span class="lay-mini" aria-hidden="true">${cells.map((w) => `<span style="flex:${w}"></span>`).join('')}${rows}</span>`;
+}
+function renderLayoutMenu() {
+  const list = $('layList');
+  if (!list) return;
+  list.innerHTML = state.layouts.map((l) => {
+    const on = l.id === state.layoutId;
+    const stock = LAY.isStock(l.id);
+    return `<div class="lay-line" data-id="${esc(l.id)}" style="display:flex;gap:2px;align-items:center">
+      <button class="lay-row" data-pick="${esc(l.id)}" aria-current="${on}"
+        aria-label="${esc(l.name)} layout">${layoutWire(l)}<span class="nm">${esc(l.name)}</span>
+        ${l.key ? `<span class="kbd">⌃${l.key}</span>` : ''}</button>
+      ${stock
+        ? `<button class="lay-act" data-restore="${esc(l.id)}" title="Restore ${esc(l.name)} to its default arrangement" aria-label="Restore ${esc(l.name)}">↺</button>`
+        : `<button class="lay-act" data-rename="${esc(l.id)}" title="Rename" aria-label="Rename ${esc(l.name)}">✎</button>
+           <button class="lay-act del" data-del="${esc(l.id)}" title="Delete" aria-label="Delete ${esc(l.name)}">✕</button>`}
+    </div>`;
+  }).join('') + (NARROW.matches
+    ? '<p class="lay-narrow">This window is too narrow for two terminal groups — split is off until it is wider.</p>'
+    : '');
+  list.querySelectorAll('[data-pick]').forEach((b) => b.onclick = () => { selectLayout(b.dataset.pick); closeLayMenu(); });
+  list.querySelectorAll('[data-restore]').forEach((b) => b.onclick = () => restoreLayout(b.dataset.restore));
+  list.querySelectorAll('[data-del]').forEach((b) => b.onclick = () => {
+    state.layouts = state.layouts.filter((l) => l.id !== b.dataset.del);
+    if (state.layoutId === b.dataset.del) state.layoutId = LAY.DEFAULT_ID;
+    applyLayout(); saveLayouts();
+  });
+  list.querySelectorAll('[data-rename]').forEach((b) => b.onclick = () => {
+    const l = state.layouts.find((x) => x.id === b.dataset.rename);
+    if (!l) return;
+    openLayNew(l.name, l.id);
+  });
+  const w = state.workspaces.find((x) => x.id === state.wsId);
+  if ($('layScope')) $('layScope').textContent = w ? w.name : 'this repo';
+}
+function openLayMenu() { $('layMenu').hidden = false; $('layBtn').setAttribute('aria-expanded', 'true'); renderLayoutMenu(); }
+function closeLayMenu() { $('layMenu').hidden = true; $('layBtn').setAttribute('aria-expanded', 'false'); closeLayNew(); }
+function openLayNew(value, renameId) {
+  $('layNewForm').hidden = false;
+  $('layNewForm').dataset.rename = renameId || '';
+  $('layNewName').value = value || '';
+  $('layNewName').focus(); $('layNewName').select();
+}
+function closeLayNew() { $('layNewForm').hidden = true; $('layNewForm').dataset.rename = ''; $('layNewName').value = ''; }
+$('layBtn').onclick = () => ($('layMenu').hidden ? openLayMenu() : closeLayMenu());
+$('layNewBtn').onclick = () => openLayNew(newLayoutName());
+$('layNewCancel').onclick = () => closeLayNew();
+$('layNewForm').onsubmit = (e) => {
+  e.preventDefault();
+  const name = $('layNewName').value.trim().slice(0, 40);
+  if (!name) return;
+  const renameId = $('layNewForm').dataset.rename;
+  if (renameId) {
+    const l = state.layouts.find((x) => x.id === renameId);
+    if (l && !LAY.isStock(l.id)) l.name = name;
+  } else {
+    const l = Object.assign({}, curLayout(), { id: 'c' + Date.now().toString(36), name, key: null, lastUsedAt: Date.now() });
+    l.folds = Object.assign({}, curLayout().folds);
+    state.layouts.push(l);
+    state.layoutId = l.id;
+  }
+  closeLayNew(); applyLayout(); saveLayouts();
+};
+function newLayoutName() {
+  const base = curLayout().name + ' (mine)';
+  let n = base, i = 2;
+  while (state.layouts.some((l) => l.name === n)) n = base + ' ' + (i++);
+  return n;
+}
+
+// ── folds: both columns, same behaviour (R11) ──
+function foldPane(which, open) {
+  const map = { doc: 'paneDoc', lib: 'paneLib', ws: 'paneWs', sess: 'paneSess' };
+  if (!map[which]) return;
+  const l = curLayout();
+  const folds = Object.assign({}, l.folds);
+  folds[which] = open;
+  tweak({ folds });
+}
+function showRail() { if (curLayout().reader === 'off') tweak({ reader: 'right' }); }
 
 $('libFold').onclick = () => foldPane('lib', $('paneLib').dataset.fold === 'off');
 $('docFold').onclick = () => foldPane('doc', $('paneDoc').dataset.fold === 'off');
-$('railBtn').onclick = () => toggleRail();
+$('wsFold').onclick = () => foldPane('ws', $('paneWs').dataset.fold === 'off');
+$('sessFold').onclick = () => foldPane('sess', $('paneSess').dataset.fold === 'off');
 
-// drag the rail's left edge — the reader is where PRDs and rubrics are actually read, and a
-// fixed narrow column makes a table of weighted dimensions unreadable
-(() => {
-  const grip = $('railGrip');
+// ── the edges: drag a column's outer edge to resize it. Keeps to the layout, like everything
+// else — a width the PM chose is part of the arrangement, not a separate preference. ──
+function wireEdge(el) {
+  if (!el) return;
+  const which = el.dataset.edge;
   let dragging = false;
-  const apply = (clientX) => {
-    const w = Math.min(Math.max(window.innerWidth - clientX, 280), Math.min(900, window.innerWidth - 420));
-    const v = Math.round(w) + 'px';
-    document.documentElement.style.setProperty('--rail-w', v);
-    store.set('railw', v);
+  const applyPx = (px) => {
+    const l = curLayout();
+    if (which === 'side') tweak({ sideW: Math.round(Math.min(Math.max(px, LAY.SIDE_MIN), LAY.SIDE_MAX)) });
+    else tweak({ readW: Math.round(Math.min(Math.max(px, LAY.READ_MIN), Math.min(LAY.READ_MAX, window.innerWidth - 360))) });
+    void l;
   };
-  grip.addEventListener('pointerdown', (e) => { dragging = true; grip.setPointerCapture(e.pointerId); e.preventDefault(); });
-  grip.addEventListener('pointermove', (e) => { if (dragging) apply(e.clientX); });
-  grip.addEventListener('pointerup', (e) => { dragging = false; try { grip.releasePointerCapture(e.pointerId); } catch {} refit(); });
-  grip.addEventListener('keydown', (e) => {
+  const fromPointer = (clientX) => {
+    const l = curLayout();
+    const r = $('bodyGrid').getBoundingClientRect();
+    if (which === 'side') return l.side === 'right' ? r.right - clientX : clientX - r.left;
+    return l.reader === 'left' ? clientX - r.left : r.right - clientX;
+  };
+  el.addEventListener('pointerdown', (e) => { dragging = true; el.classList.add('on'); el.setPointerCapture(e.pointerId); e.preventDefault(); });
+  el.addEventListener('pointermove', (e) => { if (dragging) applyPx(fromPointer(e.clientX)); });
+  el.addEventListener('pointerup', (e) => { dragging = false; el.classList.remove('on'); try { el.releasePointerCapture(e.pointerId); } catch {} refit(); });
+  el.addEventListener('keydown', (e) => {
     if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
     e.preventDefault();
-    const cur = $('rail').getBoundingClientRect().width;
-    apply(window.innerWidth - (cur + (e.key === 'ArrowLeft' ? 24 : -24)));
+    const l = curLayout();
+    const cur = which === 'side' ? l.sideW : l.readW;
+    const grow = which === 'side' ? (l.side === 'right' ? e.key === 'ArrowLeft' : e.key === 'ArrowRight')
+      : (l.reader === 'left' ? e.key === 'ArrowRight' : e.key === 'ArrowLeft');
+    applyPx(cur + (grow ? 24 : -24));
     refit();
   });
+}
+wireEdge($('railGrip'));
+wireEdge($('sideEdge'));
+
+// ── the grips: drag a pane to a new home. An ACCELERATOR — every position a drop zone offers is
+// also reachable from the layout menu, so a pointer is never required to arrange the window. ──
+(() => {
+  const body = $('bodyGrid');
+  let drag = null, ghost = null;
+  const zones = () => [...document.querySelectorAll('.dz')];
+  function allowed(pane, z) { return !(pane === 'side' && z === 'bottom'); }  // the sidebar has no bottom home
+  function hit(e) {
+    let found = null;
+    zones().forEach((d) => {
+      const r = d.getBoundingClientRect();
+      const inside = e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom;
+      const ok = inside && allowed(drag, d.dataset.z);
+      d.classList.toggle('hot', ok);
+      if (ok) found = d.dataset.z;
+    });
+    return found;
+  }
+  function move(e) {
+    if (!drag) return;
+    if (ghost) { ghost.style.left = (e.clientX + 12) + 'px'; ghost.style.top = (e.clientY + 12) + 'px'; }
+    hit(e);
+  }
+  function end(e) {
+    if (!drag) return;
+    const z = hit(e);
+    if (z) tweak(drag === 'side' ? { side: z === 'bottom' ? curLayout().side : z } : { reader: z });
+    body.classList.remove('dragging');
+    zones().forEach((d) => { d.classList.remove('hot'); d.classList.remove('no'); });
+    if (ghost) { ghost.remove(); ghost = null; }
+    drag = null;
+  }
+  document.querySelectorAll('.cap .grip').forEach((g) => {
+    g.addEventListener('pointerdown', (e) => {
+      if (PHONE.matches) return;                 // the switcher owns layout on touch
+      e.preventDefault();
+      drag = g.dataset.pane;
+      body.classList.add('dragging');
+      zones().forEach((d) => d.classList.toggle('no', !allowed(drag, d.dataset.z)));
+      ghost = document.createElement('div');
+      ghost.className = 'laghost';
+      ghost.textContent = drag === 'side' ? 'workspaces · running agents' : 'library · document';
+      document.body.appendChild(ghost);
+      move(e);
+      try { g.setPointerCapture(e.pointerId); } catch {}
+    });
+    g.addEventListener('pointermove', move);
+    g.addEventListener('pointerup', end);
+    // keyboard: the grip is a button that opens the same menu the drag reaches (R12)
+    g.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openLayMenu(); $('layBtn').focus(); }
+    });
+  });
 })();
 
+// re-apply when the window crosses a breakpoint: the float rule and the split rule are both
+// width-dependent, and a template computed for the other side of the line clips the terminal
+[NARROW, PHONE].forEach((mq) => {
+  const on = () => { applyLayout(); };
+  if (mq.addEventListener) mq.addEventListener('change', on); else if (mq.addListener) mq.addListener(on);
+});
+
+// the empty second group's own controls — a split with nothing in it offers the next step
+$('newHere1').onclick = () => { state.focusG = 1; openNewForm(); };
+$('unsplitBtn').onclick = () => tweak({ split: 'off' });
+// clicking anywhere in a group focuses it, so ⌘J's send and F2's rename act on what you last touched
+[0, 1].forEach((gi) => $(GROUP_HOST[gi]).addEventListener('pointerdown', () => {
+  if (state.focusG === gi) return;
+  state.focusG = gi; syncActive(); paintGroups();
+}));
+// a click outside the layout menu closes it — it is a popover, not a mode
+document.addEventListener('pointerdown', (e) => {
+  if ($('layMenu').hidden) return;
+  if ($('layMenu').contains(e.target) || $('layBtn').contains(e.target)) return;
+  closeLayMenu();
+}, true);
+
+applyLayout();     // paint the default arrangement before the server's layouts arrive
+
+// the library/document divider is INSIDE the reader, not part of the arrangement — it stays a
+// client preference like the theme, and keeps its original storage
+{ const s = store.get('libsplit'); if (s) document.documentElement.style.setProperty('--libsplit', s); }
+
 // drag the divider between the library and the document
 (() => {
   const split = $('railSplit');
@@ -1062,7 +1589,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 +1597,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 +1605,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 +1635,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 = '';
@@ -1197,6 +1821,11 @@ const SURFACES = [
   { name: 'needs', label: 'needs you', phase: 'deliver', console: true },
   { name: 'radar', label: 'radar', phase: 'measure', console: true },
   { name: 'metrics', label: 'metrics', phase: 'measure', console: true },
+  // The summoned document review (workspace-review-and-edit). Summoned like every surface here and
+  // never resident — nothing reviews the PM's documents until they ask. The only INTERACTIVE surface:
+  // each finding is disposed of by Apply / Edit / Dismiss, and each disposition writes a correction
+  // record. Whether an Apply control exists at all is decided by the finding contract, never here.
+  { name: 'review', label: 'review', phase: 'deliver', review: true },
 ];
 const SURFACE_BY_NAME = {}; SURFACES.forEach((v) => { SURFACE_BY_NAME[v.name] = v; });
 const SF_STAT = { planning: ['○', 'planning'], building: ['◐', 'building'], blocked: ['◆', 'blocked'], landed: ['▲', 'landed'] };
@@ -1213,15 +1842,18 @@ async function openSurface(name) {
   $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name)}<div class="sf-body"><div class="sf-skel"><i></i><i></i><i></i></div></div></div>`;
   wireSurface();
   const meta = SURFACE_BY_NAME[name] || {};
-  const endpoint = meta.console
-    ? `/api/console?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`
-    : `/api/surface?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`;
+  const endpoint = meta.review
+    ? `/api/review?ws=${encodeURIComponent(state.wsId || '')}`
+    : meta.console
+      ? `/api/console?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`
+      : `/api/surface?name=${encodeURIComponent(name)}&ws=${encodeURIComponent(state.wsId || '')}`;
   try {
     const r = await fetch(endpoint);
     const payload = await r.json();
-    const body = meta.console ? consoleBody(name, payload) : surfaceBody(name, payload);
+    const body = meta.review ? reviewBody(payload) : meta.console ? consoleBody(name, payload) : surfaceBody(name, payload);
     const okFlag = payload.ok !== false;
     $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name, okFlag)}<div class="sf-body">${body}</div></div>`;
+    if (meta.review) { state.review = payload; wireReview(); }
   } catch {
     // A failed FETCH is a broken read — render RED, never a calm "nothing here" (honesty by construction).
     $('docBody').innerHTML = `<div class="sf-wrap">${sfHead(name, false)}<div class="sf-body">${csError(name, 'could not reach the workspace server to build this surface')}</div></div>`;
@@ -1247,6 +1879,138 @@ function wireSurface() {
   document.querySelectorAll('[data-open-surface]').forEach((b) => b.onclick = () => openSurface(b.dataset.openSurface));
   $('docBody').querySelectorAll('.sf-art[data-doc]').forEach((b) => b.onclick = () => openDoc(b.dataset.doc));
 }
+// ── the summoned review (workspace-review-and-edit) ───────────────────────────────────────────
+// Renders findings in the quiet register the PM validated on the prototype: no cards, no severity
+// colours, no taxonomy headers, no explanation of its own guardrails. Each finding is a title and a
+// source line; the argument and the actions appear on expansion. Detail is AVAILABLE, not ambient.
+//
+// The load-bearing line is `f.applyable`. It comes from the SERVER, which asks finding-contract.js —
+// the client never re-derives it. A withheld finding renders no Apply control at all: the missing
+// button IS the guard (R7), and a disabled-but-present button would be the failure it exists to stop.
+function reviewBody(p) {
+  if (!p || p.ok === false) {
+    return csError('review', (p && p.error) || 'the review could not be read')
+      + (p && p.errors ? `<ul class="rv-errs">${p.errors.map((e) => `<li>${esc(e)}</li>`).join('')}</ul>` : '');
+  }
+  if (p.empty) {
+    return `<div class="rv-empty"><p>No review filed yet.</p>
+      <p class="rv-dim">Run the <b>Review documents</b> skill on the documents you want read.
+      Nothing reviews them until you ask.</p></div>`;
+  }
+  const open = p.findings.filter((f) => !f.settled);
+  const lede = open.length === 0
+    ? 'Nothing here that these documents cannot already tell you about themselves.'
+    : `${open.length} thing${open.length === 1 ? '' : 's'} ${open.length === 1 ? 'this document cannot' : 'these documents cannot'} tell you about ${open.length === 1 ? 'itself' : 'themselves'}.`;
+  return `<div class="rv">
+    <div class="rv-lede">${esc(lede)}</div>
+    <div class="rv-sub">Read ${p.read.map((r) => `<span class="mono">${esc(r)}</span>`).join(', ')}.</div>
+    ${p.findings.map((f, i) => rvFinding(f, i)).join('')}
+    <div class="rv-tail">Read ${p.read.length} document${p.read.length === 1 ? '' : 's'}. <b>Nothing written.</b></div>
+  </div>`;
+}
+function rvFinding(f, i) {
+  const ev = (f.evidence || []).map((e) => `${e.file}:${e.line}`).join(' · ');
+  // Three states, and only one of them offers a write. `settled` is terminal for this review.
+  const acts = f.settled
+    ? `<span class="rv-only">${esc(f.settled === 'dismiss' ? 'Dismissed.' : f.settled === 'edit' ? 'Edited and applied.' : 'Applied.')}</span>`
+    : f.applyable
+      ? `<button data-rv-apply="${i}">Apply</button><button data-rv-edit="${i}">Edit</button><button class="q" data-rv-dismiss="${i}">Dismiss</button>`
+      : `<span class="rv-only">${esc(f.withheld ? 'Yours to settle.' : 'Nothing to apply.')}</span><button class="q" data-rv-dismiss="${i}">Dismiss</button>`;
+  return `<div class="rv-f${f.settled ? ' rv-done' : ''}${f.applyable ? '' : ' rv-quiet'}" data-rv="${i}">
+    <div class="rv-h">${esc(f.title)}</div>
+    <div class="rv-src">${esc(ev || f.file)}</div>
+    <div class="rv-d">
+      <p>${esc(f.argument)}</p>
+      ${f.withheld_reason ? `<p class="rv-why">${esc(f.withheld_reason)}</p>` : ''}
+      <div class="rv-acts">${acts}</div>
+    </div>
+    <div class="rv-ed" data-rv-edbox="${i}"></div>
+  </div>`;
+}
+// The edit surface: opens IN PLACE under the finding — no modal, no mode switch, no navigation.
+// Gutter change bars are the VS Code cue; the replaced lines sit struck through above the new ones.
+// Cancel needs no write path at all — it just closes, which is the whole of "Cancel writes nothing".
+function rvEditor(f, i) {
+  const before = (f.proposal && f.proposal.before) || '';
+  const after = (f.proposal && f.proposal.after) || '';
+  const nl = (s) => (s ? s.split('\n').length : 0);
+  return `<div class="rv-edfile"><span class="mono">${esc(f.file)}</span>
+      <span class="rv-n"><b>+${nl(after)}</b> <i>−${nl(before)}</i></span></div>
+    <div class="rv-code">
+      ${before.split('\n').map((l) => `<div class="rv-l was"><span class="g"></span><span class="t">${esc(l)}</span></div>`).join('')}
+    </div>
+    <textarea class="rv-ta" data-rv-ta="${i}" spellcheck="false" rows="${Math.min(12, Math.max(3, nl(after) + 1))}">${esc(after)}</textarea>
+    <div class="rv-acts">
+      <button data-rv-save="${i}">Apply</button>
+      <button class="q" data-rv-cancel="${i}">Cancel</button>
+      <span class="rv-only">You are editing the change, not the file.</span>
+    </div>`;
+}
+function wireReview() {
+  const rv = state.review || {};
+  const F = (n) => (rv.findings || [])[Number(n)];
+  const box = (n) => $('docBody').querySelector(`[data-rv-edbox="${n}"]`);
+  const card = (n) => $('docBody').querySelector(`[data-rv="${n}"]`);
+
+  $('docBody').querySelectorAll('.rv-f').forEach((el) => {
+    el.addEventListener('click', (e) => {
+      if (e.target.closest('button') || e.target.closest('textarea')) return;
+      if (el.dataset.editing === '1') return;                 // never collapse an open editor by clicking it
+      el.classList.toggle('on');
+    });
+  });
+  $('docBody').querySelectorAll('[data-rv-edit]').forEach((b) => b.onclick = () => {
+    const n = b.dataset.rvEdit;
+    box(n).innerHTML = rvEditor(F(n), n);
+    card(n).dataset.editing = '1';
+    wireReview();                                             // re-wire the freshly rendered controls
+    const ta = $('docBody').querySelector(`[data-rv-ta="${n}"]`); if (ta) ta.focus();
+  });
+  $('docBody').querySelectorAll('[data-rv-cancel]').forEach((b) => b.onclick = () => {
+    const n = b.dataset.rvCancel;
+    box(n).innerHTML = ''; card(n).dataset.editing = '0';     // closing IS the whole of "writes nothing"
+  });
+  $('docBody').querySelectorAll('[data-rv-apply]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvApply), 'apply'));
+  $('docBody').querySelectorAll('[data-rv-dismiss]').forEach((b) => b.onclick = () => rvDispose(F(b.dataset.rvDismiss), 'dismiss'));
+  $('docBody').querySelectorAll('[data-rv-save]').forEach((b) => b.onclick = () => {
+    const n = b.dataset.rvSave;
+    const ta = $('docBody').querySelector(`[data-rv-ta="${n}"]`);
+    rvDispose(F(n), 'edit', ta ? ta.value : '');
+  });
+}
+async function rvDispose(f, disposition, pmText) {
+  if (!f) return;
+  const rv = state.review || {};
+  // The client sends back the exact text it rendered; the server re-derives the diff and refuses if
+  // they differ (sprint criterion 4). That is what makes a stale or tampered client safe.
+  let renderedAfter = null;
+  if (disposition !== 'dismiss') {
+    try {
+      const r = await fetch(`/api/doc?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(f.file)}`);
+      const cur = await r.text();
+      const prop = disposition === 'edit' ? { before: f.proposal.before, after: pmText } : f.proposal;
+      renderedAfter = window.ApplyChange.applyChange(cur, prop).text;
+    } catch { /* leave null — the server refuses rather than guessing */ }
+  }
+  const body = {
+    ws: state.wsId, disposition, finding: f, rendered_after: renderedAfter,
+    pm_text: disposition === 'edit' ? pmText : undefined,
+    reason: disposition === 'edit' ? 'incomplete' : undefined,   // TODO: the reason tap (PRD open q2)
+    run_id: rv.id, initiative_id: 'workspace-review-and-edit',
+  };
+  let out = {};
+  try { out = await (await fetch('/api/review/dispose', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) })).json(); }
+  catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  if (!out.ok) { rvSay(out.error || 'refused', out.detail); return; }
+  openSurface('review');                                       // re-read: the record is the source of truth
+}
+function rvSay(msg, detail) {
+  const el = document.createElement('div');
+  el.className = 'rv-say';
+  el.textContent = detail ? `${msg} — ${detail}` : msg;
+  $('docBody').querySelector('.rv') ? $('docBody').querySelector('.rv').prepend(el) : $('docBody').prepend(el);
+}
+
 function surfaceBody(name, payload) {
   if (!payload || !payload.ok) return sfCantProduce(name, payload && payload.contract);
   const s = payload.surface || {};
@@ -1657,9 +2421,18 @@ 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; }
+  // ⌃1–⌃4 — the named layouts, in one act. Ctrl only (⌘1-4 are the browser's tab switches).
+  if (e.ctrlKey && !e.metaKey && !e.altKey && /^[1-9]$/.test(e.key)) {
+    const l = state.layouts.find((x) => x.key === Number(e.key));
+    if (l) { e.preventDefault(); e.stopPropagation(); selectLayout(l.id); return; }
+  }
   if (e.key === 'Escape') {
-    if ($('palette').style.display === 'grid') { e.stopPropagation(); closePalette(); }
+    if (!$('layMenu').hidden) { e.stopPropagation(); closeLayMenu(); }
+    else if ($('palette').style.display === 'grid') { e.stopPropagation(); closePalette(); }
     else if ($('fsPicker').style.display === 'grid') { e.stopPropagation(); closeFsPicker(); }
     else if (state.renaming) { e.stopPropagation(); cancelRename(); renderSessions(); }
     else if (!$('newForm').hidden) closeNewForm();