create-pmos 0.17.0 → 0.18.1

package/README.md

@@ -333,6 +333,63 @@ 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
+bump means an existing install auto-upgrades.
+
+- **Starting a session where others are already running tells you what you are sharing.** Sessions
+  in one checkout share one branch, one index and one set of files — that was true before and
+  nothing said it. The new session's pane now names the sessions already there and points at the
+  alternative (a new branch in its own folder). It appears on the ordinary "＋ session" path too,
+  where no git operation runs at all: the server had already worked out that other sessions would
+  be disturbed, and was throwing the answer away unless you happened to pick a branch.
+- **It counts the right thing.** A repository registered at two paths — the project root and a
+  subdirectory of it, the ordinary shape when you add a product repo by path — is **one** checkout,
+  and its sessions are now told about each other; before, each was told it was alone. Two
+  *worktrees* of one repository are **two** checkouts and are deliberately not warned about, because
+  those are the sessions that isolation already made safe. A folder with no git says nothing, since
+  there is no index to collide over.
+- **One session is the declared writer; the rest read.** The first live session in a checkout holds
+  the claim, and you can hand it to another (`POST /api/tree/claim`); `GET /api/tree/peers` reports
+  who holds it and who else is there. It moves only when you move it — never on a timer or an exit —
+  and when its holder exits the checkout reads *vacant* rather than promoting somebody at random.
+- **Be clear about what that is: a declaration, not a lock.** The workspace hosts your agent's
+  terminal; it does not sit between the agent and the files, so nothing here prevents a write, a
+  checkout or a commit, and no session is ever refused because another one is there. It makes a
+  shared checkout visible. The discipline stays yours.
+- **A folder you are working in can no longer be reclaimed out from under you.** Removing a
+  worktree already refused when sessions were running in it — but it counted only sessions in the
+  workspace registered at that exact folder, so a session running in a subdirectory of it was
+  invisible. It is counted now, and named in the refusal.
+
 ## What's new in 0.17.0
 
 **Your board stops calling shipped work unstarted.** Run `npx create-pmos@latest workspace`; the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.17.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@4cb5198
+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/README.md

@@ -155,6 +155,31 @@ the folder and **keeps the branch**; nothing is ever removed automatically. Git
 between worktrees, so what a folder costs is a checkout of tracked files, not a second copy of the
 repo.
 
+## Several sessions in one tree: you are told, never stopped
+
+Sessions in one working tree share **one branch, one index and one set of files**. Starting a
+session in a tree that already has live ones now says so in the pane — naming them, and naming the
+way out (⑂ a new branch in its own folder). It fires on the plain `＋ session` path too, where no
+git operation runs at all: the server already knew, and used to say nothing.
+
+**The tree is the unit, not the folder you registered.** A repo registered twice — say `~/repo` and
+`~/repo/packages/app`, the ordinary shape for a product repo added by path — is **one** tree, and
+its sessions are told about each other. Two *worktrees* of one repo are **two** trees, and are not
+warned about at all: those are the sessions isolation made safe. A folder with no git has no tree
+and says nothing, because there is no index to collide over.
+
+**The writer claim is a declaration, not a lock.** The first live session in a tree holds it; the
+others read. `GET /api/tree/peers?ws=…` reports the tree, its holder and every session on it;
+`POST /api/tree/claim {session}` hands it over. It moves **only** when you move it — never on a
+timer, never on an exit. When the holder exits the tree reads *vacant*, and no survivor is
+promoted, because which pane should be driving is your intention and not something to derive.
+
+Be clear about what this buys: **PMOS hosts your agent's terminal, it does not sit between it and
+the files.** Nothing here prevents a write, a checkout or a commit, and no spawn is ever refused
+because someone else is in the tree. It makes a shared tree visible; the discipline is still yours.
+(The role rides on `/api/sessions` rows as `tree` / `tree_role` / `tree_peers`; the tab-bar chip is
+not wired yet.)
+
 A workspace anywhere **inside** a repo knows its branch — a subdirectory (`repo/packages/app`)
 counts, which matters for a product repo added by path. A folder with **no git** simply says so and
 starts the session; nothing about git can block work in a repo that doesn't use it.

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/lib/tree-share.js

