create-pmos 0.18.0 → 0.19.0

package/workspace/public/pm/tab-term.js

@@ -149,6 +149,7 @@ function connect() {
     for (const rec of panes.values()) {
       if (rec.kind !== 'real') continue;
       rec.attachedId = null;
+      rec.sentCols = null; rec.sentRows = null;   // the next connection has stated no grid yet
       note(rec, 'pmos: connection to the workspace server lost — retrying');
     }
     clearTimeout(SOCK.timer);
@@ -181,6 +182,17 @@ function handle(m) {
     rec.noted = null;
     try { rec.term.reset(); } catch { /* a disposed terminal */ }
     if (m.buf) { try { rec.term.write(m.buf); } catch { /* ignore */ } }
+    /* THE PTY DOES NOT KNOW HOW WIDE THIS BROWSER IS. `attached` carries the SERVER's cols/rows —
+     * 80×24 for a session nobody ever resized — and the server never adopts the client's grid on
+     * attach. The only thing that ever told it was xterm's `onResize`, which fires when a fit
+     * CHANGES the grid; the first fit runs while the socket is still connecting, so `sessionId` was
+     * null and the message was dropped, and every later fit measured the same box and changed
+     * nothing, so it never fired again. Result: a 200-column window rendering a shell that believes
+     * it has 80, wrapping a third of the way across — "the terminal only shows a small portion".
+     * The grid is therefore PUSHED here, unconditionally, the moment there is a session to push it
+     * to. `sent*` is cleared first so a re-attach after a reconnect re-states it. */
+    rec.sentCols = null; rec.sentRows = null;
+    syncSize(rec);
     refitVisible();
     return;
   }
@@ -199,6 +211,8 @@ function handle(m) {
     const rec = panes.get(id);
     if (!rec) { send({ t: 'detach', id: m.id }); return; }   // the tab closed while we waited
     rec.sessionId = m.id;
+    rec.sentCols = null; rec.sentRows = null;
+    rememberSession(rec.tab, m.id);
     attach(rec);
     return;
   }
@@ -218,22 +232,38 @@ const recFor = (sessionId) => {
 };
 
 /* ── binding a tab to a real session ───────────────────────────────────────────────────────────
- * The tab knows the initiative slug and the session NAME (`term:<slug>:<name>` is its id); the
- * server knows session ids. The join is by name within the tab's workspace, which is the same join
- * the sidebar has always made — a session's name is what the PM sees and what they named it.
- * `sessionId` set on the tab by the data layer wins, when there is one.
+ * `sessionId` on the tab is the ONLY exact join, and it is the one that is used whenever it exists:
+ * it is the server's own id, the data layer puts it on every tab opened from a listed session, and
+ * `rememberSession` writes it back (and so into localStorage) the first time a tab resolves. The
+ * name join below is the fallback for a tab that predates all of that.
+ *
+ * THE NAME JOIN IS SCOPED TO THE TAB'S OWN WORKSPACE, and no longer falls back to "a session with
+ * this name anywhere". Session names are not unique across repositories — every `＋ session` in
+ * every repo produces `agent 1` — so the unscoped fallback quietly attached a tab in one repository
+ * to a PTY running in another, and the PM was shown another repo's shell under their own repo's
+ * initiative. A name that resolves nowhere in this workspace is now reported as not found, which is
+ * the true answer.
  */
 function resolveSessionId(tab) {
-  if (tab.sessionId) return tab.sessionId;
   const pool = SOCK.sessions.length ? SOCK.sessions
     : (Array.isArray(state.sessions) ? state.sessions : []);
+  if (tab.sessionId) {
+    // A restored tab names a session from a previous run of this window — or of this SERVER. Trust
+    // it while nothing is known (the socket has not said `hello` yet), but once there is a list,
+    // an id that is not in it is a session that no longer exists: fall through rather than
+    // `attach`ing to it, which the server answers with silence and the PM reads as a dead pane.
+    if (!pool.length || pool.some((s) => s && s.id === tab.sessionId)) return tab.sessionId;
+  }
+  if (tab.spawn) return null;                 // a `＋ session` tab must START one, never adopt one
   const name = tab.sess;
   if (!name) return null;
   const byId = pool.find((s) => s && s.id === name);
   if (byId) return byId.id;
-  const ws = workspaceId();
+  const ws = wsForTab(tab);
   const inWs = pool.find((s) => s && s.name === name && (!ws || s.ws === ws));
   if (inWs) return inWs.id;
+  // No cross-workspace fallback. See the note above: it is how a repository showed another's shell.
+  if (ws) return null;
   const anywhere = pool.find((s) => s && s.name === name);
   return anywhere ? anywhere.id : null;
 }
@@ -254,40 +284,95 @@ function workspaceId() {
 }
 
 /**
- * Was this session started in THIS window (the `＋ session` path)? Only then may a terminal spawn a
- * PTY on its own: a tab opened against a session the board listed must attach to that session or
- * say it is gone — silently starting a second shell with the same name would be a lie about what
- * the PM is looking at.
+ * The workspace THIS TAB belongs to — which is not always the selected one. Every open terminal is
+ * kept live, including the ones belonging to a repository the PM is not currently looking at (see
+ * panel-tabs.js `keepSessionsLive`), so scoping a parked tab's name join by the SELECTED repository
+ * would scope it by the wrong repo entirely. `state.productWs` is the data layer's product-name →
+ * workspace-id map; a tab whose repository is not in it falls back to the selected workspace, which
+ * is right for the tab on screen and is all a fixture render has.
+ */
+function wsForTab(tab) {
+  const map = state.productWs;
+  if (tab && tab.repo && map && typeof map === 'object' && map[tab.repo]) return map[tab.repo];
+  return workspaceId();
+}
+
+/**
+ * Does this tab carry an instruction to START a session? Only then may a terminal spawn a PTY on
+ * its own: a tab opened against a session the board listed must attach to that session or say it is
+ * gone — silently starting a second shell with the same name would be a lie about what the PM is
+ * looking at.
+ *
+ * The flag is set by `＋ session` and travels ON THE TAB. It used to be inferred by looking the
+ * tab's session NAME up in `state.extraSess`, which is a different question wearing the same
+ * clothes: after a reload `extraSess` is empty and `startN` is back at 1, so a fresh `＋ session`
+ * produced the name `agent 1`, the name join found the `agent 1` still running from before the
+ * reload, and the click ATTACHED to an old session instead of starting a new one. The PM asked for
+ * a session and got someone else's.
  */
-function startedHere(tab) {
+function wantsSpawn(tab) {
+  if (tab && tab.spawn) return true;
   const list = (state.extraSess || {})[tab.slug];
   return Array.isArray(list) && list.some((s) => s && s.name === tab.sess);
 }
 
+/**
+ * Record the session a tab actually landed on, on the tab record itself — so it is written to
+ * localStorage and a reload re-attaches to exactly this PTY rather than re-running the name join.
+ * "I don't know which session it has reloaded" is that join being re-run against a list that has
+ * moved on; an id does not have that failure mode.
+ */
+function rememberSession(tab, sessionId) {
+  if (!tab || !sessionId) return;
+  // The guard is checked BEFORE the mutation, and on the tab record itself. `rec.tab` is very often
+  // the same object that sits in `state.tabs`, so mutating first and then comparing would always
+  // find them equal and the repaint that shows the id on the tab would never be scheduled.
+  if (tab.sessionId === sessionId && tab.spawn === false) return;
+  tab.sessionId = sessionId;
+  tab.spawn = false;
+  setState((s) => {
+    const i = (s.tabs || []).findIndex((t) => t.id === tab.id);
+    if (i < 0) return null;
+    const next = [...s.tabs];
+    next[i] = { ...next[i], sessionId, spawn: false };
+    return { tabs: next };
+  });
+}
+
 function bind(rec) {
   if (rec.kind !== 'real' || !rec.term) return;
   const id = resolveSessionId(rec.tab);
   if (id) {
-    if (rec.sessionId !== id) { rec.sessionId = id; rec.attachedId = null; }
+    if (rec.sessionId !== id) {
+      rec.sessionId = id; rec.attachedId = null; rec.sentCols = null; rec.sentRows = null;
+    }
+    rememberSession(rec.tab, id);
     attach(rec);
     return;
   }
   if (!SOCK.open) { note(rec, 'pmos: connecting to the workspace server…'); return; }
   if (SOCK.spawning.get(rec.tab.id)) return;
-  if (startedHere(rec.tab)) {
+  if (wantsSpawn(rec.tab)) {
     // agent 'shell' deliberately: PMOS cannot know which agent CLI the PM meant from a tab alone,
     // and falling back from an agent to a shell after the fact would be the dishonest version.
     SOCK.spawning.set(rec.tab.id, true);
     SOCK.spawnQueue.push(rec.tab.id);
     note(rec, 'pmos: starting a session…', true);
-    const ok = send({ t: 'new', name: rec.tab.sess, agent: 'shell', ws: workspaceId() });
+    const ok = send({ t: 'new', name: rec.tab.sess, agent: 'shell', ws: wsForTab(rec.tab) });
     if (!ok) {
       SOCK.spawning.delete(rec.tab.id);
       SOCK.spawnQueue = SOCK.spawnQueue.filter((x) => x !== rec.tab.id);
     }
     return;
   }
-  note(rec, 'pmos: no live session named "' + rec.tab.sess + '" — nothing was attached');
+  /* Say WHICH session was looked for and why it could not be found. A tab restored from a previous
+   * run names an id; one opened from the board names a name. Both are worth printing — "nothing was
+   * attached" without the identity is exactly the report that left the PM unable to tell which
+   * session a reloaded tab had landed on. */
+  note(rec, rec.tab.sessionId
+    ? 'pmos: session ' + rec.tab.sessionId + ' ("' + (rec.tab.sess || '?')
+      + '") is no longer running — nothing was attached'
+    : 'pmos: no live session named "' + rec.tab.sess + '" in this repository — nothing was attached');
 }
 
 function attach(rec) {
@@ -296,6 +381,24 @@ function attach(rec) {
   if (send({ t: 'attach', id: rec.sessionId })) SOCK.attached.add(rec.sessionId);
 }
 
+/**
+ * Tell the PTY the grid this browser is actually rendering. Sent whenever the pane is attached and
+ * the terminal's cols/rows differ from what this connection last stated — which covers the attach
+ * itself, every refit that moves the grid, and a reconnect (where `sent*` is cleared).
+ *
+ * Idempotent by design: `sent*` makes a re-render cost nothing, and the guard is on what was SENT
+ * rather than on what xterm reports, because the server holds the authoritative copy and a resize
+ * this connection never sent is a resize the shell never heard.
+ */
+function syncSize(rec) {
+  if (!rec || rec.kind !== 'real' || !rec.term) return;
+  if (!rec.sessionId || rec.attachedId !== rec.sessionId) return;
+  const cols = rec.term.cols, rows = rec.term.rows;
+  if (!cols || !rows) return;
+  if (rec.sentCols === cols && rec.sentRows === rows) return;
+  if (send({ t: 'resize', id: rec.sessionId, cols, rows })) { rec.sentCols = cols; rec.sentRows = rows; }
+}
+
 /** Write a status line into the terminal itself — once per distinct message, dimmed. */
 function note(rec, line, force) {
   if (!rec.term) return;
@@ -321,6 +424,10 @@ export function refitVisible() {
       if (!rec.host.isConnected) continue;
       if (!rec.host.offsetWidth || !rec.host.offsetHeight) continue;
       try { rec.fit.fit(); } catch { /* a terminal mid-teardown */ }
+      // …and state the resulting grid to the PTY. `fit()` only fires xterm's `onResize` when the
+      // grid MOVES, so a pane that was measured before it had a session would otherwise never tell
+      // the shell how wide it is. See the `attached` handler.
+      syncSize(rec);
     }
   };
   if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
@@ -339,7 +446,7 @@ if (typeof window !== 'undefined') {
 
 /* ── fixture pane ──────────────────────────────────────────────────────────────────────────── */
 
-const SCROLL_STYLE = 'flex:1;overflow-y:auto;padding:14px 16px;font-family:var(--mono);font-size:12.5px;line-height:1.65;color:#c4ccce';
+const SCROLL_STYLE = 'flex:1;min-height:0;overflow-y:auto;padding:14px 16px;font-family:var(--mono);font-size:12.5px;line-height:1.65;color:#c4ccce';
 const LINE_STYLE = (c) => 'color:' + c + ';white-space:pre-wrap;overflow-wrap:anywhere';
 const PROMPT_ROW_STYLE = 'display:flex;gap:8px;align-items:baseline';
 const PROMPT_STYLE = 'color:#47cf79;flex:none';
@@ -459,9 +566,7 @@ function buildReal(tab) {
     kind: 'real', tab, host, term, fit, sessionId: null, attachedId: null, noted: null, ro: null,
   };
   term.onData((d) => { if (rec.sessionId) send({ t: 'input', id: rec.sessionId, data: d }); });
-  term.onResize(({ cols, rows }) => {
-    if (rec.sessionId) send({ t: 'resize', id: rec.sessionId, cols, rows });
-  });
+  term.onResize(() => syncSize(rec));
   if (typeof ResizeObserver === 'function') {
     rec.ro = new ResizeObserver(() => refitVisible());
     try { rec.ro.observe(host); } catch { /* ignore */ }
@@ -534,6 +639,33 @@ export function sendToTerm(tab, data) {
   return send({ t: 'input', id: rec.sessionId, data });
 }
 
+/**
+ * End a running session, by id — the `＋ session` chooser's one destructive action.
+ *
+ * The wire message already existed (`t:'kill'`); what did not exist anywhere in the four-panel
+ * surface was a way to reach it, which is why "is it safe to end this?" had no answer the PM could
+ * act on. This is a bare send: the CONFIRMATION lives in the chooser, next to the reading of what
+ * ending it would cost, because that is the only place the PM is looking at both at once.
+ *
+ * Returns false when the socket is not up, so a caller can say "not sent" rather than imply a kill
+ * that never left the page.
+ */
+export function killSession(id) {
+  if (FIXTURE || !id) return false;
+  return send({ t: 'kill', id });
+}
+
+/**
+ * The SERVER's session id this tab is bound to, or null. The scratchpad reads it: a pad belongs to
+ * the session, and the session's identity is this id — not the tab id (which survives a session
+ * being replaced) and not the session name (which repeats across repositories).
+ */
+export function sessionIdOf(tab) {
+  const rec = panes.get(tab && (tab.id || tab));
+  if (rec && rec.kind === 'real' && rec.sessionId) return rec.sessionId;
+  return (tab && tab.sessionId) || null;
+}
+
 /** Focus the terminal of a tab, if it is live. */
 export function focusTerm(tab) {
   const rec = panes.get(tab && (tab.id || tab));

package/workspace/server.js

@@ -71,6 +71,7 @@ const consoleState = require('./lib/console-state');   // read-only console surf
 const boardCache = require('./lib/board-cache');   // the workflow board, cached + derived off the event loop (R4)
 const fmParse = require('./lib/file-mode-parse');      // canonical file-mode parsers, shared with metrics.py (D64 D)
 const gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
+const startPolicy = require('./lib/start-policy');     // ONE stated rule for where a session starts (repo-first R1/R3)
 const treeShare = require('./lib/tree-share');         // who shares a working tree, and who is DECLARED to be driving it
 const tmuxControl = require('./lib/tmux-control');     // tmux -CC protocol: the pane's raw stream, so xterm.js keeps its scrollback
 const relatedDocs = require('./lib/related-docs');            // which documents a change puts out of step (R5/R6)
@@ -368,6 +369,36 @@ function treeForWs(wsIdent) {
 function treeTenants(tree, excludeId) {
   return treeShare.coTenants([...sessions.values()], treeOfWsMap(), tree, excludeId);
 }
+/**
+ * A registry row, described for a human deciding whether to JOIN it rather than start another
+ * (workspace-session-choice). "2 sessions already running" names a fact the PM cannot act on; what
+ * they need is which one, what it is doing, and what ending it would cost.
+ *
+ * Every field is one the sidebar already publishes — the joined presented state, the quiet clock,
+ * the sidebar's own word for it, and the agent's last words. Nothing new is derived here and no
+ * word is re-invented: `sessionState` owns the vocabulary and `treeShare.endRisk` owns the
+ * consequence, and this function only joins them onto one row.
+ */
+function describePeer(s, now) {
+  const d = harness.deriveState(s.state, s.lastOutputAt, now || Date.now());
+  const hx = transcriptHarness(s);
+  const shown = sessionState.presented(d.state, hx && hx.turn);
+  const oc = hx && hx.openCall;
+  const call = oc && oc.verb
+    ? { verb: oc.verb, ageMs: oc.sinceTs ? Math.max(0, (now || Date.now()) - Date.parse(oc.sinceTs)) : null }
+    : null;
+  return {
+    id: s.id, ws: s.ws, name: s.name, agent: s.agent, state: s.state, shown,
+    quietMs: d.quietMs,
+    label: sessionState.label(shown, { quietMs: d.quietMs, call, fmtDur: treeShare.ago }),
+    doing: (harnessOf(s) || {}).lastWords || null,
+  };
+}
+/** The same set as `treeTenants`, each row described. The order is the registry's, unchanged. */
+function treePeersDescribed(tree, excludeId) {
+  const now = Date.now();
+  return treeTenants(tree, excludeId).map((s) => describePeer(s, now));
+}
 function treeWriter(tree) {
   return treeShare.writerOf(treeClaims, treeOfWsMap(), [...sessions.values()], tree);
 }
@@ -381,12 +412,16 @@ function announceTree(s) {
   const tree = treeForWs(s.ws);
   s.tree = tree || null;
   if (!tree) return [];
-  const mates = treeTenants(tree, s.id);
+  // DESCRIBED rows, not bare registry objects: the pane line now carries what each co-tenant is
+  // doing and what ending it would cost, and it must read from the same join the sidebar does.
+  const mates = treePeersDescribed(tree, s.id);
   const holder = treeWriter(tree);
   if (!holder) treeClaims.set(tree, s.id);           // vacant → this session declares itself
   if (!mates.length) return [];                      // alone in the tree: nothing to say
   const held = holder ? (sessions.get(holder) || {}).name : null;
-  const line = treeShare.paneAdvisory(mates, { role: holder ? 'reader' : 'writer', writerName: held });
+  const line = treeShare.paneAdvisory(mates, {
+    role: holder ? 'reader' : 'writer', writerName: held, writerId: holder || s.id, tree,
+  });
   if (line) appendBuf(s, line);
   return mates;
 }
@@ -395,7 +430,9 @@ function treeNoticeFor(s, mates) {
   if (!mates || !mates.length) return null;
   const holder = treeWriter(s.tree);
   const held = holder && holder !== s.id ? (sessions.get(holder) || {}).name : null;
-  return treeShare.coTenancyNotice(mates, { role: holder === s.id ? 'writer' : 'reader', writerName: held });
+  return treeShare.coTenancyNotice(mates, {
+    role: holder === s.id ? 'writer' : 'reader', writerName: held, writerId: holder, tree: s.tree,
+  });
 }
 function wsList() {
   return [...workspaces.values()].map((w) => {
@@ -409,6 +446,12 @@ function wsList() {
       // the client renders the first quietly and the second as a fault (R1/R2).
       repo_key: rid.key, repo_name: rid.name, branch: rid.branch,
       branch_error: rid.branchError, branch_code: rid.branchCode,
+      // The COLLISION UNIT (workspace-session-concurrency), published so a client can answer "who
+      // else is in the tree I am about to start in?" BEFORE it starts anything. Without it the
+      // browser could only find co-tenants via a session that already exists there, which is
+      // exactly one session too late for a chooser. Null for a folder with no git — no index to
+      // collide over, so no group.
+      tree: rid.tree || null,
       // Where the tree came from, and the ONE label the repository list can honestly put on a row.
       // `remote` is the raw origin URL (null when there is none) so a caller can derive a richer
       // answer without guessing; `kind` is the surface's own two-value vocabulary — a repository
@@ -1306,6 +1349,10 @@ function persist(s) {
   try {
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
+    // What is on disk now matches `s.buf`. The periodic writer reads this to skip a session whose
+    // buffer has not moved — see the interval below. Cleared only on a write that SUCCEEDED, so a
+    // disk blip leaves the session dirty and it is retried on the next tick.
+    s.bufDirty = false;
   } catch { /* best-effort; never crash a live session on a disk blip */ }
 }
 function unpersist(id) {
@@ -1554,6 +1601,17 @@ function sessionList() {
       // `failed` does not exist (no observable for it). The client re-derives this from the SAME
       // module — see /lib/session-state.js below — so the two can never hold different opinions.
       shown: sessionState.presented(d.state, hx && hx.turn), quietMs: d.quietMs,
+      // The rendered word for that state — computed HERE rather than in each client, because it is
+      // the same join (`sessionState.label`) with the same clock, and a client re-deriving it was
+      // already producing a second, slightly different sentence for one session.
+      label: sessionState.label(sessionState.presented(d.state, hx && hx.turn), {
+        quietMs: d.quietMs,
+        call: hx && hx.openCall && hx.openCall.verb
+          ? { verb: hx.openCall.verb,
+            ageMs: hx.openCall.sinceTs ? Math.max(0, now - Date.parse(hx.openCall.sinceTs)) : null }
+          : null,
+        fmtDur: treeShare.ago,
+      }),
       lastOutputAt: s.lastOutputAt || null,
       lastWords: h.lastWords,
       // the harness proper — structured record, not rendered bytes. Resolved ONCE above and
@@ -1641,6 +1699,7 @@ function trimBuf(buf, limit) {
 function appendBuf(s, data) {
   s.buf += data;
   if (s.buf.length > SCROLLBACK) s.buf = trimBuf(s.buf, SCROLLBACK);
+  s.bufDirty = true;                    // the periodic writer skips a session that is not dirty
   // Parser 2's whole input: the moment output last arrived. `quiet` is derived from this, never
   // from reading the bytes — which is why it is the only one of the five that cannot misread.
   s.lastOutputAt = Date.now();
@@ -1808,6 +1867,7 @@ function seedFromPaneHistory(s, name) {
   if (!text) return false;
   s.buf = trimBuf(text + '\r\n', SCROLLBACK);          // 5000 lines of history can overrun the ring
   s.parsed = null;
+  s.bufDirty = true;                                   // the ring moved; the file on disk is stale
   return true;
 }
 
@@ -2108,10 +2168,90 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
   // Both facts travel: `notice` is a single string on the wire and a branch notice and a co-tenancy
   // notice can both be true of one spawn. joinNotices keeps them both rather than letting the
   // second evict the first exactly when the PM most needs both.
-  const shared = treeNoticeFor(s, treeTenants(s.tree, s.id));
+  const shared = treeNoticeFor(s, treePeersDescribed(s.tree, s.id));
   return { ok: true, session: s, notice: treeShare.joinNotices(notice, shared) };
 }
 
+/* ── workspace-repo-first · start work in one click (PRD R1 · R3) ───────────────────────────────
+ * The composer asked six questions to open a terminal, and the one question the PM actually has —
+ * "which initiative am I working on?" — was not among them. It asked for a BRANCH instead, plus an
+ * isolation checkbox whose default came from liveSessionCount(). These three functions replace that
+ * with: pick a repository, optionally pick an initiative, press one control.
+ *
+ * The policy itself is lib/start-policy.js — pure, so the git-touching paths are testable without
+ * a repository. This layer only supplies it with facts and carries out what it decides.
+ *
+ * R3 is why `agent` appears NOWHERE below except as a value passed through to the spawn: the
+ * destination is derived from the repository and the initiative, so `shell` and `claude` cannot
+ * land in different directories for the same selection. Previously both resolved through
+ * `state.wsId` — whichever folder the client happened to have selected — which is exactly how they
+ * came apart.
+ */
+function treesOfRepo(repoKey) {
+  const out = [];
+  for (const w of workspaces.values()) {
+    const ident = repoIdentity(w.root);
+    if (String(ident.key) !== String(repoKey)) continue;
+    out.push({ id: w.id, root: w.root, name: w.name, repo_key: ident.key, branch: ident.branch });
+  }
+  return out;
+}
+// The repo key for a request that named a workspace rather than a repository. The client sends
+// whichever it has; a stale ws id must not silently retarget another repo, so an unknown id is an
+// error rather than a fallback to "some repository".
+function repoKeyFor({ repoKey, ws }) {
+  if (repoKey) return String(repoKey);
+  const w = ws && workspaces.get(ws);
+  return w ? String(repoIdentity(w.root).key) : null;
+}
+// What the PM is about to get, BEFORE they press anything (R1: the destination is named first).
+// Read-only: it reads git and resolves the policy, and starts nothing.
+function startPreview({ initiative, repoKey, ws }) {
+  const key = repoKeyFor({ repoKey, ws });
+  if (!key) return { ok: false, error: 'no repository selected' };
+  const trees = treesOfRepo(key);
+  const main = startPolicy.mainTreeOf(trees);
+  // branchInfo is shelled per call and only when an initiative is named — the no-initiative plan
+  // needs no branch list, and this runs on every selection change.
+  let branches = null;
+  if (initiative && main) {
+    try { const bi = gitInfo.branchInfo(main.root); if (bi.ok) branches = bi.branches; } catch {}
+  }
+  const plan = startPolicy.resolveStart({ initiative, trees, branches });
+  if (!plan.ok) return plan;
+  // The literal directory, so the sentence in the UI is checkable rather than a promise.
+  let dir = null;
+  if (plan.plan === 'new-worktree' && main) { try { dir = gitInfo.worktreePath(main.root, plan.branch); } catch {} }
+  else { const t = trees.find((x) => x.id === plan.wsId); dir = t ? t.root : null; }
+  return { ok: true, plan: plan.plan, why: plan.why, dir, branch: plan.branch, wsId: plan.wsId };
+}
+// One click. Resolves the policy, then hands the SAME seam spawnWithBranch already exposes the
+// branch/isolate decision it made — so the inherited hard floor (a failed git operation spawns
+// nothing) is enforced in exactly one place and is not re-implemented here.
+function startWork({ initiative, repoKey, ws, agent, name, profile }) {
+  const key = repoKeyFor({ repoKey, ws });
+  if (!key) return { ok: false, error: 'no repository selected' };
+  const trees = treesOfRepo(key);
+  const main = startPolicy.mainTreeOf(trees);
+  let branches = null;
+  if (initiative && main) {
+    try { const bi = gitInfo.branchInfo(main.root); if (bi.ok) branches = bi.branches; } catch {}
+  }
+  const plan = startPolicy.resolveStart({ initiative, trees, branches });
+  if (!plan.ok) return plan;
+  const r = spawnWithBranch({
+    name: name || initiative || agent || 'shell',
+    agent: agent || 'shell',
+    ws: plan.wsId,
+    branch: plan.branch,
+    createBranch: plan.createBranch,
+    isolate: plan.isolate,
+    profile,
+  });
+  if (!r.ok) return r;
+  return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
+}
+
 // ── Worktree housekeeping: the app that creates the folders shows and clears them ──────────────
 // Isolation buys "your other sessions keep running" at the price of a directory per branch. That
 // price is only fair if the PM can see the folders and reclaim them without leaving the workspace
@@ -2255,8 +2395,17 @@ function renameSession(id, name) {
   return true;
 }
 
-// periodic scrollback persistence so a crash loses at most a few seconds of history
-setInterval(() => { for (const s of sessions.values()) if (s.pty) persist(s); }, 5000).unref?.();
+// Periodic scrollback persistence so a crash loses at most a few seconds of history — but ONLY for
+// sessions whose buffer actually moved. `persist()` is two SYNCHRONOUS writes, the second of them
+// the whole ring buffer (up to 200 KB), and this ran unconditionally for every live session every
+// five seconds. A workspace with six idle panes open was therefore doing over a megabyte of blocking
+// disk I/O, on a timer, forever — rewriting bytes identical to the ones already on disk, on the same
+// thread that carries every keystroke to a PTY and every byte back to the browser. That is a stall
+// the PM feels as the terminal going unresponsive for no reason they can see.
+//
+// `bufDirty` is set by appendBuf (the only writer of `s.buf`) and cleared by persist(), so an idle
+// session now costs one map lookup per tick and a busy one is written exactly as often as before.
+setInterval(() => { for (const s of sessions.values()) if (s.pty && s.bufDirty) persist(s); }, 5000).unref?.();
 
 // ── File-mode state, per workspace. ───────────────────────────────────────────────────
 // A repo that carries PMOS state OWNS its records. The kit (D54) keeps them under `pmos/state/`
@@ -2995,6 +3144,7 @@ async function handleRequest(req, res) {
   if (p === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.js'));
   if (p === '/lib/mobile-nav.js') return serveFile(res, path.join(__dirname, 'lib', 'mobile-nav.js'));
   if (p === '/lib/session-state.js') return serveFile(res, path.join(__dirname, 'lib', 'session-state.js'));
+  if (p === '/lib/tree-share.js') return serveFile(res, path.join(__dirname, 'lib', 'tree-share.js'));
   // The editor computes its live diff with the SAME module the server saves through, so what the PM
   // sees while typing and what gets written cannot disagree. NB: /lib/ is an explicit allowlist, not
   // a directory route — a <script src> for a file missing from this list 404s silently, and the
@@ -3504,6 +3654,16 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' });
     return json(res, gitInfo.branchInfo(w.root));
   }
+  if (p === '/api/start/preview') {
+    // repo-first R1 — what one click will do, said BEFORE the click. Read-only: it resolves the
+    // policy and names the literal destination directory, and starts nothing. This exists so the
+    // rule is checkable by the PM rather than inferred after a folder appears.
+    return json(res, startPreview({
+      initiative: url.searchParams.get('initiative') || '',
+      repoKey: url.searchParams.get('repo') || '',
+      ws: url.searchParams.get('ws') || '',
+    }));
+  }
   if (p === '/api/git/worktrees') {
     // Every working tree attached to this workspace's repo, each with the reasons it can or cannot
     // be removed. A worktree the workspace made is a folder the PM has to live with, so the app
@@ -3524,9 +3684,13 @@ async function handleRequest(req, res) {
         note: 'this workspace is not inside a git working tree — there is no shared index to collide over' });
     }
     const writer = treeWriter(tree);
-    const rows = treeTenants(tree, null).map((s) => ({
-      id: s.id, name: s.name, ws: s.ws, agent: s.agent, state: s.state,
+    // Described, not merely listed (workspace-session-choice): a caller deciding between joining a
+    // running session and starting another needs the state, the word for it, what the agent is
+    // doing and what ending it would cost — the same four facts the chooser and the pane line show.
+    const rows = treePeersDescribed(tree, null).map((s) => ({
+      ...s,
       role: treeShare.roleOf(s.id, tree, writer),
+      risk: treeShare.endRisk(s.shown, s.quietMs),
     }));
     return json(res, { ok: true, tree, writer, sessions: rows, advisory: true,
       note: writer
@@ -4159,7 +4323,7 @@ wss.on('connection', (ws) => {
   ws.on('message', (raw) => {
     let m; try { m = JSON.parse(raw); } catch { return; }
     // Gate the shell-spawning / PTY-feeding messages through the buckets before they do any work.
-    if ((m.t === 'new' || m.t === 'respawn') && !rateLimit.take(ws._rlSpawn)) {
+    if ((m.t === 'new' || m.t === 'start' || m.t === 'respawn') && !rateLimit.take(ws._rlSpawn)) {
       ws.send(JSON.stringify({ t: 'error', error: 'rate limited: too many session spawns — slow down' }));
       return;
     }
@@ -4183,6 +4347,15 @@ wss.on('connection', (ws) => {
       // non-repo) — said out loud, never swallowed
       if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
       ws.send(JSON.stringify({ t: 'created', id: r.session.id }));
+    } else if (m.t === 'start') {
+      // repo-first R1 — the one-click path. It carries an INITIATIVE (or none) and a repository,
+      // never a branch and never an isolate flag: those are the policy's to decide, and a client
+      // that could still send them would be a second place the rule lives.
+      const r = startWork({ initiative: m.initiative, repoKey: m.repoKey, ws: m.ws,
+        agent: m.agent, name: m.name, profile: m.profile });
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'start: ') + r.error })); return; }
+      if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
+      ws.send(JSON.stringify({ t: 'created', id: r.session.id }));
     } else if (m.t === 'respawn') {
       const old = sessions.get(m.id); if (!old || old.pty) return;
       // `respawn` is UNCHANGED on the wire (profiles R9): the profile is read off the record the
@@ -4291,6 +4464,10 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // (one repo registered twice is one tree; two worktrees of one repo are two) without driving
   // every case through a spawn.
   treeForWs, treeTenants, treeWriter, treeClaims,
+  // …and the DESCRIBED form, exported for the same reason: "what is that session doing and what
+  // would ending it cost?" is the half of co-tenancy the PM actually acts on, so the suite asserts
+  // it directly rather than reading it back out of a rendered sentence.
+  describePeer, treePeersDescribed,
   // exported so the suite can assert the D08 invariant end-to-end: the harness parsers consume
   // scrubbed text, so a secret printed into scrollback must not survive into a rendered value.
   scrub, harnessOf,