create-pmos 0.18.0 → 0.18.1

package/README.md

@@ -333,6 +333,33 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.18.1
+
+**Three fixes to the workspace terminal, all of them about what the window knew about a session.**
+Run `npx create-pmos@latest workspace`; the version bump means an existing install auto-upgrades.
+
+- **Your terminal now uses its whole width.** Nothing ever told the shell how wide the browser
+  was. A session starts at 80 columns; the server stated its own size on attach rather than
+  adopting yours, and the browser only spoke up when a resize *changed* its grid — which happened
+  once, while the connection was still opening and there was no session to tell. So the process on
+  the other end kept wrapping at 80 columns inside a window three times that wide, and a
+  full-screen agent CLI painted into a box that was not there.
+- **The window stops rebuilding itself while you type.** It repainted every panel every four
+  seconds whether or not anything had changed — on a project with a hundred-odd initiatives that is
+  a real stall, on a timer, next to a terminal you are typing into. It now repaints when something
+  it shows actually moves. Separately, the server rewrote every session's scrollback file to disk
+  every five seconds, synchronously, whether or not a byte had changed; it now writes only what
+  moved.
+- **The scratchpad belongs to a session again.** It had become one shared buffer for the whole
+  page, so every terminal — in every repository — showed and overwrote the same text, and none of
+  it outlived the tab. Each session has its own pad again, saved on your machine, and it comes back
+  with the session.
+- **Reopening the workspace brings your sessions back.** Open tabs are remembered and re-attach to
+  the exact session they were on, named on the tab so you can tell which one it is. Previously they
+  were forgotten on reload and had to be re-found by hand — and the re-finding matched on a session
+  *name*, which is not unique between repositories, so a tab in one project could silently attach
+  to a shell running in another. `＋ session` also always starts a new session now, instead of
+  sometimes adopting one that was already running.
 ## What's new in 0.18.0
 
 **Several sessions in one folder now say so.** Run `npx create-pmos@latest workspace`; the version

package/package.json

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

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@83f52ff
+kernel-source: pmos@9fee84a
 assembled: 2026-07-31
 mode: vendor

package/payload/scripts/metrics.py