@@ -0,0 +1,129 @@
+'use strict';
+// Who shares a working tree with whom, and who is DECLARED to be driving it.
+//
+// The premise, stated once so nothing below has to hedge: PMOS hosts real PTYs and the agent CLI
+// inside one is untouched (D62). There is nothing between an agent and the filesystem, so this
+// module cannot prevent a write, a checkout or a commit — and never claims to. What it can do is
+// compute the right SET of sessions that would collide, and carry one declaration about which of
+// them the PM says is driving. Advisory, and every sentence it produces says so.
+//
+// The one idea worth holding: **three keys look like "which repo is this" and only one of them is
+// the collision unit.**
+//   • the workspace id  — a registered DIRECTORY. Too narrow: one repo can be registered twice
+//     (`~/repo` and `~/repo/packages/app`, the ordinary shape for a tenant repo added by path),
+//     and those two ids share one HEAD, one index, one set of files.
+//   • `repo_key`        — the repository, i.e. its MAIN worktree. Too wide: it deliberately groups
+//     a repo's linked worktrees, which are exactly the sessions that are SAFELY isolated. Warning
+//     on those is how a warning gets trained away.
+//   • the working-tree top (`git rev-parse --show-toplevel`) — one HEAD, one index, one
+//     `index.lock`. This is the one. A folder with no git has no tree key, and therefore no
+//     co-tenants: there is no index to corrupt, so there is nothing to say.
+//
+// Pure functions over plain rows, on purpose: the server owns the git shell-outs and the session
+// registry, and the rules are the part worth testing without either.
+
+/** Live = a session the PM could still be driving. `exited` is a corpse and collides with nobody. */
+function isLive(s) { return !!s && s.state !== 'exited'; }
+
+/**
+ * The live sessions sharing `tree`, excluding one id (normally the session asking).
+ * `treeOfWs` maps a workspace id → its working-tree top (null for a folder with no git).
+ * A null/empty `tree` matches nothing — "not in a repo" is never a group.
+ */
+function coTenants(sessions, treeOfWs, tree, exclude) {
+  if (!tree) return [];
+  const out = [];
+  for (const s of sessions || []) {
+    if (!isLive(s) || s.id === exclude) continue;
+    if (treeOfWs.get(s.ws) === tree) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * Who holds the writer claim on `tree` — or null when nobody does.
+ *
+ * The claim is stored, but it is only BELIEVED while its holder is live: a claim is a statement
+ * about a running session, and a dead session cannot be driving anything. Deriving the answer this
+ * way is what makes "the holder exited" read as **vacant** rather than as a stale name, without a
+ * cleanup pass having to be correct for the UI to be honest.
+ *
+ * Note what this deliberately does NOT do: promote the oldest survivor. Which pane should drive is
+ * the PM's intention, not an observable, and a derived answer must never impersonate a decision.
+ */
+function writerOf(claims, treeOfWs, sessions, tree) {
+  if (!tree) return null;
+  const held = claims.get(tree);
+  if (!held) return null;
+  const s = (sessions || []).find((x) => x && x.id === held);
+  if (!isLive(s) || treeOfWs.get(s.ws) !== tree) return null;
+  return held;
+}
+
+/** 'writer' | 'reader' for a session in a tree; null when it is not in one (no git → no role). */
+function roleOf(sessionId, tree, writerId) {
+  if (!tree) return null;
+  return sessionId === writerId ? 'writer' : 'reader';
+}
+
+/** Name a handful of panes without letting a 12-session tree produce a paragraph. */
+function nameList(rows, cap = 3) {
+  const names = (rows || []).map((s) => `“${s.name}”`);
+  if (names.length <= cap) return names.join(', ');
+  return `${names.slice(0, cap).join(', ')} and ${names.length - cap} more`;
+}
+
+/**
+ * The sentence a session gets when it starts in a tree somebody is already working in.
+ *
+ * It names the panes (a bare count tells the PM nothing they can act on), states the ONE fact that
+ * makes this matter — a shared branch, index and file set — and names the way out that already
+ * exists, because a warning with no alternative is just a nag. Returns null when there is nobody
+ * there, so the caller never has to test for emptiness.
+ */
+function coTenancyNotice(mates, opts) {
+  const rows = mates || [];
+  if (!rows.length) return null;
+  const n = rows.length;
+  const role = opts && opts.role === 'writer' ? 'writer' : 'reader';
+  const held = opts && opts.writerName;
+  const who = role === 'writer'
+    // Vacant tree: this session took the claim. Say so — the PM should know a declaration was made
+    // on their behalf, not discover it later in a list.
+    ? 'nobody had claimed it, so this session now holds the writer claim'
+    : held
+      ? `“${held}” holds the writer claim`
+      : 'no session holds the writer claim';
+  return `${n} session${n === 1 ? '' : 's'} already running in this working tree (${nameList(rows)}) — `
+    + `you share one branch, one index and one set of files with ${n === 1 ? 'it' : 'them'}. ${who}. `
+    + 'Claims are advisory: PMOS hosts your agent’s terminal, it does not sit between it and the '
+    + 'files. To work in parallel for real, start the session on a new branch with its own folder (⑂).';
+}
+
+/**
+ * The same fact, written into the pane's own scrollback at spawn.
+ *
+ * The notice frame is a transient line in whichever client was listening; this one is part of the
+ * session's record, so re-opening the tab tomorrow still shows what it was told. Dim, one line,
+ * and it never claims anything was prevented.
+ */
+function paneAdvisory(mates, opts) {
+  const line = coTenancyNotice(mates, opts);
+  if (!line) return null;
+  return `\x1b[38;5;244m⑂ ${line}\x1b[0m\r\n`;
+}
+
+/**
+ * Carry two non-fatal truths on a channel that has only ever carried one.
+ *
+ * `spawnWithBranch` returns a single `notice` string and, until now, at most one of its facts could
+ * be set at a time. A branch notice and a co-tenancy notice can both be true of the same spawn, and
+ * the second must not evict the first — dropping one would make the wire format quietly lossy in
+ * exactly the situation the PM most needs both.
+ */
+function joinNotices(...parts) {
+  const kept = parts.filter((p) => p != null && String(p).trim() !== '');
+  return kept.length ? kept.join(' · ') : null;
+}
+
+module.exports = { isLive, coTenants, writerOf, roleOf, coTenancyNotice, paneAdvisory, joinNotices, nameList };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.17.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.17.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),
   });
 }