create-pmos 0.8.0 → 0.10.0

package/workspace/public/app.js

@@ -28,6 +28,9 @@ const state = {
   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
+  scratchKey: null,            // whose scratchpad is on screen — 'session:<id>' or 'ws:<id>'
+  scratchT: null,              // debounce handle for the pad's write-back (like layoutSaveT)
+  scratchPending: null,        // {session,ws,text} typed but not yet written — flushed on a switch
   terms: new Map(),            // id -> {term, fit, el, g}
   attached: new Set(),         // ids attached ON THIS CONNECTION (cleared on reconnect)
   needs: [],
@@ -38,6 +41,7 @@ const state = {
   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
+  worktrees: [],               // the selected workspace's repo's working trees, with removability
   newBranchMode: false,        // new-session form: creating a branch vs picking an existing one
   sessSig: null,               // structural fingerprint of the last session push (see structSig)
 };
@@ -151,8 +155,13 @@ function handle(m) {
     // 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(); }
+    // a checkout changed the repo's branch — refresh the chip if it's the workspace on screen,
+    // and the picker too when the form is open (a stale branch list is how a PM picks wrong)
+    if (m.ws === state.wsId) { state.branch = m; renderBranch(); loadWorktrees(); if (!$('newForm').hidden) fillBranchPicker(); }
+  } else if (m.t === 'notice') {
+    // something non-fatal but worth knowing: where a worktree landed, or that a branch was
+    // ignored because the workspace has no git. Never a blocked session, never a silent one.
+    flash(m.notice, 12000);
   } 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');
@@ -169,6 +178,9 @@ async function loadBranch() {
   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();
+  // Refill the open form ONLY while the PM has not chosen anything yet — a refresh landing a beat
+  // after a quick selection must never silently reset it back to "stay on current".
+  if (!$('newForm').hidden && !$('newBranch').value && !state.newBranchMode) fillBranchPicker();
 }
 function renderBranch() {
   const el = $('branchChip'); if (!el) return;
@@ -176,8 +188,12 @@ function renderBranch() {
   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)';
+  // `⑂` marks a workspace that IS an isolated worktree — the PM should be able to see at a glance
+  // that this window's branch is its own, not the shared one.
+  el.textContent = (b.linked ? '⑂ ' : '⎇ ') + label + (b.dirty ? '*' : '');
+  const where = b.linked ? 'this workspace has its own working tree — switching here moves only its sessions'
+    : 'shared working tree — switching here moves every session in this repo';
+  el.title = (b.dirty ? 'uncommitted changes · ' : '') + where;
   el.classList.toggle('dirty', !!b.dirty);
 }
 
@@ -196,8 +212,10 @@ async function selectWorkspace(id, opts = {}) {
   const pick = mine.find((s) => s.id === remembered) || mine.find((s) => s.state !== 'exited') || mine[0];
   if (pick) selectSession(pick.id); else clearActive();
   // 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()]);
+  // the scratchpad follows the ACTIVE TAB, and selectSession/clearActive above have already
+  // settled which that is — syncActive() reloaded it, so there is nothing to do here
+  if (changed) { state.branch = null; renderBranch(); state.worktrees = []; renderWorktrees(); loadLayouts(); }
+  await Promise.all([loadLibrary(), loadNeeds(), loadBranch(), loadWorktrees()]);
 }
 function renderWorkspaces() {
   const html = state.workspaces.map((w) => {
@@ -235,16 +253,21 @@ async function addWorkspace(root) {
     return true;
   } catch { flash('could not reach the server'); return false; }
 }
-function flash(msg) {
+// `ms` is longer for messages carrying something to READ — a worktree's path is useless if it
+// vanishes before the PM can copy it out.
+function flash(msg, ms = 4000) {
   const el = $('wsFoot'); const prev = el.textContent;
   el.textContent = msg;
-  setTimeout(() => { el.textContent = prev; }, 4000);
+  setTimeout(() => { el.textContent = prev; }, ms);
 }
 
-const GLYPH = { working: '●', quiet: '◼', blocked: '◆', done: '✓', idle: '—', exited: '○' };
-// 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' };
+// The glyph and the word both come from the SHARED join module (/lib/session-state.js), never
+// re-typed here. `quiet` still means no output for a while and still NEVER means "waiting on you"
+// (harness-tower R1) — the stronger words exist only where the transcript corroborates the
+// silence, which is a different cell of the table, not a relabelling of this one.
+const SS = window.PMOSSessionState;
+const GLYPH = SS.GLYPH;
+const STATE_WORD = SS.WORD;
 // 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
@@ -257,37 +280,42 @@ function shortDur(ms) {
   const min = Math.round(sec / 60);
   return min < 60 ? min + 'm' : Math.round(min / 60) + 'h';
 }
-// Derived client-side too, so a row can go quiet WITHOUT a server push. The server only pushes
-// on lifecycle events; a periodic full re-render would destroy an open drill-in and the rename
-// input (the defect the pre-promotion grilling caught), so the ticker below repaints chips only.
-function shownState(s) {
-  if (s.state === 'exited') return { shown: 'exited', quietMs: null };
-  if (!s.lastOutputAt) return { shown: 'working', quietMs: null };
+// The CADENCE clock, derived client-side too so a row can change WITHOUT a server push. The server
+// only pushes on lifecycle events plus the liveness heartbeat; a periodic full re-render would
+// destroy an open drill-in and the rename input (the defect the pre-promotion grilling caught), so
+// the ticker below repaints chips only. This is one of the join's two inputs — never the answer.
+function cadenceState(s) {
+  if (s.state === 'exited') return { cadence: 'exited', quietMs: null };
+  if (!s.lastOutputAt) return { cadence: 'working', quietMs: null };
   const q = Math.max(0, Date.now() - s.lastOutputAt);
-  return q >= QUIET_AFTER_MS ? { shown: 'quiet', quietMs: q } : { shown: 'working', quietMs: q };
-}
-// The open call's AGE, appended to `working` only. `working · Bash 4m` is the first honest signal
-// for HUNG the workspace has — a call open past a glance is a call that may be stuck. The honesty
-// bound is structural, not a check bolted on: age rides `shown === 'working'`, and shownState only
-// returns 'working' while lastOutputAt is recent, so a crashed/interrupted session whose dangling
-// tool_use is a permanent phantom reads `quiet`/`exited` and NEVER a live age. Age without liveness
-// is refused. `sinceTs` comes from the transcript record; we tick it client-side like the quiet clock.
-function callAge(s, shown) {
-  if (shown !== 'working') return '';
+  return q >= QUIET_AFTER_MS ? { cadence: 'quiet', quietMs: q } : { cadence: 'working', quietMs: q };
+}
+// The open call's verb + AGE. `working · Bash 4m` is the first honest signal for HUNG the workspace
+// has; the weak claim's `· Bash 6m` is the same fact once the bytes stop, and is the whole content
+// of that claim. WHICH states may carry it is the shared module's call (CARRIES_CALL_AGE), not a
+// condition re-typed here — as the words themselves are its call, never literals in this file.
+//
+// The honesty bound is structural, not a check bolted on: the age rides states that require a LIVE
+// cadence or an explicitly-suspect one, and `needs` is not among them — so a crashed session's
+// dangling tool_use (a permanent phantom) can never dress itself as a live age on the strong claim.
+// `sinceTs` comes from the transcript record; we tick it client-side like the quiet clock.
+function openCallOf(s) {
   const oc = s.hx && s.hx.openCall;
-  if (!oc || !oc.sinceTs) return '';
+  if (!oc || !oc.sinceTs) return null;
   const ms = Date.parse(oc.sinceTs);
-  if (!Number.isFinite(ms)) return '';
+  if (!Number.isFinite(ms)) return null;
   const age = Date.now() - ms;
-  if (age < 0) return '';
-  return ` · ${oc.verb} ${shortDur(age)}`;
+  if (age < 0) return null;
+  return { verb: oc.verb, ageMs: age };
 }
+// THE JOIN, client side — the same module the server uses (R6). Two inputs: the cadence clock above
+// and the transcript's answer to whose turn it is. Neither the table nor the words are duplicated
+// here; if they were, the sidebar and the server could drift into different opinions about one
+// session, which is exactly what shipping QUIET_AFTER_MS from `hello` was done to prevent.
 function stateLabel(s) {
-  const { shown, quietMs } = shownState(s);
-  const w = STATE_WORD[shown] || shown;
-  if (shown === 'quiet') return { shown, text: `${w} ${shortDur(quietMs)}` };
-  if (shown === 'working') return { shown, text: `${w}${callAge(s, shown)}` };
-  return { shown, text: w };
+  const { cadence, quietMs } = cadenceState(s);
+  const shown = SS.presented(cadence, s.hx && s.hx.turn);
+  return { shown, text: SS.label(shown, { quietMs, call: openCallOf(s), fmtDur: shortDur }) };
 }
 function renderSessions() {
   const mine = mySessions();
@@ -529,6 +557,7 @@ function syncActiveState() {
   });
   updateExitedOverlay();
   refreshScratchSend();   // the scratchpad's send button follows the active session's liveness
+  renderScratchWho();     // …and its label follows the active tab's name, including a rename
 }
 
 // ── renaming a session (R11): inline, in both surfaces, live or exited. The name chosen at
@@ -584,7 +613,7 @@ 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 syncActive() { state.active = state.groups[state.focusG].activeId; syncScratchpad(); }
 
 function ensureTerm(id, g) {
   const want = typeof g === 'number' ? g : 0;
@@ -646,7 +675,7 @@ 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.branch = null; renderBranch(); loadBranch(); loadScratchpad(); loadLayouts(); }
+  if (s.ws !== state.wsId) { state.wsId = s.ws; store.set('wsid', s.ws); renderWorkspaces(); renderSessions(); loadLibrary(); loadNeeds(); state.branch = null; renderBranch(); loadBranch(); 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);
@@ -1078,6 +1107,8 @@ function flushLayouts() {
   } catch {}
 }
 window.addEventListener('pagehide', flushLayouts);
+// a pad typed into and closed within the debounce window is still the PM's text — write it
+window.addEventListener('pagehide', () => flushScratchpad());
 document.addEventListener('visibilitychange', () => { if (document.hidden) flushLayouts(); });
 
 // ── the layout menu ──
@@ -1598,7 +1629,8 @@ 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
+  fillBranchPicker();               // paint immediately from what we already know…
+  loadBranch();                     // …then re-fetch: branches made in a terminal must show up here
   const inp = $('newName');
   setTimeout(() => { inp.focus(); inp.select(); }, 0);
 }
@@ -1606,29 +1638,148 @@ 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).
+// Populate the branch control from state.branch. A workspace with no git hides the whole control
+// and says so once, plainly — a silently missing control reads as "broken", and a PM working in a
+// tenant product repo that has no git should never be asked a branch question at all. The default
+// is always "stay on current": starting a session must never require a git decision.
 function fillBranchPicker() {
-  const wrap = $('newBranchWrap'), sel = $('newBranch');
+  const wrap = $('newBranchWrap'), sel = $('newBranch'), nogit = $('newNoGit');
   const b = state.branch;
-  if (!b || !b.ok) { wrap.hidden = true; return; }
+  if (!b || !b.ok) {
+    wrap.hidden = true;
+    // `no-git` is an ordinary folder, not a fault: one muted line, no warning colour. A real git
+    // error (unreadable HEAD, git missing) says what it was instead of pretending all is well.
+    nogit.hidden = !b || !b.code;
+    nogit.textContent = b && b.code === 'git-error'
+      ? `git could not read this folder (${b.error}) — the session starts here, with no branch applied`
+      : 'no git in this folder — nothing to branch, the session just starts here';
+    nogit.classList.toggle('warn', !!b && b.code === 'git-error');
+    return;
+  }
+  nogit.hidden = true;
   wrap.hidden = false;
   const cur = b.detached ? '' : (b.current || '');
+  // a branch checked out in another worktree cannot be checked out again — git refuses, so the
+  // picker says where it lives rather than letting the PM discover it as an error
+  const elsewhere = new Map((b.worktrees || [])
+    .filter((w) => w.branch && w.branch !== cur).map((w) => [w.branch, w.dir]));
   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((b.branches || []).map((n) => {
+      const where = elsewhere.get(n);
+      const tail = n === cur ? ' — current' : (where ? ' — open in ' + shortPath(where) : '');
+      return `<option value="${esc(n)}"${n === cur ? ' disabled' : ''}>${esc(n)}${esc(tail)}</option>`;
+    }))
     .concat([`<option value="__new__">+ new branch…</option>`]);
   sel.innerHTML = opts.join('');
   sel.value = '';
+  // Isolation protects OTHER sessions — so default it on only when there are others to protect.
+  // Alone in a workspace a plain checkout disturbs nobody and leaves no folder behind, which is
+  // what stops a directory accumulating per branch. Either way the PM can flip it.
+  $('newIsolate').checked = mySessions().some((s) => s.state !== 'exited');
   setNewBranchMode(false);
 }
+// last two segments of a path — enough to recognise, short enough for a <option> or a hint line
+function shortPath(p) { const parts = String(p).split('/').filter(Boolean); return parts.slice(-2).join('/'); }
+
+// ── worktree housekeeping (R7): isolation buys "your other sessions keep running" at the price of
+// a folder per branch. That price is only fair if the folders are visible and reclaimable from
+// here — a delete is never a guess, so a tree that is busy, dirty, or holds commits nothing else
+// holds is refused with the reason spelled out, not silently greyed. ──
+async function loadWorktrees() {
+  const id = state.wsId;
+  let r = { ok: false };
+  try { r = await (await fetch('/api/git/worktrees?ws=' + encodeURIComponent(id || ''))).json(); } catch {}
+  if (id !== state.wsId) return;
+  state.worktrees = r.ok ? (r.worktrees || []) : [];
+  renderWorktrees();
+}
+function renderWorktrees() {
+  const box = $('wtBox'); if (!box) return;
+  const list = (state.worktrees || []).filter((t) => !t.main);
+  box.hidden = list.length === 0;          // a repo with one working tree has nothing to manage
+  if (!list.length) return;
+  $('wtSummary').textContent = `⑂ ${list.length} worktree${list.length === 1 ? '' : 's'}`;
+  $('wtList').innerHTML = list.map((t) => `
+    <div class="wtrow" data-dir="${esc(t.dir)}">
+      <span class="wtb" title="${esc(t.dir)}">${esc(t.branch || 'detached')}</span>
+      <button type="button" data-rm="${esc(t.dir)}"${t.removable ? '' : ' disabled'}
+        title="${esc(t.removable ? 'Remove ' + t.dir : t.reasons.join('; '))}">remove</button>
+      ${t.removable ? '' : `<span class="wtwhy">kept — ${esc(t.reasons.join('; '))}</span>`}
+    </div>`).join('');
+  $('wtList').querySelectorAll('[data-rm]').forEach((b) => { b.onclick = () => removeWorktree(b.dataset.rm); });
+}
+async function removeWorktree(dir) {
+  // The server re-checks every hazard; this confirm exists because a folder disappearing from
+  // under the PM should be something they said yes to, not a side effect of a mis-click.
+  if (!confirm(`Remove the worktree at\n${dir}\n\nThe branch itself is kept — only the folder goes.`)) return;
+  let r = { ok: false, error: 'request failed' };
+  try {
+    r = await (await fetch('/api/git/worktrees/remove', { method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ws: state.wsId, dir }) })).json();
+  } catch {}
+  flash(r.ok ? (r.pruned ? 'cleared git’s record of a folder that was already gone' : 'worktree removed — the branch is still there')
+    : (r.error || 'the worktree was not removed'), r.ok ? 6000 : 12000);
+  loadWorktrees();
+}
+
 function setNewBranchMode(on) {
   state.newBranchMode = on;
   $('newBranchName').hidden = !on;
   if (on) setTimeout(() => $('newBranchName').focus(), 0);
+  renderBranchHint();
+}
+
+// The one line that decides whether the PM trusts this control. It changes with the choice, because
+// the three choices do genuinely different things:
+//   stay             → nothing happens to git at all
+//   isolate (default)→ the branch gets its own folder; running sessions are untouched
+//   switch this repo → every session in this repo moves, and so does every other workspace on it
+function renderBranchHint() {
+  const hint = $('newBranchHint'), iso = $('newIsolate'), isoWrap = $('newIsolateWrap');
+  const b = state.branch; if (!hint || !b || !b.ok) return;
+  const sel = $('newBranch');
+  const picked = sel.value === '__new__' ? ($('newBranchName').value.trim() || 'the new branch') : sel.value;
+  const cur = b.detached ? 'a detached HEAD' : (b.current || 'the current branch');
+
+  if (!sel.value) {                       // "stay on current" — no git action, so no warning
+    isoWrap.hidden = true;
+    hint.hidden = false; hint.classList.remove('warn');
+    hint.textContent = `runs on ${cur} — nothing is checked out, nothing else moves`;
+    return;
+  }
+  isoWrap.hidden = false;
+  hint.hidden = false;
+  if (iso.checked) {
+    const dir = worktreeHint(picked);
+    hint.classList.remove('warn');
+    hint.textContent = `${picked} gets its own folder${dir ? ' at ' + dir : ''} — every running session stays on its own branch`;
+  } else {
+    // How alarming this is depends entirely on who is here. Warning about "every session" when
+    // the PM is the only one running teaches them to ignore the warning that matters.
+    const others = mySessions().filter((s) => s.state !== 'exited').length;
+    const extra = b.subdir ? ` (the repo is ${shortPath(b.repoRoot || '')}, this workspace is only ${b.subdir}/ inside it)` : '';
+    hint.classList.toggle('warn', others > 0);
+    hint.textContent = others > 0
+      ? `switches this whole repo to ${picked} — ${others} running session${others === 1 ? '' : 's'} here move${others === 1 ? 's' : ''} with it${extra}`
+      : `checks out ${picked} here — nothing else is running in this workspace, and no new folder is made${extra}`;
+  }
+}
+// Mirror of the server's worktreePath, for the hint only — the server is the authority and reports
+// the real path back in its notice. Kept in sync deliberately: a PM deciding where work lands
+// should see the answer before committing to it, not after.
+function worktreeHint(branch) {
+  const b = state.branch;
+  if (!b || !b.ok || !b.repoRoot || !branch || branch === 'the new branch') return '';
+  const parts = String(b.repoRoot).split('/').filter(Boolean);
+  const name = parts[parts.length - 1] || 'repo';
+  return `../${name}-worktrees/${branch.replace(/\//g, '-')}`;
 }
 $('newBtn').onclick = () => ($('newForm').hidden ? openNewForm() : closeNewForm());
 $('newCancel').onclick = closeNewForm;
 $('newBranch').onchange = (e) => setNewBranchMode(e.target.value === '__new__');