@@ -49,11 +49,18 @@ def review_gate_pass(verdict, score):
 
 def leading_frontmatter(path):
     """The LEADING frontmatter block only — body text cannot fake a declaration. Mirror of
-    workspace/lib/file-mode-parse.js parseLeadingFrontmatter (agreement enforced by the fixture test)."""
+    workspace/lib/file-mode-parse.js parseLeadingFrontmatter (agreement enforced by the fixture test).
+
+    The value group is `(.*?)`, NOT `(.+?)`. A key written bare (`prd_path:` with nothing after it)
+    is legal YAML for a null value; under `.+?` the line does not match, so it reads as the first
+    body line, the loop breaks, and every key below it is dropped. Agreement with the JS parser was
+    never sufficient to catch this — both carried the same wrong regex, so the fixture compared two
+    identical mistakes and passed. See kit/fixtures/state/initiatives/epsilon-empty-value.md.
+    """
     fm = {}
     with open(path, encoding="utf-8") as fh:
         for line in fh:
-            m = re.match(r"^([a-z_]+):\s*(.+?)\s*$", line.rstrip("\n"))
+            m = re.match(r"^([a-z_]+):\s*(.*?)\s*$", line.rstrip("\n"))
             if m:
                 fm.setdefault(m.group(1), m.group(2))
             elif line.strip() and not line.startswith("---"):

package/workspace/lib/file-mode-parse.js

@@ -14,10 +14,21 @@ const reviewGate = require('./review-gate');
 // The LEADING YAML-ish frontmatter block ONLY — body text must never be able to fake a declaration.
 // Mirrors metrics.py exactly: `key: value` lines (first value wins), `---` fences and blank lines are
 // skipped, and the FIRST non-frontmatter, non-fence, non-blank line ends the block.
+//
+// The value group is `(.*?)`, NOT `(.+?)`. A key written bare — `prd_path:` with nothing after it —
+// is legal YAML for a null value, and 30 of the 136 records in planning/initiatives/ are written
+// that way. Under `.+?` such a line does not match, so it is treated as the first body line, the
+// loop BREAKS, and every key below it is silently dropped: parent_kr, outcome_metric, the lot. The
+// spine then rendered those initiatives as "unanchored — rejected work under D59".
+//
+// This is not a hypothetical. metrics.py carried the identical regex and kit/fixtures/test_parsers.py
+// existed to prove the two agreed — which they did, on being wrong, for as long as the fixture only
+// ever compared them to each other. scripts/workflow-state.js:105 was the one correct parser and was
+// compared against nothing. The fixture now asserts VALUES; see epsilon-empty-value.md.
 function parseLeadingFrontmatter(text) {
   const fm = {};
   for (const line of String(text == null ? '' : text).split('\n')) {
-    const m = line.match(/^([a-z_]+):\s*(.+?)\s*$/);
+    const m = line.match(/^([a-z_]+):\s*(.*?)\s*$/);
     if (m) { if (!(m[1] in fm)) fm[m[1]] = m[2]; continue; }
     if (line.trim() && !line.startsWith('---')) break;
   }

package/workspace/lib/start-policy.js

@@ -0,0 +1,118 @@
+/* workspace-repo-first · the start-work policy (PRD R1 · R3)
+ * ──────────────────────────────────────────────────────────────────────────────────────────────
+ * ONE declared rule for where a session starts, replacing a decision the server used to make per
+ * call from invisible state.
+ *
+ * What it replaced, and why that had to go. `spawnWithBranch` chose isolation with
+ *
+ *     if (isolate === undefined || isolate === null) isolate = liveSessionCount(w.id) > 0;
+ *
+ * — so the SAME click created a worktree or moved the shared checkout depending on whether some
+ * other session happened to be alive at that moment. A PM cannot hold that rule in their head,
+ * cannot predict it, and cannot see it in the UI before pressing the button. It is not a policy;
+ * it is a coin flip with a plausible-looking reason.
+ *
+ * The rule this module states instead:
+ *
+ *   no initiative chosen  → the repository's MAIN working tree, on whatever branch it is on.
+ *                           No git operation at all. Nothing moves, no folder appears.
+ *   an initiative chosen  → that initiative's own worktree on `initiative/<id>`, created if absent
+ *                           and REUSED if present. The main tree is never moved off its branch.
+ *
+ * The PM's framing, which this encodes: keep the main checkout on main, and let work live in
+ * worktrees rather than accumulating branches in the shared tree.
+ *
+ * Two consequences worth stating because they are easy to get wrong:
+ *
+ *   * If the MAIN tree already happens to be on `initiative/<id>`, the answer is the main tree —
+ *     not a second folder for a branch that is already checked out. git allows one working tree
+ *     per branch, so building a worktree here would fail, and failing is the better outcome only
+ *     if the alternative were wrong. It isn't: the PM asked to work on that initiative and the
+ *     repository is already there.
+ *   * `create` is derived from whether the branch EXISTS, never assumed. `addWorktree(root, b,
+ *     {create:true})` errors when the branch is already there, and `{create:false}` errors when it
+ *     is not. Guessing produces a failed git operation, and a failed git operation is the one thing
+ *     the rubric's veto forbids being followed by a spawned session.
+ *
+ * PURE ON PURPOSE. Everything it needs arrives as plain data, so the whole policy — including the
+ * paths that touch git — is exercisable in node with no repository, no socket and no PTY. The
+ * predecessor's hard floor ("a failed git operation must never start a session in the wrong
+ * directory") is inherited by this initiative, and a floor whose only proof is a manual click is
+ * not a floor.
+ */
+
+const BRANCH_PREFIX = 'initiative/';
+
+// The branch an initiative's work belongs on. One definition, so the client's preview and the
+// server's git call cannot disagree about what the PM is about to get.
+function branchForInitiative(id) {
+  const s = String(id == null ? '' : id).trim();
+  return s ? BRANCH_PREFIX + s : null;
+}
+
+// The repository's MAIN working tree among the registered ones. `repo_key` IS the main worktree's
+// directory (repoIdentity resolves it from `git worktree list`, which names the main tree first),
+// so the main tree is the one whose root equals the key. A repo where only LINKED worktrees are
+// registered has no main tree on screen; the first registered tree stands in, which is the same
+// fallback surfaceProducts already makes for the same reason.
+function mainTreeOf(trees) {
+  const list = (trees || []).filter(Boolean);
+  if (!list.length) return null;
+  return list.find((t) => t.repo_key && t.root && String(t.root) === String(t.repo_key)) || list[0];
+}
+
+/* Resolve one "start work here" request to a plan.
+ *
+ * trees      — the registered workspaces of ONE repository: { id, root, repo_key, branch }
+ * initiative — an initiative id, or null/'' for "just give me a terminal"
+ * branches   — branch names known to the repo (branchInfo().branches), or null when unread
+ *
+ * Returns { ok, plan, wsId, branch, createBranch, isolate, why } — or { ok:false, error } when
+ * there is nothing to act on. `wsId` is the workspace the session is spawned against; `branch`
+ * non-null means a git operation is required first, and `isolate` says which kind.
+ */
+function resolveStart({ initiative, trees, branches } = {}) {
+  const list = (trees || []).filter(Boolean);
+  if (!list.length) return { ok: false, error: 'no working tree is registered for this repository' };
+  const main = mainTreeOf(list);
+  if (!main) return { ok: false, error: 'no working tree is registered for this repository' };
+
+  const id = String(initiative == null ? '' : initiative).trim();
+  if (!id) {
+    return {
+      ok: true, plan: 'main-tree', wsId: main.id, branch: null, createBranch: false, isolate: false,
+      why: `runs in ${main.name || 'the main working tree'}${main.branch ? ` on ${main.branch}` : ''} — no branch is checked out and nothing else moves`,
+    };
+  }
+
+  const branch = branchForInitiative(id);
+  if (!branch) return { ok: false, error: 'an initiative id is required to derive a branch' };
+
+  // Already checked out in a LINKED worktree → go there. No git operation; the folder exists.
+  const existing = list.find((t) => t.id !== main.id && t.branch === branch);
+  if (existing) {
+    return {
+      ok: true, plan: 'reuse-worktree', wsId: existing.id, branch: null, createBranch: false, isolate: false,
+      why: `${id} already has its own folder — this reuses it, and creates nothing`,
+    };
+  }
+  // The MAIN tree is already on it. Use it rather than attempting a worktree git would refuse.
+  if (main.branch === branch) {
+    return {
+      ok: true, plan: 'main-tree-on-branch', wsId: main.id, branch: null, createBranch: false, isolate: false,
+      why: `this repository is already on ${branch} — the session runs here, and no second folder is made`,
+    };
+  }
+  // Otherwise: a new worktree, off the main tree, which stays exactly where it is.
+  // `create` is DERIVED. A null `branches` means the branch list was never read — assuming the
+  // branch is new would make `git worktree add -b` fail on every existing branch, so the honest
+  // default is to treat it as existing and let git's own error surface if it is not.
+  const known = Array.isArray(branches) ? branches : null;
+  const createBranch = known ? !known.includes(branch) : false;
+  return {
+    ok: true, plan: 'new-worktree', wsId: main.id, branch, createBranch, isolate: true,
+    why: `${branch} gets its own folder — ${main.name || 'the main working tree'} stays on ${main.branch || 'its branch'} and every running session stays put`,
+  };
+}
+
+module.exports = { resolveStart, branchForInitiative, mainTreeOf, BRANCH_PREFIX };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.18.0",
+      "version": "0.18.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node no-network.test.js && node fixture-parity.test.mjs",
+    "test:modules": "node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node no-network.test.js && node fixture-parity.test.mjs && node start-policy.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",

package/workspace/public/pm/data.js

@@ -552,14 +552,22 @@ async function loadBoard(prod) {
 /** Publish every loaded product's board and records into state, in one patch. */
 function publishBoards() {
   const board = {};
+  /* Product NAME → workspace id, for every registered repository — not only the selected one.
+   * panel 4 keeps every open terminal live, including those belonging to a repository the PM is not
+   * currently looking at, and a parked tab's session must be resolved inside ITS OWN repository.
+   * Scoping it by the selected workspace is how a tab in one repo attached to a shell in another
+   * (tab-term.js `wsForTab`). */
+  const productWs = {};
   let records = {};
   for (const name of productOrder) {
     const p = products.get(name);
-    if (!p || !p.board) continue;
+    if (!p) continue;
+    if (p.ws) productWs[name] = p.ws;
+    if (!p.board) continue;
     board[name] = p.board;
     records = { ...records, ...p.records };
   }
-  setState({ board, records: { ...records, ...(hydrated) } });
+  setState({ board, productWs, records: { ...records, ...(hydrated) } });
 }
 
 /* Hydrated (fully derived) records live apart from the light ones so that a board reload cannot
@@ -617,12 +625,48 @@ function currentProductName() {
  */
 
 let pollTimer = null;
+let sessionDigest = null;
+
+/**
+ * WHAT THE SURFACE ACTUALLY RENDERS from a session row, as one string.
+ *
+ * Every `setState` repaints all four panels, and panel 2 rebuilds a board that is 138 initiatives
+ * deep on this repository. Publishing the poll unconditionally therefore tore down and rebuilt the
+ * whole window every four seconds, forever, whether or not anything had changed — which is a
+ * hundreds-of-milliseconds stall on the main thread, on a cadence, next to a terminal the PM is
+ * typing into. That is the jitter: input queued behind a repaint nobody asked for.
+ *
+ * The rows themselves change constantly (`lastOutputAt` moves with every byte an agent writes), so
+ * comparing the payload is useless. What is compared is the PROJECTION the panels read — id, name,
+ * workspace, derived state, the quiet reading ROUNDED THE WAY THE LABEL ROUNDS IT (minutes), and
+ * the fields the sidebar prints. A working agent produces an identical projection minute after
+ * minute, so the window stays still while it works, and repaints the moment something it shows
+ * actually moves.
+ */
+function sessionProjection(rows) {
+  return (rows || []).map((s) => [
+    s.id, s.ws, s.name, s.agent, s.state, s.shown, s.note || '', s.cwd || '',
+    s.profile_id || '', s.profile_line || '',
+    // the label's own resolution, not the millisecond behind it
+    s.shown === 'quiet' && Number.isFinite(s.quietMs) ? Math.max(1, Math.round(s.quietMs / 60000)) : '',
+    // Joined on U+0000, fields and rows both. A separator that cannot occur in any of these
+    // values is what stops two different lists folding into one identical string and
+    // suppressing a repaint that was real.
+  ].join('\u0000')).join('\u0000\u0000');
+}
 
 async function pollSessions() {
   if (FIXTURE) return;
   const out = await getJson('/api/sessions');
   if (out && Array.isArray(out.sessions)) {
-    setState({ sessions: out.sessions, runningCount: liveCount(out.sessions) });
+    const digest = sessionProjection(out.sessions);
+    const count = liveCount(out.sessions);
+    // A poll that found nothing new is not a render. `runningCount` is compared too: it folds in
+    // `extraSess`, so a session started in this window still publishes on the very next poll.
+    if (digest !== sessionDigest || count !== state.runningCount) {
+      sessionDigest = digest;
+      setState({ sessions: out.sessions, runningCount: count });
+    }
   }
   schedulePoll();
 }
@@ -817,6 +861,46 @@ export function startSession(slug, sess) {
   setTimeout(pollSessions, 800);
 }
 
+/* ── the scratchpad ─────────────────────────────────────────────────────────────────────────────
+ * The pad is PER SESSION, and the server has always stored it that way: `/api/scratchpad` is keyed
+ * by the server-issued session id (workspace-scoped, one file per session, deleted with it). What
+ * was lost in the four-panel port was the CLIENT half — the pad became one in-memory string for the
+ * whole page, so every tab in every repository showed, and overwrote, the same text.
+ *
+ * These two functions are the whole restoration. The key is `sess:<id>` or `ws:<id>`; the panel
+ * derives it, this file only speaks the two shapes the endpoint accepts.
+ */
+
+function padParams(key) {
+  const k = String(key || '');
+  if (k.startsWith('sess:')) return { session: k.slice(5) };
+  if (k.startsWith('ws:')) return { ws: k.slice(3) };
+  return null;
+}
+
+/** panel-tabs.js — the stored text for one pad, or '' when there is none (and on any failure). */
+export async function loadScratchpad(key) {
+  if (FIXTURE) return '';
+  const params = padParams(key);
+  if (!params) return '';
+  const out = await getJson('/api/scratchpad', params);
+  return out && out.ok !== false && typeof out.text === 'string' ? out.text : '';
+}
+
+/**
+ * panel-tabs.js — write one pad. A failure is reported to the console and NOT surfaced as a lost
+ * buffer: the text stays in `state.scratchPads`, so the PM keeps what they typed for this page even
+ * when the disk write refused.
+ */
+export async function saveScratchpad(key, text) {
+  if (FIXTURE) return { ok: true };
+  const params = padParams(key);
+  if (!params) return { ok: false, error: 'no session or workspace to file this pad under' };
+  const out = await postJson('/api/scratchpad', { ...params, text });
+  if (out && out.ok === false) console.warn('[pm] the scratchpad was NOT saved: ' + out.error);
+  return out;
+}
+
 /** tab-doc.js — `readDoc(path)`. The raw document body, or a rejected promise carrying the reason. */
 export async function readDoc(path) {
   if (FIXTURE) return '';

package/workspace/public/pm/panel-initiatives.js

@@ -131,6 +131,13 @@ export function openTerm(slug, sess) {
   openTab({
     id: 'term:' + slug + ':' + sess.name, kind: 'term', title: sess.name, slug,
     repo: slugProduct()[slug], sess: sess.name, state: sess.st, profile: sess.profile || 'claude-work',
+    /* The SERVER's session id, when the row that was clicked carries one. This is the exact join:
+     * with it, the terminal attaches to precisely the PTY the PM pointed at, and a reload attaches
+     * to the same one again. Without it the tab falls back to matching by NAME, and names repeat
+     * across repositories — which is how a click in one repo opened another repo's shell.
+     * `spawn` is the opposite instruction, set only by `＋ session`: start one, never adopt one. */
+    sessionId: (sess && sess.id) || null,
+    spawn: !!(sess && sess.spawn),
   });
 }
 

package/workspace/public/pm/panel-tabs.js

@@ -146,7 +146,32 @@ export function closeTab(id) {
 /* The data layer's optional session-start hook. In fixture mode nothing is ever started; in real
  * mode the PTY is data.js's to create, and panel 4's part is only to show the tab for it. */
 let dataMod = null;
-import('./data.js').then((m) => { dataMod = m; }).catch(() => { dataMod = null; });
+/* The repaint matters: `syncPad` below cannot name a pad before this module exists, so the render
+ * that lands it is the render that first loads the PM's staged text. */
+import('./data.js').then((m) => { dataMod = m; setState({}); }).catch(() => { dataMod = null; });
+
+/**
+ * The next free `agent <n>`, counted against EVERY name the window can see — the server's live
+ * sessions, the ones started in this window, and the tabs already open — not just this page's
+ * counter.
+ *
+ * `startN` resets to 1 on every reload, and the name is what the terminal used to join on and what
+ * the tab id is built from. So after a reload the first `＋ session` proposed `agent 1`, which was
+ * already running from before the reload: the click attached to that old session instead of
+ * starting a new one, and a second click collided with its own tab id. Counting past what exists
+ * is what makes `＋ session` mean "a new one" again.
+ */
+function nextSessionName() {
+  let max = state.startN - 1;
+  const bump = (name) => {
+    const m = /^agent (\d+)$/.exec(String(name || ''));
+    if (m) max = Math.max(max, Number(m[1]));
+  };
+  for (const s of (state.sessions || [])) bump(s && s.name);
+  for (const k in (state.extraSess || {})) for (const s of (state.extraSess[k] || [])) bump(s && s.name);
+  for (const t of (state.tabs || [])) if (t && t.kind === 'term') bump(t.sess);
+  return { n: max + 1, name: 'agent ' + (max + 1) };
+}
 
 /**
  * `＋ session` (line 2087): file a new session against the selected initiative and open its tab.
@@ -156,8 +181,11 @@ import('./data.js').then((m) => { dataMod = m; }).catch(() => { dataMod = null;
 export function newSession(slug) {
   const target = slug || selSlug();
   if (!target) return;
-  const n = state.startN;
-  const sess = { name: 'agent ' + n, st: 'working', label: 'working', profile: state.newSessProfile };
+  const { n, name } = nextSessionName();
+  /* `spawn` is carried on the session and thence onto the tab: it is an INSTRUCTION to start a PTY,
+   * and it is the only thing that authorises one. Without it the terminal resolves by name, which
+   * is a question about what already exists, not a request for something new. */
+  const sess = { name, st: 'working', label: 'working', profile: state.newSessProfile, spawn: true };
   setState((s) => ({
     startN: n + 1,
     extraSess: { ...s.extraSess, [target]: [...(s.extraSess[target] || []), sess] },
@@ -204,13 +232,118 @@ const panesRow = el('div', { style: 'flex:1;display:flex;min-height:0' });
  * One textarea, created once. Its text is written back as a CHILD TEXT NODE as well as a value,
  * because that is what the prototype's runtime does and the comparator reads text nodes — but only
  * when the two differ, so a repaint mid-sentence never moves the PM's caret.
+ *
+ * ── ONE PAD PER SESSION ─────────────────────────────────────────────────────────────────────
+ * The pad stages the next thing to type into a PARTICULAR agent, so it belongs to that agent's
+ * session. The four-panel port shipped it as one in-memory string for the whole page, which meant
+ * every terminal — in every repository, in every window — showed and overwrote the same buffer.
+ *
+ * The store is `state.scratchPads`, keyed by:
+ *   `sess:<server session id>` — a terminal tab bound to a live PTY. The id is the SERVER's, so two
+ *                                sessions both called `agent 1` in two repositories are two pads.
+ *   `ws:<workspace id>`        — everything else (a doc, a task, nothing open): the repository pad.
+ * That is exactly the key space `/api/scratchpad` already stores under — the endpoint has been
+ * per-session all along, and it is the client half that went missing. `state.scratchText` remains
+ * the text ON SCREEN, so the copy button, `⇥ send to terminal` and the fixture render are unchanged.
+ *
+ * FIXTURE MODE IS UNTOUCHED: no key, no fetch, one pad, the prototype's own placeholder. The offline
+ * demo path must make no network call, and the comparator must see the design's string.
  */
+const SCRATCH_PLACEHOLDER = FIXTURE
+  ? 'scratchpad — survives tab switches, dies with the page'
+  : 'scratchpad — one pad per session, saved on this machine';
+
 const scratchTa = el('textarea', {
-  placeholder: 'scratchpad — survives tab switches, dies with the page',
+  placeholder: SCRATCH_PLACEHOLDER,
   style: 'height:96px;background:oklch(0.11 0.004 228.8);color:#c4ccce;padding:10px 14px;font-family:var(--mono);font-size:12px',
-  onInput: (e) => setState({ scratchText: e.target.value }),
+  onInput: (e) => onScratchInput(e.target.value),
 });
 
+/* ── pad identity, loading and autosave ─────────────────────────────────────────────────────── */
+
+const padLoading = new Set();      // keys with a read in flight — one read per key, ever
+let padTimer = null;
+let padPending = null;             // {key, text} not yet written
+
+/** The pad the ACTIVE tab stages against, or null when it cannot be named yet. */
+function padKey() {
+  if (FIXTURE) return null;
+  const act = activeTab();
+  if (act && act.kind === 'term') {
+    const id = (termMod && typeof termMod.sessionIdOf === 'function')
+      ? termMod.sessionIdOf(act) : (act.sessionId || null);
+    // A terminal whose session has not resolved yet has no pad of its own YET. Null holds the
+    // drawer on whatever it was showing rather than flashing an empty pad and then SAVING it over
+    // the real one the moment the session lands.
+    return id ? 'sess:' + id : null;
+  }
+  return state.wsId ? 'ws:' + state.wsId : null;
+}
+
+/** Write the pending pad now. Called before leaving a pad, and when the page goes away. */
+function flushPad() {
+  if (padTimer) { clearTimeout(padTimer); padTimer = null; }
+  if (!padPending) return;
+  const { key, text } = padPending;
+  padPending = null;
+  if (dataMod && typeof dataMod.saveScratchpad === 'function') {
+    try { dataMod.saveScratchpad(key, text); } catch { /* the text stays in state either way */ }
+  }
+}
+
+function schedulePadSave(key, text) {
+  padPending = { key, text };
+  if (padTimer) clearTimeout(padTimer);
+  padTimer = setTimeout(flushPad, 500);      // one write per pause, not one per keystroke
+}
+
+function onScratchInput(text) {
+  if (FIXTURE) { setState({ scratchText: text }); return; }
+  const key = state.scratchKey;
+  setState((s) => ({
+    scratchText: text,
+    scratchPads: key ? { ...s.scratchPads, [key]: text } : s.scratchPads,
+  }));
+  if (key) schedulePadSave(key, text);
+}
+
+/**
+ * Bring the drawer onto the pad the active tab belongs to, reading it from the server the first
+ * time that pad is seen. Called at the top of every render; a no-op unless the pad CHANGED.
+ */
+function syncPad() {
+  if (FIXTURE || !dataMod) return;           // no data layer yet — retried on the next render
+  const key = padKey();
+  if (!key || key === state.scratchKey) return;
+  flushPad();                                // the pad being left is written before it is left
+  if (Object.prototype.hasOwnProperty.call(state.scratchPads, key)) {
+    setState({ scratchKey: key, scratchText: state.scratchPads[key] });
+    return;
+  }
+  setState({ scratchKey: key, scratchText: '' });
+  if (padLoading.has(key)) return;
+  padLoading.add(key);
+  const landed = (text) => {
+    padLoading.delete(key);
+    setState((s) => ({
+      scratchPads: { ...s.scratchPads, [key]: text },
+      // …and onto the screen only if this is still the pad on screen. A PM who switched tabs while
+      // the read was in flight must not have the arriving text land in the pad they moved to.
+      ...(s.scratchKey === key ? { scratchText: text } : {}),
+    }));
+  };
+  try { dataMod.loadScratchpad(key).then(landed, () => landed('')); }
+  catch { padLoading.delete(key); }
+}
+
+/* A pad edited in the last half-second is still worth keeping when the tab is closed or the machine
+ * sleeps. `pagehide` fires where `beforeunload` is unreliable (bfcache, mobile), and both are cheap. */
+if (typeof window !== 'undefined' && !FIXTURE) {
+  window.addEventListener('pagehide', flushPad);
+  window.addEventListener('beforeunload', flushPad);
+  document.addEventListener('visibilitychange', () => { if (document.hidden) flushPad(); });
+}
+
 const scratchCopyLabel = iv('⧉ copy');
 const scratchCopyBtn = el('button', {
   onClick: () => {
@@ -396,7 +529,13 @@ function tabNode(t, act, splitTab) {
   const bc = selected ? FX.TAB_COLORS.activeBorder : FX.TAB_COLORS.idleBorder;
   const color = act && act.id === t.id ? FX.TAB_COLORS.activeText : FX.TAB_COLORS.idleText;
   const dotColor = FX.TAB_COLORS.dot[t.kind] || FX.TAB_COLORS.dot.doc;
-  const meta = t.kind === 'term' ? 'session' : (t.kind === 'task' ? 'task' : t.role);
+  /* A terminal's sub-line names the SESSION IT IS ON, not the word "session". After a reload the PM
+   * could not tell which session a re-opened tab had landed on, and the answer was on screen
+   * nowhere; the server's id is the one identifier that does not repeat across repositories. The
+   * fixture render keeps the design's literal — the comparator reads this text node. */
+  const meta = t.kind === 'term'
+    ? ((!FIXTURE && t.sessionId) ? 'session ' + t.sessionId : 'session')
+    : (t.kind === 'task' ? 'task' : t.role);
 
   return el('div', {
     style: 'flex:none;display:flex;align-items:center;gap:8px;padding:0 10px;background:' + bg
@@ -433,6 +572,8 @@ function tabNode(t, act, splitTab) {
  * bar. The panes row renders even when nothing is open, exactly as the design does.
  */
 export function renderTabs(host) {
+  // Which pad the drawer is on is decided from the active tab, before anything is painted from it.
+  syncPad();
   const visTabs = visibleTabs();
   const act = visTabs.find((t) => t.id === state.active) || null;
   const splitTab = state.splitId

package/workspace/public/pm/state.js

@@ -41,15 +41,37 @@ function initial() {
     col0: true, col1: true, col2: true, scratchOpen: false, scratchText: '', copied: false,
     flowsMap: null, schedList: null, agentList: null, memory: null,
     savedDocs: {}, scratchCopied: false,
+    /* The scratchpad is ONE PAD PER SESSION, not one per page (see panel-tabs.js). `scratchPads`
+     * holds every pad this window has loaded, keyed by the pad key the panel derives — `sess:<id>`
+     * for a terminal bound to a PTY, `ws:<id>` for the repository pad a non-terminal tab stages
+     * against. `scratchText` remains the text ON SCREEN, so every existing reader (the copy button,
+     * ⇥ send to terminal, the fixture render) is unchanged. `scratchKey` is which pad that is. */
+    scratchPads: {}, scratchKey: null,
   };
 }
 
 /* ── persistence ──────────────────────────────────────────────────────────────────────────────
- * Only the PM's *arrangement* is persisted — never content, never tabs, never a live session.
- * Each key carries its own validator. A stored value that fails its validator is DROPPED and the
- * rest of the record is still applied: "layout amnesia" in the PRD's failure-mode list means a
- * stale record from an older build throwing, or silently wiping a layout the PM is working in.
- * An unknown key is simply not read, so an older or newer schema costs nothing.
+ * The PM's *arrangement*, and — since the reload defect — WHICH VIEWS WERE OPEN. Never content,
+ * never a pad's text, never a live PTY: a tab is a view of a session the server owns, and what is
+ * stored here is the identity of the view, not the thing it looks at.
+ *
+ * Each key carries its own validator, and optionally a `pack` that decides what is WRITTEN. A
+ * stored value that fails its validator is DROPPED and the rest of the record is still applied:
+ * "layout amnesia" in the PRD's failure-mode list means a stale record from an older build
+ * throwing, or silently wiping a layout the PM is working in. An unknown key is simply not read,
+ * so an older or newer schema costs nothing.
+ *
+ * ── Why `tabs` is here, and why it was not ──────────────────────────────────────────────────
+ * It read "never tabs" because a tab was thought to be a live thing. It is not: the PTY lives in
+ * the server and survives both detach and a server restart (R7), so a window that forgot its tabs
+ * was not protecting anything — it was throwing away the only record of which sessions the PM had
+ * open. The PM then had to re-find them by hand, one click at a time, with no way to tell which
+ * session a re-opened tab had landed on. Restoring the views is what makes the surviving sessions
+ * visible again on reload.
+ *
+ * The stored tab is PACKED, not the live record: a whitelist of scalar fields, capped at 40 tabs.
+ * A doc tab's edited buffer, a task's derived prose, and anything a future field might carry stay
+ * out of localStorage by construction rather than by remembering to exclude them.
  */
 const isBool = (v) => typeof v === 'boolean';
 const isSlug = (v) => v === null || typeof v === 'string';
@@ -57,6 +79,28 @@ const isFlagMap = (v) =>
   !!v && typeof v === 'object' && !Array.isArray(v) &&
   Object.keys(v).every((k) => typeof k === 'string' && typeof v[k] === 'boolean');
 
+/* The only tab fields that are written. `sessionId` is the load-bearing one: it is the SERVER's own
+ * id, so a restored terminal re-attaches to exactly the PTY it was showing rather than re-running
+ * the name join — which is what made a reloaded tab land on a session the PM could not identify. */
+const TAB_FIELDS = ['id', 'kind', 'title', 'slug', 'repo', 'sess', 'sessionId', 'state', 'profile',
+  'path', 'role', 'phase', 'status'];
+const MAX_TABS = 40;
+
+function packTab(t) {
+  if (!t || typeof t !== 'object' || typeof t.id !== 'string' || typeof t.kind !== 'string') return null;
+  const out = {};
+  for (const k of TAB_FIELDS) {
+    const v = t[k];
+    if (v === null || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') out[k] = v;
+  }
+  return out;
+}
+
+const isTabList = (v) =>
+  Array.isArray(v) && v.length <= MAX_TABS &&
+  v.every((t) => t && typeof t === 'object' && !Array.isArray(t)
+    && typeof t.id === 'string' && typeof t.kind === 'string');
+
 const PERSIST = {
   theme: (v) => v === 'dark' || v === 'light',
   col0: isBool, col1: isBool, col2: isBool,
@@ -65,6 +109,15 @@ const PERSIST = {
   sel: isSlug,
   collapsedGroups: isFlagMap,
   collapsedPhases: isFlagMap,
+  tabs: isTabList,
+  active: isSlug,
+  splitId: isSlug,
+  scratchOpen: isBool,
+};
+
+/** What is WRITTEN for a key, when it is not the live value verbatim. */
+const PACK = {
+  tabs: (v) => (Array.isArray(v) ? v.slice(0, MAX_TABS).map(packTab).filter(Boolean) : []),
 };
 
 /** The exact set of keys written to localStorage, in write order. */
@@ -84,13 +137,19 @@ function restore(target) {
     try { ok = PERSIST[k](saved[k]); } catch { ok = false; }
     if (ok) target[k] = saved[k];
   }
+  /* `active` and `splitId` name tabs. A record whose tab list was dropped (or that names a tab the
+   * list no longer holds) must not restore a pointer into nothing — panel 4 would render an empty
+   * pane and the PM would see a window with no tab selected and no way to guess why. */
+  const ids = new Set((target.tabs || []).map((t) => t.id));
+  if (!ids.has(target.active)) target.active = target.tabs.length ? target.tabs[target.tabs.length - 1].id : null;
+  if (!ids.has(target.splitId)) target.splitId = null;
   return target;
 }
 
 function persist() {
   if (FIXTURE) return;
   const out = {};
-  for (const k of persistKeys) out[k] = state[k];
+  for (const k of persistKeys) out[k] = PACK[k] ? PACK[k](state[k]) : state[k];
   try { localStorage.setItem(STORE_KEY, JSON.stringify(out)); } catch { /* quota / private mode */ }
 }
 

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);
@@ -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,17 @@ export function sendToTerm(tab, data) {
   return send({ t: 'input', id: rec.sessionId, data });
 }
 
+/**
+ * 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)
@@ -1306,6 +1307,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) {
@@ -1641,6 +1646,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 +1814,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;
 }
 
@@ -2112,6 +2119,86 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
   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 +2342,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/`
@@ -3504,6 +3600,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
@@ -4159,7 +4265,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 +4289,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