+$('newIsolate').onchange = renderBranchHint;
+$('newBranchName').oninput = renderBranchHint;   // the hint names the folder as the PM types it
 $('newAgents').querySelectorAll('button').forEach((b) => b.onclick = () => {
   state.newAgent = b.dataset.agent;
   $('newAgents').querySelectorAll('button').forEach((x) => x.setAttribute('aria-checked', String(x === b)));
@@ -1637,7 +1788,9 @@ $('newForm').addEventListener('submit', (e) => {
   e.preventDefault();
   const name = $('newName').value.trim();
   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).
+  // branch: either create a new one, or check out an existing pick. Empty = stay put (no git call
+  // at all) — and that is what a hidden control means too, so a non-git workspace can never have a
+  // stale pick from a previous repo smuggled onto it.
   const sel = $('newBranch');
   if (!$('newBranchWrap').hidden && sel) {
     if (sel.value === '__new__') {
@@ -1647,29 +1800,75 @@ $('newForm').addEventListener('submit', (e) => {
     } else if (sel.value) {
       msg.branch = sel.value;
     }
+    // isolate → the branch gets its own worktree and running sessions are left alone. Only
+    // meaningful when a branch was actually chosen.
+    if (msg.branch) msg.isolate = !!$('newIsolate').checked;
   }
   send(msg);
   closeNewForm();
 });
 
-// ── scratchpad (R4): per-workspace staging text; copy or send-to-terminal without auto-running ──
-let scratchTimer = null;
+// ── scratchpad (R4): PER-TAB staging text; copy or send-to-terminal without auto-running. The pad
+// belongs to the session it is staged against, not to the workspace: moving between tabs brings
+// each tab's own text, and typing in one never overwrites another's. ──
+// The debounce handle and the not-yet-written text live on `state` (like layoutSaveT): syncActive()
+// can run before this section of the module has evaluated, and module-level `let`s would be in
+// their temporal dead zone at that point — which blanked the whole app on first paint.
 function setScratchStatus(s) { const el = $('scratchStatus'); if (el) el.textContent = s; }
+// Which pad is on screen: the active tab's, or — when the workspace has no tab at all — the
+// workspace's own. Encoded as one key so a switch is a simple inequality.
+function scratchKey() { return state.active ? 'session:' + state.active : 'ws:' + (state.wsId || ''); }
+function renderScratchWho() {
+  const el = $('scratchWho'); if (!el) return;
+  const s = state.sessions.find((x) => x.id === state.active);
+  el.textContent = s ? s.name : '';
+  el.title = s ? `staged for “${s.name}” — each tab keeps its own scratchpad` : '';
+}
 async function loadScratchpad() {
-  const id = state.wsId;
+  const key = scratchKey();
+  state.scratchKey = key;
+  const q = state.active
+    ? 'session=' + encodeURIComponent(state.active)
+    : 'ws=' + encodeURIComponent(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
+  try { const r = await fetch('/api/scratchpad?' + q); const j = await r.json(); if (j && j.ok) text = j.text || ''; } catch {}
+  if (key !== scratchKey()) return;   // a slower fetch for a tab we've since left must not paint
   $('scratchText').value = text; setScratchStatus('');
+  renderScratchWho();
+}
+// Called on every active-session change. It flushes whatever the PM had just typed into the tab
+// they are LEAVING before loading the one they are arriving at — without this, the debounce could
+// still be holding text that would land after the new tab's pad had already painted.
+function syncScratchpad() {
+  const key = scratchKey();
+  if (key === state.scratchKey) { renderScratchWho(); return; }
+  flushScratchpad();
+  loadScratchpad();
+}
+function postScratchpad(p) {
+  return fetch('/api/scratchpad', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(p.session ? { session: p.session, text: p.text } : { ws: p.ws, text: p.text }) });
+}
+function flushScratchpad() {
+  clearTimeout(state.scratchT);
+  const p = state.scratchPending;
+  state.scratchPending = null;
+  if (!p) return;
+  postScratchpad(p).catch(() => {});   // fire-and-forget: the switch must not wait on the network
 }
 function saveScratchpad() {
-  const ws = state.wsId, text = $('scratchText').value;
-  clearTimeout(scratchTimer);
-  scratchTimer = setTimeout(async () => {
+  // The target is captured NOW, with the text — a save that lands after a tab switch must still
+  // write to the tab it was typed in.
+  state.scratchPending = { session: state.active, ws: state.wsId, text: $('scratchText').value };
+  clearTimeout(state.scratchT);
+  state.scratchT = setTimeout(async () => {
+    const p = state.scratchPending;
+    state.scratchPending = null;
+    if (!p) return;
     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();
+      const j = await (await postScratchpad(p)).json();
+      if (p.session && p.session !== state.active) return;    // a pad we've since left: saved, quietly
       setScratchStatus(j && j.ok ? 'saved' : 'save failed');   // a broken save is never a silent green
     } catch { setScratchStatus('save failed'); }
   }, 500);
@@ -1871,10 +2070,12 @@ function edRender() {
   $('edDiff').innerHTML = rows.join('') || '<div class="ed-none">whitespace only</div>';
 }
 
-function edClose(reload) {
+async function edClose(reload) {
   ed.on = false; ed.path = null; ed.base = ''; ed.dirty = false;
   edControls();
-  if (reload && state.docPath) openDoc(state.docPath);
+  // awaited: the reload replaces docBody, so anything that renders into it afterwards (the
+  // alignment offer) must not race the replacement.
+  if (reload && state.docPath) await openDoc(state.docPath);
 }
 
 async function edSave() {
@@ -1899,7 +2100,120 @@ async function edSave() {
     return;
   }
   flash(out.warning ? 'saved — but the change could not be logged' : `saved · +${out.change.added} −${out.change.removed}`);
-  edClose(true);
+  const saved = ed.path;
+  await edClose(true);
+  alOffer(saved);                                          // R7: offered, never blocking — the save is already done
+}
+
+
+// ── alignment (workspace-doc-editor R5–R7) ────────────────────────────────────────────────────
+// Strictly downstream of a save. Nothing here runs until the PM has changed something, and what it
+// looks at is scoped by that change — not the repository. It is offered, never blocking: the save
+// completed before any of this, and ignoring it costs nothing.
+async function alOffer(pth) {
+  if (!pth) return;
+  let out = {};
+  try { out = await (await fetch(`/api/align/candidates?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(pth)}`)).json(); }
+  catch { return; }
+  if (!out.ok || out.empty || !out.candidates || !out.candidates.length) return;
+  state.alCand = out;
+  const n = out.candidates.length;
+  const bar = document.createElement('div');
+  bar.className = 'al-offer';
+  bar.innerHTML = `<span>${n} other document${n === 1 ? '' : 's'} may now be out of step with that change.</span>
+    <button data-al-see>see them</button><button class="q" data-al-no>not now</button>`;
+  const body = $('docBody');
+  body.prepend(bar);
+  bar.querySelector('[data-al-no]').onclick = () => bar.remove();
+  bar.querySelector('[data-al-see]').onclick = () => alShow();
+}
+
+// The candidate list, each with the concrete reason it qualified. The PM chooses which to hand to
+// an agent — so even the drafting step is something they asked for, not something that happened.
+function alShow() {
+  const c = state.alCand; if (!c) return;
+  $('docBody').innerHTML = `<div class="al">
+    <div class="al-lede">Your change to <span class="mono">${esc(c.change.file)}</span> may leave these out of step.</div>
+    <div class="al-sub">Each one has a concrete tie to what you changed — a link, a shared initiative, or text it quotes. Considered ${c.considered} documents.</div>
+    ${c.candidates.map((x, i) => `<label class="al-c">
+        <input type="checkbox" data-al-pick="${i}" checked />
+        <span><span class="al-p mono">${esc(x.path)}</span>
+        <span class="al-why">${x.reasons.map((r) => esc(r)).join(' · ')}</span></span>
+      </label>`).join('')}
+    <div class="al-acts">
+      <button data-al-go>Draft the edits</button>
+      <button class="q" data-al-close>Close</button>
+      <span class="al-note">An agent reads only the documents you tick, and only against this change.</span>
+    </div></div>`;
+  $('docBody').querySelector('[data-al-close]').onclick = () => openDoc(c.change.file);
+  $('docBody').querySelector('[data-al-go]').onclick = async () => {
+    const targets = [...$('docBody').querySelectorAll('[data-al-pick]')]
+      .filter((b) => b.checked).map((b) => c.candidates[Number(b.dataset.alPick)].path);
+    if (!targets.length) { flash('nothing ticked'); return; }
+    let out = {};
+    try {
+      out = await (await fetch('/api/align/start', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ws: state.wsId, path: c.change.file, change: c.change, targets }) })).json();
+    } catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+    if (!out.ok) { flash(out.error || 'could not start'); return; }
+    flash(`drafting against ${targets.length} document${targets.length === 1 ? '' : 's'} — watch the session, then open drafts`);
+    if (out.sessionId) selectSession(out.sessionId);
+  };
+}
+
+// The drafts an agent produced, each an applyable diff. Apply uses the same anchored guard as every
+// other write here: the anchor must appear exactly once or the write is refused.
+async function alDrafts() {
+  let out = {};
+  try { out = await (await fetch(`/api/align/drafts?ws=${encodeURIComponent(state.wsId || '')}`)).json(); }
+  catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  showRail(); $('paneDoc').hidden = false; foldPane('doc', true);
+  $('crumb').innerHTML = '<bdi>alignment drafts</bdi>';
+  if (!out.ok) { $('docBody').innerHTML = `<div class="al"><div class="al-lede">${esc(out.error || 'could not read the drafts')}</div></div>`; return; }
+  if (out.empty || !out.drafts.length) {
+    $('docBody').innerHTML = `<div class="al"><div class="al-lede">No drafts yet.</div>
+      <div class="al-sub">Edit a document, then ask for the alignment when it offers.</div></div>`;
+    return;
+  }
+  state.alDrafts = out;
+  $('docBody').innerHTML = `<div class="al">
+    <div class="al-lede">${out.drafts.length} edit${out.drafts.length === 1 ? '' : 's'} to bring other documents back in line.</div>
+    <div class="al-sub">Drafted against your change to <span class="mono">${esc(out.source || '')}</span>. Nothing is written until you apply it.</div>
+    ${out.drafts.map((d, i) => `<div class="al-d" data-al-d="${i}">
+      <div class="al-p mono">${esc(d.file)}</div>
+      <div class="al-why">${esc(d.why || '')}</div>
+      <div class="al-code">
+        ${String(d.before || '').split('\n').map((l) => `<div class="ed-l del"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`).join('')}
+        ${String(d.after || '').split('\n').map((l) => `<div class="ed-l add"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`).join('')}
+      </div>
+      <div class="al-acts"><button data-al-apply="${i}">Apply</button>
+        <button class="q" data-al-skip="${i}">Skip</button></div>
+    </div>`).join('')}</div>`;
+  $('docBody').querySelectorAll('[data-al-skip]').forEach((b) => b.onclick = () => {
+    $('docBody').querySelector(`[data-al-d="${b.dataset.alSkip}"]`).classList.add('done');
+  });
+  $('docBody').querySelectorAll('[data-al-apply]').forEach((b) => b.onclick = async () => {
+    const d = state.alDrafts.drafts[Number(b.dataset.alApply)];
+    b.disabled = true;
+    let r = {};
+    try {
+      r = await (await fetch('/api/align/apply', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ws: state.wsId, file: d.file, before: d.before, after: d.after, why: d.why, source: state.alDrafts.source }) })).json();
+    } catch { r = { ok: false, error: 'could not reach the workspace server' }; }
+    b.disabled = false;
+    const card = $('docBody').querySelector(`[data-al-d="${b.dataset.alApply}"]`);
+    if (!r.ok) {
+      let e = card.querySelector('.al-err');
+      if (!e) { e = document.createElement('div'); e.className = 'al-err'; card.appendChild(e); }
+      e.textContent = r.error === 'stale' ? 'that text is no longer in the file — the draft is out of date'
+        : r.error === 'ambiguous' ? (r.detail || 'that text appears more than once — refusing to guess')
+        : (r.detail || r.error || 'refused');
+      return;
+    }
+    card.classList.add('done');
+    flash('aligned ' + d.file.split('/').pop());
+  });
+  refit();
 }
 
 $('docEdit').onclick = edOpen;
@@ -1936,6 +2250,7 @@ const SURFACES = [
   { name: 'report', label: 'weekly report', phase: 'report' },
   // Read-only console surfaces (D64 Track B): file-mode state, honest-by-construction (a broken
   // read renders RED, never a green empty). Sourced from /api/console, not the deliverable contract.
+  { name: 'workflow', label: 'workflow', phase: 'plan', console: true },
   { 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 },
@@ -1988,7 +2303,7 @@ function sfHead(active, ok) {
 function wireSurface() {
   document.querySelectorAll('[data-surface]').forEach((b) => b.onclick = () => openSurface(b.dataset.surface));
   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));
+  $('docBody').querySelectorAll('.sf-art[data-doc],.wf-id[data-doc]').forEach((b) => b.onclick = () => openDoc(b.dataset.doc));
 }
 function surfaceBody(name, payload) {
   if (!payload || !payload.ok) return sfCantProduce(name, payload && payload.contract);
@@ -2077,6 +2392,7 @@ function consoleBody(name, p) {
   if (name === 'needs') return csNeeds(p.data);
   if (name === 'radar') return csRadar(p.data, p.source);
   if (name === 'metrics') return csMetrics(p.data, p.source);
+  if (name === 'workflow') return csWorkflow(p.data);
   return csError(name, 'unknown console surface');
 }
 function csError(name, why) {
@@ -2089,7 +2405,9 @@ function csError(name, why) {
 function csEmpty(name) {
   const msg = name === 'needs'
     ? 'Nothing needs your decision right now. No open Acceptance Gate, no overdue outcome check.'
-    : `No ${esc(name)} data yet — the state read succeeded and there is genuinely nothing to show.`;
+    : name === 'workflow'
+      ? 'No initiative records in this repo — the read succeeded and there is genuinely nothing in flight.'
+      : `No ${esc(name)} data yet — the state read succeeded and there is genuinely nothing to show.`;
   return `<div class="cs-empty"><span class="dot" aria-hidden="true"></span><b>Nothing awaits</b>
     <p>${msg}</p><p class="cs-empty-note">This is a real, verified empty — not a failed read.</p></div>`;
 }
@@ -2103,6 +2421,59 @@ function csNeeds(d) {
         <div class="m">${esc(n.kind)}${n.initiative_id ? ' · ' + esc(n.initiative_id) : ''}${n.derived ? ' · derived' : ''}${n.run_id ? ' · ' + esc(n.run_id) : ''}</div></div>
     </div>`).join('')}</div>`;
 }
+// The workflow ladder — the same steps, glyphs and next-actions the CLI and the Initiative Gate
+// print, from the same engine. Parity is the point: a panel that disagreed with CI would be worse
+// than no panel, because the PM would trust the one that is about to fail them.
+const WF_GLYPH = { done: '✓', current: '●', blocked: '✗', pending: '·', na: '─', unknown: '?' };
+const WF_STAGES = ['intake', 'spec', 'contract', 'build', 'eval', 'accepted'];
+function csWorkflow(d) {
+  const live = (d && d.live) || [];
+  const bad = (d && d.unreadable) || [];
+  // "Open" is named for what it is derived from — no recorded acceptance — never as "in flight".
+  // Most of these are finished work whose acceptance was never logged, and the count IS the finding.
+  const head = `<div class="cs-h"><span class="dot ${d.blocked ? 'warn' : 'ok'}" aria-hidden="true"></span>
+    <b>${d.total} without a recorded acceptance${d.blocked ? ` · ${d.blocked} blocked` : ''}</b>
+    <span class="src">derived — no status field to keep updated${d.accepted ? ` · ${d.accepted} accepted` : ''}</span></div>`;
+  // A degraded read is stated, never absorbed: without history the order rules are unknown, and an
+  // unknown that renders like a tick is exactly the false green this surface exists to prevent.
+  const degraded = d.degraded
+    ? `<div class="wf-degraded" role="alert"><b>Order checks degraded</b> — ${esc(d.degraded)}.
+        Steps that depend on commit order show <span class="mono">?</span>, not a tick.</div>` : '';
+  const unreadable = bad.length
+    ? `<div class="wf-degraded" role="alert"><b>${bad.length} record${bad.length === 1 ? '' : 's'} unreadable</b> —
+        ${bad.map((b) => esc(b.id)).join(', ')}. Shown here rather than dropped from the count.</div>` : '';
+  if (!live.length) {
+    return `<div class="cs-workflow">${head}${degraded}${unreadable}
+      <div class="cs-none">Every initiative in this repo has a recorded acceptance.</div></div>`;
+  }
+  // Never a silent cap: a truncated list that does not say so reads as "that is everything".
+  const more = d.hidden
+    ? `<div class="wf-more">+ ${d.hidden} more without a recorded acceptance, not shown —
+        <span class="mono">node scripts/workflow-state.js --all</span></div>` : '';
+  return `<div class="cs-workflow">${head}${degraded}${unreadable}
+    ${live.map((r) => {
+    const at = Math.max(0, WF_STAGES.indexOf(r.stage));
+    const rail = WF_STAGES.map((s, i) =>
+      `<span class="wf-st ${i < at ? 'past' : i === at ? 'at' : ''}">${esc(s)}</span>`).join('<i class="wf-sep" aria-hidden="true"></i>');
+    return `<div class="wf-card" data-blocked="${r.blockers.length ? '1' : '0'}">
+      <div class="wf-top">
+        <button class="wf-id" data-doc="${esc(r.record)}" title="open the initiative record">${esc(r.id)}</button>
+        <span class="wf-lane">${esc(r.lane)}</span>
+        ${r.in_change ? '<span class="wf-here">this change</span>' : ''}
+        <span class="wf-anchor" title="${esc(r.anchor || '')}">${esc((r.anchor || 'unanchored').split(/[(—]/)[0].trim())}</span>
+      </div>
+      <div class="wf-rail">${rail}</div>
+      <div class="wf-steps">${r.steps.map((s) => `
+        <div class="wf-step" data-st="${esc(s.status)}">
+          <span class="wf-g" aria-hidden="true">${WF_GLYPH[s.status] || '?'}</span>
+          <span class="wf-k">${esc(s.key)}</span>
+          <span class="wf-e">${esc(s.evidence || '')}${s.rule && s.status === 'blocked' ? ` <span class="wf-rule">${esc(s.rule)}</span>` : ''}</span>
+        </div>${s.next ? `<div class="wf-next" data-st="${esc(s.status)}">→ ${esc(s.next)}</div>` : ''}`).join('')}</div>
+      ${r.next ? `<div class="wf-do"><b>next</b> ${esc(r.next.action || '')}</div>`
+        : `<div class="wf-do ok"><b>nothing blocking</b> — the ladder is complete</div>`}
+    </div>`;
+  }).join('')}${more}</div>`;
+}
 function csRadar(d, source) {
   const g = d.eval_gate || {};
   const cal = d.calibration;
@@ -2346,6 +2717,7 @@ function openPalette() {
   const wss = state.workspaces.filter((w) => w.id !== state.wsId).map((w) => ({ kind: 'workspace', label: w.name, wsid: w.id }));
   // summon a P/D/M/R surface on demand — listed first so "initiatives"/"roadmap"/"okr"/"report" are reachable
   const views = SURFACES.map((v) => ({ kind: 'view', label: v.label, view: v.name }));
+  views.push({ kind: 'align', label: 'alignment drafts' });   // downstream of a save, never resident
   palItems = [...views, ...wss, ...sess, ...inits, ...docs];
   $('palette').style.display = 'grid';
   const inp = $('palInput'); inp.value = ''; renderPalette('');
@@ -2371,6 +2743,7 @@ function choosePalette(n) {
   const it = items[n]; if (!it) return;
   closePalette();
   if (it.kind === 'view') openSurface(it.view);
+  else if (it.kind === 'align') alDrafts();
   else if (it.kind === 'session') selectSession(it.id);
   else if (it.kind === 'workspace') selectWorkspace(it.wsid);
   else if (it.kind === 'initiative') {